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:
- Erstellen Sie die SharePoint-Add-In- und Remotewebprojekte.
- Hinzufügen eines Formulars für den Inhalt des Add-In-Webparts
- 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
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.
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.
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("&"); 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>Speichern und schließen Sie die Datei.
Hinzufügen des Add-In-Webparts zum SharePoint-Add-In-Projekt
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".)
Geben Sie dem Webpart den Namen Add-In-Basiswebpart.
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.)
Wählen Sie Fertig stellen aus.
Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf Add-In-Basiswebpart, und wählen Sie Eigenschaften aus.
Wählen Sie im Bereich Eigenschaften die Option Benutzerdefinierte Eigenschaften aus, und klicken Sie dann auf die Popupschaltfläche ( ...).
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.
Klicken Sie auf Hinzufügen.
Wählen Sie in der Attributliste das erste Attribut aus Tabelle 1 aus: DefaultValue.
Legen Sie den Wert fest, z. B. Standardwert der Zeichenfolge.
Wählen Sie das nächste Attribut, Name, aus, und legen Sie seinen Wert fest, z. B. strProp.
Fahren Sie mit den Attributen Type, WebCategory und WebDisplayName fort.
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
Wählen Sie die Eigenschaft EnumProp, dann das Attribut EnumItems und schließlich die Popupschaltfläche ( ...) aus.
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.
Klicken Sie auf Hinzufügen.
Wählen Sie in der Attributliste das erste Attribut aus Tabelle 2 aus: Value.
Legen Sie den Wert des Attributs fest, z. B. 1..
Wählen Sie das nächste Attribut, WebDisplayName, aus, und legen Sie seinen Wert fest, z. B. Erste Option.
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
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.
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;intProp=_intProp_&amp;boolProp=_boolProp_&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
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.
Öffnen Sie das Add-In-Manifest, und fügen Sie die URL in das Feld Startseite ein.
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
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.
Wählen Sie die Schaltfläche Vertrauen.
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
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.
Öffnen Sie Add-In-Basiswebpartkategorie, und ändern Sie einige der Eigenschaftswerte.
Klicken Sie auf OK, um Ihre Änderungen zu speichern, und stellen Sie sicher, dass die Eigenschaften im Add-In-Webpart geändert wurden.
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
| Problem | Lösung |
|---|---|
| Das Add-In-Webpart zeigt keinen Inhalt an. Das Add-In-Webpart zeigt folgenden Fehler an: Die Navigation zu der Webseite wurde abgebrochen. Dieser Fehler tritt auf, weil der Browser die Inhaltsseite gesperrt hat. | Aktivieren Sie gemischte Inhalte. Das Verfahren ist möglicherweise je nach verwendetem Browser unterschiedlich: In Internet Explorer 9 und 10 wird unten auf der Seite die folgende Meldung angezeigt: Nur sicherer Inhalt wird angezeigt. Wählen Sie Gesamten Inhalt anzeigen, um den Inhalt des Add-In-Webparts anzuzeigen. Internet Explorer 8 zeigt ein Dialogfeld mit der folgenden Meldung an: Möchten Sie nur den Inhalt der Webseite anzeigen, der sicher übermittelt wurde? Wählen Sie Nein aus, um den Inhalt des Add-In-Webparts anzuzeigen. Alternativ können Sie gemischte Inhalte für die Internetzone aktivieren, an der Sie arbeiten. Für die meisten Entwickler ist die Internetzone Lokales Intranet. Ist dies bei Ihnen nicht der Fall, ersetzen Sie Lokales Intranet durch die Internetzone, an der Sie arbeiten. Klicken Sie im Internet Explorer auf Extras>Internetoptionen. Wählen Sie im Dialogfeld Internetoptionen auf der Registerkarte SicherheitLokales Intranet aus und klicken Sie anschließend auf die Schaltfläche Stufe anpassen. Aktivieren Sie im Dialogfeld Sicherheitseinstellungen im Abschnitt Verschiedenes die Option Gemischte Inhalte anzeigen. |
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;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.