Erstellen von Add-In-Webparts zur Installation mit Ihrem SharePoint-Add-In

Mit Add-In-Webparts können Sie die Add-In-Benutzeroberfläche direkt auf den Seiten der SharePoint-Website anzeigen. Ein Add-In-Webpart zeigt die von Ihnen angegebene Webseite (normalerweise ein interaktives Formular oder eine dynamische Anzeige von Daten) mithilfe eines IFrame (der auch als Frame bezeichnet wird) auf einer Seite im Hostweb an.

Weitere Informationen zu Add-In-Webparts finden Sie in den folgenden Artikeln:

• Zugreifen auf das Add-In über die Benutzeroberfläche
• UX-Design für SharePoint-Add-Ins
• Erweitern der SharePoint-Benutzeroberfläche in Add-Ins

In der folgenden Abbildung wird gezeigt, wie der Inhalt des Add-In-Webparts auf einer SharePoint-Seite angezeigt wird.

Inhalt des Add-In-Webparts dargestellt auf einer SharePoint-Seite

Ein Add-In-Webpart wird mit der ClientWebPart-Klasse implementiert und ist (wie alle Webparts) im Webpartkatalog verfügbar, nachdem ein Benutzer das SharePoint-Add-In installiert hat, in dem es enthalten ist. Ihre Benutzer können das Add-In-Webpart weiter anpassen, indem Sie die von Ihnen bereitgestellten Eigenschaften verwenden. (Ein Beispiel für in einem Add-In-Webpart konfigurierbare Eigenschaften finden Sie in der Abbildung SharePoint-Seite, auf der ein Add-In-Basiswebpart gehostet wird weiter unten in diesem Artikel.)

Das Beispiel in diesem Artikel verwendet eine Webseite, die auf einem Remoteserver und nicht auf SharePoint gehostet wird, als Inhaltsseite. Beachten Sie, dass Sie auch SharePoint-Seiten verwenden können, um den Inhalt des Add-In-Webparts zu hosten, wie weiter unten in diesem Artikel im Abschnitt Andere häufige Add-In-Komponenten beschrieben.

Voraussetzungen für die Verwendung des Beispiels in diesem Artikel

Um die Schritte in diesem Beispiel auszuführen, benötigen Sie Folgendes:

• Visual Studio
• Microsoft Office-Entwicklertools für Visual Studio
• Eine SharePoint-Entwicklungsumgebung. Hilfe zum Einrichten einer Entwicklungsumgebung finden Sie unter Zwei Arten von SharePoint-Add-Ins: von SharePoint-gehostet und vom Anbieter gehostet.

Erstellen eines Add-In-Webparts zur Installation auf dem Hostweb

Es gibt mehrere Aufgaben, die erforderlich sind, um Ihr Add-In-Webpart zu erstellen und auf dem Hostweb zu installieren:

1. Erstellen Sie die SharePoint-Add-In- und Remotewebprojekte.
2. Hinzufügen eines Formulars für den Inhalt des Add-In-Webparts
3. Fügen Sie dem SharePoint-Add-In-Projekt das Add-In-Webpart hinzu.

Nach Abschluss der Aufgaben sollte das Add-In-Webpart wie in der folgenden Abbildung aussehen, wenn sich das Add-In-Webpart im Bearbeitungsmodus befindet. Hier sehen Sie (1) den Add-In-Inhalt, der auf einer SharePoint-Seite angezeigt wird, und (2) die benutzerdefinierten Eigenschaften des Add-Ins.

SharePoint-Seite als Host für ein Add-In-Basiswebpart

Hinzufügen eines Formulars für den Inhalt des Add-In-Webparts

1. Erstellen Sie ein vom Anbieter gehostetes Add-In, wie unter Erste Schritte beim Erstellen von von einem Anbieter gehosteten SharePoint-Add-Ins beschrieben, aber geben Sie dem Projekt den Namen TestAppPart.

2. Klicken Sie nach dem Erstellen der Visual Studio-Projektmappe mit der rechten Maustaste auf das Webanwendungsprojekt (nicht das SharePoint-Add-In-Projekt), und fügen Sie ein neues Webformular hinzu, indem Sie Hinzufügen>Neues Element>Web>Webformular auswählen. Nennen Sie das Formular AppPartContent.aspx.

3. Ersetzen Sie in der Datei „AppPartContent.aspx“ das gesamte HTML-Element und seine untergeordneten Elemente durch den folgenden HTML-Code. Lassen Sie das gesamte Markup so wie es ist über dem HTML-Element. Der HTML-Code enthält JavaScript, das die folgenden Aufgaben ausführt:

   • Extrahieren der Standardeigenschaftswerte aus der Abfragezeichenfolge
   • Rendern der Eigenschaftswerte

   Beachten Sie, dass der Code einige Parameter in der Abfragezeichenfolge erwartet. Das Add-In-Webpart stellt seine benutzerdefinierten Eigenschaften durch die Abfragezeichenfolge bereit, sodass die Webseite sie nutzen kann. In der nächsten Aufgabe wird erklärt, wie Sie benutzerdefinierte Eigenschaften festlegen und diese für die Add-In-Webseite verfügbar machen.

   <html>
       <body>
           <div id="content">
               <!-- Placeholders for properties -->
               String property: <span id="strProp"></span><br />
               Integer property: <span id="intProp"></span><br />
               Boolean property: <span id="boolProp"></span><br />
               Enumeration property: <span id="enumProp"></span><br />
           </div>
   
       <!-- Main JavaScript function, controls the rendering
           logic based on the custom property values -->
       <script lang="javascript">
           "use strict";
   
           var params = document.URL.split("?")[1].split("&amp;");
           var strProp;
           var intProp;
           var boolProp;
           var enumProp;
   
           // Extracts the property values from the query string.
           for (var i = 0; i < params.length; i = i + 1) {
               var param = params[i].split("=");
               if (param[0] == "strProp")
                   strProp = decodeURIComponent(param[1]);
               else if (param[0] == "intProp")
                   intProp = parseInt(param[1]);
               else if (param[0] == "boolProp")
                   boolProp = (param[1] == "true");
               else if (param[0] == "enumProp")
                   enumProp = decodeURIComponent(param[1]);
           }
   
           document.getElementById("strProp").innerText = strProp;
           document.getElementById("intProp").innerText = intProp;
           document.getElementById("boolProp").innerText = boolProp;
           document.getElementById("enumProp").innerText = enumProp;
       </script>
       </body>
   </html>
   

4. Speichern und schließen Sie die Datei.

Hinzufügen des Add-In-Webparts zum SharePoint-Add-In-Projekt

1. Klicken Sie mit der rechten Maustaste auf das SharePoint-Add-In-Projekt (nicht das Webanwendungsprojekt), und wählen Sie dann Hinzufügen>Neues Element>Office/SharePoint>Clientwebpart (Hostweb) aus. ("Clientwebpart" ist eine andere Bezeichnung für "Add-In-Webpart".)

2. Geben Sie dem Webpart den Namen Add-In-Basiswebpart.

3. Wählen Sie im Dialogfeld Clientwebpartseite angeben die Option URL für eine vorhandene Webseite auswählen oder anzeigen aus. Wählen Sie die Seite TestAppWebPart/AppPartContent.aspx in der Dropdownliste aus. (Nachdem Sie Ihre Auswahl getroffen haben, wird die Seiten-URL möglicherweise in dem Feld angezeigt, wobei „TestAppWebPart“ durch ~remoteAppUrl ersetzt und {StandardTokens} für die Abfrageparameter hinzugefügt wurde.)

4. Wählen Sie Fertig stellen aus.

5. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf Add-In-Basiswebpart, und wählen Sie Eigenschaften aus.

6. Wählen Sie im Bereich Eigenschaften die Option Benutzerdefinierte Eigenschaften aus, und klicken Sie dann auf die Popupschaltfläche ( ...).

7. Verwenden Sie das Dialogfeld Benutzerdefinierte Eigenschaften, um dem Add-In-Webpart vier benutzerdefinierte Eigenschaften hinzuzufügen. Sie müssen für jedes der vier benutzerdefinierten Eigenschaften fünf Attribute festlegen. Die Namen der Attribute und Werte sind in Tabelle 1 aufgeführt. Erstellen Sie die Eigenschaften mithilfe des folgenden Verfahrens.

   1. Klicken Sie auf Hinzufügen.

   2. Wählen Sie in der Attributliste das erste Attribut aus Tabelle 1 aus: DefaultValue.

   3. Legen Sie den Wert fest, z. B. Standardwert der Zeichenfolge.

   4. Wählen Sie das nächste Attribut, Name, aus, und legen Sie seinen Wert fest, z. B. strProp.

   5. Fahren Sie mit den Attributen Type, WebCategory und WebDisplayName fort.

   6. Wählen Sie erneut Hinzufügen aus, und wiederholen Sie den Vorgang für alle Zeilen in Tabelle 1. Schließen Sie das Dialogfeld nicht.

      Tabelle 1. Attribute für die benutzerdefinierten Eigenschaften des Add-In-Webparts

      DefaultValue	Name	Typ	WebCategory	WebDisplayName
      Standardwert für Zeichenfolge	strProp	string	Kategorie Add-In-Basiswebpart	Eine Eigenschaft vom Typ "string"
      0	intProp	int	Kategorie Add-In-Basiswebpart	Eine Eigenschaft vom Typ "integer"
      false	boolProp	boolean	Kategorie Add-In-Basiswebpart	Eine Eigenschaft vom Typ "boolean"
      1st	enumProp	enum	Kategorie Add-In-Basiswebpart	Eine Eigenschaft vom Typ "enumeration"

      An diesem Punkt sollte das Dialogfeld wie folgt aussehen:

      Dialogfeld „Benutzerdefinierte Eigenschaften" für Clientwebpart

      

8. Wählen Sie die Eigenschaft EnumProp, dann das Attribut EnumItems und schließlich die Popupschaltfläche ( ...) aus.

9. Verwenden Sie den ClientWebPartEnumItem-Auflistungs-Editor, um drei Elemente hinzuzufügen. Sie müssen für jedes der drei Elemente zwei Attribute festlegen. Die Namen der Attribute und Werte sind in Tabelle 1 aufgeführt. Erstellen Sie die Eigenschaften mithilfe des folgenden Verfahrens.

   1. Klicken Sie auf Hinzufügen.

   2. Wählen Sie in der Attributliste das erste Attribut aus Tabelle 2 aus: Value.

   3. Legen Sie den Wert des Attributs fest, z. B. 1..

   4. Wählen Sie das nächste Attribut, WebDisplayName, aus, und legen Sie seinen Wert fest, z. B. Erste Option.

   5. Wählen Sie erneut Hinzufügen aus, und wiederholen Sie den Vorgang für alle Zeilen in Tabelle 2.

      Tabelle 2. Enumerationselemente der enumProp-Eigenschaft

      Wert	WebDisplayName
      1st	Erste Option
      2nd	Zweite Option
      3rd	Dritte Option

      Das Dialogfeld sollte wie folgt aussehen, wenn Sie fertig sind:

      ClientWebPartEnumItem-Auflistungs-Editor

      

   6. Wählen Sie OK aus, um das Dialogfeld zu schließen, und wählen Sie dann erneut OK aus, um das Dialogfeld Benutzerdefinierte Eigenschaften zu schließen.

10. Visual Studio generiert den folgenden XML-Code in der Datei „elements.xml“ des Add-In-Webparts (aus Gründen der Übersichtlichkeit wurden Zeilenumbrüche hinzugefügt). Beachten Sie, dass das Title-Attribut im ClientWebPart-Element auf „Titel des Add-In-Basiswebparts“ und die Beschreibung auf „Beschreibung des Add-In-Basiswebparts“ festgelegt ist. Löschen Sie das Wort „Titel“ aus ersterem, und ersetzen Sie zweiteres durch ein Add-In-Basiswebpart.

<?xml version="1.0" encoding="UTF-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <ClientWebPart
        Name="Basic add-in part"
        Title="Basic add-in part Title"
        Description="Basic add-in part Description" >

        <!-- The properties are passed through the query string
                using the following notation: _propertyName_
                in the Src property of the Content element.
          -->
        <Content
            Src="~remoteAppUrl/AppPartContent.aspx?strProp=_strProp_&amp;amp;intProp=_intProp_&amp;amp;boolProp=_boolProp_&amp;amp;enumProp=_enumProp_"
            Type="html"/>
        <Properties>
            <Property
                Name="strProp"
                Type="string"
                RequiresDesignerPermission="true"
                DefaultValue="String default value"
                WebCategory="Basic add-in part category"
                WebDisplayName="A property of type string.">
            </Property>
            <Property
                Name="intProp"
                Type="int"
                RequiresDesignerPermission="true"
                DefaultValue="0"
                WebCategory="Basic add-in part category"
                WebDisplayName="A property of type integer.">
            </Property>
            <Property
                Name="boolProp"
                Type="boolean"
                RequiresDesignerPermission="true"
                DefaultValue="false"
                WebCategory="Basic add-in part category"
                WebDisplayName="A property of type boolean.">
            </Property>
            <Property
                Name="enumProp"
                Type="enum"
                RequiresDesignerPermission="true"
                DefaultValue="1st"
                WebCategory="Basic add-in part category"
                WebDisplayName="A property of type enum.">
                <EnumItems>
                    <EnumItem WebDisplayName="First option" Value="1st"/>
                    <EnumItem WebDisplayName="Second option" Value="2nd"/>
                    <EnumItem WebDisplayName="Third option" Value="3rd"/>
                </EnumItems>
            </Property>
        </Properties>
    </ClientWebPart>
</Elements>

Festlegen der Add-In-Startseite auf die Hostweb-Startseite

1. Das fortlaufende Beispiel-SharePoint-Add-In verfügt nicht über ein Add-In-Web, und die Remotewebanwendung ist nur für das Hosten des Formulars vorhanden. Es gibt keine umfassende ganzseitige Oberfläche für dieses Add-In. Deshalb sollte die Startseite des Add-Ins auf die Startseite des Hostwebs festgelegt werden.

   Wählen Sie zunächst das SharePoint-Add-In-Projekt (nicht das Webanwendungsprojekt) in Projektmappen-Explorer aus, und kopieren Sie den Wert der Website-URL-Eigenschaft einschließlich des Protokolls (z. Bhttps://contoso.sharepoint.com. ) in die Zwischenablage.

2. Öffnen Sie das Add-In-Manifest, und fügen Sie die URL in das Feld Startseite ein.

3. Optional können Sie die Seite „Default.aspx“ aus dem Webanwendungsprojekt löschen, da sie nicht im SharePoint-Add-In verwendet wird.

Erstellen und Testen der Lösung

1. Wählen Sie die F5-Taste.

   Hinweis

   Wenn Sie F5 wählen, erstellt Visual Studio die Lösung, installiert das Add-In und öffnet die Berechtigungsseite für das Add-In.

2. Wählen Sie die Schaltfläche Vertrauen.

3. Fügen Sie das Add-In-Basiswebpart aus dem Add-In-Webpartkatalog hinzu. Ausführliche Anweisungen finden Sie unter Hinzufügen eines Add-In-Webparts zu einer Seite.

   Wenn das Add-In auf dem Hostweb installiert ist, ist das Add-In-Basiswebpart im Add-In-Webpartkatalog verfügbar. Es sollte weitestgehend wie in der folgenden Abbildung aussehen.

   Add-In-Webpart im Webpartkatalog

   

4. Nachdem Sie das Add-In-Webpart hinzugefügt haben, wählen Sie die Pfeilspitze nach unten rechts neben dem Titel Add-In-Basiswebpart und dann Webpart bearbeiten aus.

   Das Add-In-Webpart sollte im Bearbeitungsmodus angezeigt werden.

5. Öffnen Sie Add-In-Basiswebpartkategorie, und ändern Sie einige der Eigenschaftswerte.

6. Klicken Sie auf OK, um Ihre Änderungen zu speichern, und stellen Sie sicher, dass die Eigenschaften im Add-In-Webpart geändert wurden.

7. Wenn Sie die Debugsitzung beenden und für eine Weile nicht mehr F5 bei diesem Projekt verwenden, sollten Sie das SharePoint-Add-In ein letztes Mal zurückziehen, um sicherzustellen, dass das Test-Add-In-Webpart von Ihrer Startseite entfernt wird. Klicken Sie mit der rechten Maustaste auf das SharePoint-Add-In-Projekt, und wählen Sie Zurückziehen aus.

Problembehandlung für die Lösung

Andere gängige Szenarien mit Add-In-Webparts

In diesem Artikel wurde gezeigt, wie Sie ein Add-In-Basiswebpart mit benutzerdefinierten Eigenschaften mit einer Remotewebseite als Inhaltsseite erstellen. Darüber hinaus können Sie auch die folgenden Szenarien und Details zu Add-In-Webparts erkunden.

Verwenden einer SharePoint-Seite als Inhaltsseite

In den meisten Fällen kann eine Webseite nicht in einem Frame angezeigt werden, wenn der HTTP-Header X-Frame-Options in der Antwort gesendet wird. SharePoint-Seiten enthalten standardmäßig die Kopfzeile X-Frame-Options. Wenn Sie eine im Add-In-Web gehostete SharePoint-Webseite verwenden, tritt möglicherweise der folgende Fehler auf (in der folgenden Abbildung dargestellt): Dieser Inhalt kann nicht in einem Frame angezeigt werden..

Add-In-Webpart, dessen Inhalt nicht in einem Frame angezeigt werden kann

Beachten Sie, dass bestimmte Szenarien anfällig für ClickJacking-Angriffe sind, wenn die Webseiten in einem Frame angezeigt werden. Beurteilen Sie die Szenarien Ihres Add-In-Webparts sorgfältig, um sicherzustellen, dass kein Risiko von ClickJacking-Angriffen besteht.

Wenn Ihre im Add-In-Web gehostete Seite nicht anfällig für ClickJacking-Angriffe ist, können Sie das Webpart AllowFraming verwenden, um den Header X-Frame-Options aus der Antwort Ihrer Seite zu unterdrücken. Das folgende Codebeispiel zeigt, wie das Webpart AllowFraming auf einer SharePoint-Seite verwendet wird. Kopieren Sie dieses Markup auf die Seite, die im Add-In-Web gehostet wird. Platzieren Sie es direkt über das erste asp:content-Element auf der Seite. Es sollten kein untergeordnetes Element eines beliebigen anderen Elements sein.

<WebPartPages:AllowFraming ID="AllowFraming1" runat="server" />

Sie können das Codebeispiel für ein Add-In-Webpart Anzeigen von Add-In-Webinhalten im Hostweb mithilfe eines Add-In-Webparts herunterladen, das zeigt, wie Sie eine SharePoint-Seite als Inhaltsseite verwenden.

Ändern der Größe des Add-In-Webparts

Wenn Sie in Ihrem Add-In-Webpart dynamische Inhalte verwenden, ändern sich möglicherweise Breite und Höhe des Inhalts. Der Inhalt passt dann aufgrund seiner dynamischen Größe nicht mehr in den Frame. Möglicherweise wird auch zu viel Platz verbraucht. Bei Verwendung dynamischer Inhalte ist es schwierig, eine feste Größe in der Deklaration des Add-In-Webparts anzugeben. Sie können allerdings die Größe des Frames an die Breite und Höhe des Inhalts anpassen.

Sie können POST-Nachrichten aus Ihrer Inhaltswebseite verwenden, um die Framegröße anzugeben. Im folgenden JavaScript-Beispiel wird gezeigt, wie Sie eine POST-Nachricht senden, um die Größe des Frames zu ändern, in dem Ihr Add-In-Webpart gehostet wird. In der Regel würde dies in einer JavaScript-Methode in einer JavaScript-Datei erfolgen, die Sie von der Seite aufrufen. Die Seite könnte z. B. ein Steuerelement aufweisen, in dem der Benutzer die Größe des Add-In-Webpartfensters angibt. Die benutzerdefinierte Methode wird dann aus dem onchange-Handler des Steuerelements abgerufen.

Ein vollständiges Beispiel für ein Add-In-Webpart, dessen Größe automatisch geändert wird, finden Sie unter Codebeispiel: Dynamisches Anpassen der Größe von Add-In-Webparts in SharePoint-Add-Ins.

window.parent.postMessage("<message senderId={SenderId}>resize(120, 300)</message>", {hostweburl});

Im Beispiel oben wird der senderId-Wert in der Abfragezeichenfolge der Seite automatisch vom Add-In-Webpartcode festgelegt, wenn die Seite gerendert wird. Die Seite müsste lediglich zum den SenderId-Wert aus der Abfragezeichenfolge lesen und diese verwenden, wenn das Ändern der Größe angefordert wird. Sie können die Hostweb-URL aus der Abfragezeichenfolge abrufen, indem Sie die Token StandardTokens oder HostUrl an das Src-Attribut in der Add-In-Webpartdefinition anfügen.

Verwenden des SharePoint-Stylesheets in Ihrem Add-In-Webpart-Inhalt

Da das Add-In-Webpart in einer SharePoint-Seite gehostet wird, möchten Sie vielleicht, dass der Add-In-Webpartinhalt so aussieht, als wäre er Teil der Seite. Eine Möglichkeit, ein einheitliches Aussehen und Verhalten zu erzielen, besteht darin, dieselben Formatvorlagenklassen wie die SharePoint-Seite zu verwenden, die das Add-In-Webpart hostet. Sie können das Stylesheet der SharePoint-Website für das Add-In-Webpart verfügbar machen, indem Sie einen Verweis zu der Datei defaultcss.ashx aus dem Add-In-Web hinzufügen.

Eine Erläuterung zum Verweisen auf die Datei defaultcss.ashx in Ihren SharePoint-Add-Ins finden Sie unter Verwenden des Stylesheets einer SharePoint-Website in SharePoint-Add-Ins.

Um ein Add-In-Webpart zu sehen, das auf das Stylesheet verweist, laden Sie das Codebeispiel: Anzeigen des Inhalts einer Remotewebseite mit dem Coffeemaker-Add-In-Webpart herunter.

Erkennen, wenn sich das Add-In-Webpart im Bearbeitungsmodus befindet

Benutzer können das Add-In-Webpart bearbeiten, um seine Eigenschaften zu ändern. Ein Benutzer möchte vielleicht eine der Eigenschaften Darstellung oder Layout des Add-In-Webparts ändern. Wenn sich das Add-In im Bearbeitungsmodus befindet, möchten Sie vielleicht die Renderinglogik ändern oder verhindern, dass unnötige Änderungen vorgenommen werden. Denken Sie beispielsweise an ein Add-In-Webpart, das eine Back-End-Datenbank aufruft, wenn die Hostseite geladen wird. Durch Ändern des Eigenschaftenwerts eines Add-In-Webparts im Bearbeitungsmodus wird das erneute Laden einer Seite verursacht, aber vielleicht möchten Sie in diesem Fall nicht, dass der Netzwerkaufruf ausgelöst wird. Sie können das editMode-Token verwenden, um zu ermitteln, ob Benutzer Ihr Add-In-Webpart bearbeiten.

Um das editMode -Token zu verwenden, fügen Sie in der Add-In-Webpart-Deklaration eine Abfragezeichenfolge an das Src-Attribut des Content-Elements an.

<Content Src="content_page_url&amp;amp;editmode=_editMode_">

Über das editMode-Token kann die Inhaltsseite bestimmen, ob sich das Add-In-Webpart im Bearbeitungsmodus befindet. Wenn sich das Add-In-Webpart im Bearbeitungsmodus befindet, wird das editMode-Token zu 1 ausgewertet, andernfalls zu 0.

Siehe auch

• Codebeispiel: Anzeigen von Remote-Add-In-Inhalten im Hostweb mit einem Add-In-Webpart
• Erstellen von UX-Komponenten in SharePoint