Share via

Procédure : créer un fournisseur d’applications externes personnalisées

  • Article

Cette rubrique fournit une vue d’ensemble du processus de création d’un fournisseur d’applications externes.

Dernière modification : jeudi 8 avril 2010

S’applique à : SharePoint Foundation 2010

La création d’un fournisseur d’applications externes personnalisé requiert la dérivation de nouvelles classes à partir de l’une ou des deux classes abstraites suivantes :

  • SPExternalApplicationRequestResult  Il y a deux scénarios dans lesquels vous implémentez une classe dérivée de SPExternalApplicationRequestResult :

    • Le site et le redirecteur de requêtes où l’application externe est installée requiert que tous les résultats qu’il reçoit de Microsoft SharePoint Foundation comprenne un hachage client que le redirecteur de requêtes peut vérifier pour s’assurer que le résultat n’a pas été falsifié.

    • Vous souhaitez changer la façon dont SilverlightWebPart ou un certain composant WebPart personnalisé hébergeant une application non-SharePoint s’affiche, par exemple pour produire un chrome personnalisé autour du composant WebPart.

  • SPExternalApplicationProvider   Vous devrez implémenter cette classe dans les scénarios suivants :

    • Dans toute situation où vous implémentez une classe dérivée de la classe SPExternalApplicationRequestResult (voir plus haut).

    • Le Code XML d’application externe pour le composant WebPart contient du balisage personnalisé qui doit être lu et traité.

    • Vous souhaitez qu’une logique spéciale s’exécute lorsque le contrôle enfant du composant WebPart est créé.

    • Vous souhaitez personnaliser l’interface utilisateur du SilverlightToolPart ou modifier la page d’inscription d’application qui s’ouvre lorsque vous cliquez sur le bouton Configurer du composant outil.

Important

Pour envisager si vous créez un fournisseur d’applications externes personnalisé, gardez à l’esprit qu’il ne peut y avoir qu’un seul fournisseur d’applications externes pour tous les composants WebPart qui hébergent une application dans toutes les applications Web SharePoint Foundation qui sont enfants d’un service Web spécifié.

Pour implémenter une classe de résultats de requête

  1. Dans Microsoft Visual Studio 2010, démarrez un projet SharePoint vide.

  2. Ajoutez un élément de classe au projet.

  3. Définissez la classe comme héritant de SPExternalApplicationRequestResult.

  4. Si vous ne souhaitez pas de hachage client, implémentez la propriété ClientHash qui retourne null. Si vous voulez inclure un hachage client dans les résultats renvoyés à l’application externe, implémentez la propriété ClientHash en tant que wrapper d’un champ de sauvegarde privé qui est un tableau Byte.

    private Byte[] clientHash;
public override Byte[] ClientHash 
{
    get { return clientHash; } 
}

    Private clientHash_Renamed() As Byte
Public Overrides ReadOnly Property ClientHash() As Byte()
    Get
        Return clientHash_Renamed
    End Get
End Property

  5. Si vous utilisez un hachage client, créez un constructeur qui accepte un paramètre du type SPExternalApplicationRequestProperties, et comme second paramètre un tableau d’octets (qui représente le salt client). Ce constructeur doit utiliser la propriété RequestTokenPrefix de l’objet SPExternalApplicationRequestProperties et le tableau d’octets en entrée lors de la création d’une valeur de hachage client. Le tableau d’octets doit être une valeur fournie par le serveur hébergeant l’application externe, et l’algorithme utilisé doit être le même que celui utilisé par l’application externe pour créer sa copie du hachage client. Envisagez d’utiliser les classes de l’espace de noms System.Security.Cryptography, comme HashAlgorithm ou SHA512Managed (voir l’exemple suivant). Pour utiliser la classe SHA512Managed comme dans cet exemple, vous devez ajouter une instruction using (Imports dans Visual Basic) pour l’espace de noms System.Security.Cryptography dans le fichier du code.

    public CustomRequestResult() { }
public CustomRequestResult(SPExternalApplicationRequestProperties externalAppRequest, byte[] clientSalt)
{
    string prefix = externalAppRequest.RequestTokenPrefix;

    int nCount = Encoding.Unicode.GetByteCount(prefix);
    nCount += clientSalt.Length;
    byte[] bytes = new byte[nCount];
    nCount = Encoding.Unicode.GetBytes(prefix, 0, prefix.Length, bytes, 0);
    for (int i = 0; i < clientSalt.Length; i++)
    {
        bytes[nCount + i] = clientSalt[i];
    }
    // Compute the hash value
    SHA512Managed sha512 = new SHA512Managed();
    clientHash = sha512.ComputeHash(bytes);
}

    Public Sub New()
End Sub

Public Sub New(ByVal externalAppRequest As SPExternalApplicationRequestProperties, ByVal clientSalt() As Byte)
    Dim prefix As String = externalAppRequest.RequestTokenPrefix

    Dim nCount As Integer = Encoding.Unicode.GetByteCount(prefix)
    nCount += clientSalt.Length
    Dim bytes(nCount - 1) As Byte
    nCount = Encoding.Unicode.GetBytes(prefix, 0, prefix.Length, bytes, 0)
    For i As Integer = 0 To clientSalt.Length - 1
        bytes(nCount + i) = clientSalt(i)
    Next i
    ' Compute the hash value
    Dim sha512 As New SHA512Managed()
    clientHash = sha512.ComputeHash(bytes)
End Sub

    Si la seule partie de la classe SPExternalApplicationRequestProperties que votre classe dérivée utilise est la propriété RequestTokenPrefix, le constructeur peut accepter l’objet String comme premier paramètre, et le code appelant (qui est la méthode OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties) présentée plus loin) lui passe simplement la propriété RequestTokenPrefix. Une autre option consiste à concevoir le code appelant pour créer le hachage client avant de construire un objet de votre type dérivé. Dans ce cas, le constructeur du type peut être conçu pour accepter la valeur du hachage en tant que paramètre de tableau d’octets et écrire immédiatement dans le champ de stockage clientHash.

  6. Si vous ne souhaitez pas personnaliser l’affichage du composant WebPart Silverlight ou la façon dont certains composants WebPart personnalisés hébergeant une application non-SharePoint sont affichés, implémentez la méthode GetContentControl(String) qui retourne null. Mais si vous souhaitez personnaliser l’affichage du composant WebPart, implémentez la méthode qui retourne un Control qui sera l’unique contrôle enfant du composant WebPart. En général, il s’agira d’un élément Literal contenant le balisage HTML.

Pour implémenter une classe de fournisseur d’applications externes

  1. Ajoutez un élément de classe au projet.

  2. Définissez la classe comme héritant de SPExternalApplicationProvider.

  3. Si vous souhaitez personnaliser l’interface utilisateur du SilverlightToolPart, implémentez la méthode GetRegistrationInformation(SPWeb). Vous pouvez modifier l’une des cinq propriétés de l’objet SPExternalApplicationRegistrationInformation que la méthode retourne. Par exemple, pour substituer une page d’inscription personnalisée, attribuez l’URL de votre page personnalisée à la propriété HyperlinkUrl. Vous pouvez utiliser du code incorporé ou du code-behind de la page personnalisée pour fournir d’autres services aux utilisateurs. Par exemple, votre code peut lire le code XML d’application et voir s’il spécifie un nom principal d’application. Si c’est le cas, le code vérifie si cet utilisateur principal d’application existe et, s’il n’existe pas, il le crée.

    L’exemple suivant remplace le nom du bouton sur la page de « Configure » en « Register », le texte explicatif du bouton, et la taille de la boîte de dialogue qu’il ouvre. Il provoque également l’ouverture par le bouton d’une page d’inscription d’application personnalisée différente (la page d’inscription par défaut est newslwp.aspx).

    public override SPExternalApplicationRegistrationInformation GetRegistrationInformation(SPWeb web)
{
    SPExternalApplicationRegistrationInformation info = new SPExternalApplicationRegistrationInformation();
    info.Description = "To register a Silverlight application (.xap), click Register";
    info.DialogHeight = 600;
    info.DialogWidth = 500;
    string url = web.ServerRelativeUrl;
    if (!url.EndsWith("/"))
    {
        url = url + "/";
    }
    url += "_layouts/alternateReg.aspx";
    info.HyperlinkText = "Register";
    info.HyperlinkUrl = url;

    return info;
}

    Public Overrides Function GetRegistrationInformation(ByVal web As SPWeb) As SPExternalApplicationRegistrationInformation
    Dim info As New SPExternalApplicationRegistrationInformation()
    info.Description = "To register a Silverlight application (.xap), click Register"
    info.DialogHeight = 600
    info.DialogWidth = 500
    Dim url As String = web.ServerRelativeUrl
    If Not url.EndsWith("/") Then
        url = url & "/"
    End If
    url &= "_layouts/alternateReg.aspx"
    info.HyperlinkText = "Register"
    info.HyperlinkUrl = url

    Return info
End Function

  4. Si vous n’avez pas dérivé de classe de SPExternalApplicationRequestResult, vous pouvez implémenter OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties) pour retourner simplement null. Sinon, vous devez donner à cette méthode une implémentation conséquente pour construire et utiliser votre classe de résultats de requête.

    La méthode OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties) est appelée par la méthode CreateChildControls du composant WebPart. Spécifiquement, la méthode CreateChildControls effectue les opérations suivantes :

    1. Elle construit un objet SPExternalApplicationRequestProperties à partir du Code XML d’application externe qui a été utilisé pour enregistrer le composant WebPart, et à partir d’informations sur le site Web actuel.

    2. Elle passe un objet SPExternalApplicationRequestProperties à la méthode OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties).

    3. Elle reçoit un objet dérivé de SPExternalApplicationRequestResult qui est retourné par la méthode OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties).

    4. Elle utilise la méthode GetContentControl(String) de l’objet de résultats de requête pour obtenir l’unique contrôle enfant du composant WebPart.

    Figure 1: appels réalisés par la méthode CreateChildControls.

    Composant WebPart Silverlight CreateChildControls

    Si, pour une raison quelconque, la méthode OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties) retourne null, comme dans le fournisseur d’applications externes par défaut intégré dans SharePoint Foundation, la méthode CreateChildControls doit afficher un contrôle enfant par défaut. La méthode CreateChildControls() de la classe SilverlightWebPart intégrée procède ainsi.

    Ainsi, l’opération principale de votre implémentation de la méthode OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties) consiste à appeler le constructeur de votre classe dérivée de SPExternalApplicationRequestResult et à retourner l’objet construit. Voici quelques points à garder à l’esprit lors du développement de votre substitution de la méthode OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties) :

    Dans l’exemple suivant, la substitution de OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties) appelle le constructeur non défini par défaut d’une classe dérivée de SPExternalApplicationRequestResult et nommée CustomRequestResult. Pour en savoir plus sur ce constructeur non défini par défaut, voir la procédure Pour implémenter une classe de résultats de requête plus haut dans cet article.

    public override SPExternalApplicationRequestResult OnApplicationWebPartCreateChildControls(
            SPExternalApplicationRequestProperties args)
{
    SPExternalApplicationRequestResult reqRes = CustomRequestResult(args, saltFromApplication);
    return reqRes;
}

    Public Overrides Function OnApplicationWebPartCreateChildControls(ByVal args As SPExternalApplicationRequestProperties) As SPExternalApplicationRequestResult
        Dim reqRes As SPExternalApplicationRequestResult = CustomRequestResult(args, saltFromApplication)
        Return reqRes
End Function

Identification de votre fournisseur d’applications externes auprès du service Web

Le processus qui permet d’identifier votre fournisseur d’applications externes personnalisé auprès de SharePoint Foundation est pratiquement le même que celui pour activer un fournisseur d’applications externes, comme décrit dans Procédure : activer un fournisseur d’applications externes. La seule différence est qu’au lieu de simplement activer un fournisseur d’applications externes, vous construisez un objet du type de votre fournisseur d’applications externes, que vous affectez à la propriété ExternalApplicationSettings.Provider. Voici un exemple, où ContosoEAP est une classe dérivée de SPExternalApplicationProvider.

ContosoEAP exAppProvider = new ContosoEAP();
SPWebService.ContentService.ExternalApplicationSettings.Provider = exAppProvider;
SPWebService.ContentService.ExternalApplicationSettings.Enabled = true;
SPWebService.ContentService.Update(); 

Dim exAppProvider As New ContosoEAP()
SPWebService.ContentService.ExternalApplicationSettings.Provider = exAppProvider
SPWebService.ContentService.ExternalApplicationSettings.Enabled = True
SPWebService.ContentService.Update()
ConseilConseil

La ligne qui définit la propriété Enabled n’est pas nécessaire si la gestion des applications externes a déjà été activée pour le service Web, mais elle ne présente pas de risque. Si la gestion n’a pas déjà été activée, l’inclure rend inutile la procédure de la section Procédure : activer un fournisseur d’applications externes. Cependant, dans le cas contraire, même si le fournisseur d’applications externes par défaut est utilisé, le code d’activation de la gestion doit être exécuté.

Vous disposez de toutes les méthodes pour exécuter les lignes de code précédentes mentionnées dans Procédure : activer un fournisseur d’applications externes. L’exemple suivant montre comment exécuter le code avec l’applet de commande PowerShell Windows Add-Type dans un script d’interface de ligne de commande PowerShell.

Pour identifier votre fournisseur d’applications externes auprès du service Web

  1. Ajoutez le code suivant dans un fichier texte.

    Add-type @"
using System;
using Microsoft.SharePoint.Administration;

namespace ContosoCmdlets

    public class EAPIdentifier
    {
        public static void IdentifyEAP()
        {
            ContosoEAP exAppProvider = new ContosoEAP();
            SPWebService.ContentService.ExternalApplicationSettings.Provider = exAppProvider;
            SPWebService.ContentService.ExternalApplicationSettings.Enabled = true;
            SPWebService.ContentService.Update(); 
        }
    }
"@ -Language CsharpVersion3
[ContosoCmdlets.EAPIdentifier]::IdentifyEAP()

  2. Enregistrez le fichier en tant que EAPIdentify.ps.

  3. Exécutez le script dans une fenêtre Windows PowerShell.