Gewusst wie: Erstellen eines benutzerdefinierten externen Anwendungsanbieters

Dieses Thema enthält eine Übersicht über den Prozess beim Erstellen eines benutzerdefinierten externen Anwendungsanbieters (External Application Provider, EAP).

Letzte Änderung: Donnerstag, 8. April 2010

Gilt für: SharePoint Foundation 2010

Beim Erstellen eines benutzerdefinierten EAP müssen Sie aus einer oder beiden dieser zwei abstrakten Klassen neue Klassen ableiten:

• SPExternalApplicationRequestResult Es gibt zwei Szenarien, in denen Sie eine von SPExternalApplicationRequestResult abgeleitete Klasse implementieren:

  • Die Website und die Anforderungsweiterleitung, für die die externe Anwendung installiert ist, erfordern, dass alle von Microsoft SharePoint Foundation empfangenen Ergebnisse einen Clienthash enthalten, der von der Anforderungsweiterleitung überprüft werden kann. Damit soll sichergestellt werden, dass das Ergebnis nicht manipuliert wurde.

  • Sie möchten ändern, auf welche Weise das SilverlightWebPart oder ein benutzerdefiniertes Webpart, in dem eine nicht zu SharePoint gehörende Anwendung gehostet wird, gerendert wird; beispielsweise möchten Sie um das Webpart herum benutzerdefiniertes Chrom rendern.

• SPExternalApplicationProvider Sie müssen diese Klasse in einem der folgenden Szenarien implementieren:

  • Eine Situation, in der Sie eine von der SPExternalApplicationRequestResult-Klasse abgeleitete Klasse implementieren (siehe oben).

  • Das Externes Anwendungs-XML für das Webpart enthält benutzerdefiniertes Markup, das gelesen und verarbeitet werden muss.

  • Sie möchten, dass eine spezielle Logik ausgeführt wird, wenn das untergeordnete Steuerelement des Webparts erstellt wird.

  • Sie möchten die Benutzeroberfläche von SilverlightToolPart anpassen oder die Anwendungsregistrierungsseite ändern, die durch Klicken auf die Schaltfläche Konfigurieren des Toolparts geöffnet wird.

Wichtig
Berücksichtigen Sie bei der Entscheidung über die Erstellung eines benutzerdefinierten EAP, dass es für alle Webparts für Anwendungshosting in allen SharePoint Foundation-Webanwendungen, die einem angegebenen Webdienst untergeordnet sind, nur einen EAP geben kann.

So implementieren Sie eine Anforderungsergebnisklasse

1. Starten Sie in Microsoft Visual Studio 2010 ein leeres SharePoint-Projekt.

2. Fügen Sie dem Projekt ein Klassenelement hinzu.

3. Legen Sie fest, dass die Klasse von SPExternalApplicationRequestResult erbt.

4. Wenn Sie keinen Clienthash verwenden möchten, implementieren Sie die ClientHash-Eigenschaft, um null zurückzugeben. Wenn Sie einen Clienthash in die an die externe Anwendung zurückgesendeten Ergebnisse einschließen möchten, implementieren Sie die ClientHash-Eigenschaft als Wrapper für ein privates Sicherungsfeld, das einem Byte-Array entspricht.

   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. Wenn Sie einen Clienthash verwenden, erstellen Sie einen Konstruktor, für den ein Parameter vom Typ SPExternalApplicationRequestProperties verwendet werden kann sowie ein zweiter Parameter, bei dem es sich um ein Bytearray handelt (das die Clientsalt darstellt). Für diesen Konstruktor sollten die RequestTokenPrefix-Eigenschaft des SPExternalApplicationRequestProperties-Objekts und das Bytearray als Eingabe beim Erstellen eines Clienthashwerts verwendet werden. Das Bytearray muss einem Wert entsprechen, der von dem Server bereitgestellt wird, auf dem die externe Anwendung gehostet wird. Der verwendete Algorithmus muss dem entsprechen, der von der externen Anwendung verwendet wird, um die eigene Kopie des Clienthash zu erstellen. Ziehen Sie die Verwendung der Klassen des System.Security.Cryptography-Namespace in Betracht, beispielsweise HashAlgorithm oder SHA512Managed. Der folgende Code ist ein Beispiel dafür. Wenn Sie wie im Beispiel die SHA512Managed-Klasse verwenden möchten, müssen Sie der Codedatei eine using-Anweisung (Imports in Visual Basic) für den System.Security.Cryptography-Namespace hinzufügen.

   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
   

   Wenn von der abgeleiteten Klasse als einziger Teil der SPExternalApplicationRequestProperties-Klasse die RequestTokenPrefix-Eigenschaft verwendet wird, können Sie den Konstruktor so schreiben, dass das String-Objekt als erster Parameter verwendet wird und dann vom Aufrufcode (die im folgenden Verfahren beschriebene OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties)-Methode) einfach die RequestTokenPrefix-Eigenschaft übergeben wird. Alternativ können Sie den Aufrufcode so entwerfen, dass der Clienthash erstellt wird, bevor ein Objekt vom abgeleiteten Typ erstellt wird. In diesem Fall kann der Konstruktor des Typs so entworfen werden, dass der Hashwert selbst als Bytearrayparameter verwendet und unmittelbar in das clientHash-Sicherungsfeld geschrieben wird.

6. Wenn Sie nicht anpassen möchte, wie das Silverlight-Webpart gerendert wird oder wie ein benutzerdefiniertes Webpart, in dem eine nicht zu SharePoint gehörende Anwendung gehostet wird, gerendert wird, implementieren Sie die GetContentControl(String)-Methode, um null zurückzugeben. Wenn Sie jedoch anpassen möchten, wie das Webpart gerendert wird, implementieren Sie die Methode, um ein Control zurückzugeben, bei dem es sich um das einzige untergeordnete Steuerelement des Webparts handelt. Normalerweise handelt es sich dabei um ein Literal, das HTML-Markup enthält.

So implementieren Sie eine EAP-Klasse

1. Fügen Sie dem Projekt ein Klassenelement hinzu.

2. Legen Sie fest, dass die Klasse von SPExternalApplicationProvider erbt.

3. Wenn Sie die Benutzeroberfläche von SilverlightToolPart anpassen möchten, implementieren Sie die GetRegistrationInformation(SPWeb)-Methode. Sie können alle fünf Eigenschaften des von der Methode zurückgegebenen SPExternalApplicationRegistrationInformation-Objekts ändern. Wenn Sie beispielsweise eine benutzerdefinierte Registrierungsseite ersetzen möchten, weisen Sie die URL der benutzerdefinierten Seite der HyperlinkUrl-Eigenschaft zu. Sie können Inlinecode oder Code hinter der benutzerdefinierten Seite verwenden, um weitere Dienste für Benutzer bereitzustellen. Der Code kann beispielsweise das Anwendungs-XML lesen und ermitteln, ob ein Anwendungsprinzipalname angegeben ist. Wenn dies der Fall ist, überprüft der Code, ob der Anwendungsprinzipalbenutzer vorhanden ist. Anderenfalls wird dieser erstellt.

   Im folgenden Beispiel wird der Name der Schaltfläche auf der Seite von Configure in Register geändert. Außerdem wird der Anweisungstext für die Schaltfläche und die Größe des geöffneten Dialogfelds geändert. Darüber hinaus wird über die Schaltfläche eine benutzerdefinierte alternative Anwendungsregistrierungsseite geöffnet. (Die Standardregistrierungsseite ist 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. Wenn Sie nicht eine Klasse von SPExternalApplicationRequestResult abgeleitet haben, können Sie OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties) implementieren, um einfach null zurückzugeben. Anderenfalls müssen Sie diese Methode umfassend implementieren, damit die Anforderungsergebnisklasse erstellt und verwendet wird.

   Die OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties)-Methode wird durch die CreateChildControls-Methode des Webparts aufgerufen. Konkret bewirkt die CreateChildControls-Methode Folgendes:

   1. Erstellt ein SPExternalApplicationRequestProperties-Objekt aus dem Externes Anwendungs-XML, das zum Registrieren des Webparts verwendet wurde, und aus Informationen zur aktuellen Website.

   2. Übergibt ein SPExternalApplicationRequestProperties-Objekt an die OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties)-Methode.

   3. Empfängt ein von SPExternalApplicationRequestResult abgeleitetes Objekt, das von der OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties)-Methode zurückgegeben wird.

   4. Verwendet die GetContentControl(String)-Methode des Anforderungsergebnisobjekts, um das einzige untergeordnete Steuerelement des Webparts abzurufen.

   Abbildung 1: Aufrufe durch die "CreateChildControls"-Methode.

   

   Wenn aus irgendeinem Grund durch die OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties)-Methode null zurückgegeben wird (wie beim in SharePoint Foundation integrierten Standard-EAP), muss durch die CreateChildControls-Methode ein standardmäßiges untergeordnetes Steuerelement gerendert werden Dazu wird die CreateChildControls()-Methode der integrierten SilverlightWebPart-Klasse verwendet.

   Daher besteht die primäre Aufgabe Ihrer Implementierung der OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties)-Methode darin, den Konstruktor der von SPExternalApplicationRequestResult abgeleiteten Klasse aufzurufen und das erstellte Objekt zurückzugeben. Die folgenden Punkte sollten Sie beim Entwickeln der Außerkraftsetzung der OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties)-Methode berücksichtigen:

   • Wenn das von SPExternalApplicationRequestResult abgeleitete Objekt eine ClientHash-Eigenschaft ungleich null hat, sollte von OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties) der nicht standardmäßige Konstruktor aufgerufen werden, den Sie für die von SPExternalApplicationRequestResult abgeleitete Klasse erstellt haben. Diesem Konstruktor sollte von OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties) das gleiche SPExternalApplicationRequestProperties-Objekt übergeben werden, das beim Aufruf als Parameter empfangen wurde.

   • Auch wenn die Anforderungsergebnisklasse keine umfassende Implementierung von ClientHash ermöglicht (und daher nur über einen Standardkonstruktor verfügt), müssen Sie für die CreateChildControls-Methode des Webparts ein SPExternalApplicationRequestResult-Objekt festlegen, damit die GetContentControl(String)-Methode aufgerufen werden kann. Aus diesem Grund müssen Sie die OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties)-Methode implementieren, wenn Sie eine Klasse von SPExternalApplicationRequestResult abgeleitet haben.

   • Eine Implementierung der OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties)-Methode eignet sich auch für andere Aufgaben, beispielsweise zum Lesen benutzerdefinierter Eigenschaften in Externes Anwendungs-XML.

   Im folgenden Beispiel wird durch das außer Kraft gesetzte OnApplicationWebPartCreateChildControls(SPExternalApplicationRequestProperties) der nicht standardmäßige Konstruktor der von SPExternalApplicationRequestResult abgeleiteten CustomRequestResult-Klasse aufgerufen. Weitere Informationen zu diesem nicht standardmäßigen Konstruktor finden Sie weiter oben in diesem Artikel unter So implementieren Sie eine Ergebnisanforderungsklasse.

   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
   

Identifizieren des EAP gegenüber dem Webdienst

Der Prozess für die Identifizierung des benutzerdefinierten EAP gegenüber dem SharePoint Foundation ist praktisch identisch mit dem Prozess für die Aktivierung eines EAP, der unter Gewusst wie: Aktivieren eines externen Anwendungsanbieters beschrieben wurde. Der einzige Unterschied besteht darin, dass Sie nicht einfach einen EAP aktivieren, sondern ein Objekt vom EAP-Typ erstellen und dieses der ExternalApplicationSettings.Provider-Eigenschaft zuweisen. Im folgenden Beispiel handelt es sich bei ContosoEAP um eine Klasse, die von SPExternalApplicationProvider abgeleitet wurde.

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()

Tipp

Die Zeile zum Festlegen der Enabled-Eigenschaft wird nicht benötigt, wirkt sich aber auch nicht nachteilig aus, wenn die externe Anwendungsverwaltung für den Webdienst bereits aktiviert ist. Wenn die Verwaltung noch nicht aktiviert ist und Sie die Zeile einschließen, entfällt das Verfahren unter Gewusst wie: Aktivieren eines externen Anwendungsanbieters. Das Gegenteil trifft jedoch nicht zu: Auch wenn der Standard-EAP verwendet wird, muss der Code zum Aktivieren der Verwaltung ausgeführt werden.

Zum Ausführen der vorstehenden Codezeilen stehen Ihnen alle Methoden zur Verfügung, die unter Gewusst wie: Aktivieren eines externen Anwendungsanbieters genannt wurden. Im folgenden Beispiel wird das Ausführen des Codes mit dem Windows PowerShell-Cmdlet Add-Type in einem Windows PowerShell-Skript für die Befehlszeilenschnittstelle gezeigt.

So identifizieren Sie den EAP gegenüber dem Webdienst

1. Fügen Sie den folgenden Code einer Textdatei hinzu.

   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. Speichern Sie die Datei als EAPIdentify.ps.

3. Führen Sie das Skript in einem Windows PowerShell-Fenster aus.