Freigeben über

Durchsuchen der App Manifestdatei-Struktur und des Pakets eines SharePoint-Add-Ins

  • Artikel

Paketstruktur von SharePoint-Add-Ins

Ein SharePoint-Add-In-Paket ist eine Datei mit der Erweiterung „APP“, die dem Standard Open Packaging Conventions (OPC) entspricht. Das Paket umfasst die folgenden Elemente:

  • Add-in-Manifest: Dies ist eine erforderliche Datei, die „appmanifest.xml“ benannt ist. Sie teilt SharePoint wichtige Eigenschaften des Add-Ins mit, z. B. Titel und erforderliche Berechtigungen. Weitere Informationen zum Inhalt dieser Datei finden Sie unter Manifestdatei für Add-In für SharePoint.

  • SharePoint-Lösungspakete: Das Add-In enthält optional ein SharePoint-Lösungspaket (WSP-Datei), das die Komponenten des Add-In-Web enthält. Diese Komponenten können Seiten, Listeninstanzen, Ansichten, Dokumente, Funktionen mit Webgültigkeitsbereich und andere SharePoint-Komponenten sein. (Weitere Informationen dazu, welche SharePoint-Komponenten in einem SharePoint-Add-In enthalten sein können, finden Sie unter Typen von SharePoint-Komponenten, die in einem SharePoint-Add-In enthalten sein können.) Die WSP-Datei kann auch Office-Add-Ins enthalten. Die Komponenten in der WSP-Datei werden im Add-In-Web bereitgestellt. Ein Beispiel für ein Add-In-Paket, das ein SharePoint-Lösungspaket enthält, finden Sie unter Erstellen eines von einem Anbieter gehosteten Add-In, das eine benutzerdefinierte SharePoint-Liste und einen benutzerdefinierten Inhaltstyp enthält.

  • Hostwebfeatures mit benutzerdefinierten Aktionen oder Add-In-Teilen: Neben den SharePoint-Komponenten, die im Add-In-Web bereitgestellt werden, kann ein SharePoint-Add-In auch eine oder mehrere benutzerdefinierte Aktionen (Kontextmenüelemente oder Menübanderweiterungen) im Hostweb bereitstellen. Hierzu wird ein Feature in das Add-In-Paket eingefügt, das nicht in der WSP-Datei des Pakets enthalten ist und das die Komponenten bereitstellt, die für das Hostweb vorgesehen sind. Dieses „freie“ Feature wird als Hostwebfeature bezeichnet.

    Add-In-Parts werden auf die gleiche Weise im Hostweb bereitgestellt. Das Hostwebfeature besteht aus einer Standardmäßigen SharePoint-feature.xml-Datei und einer oder mehreren zugeordneten elements.xml-Dateien. Die "elements.xml"-Datei für eine benutzerdefinierte Aktion enthält beispielsweise das CustomAction-Markup für die benutzerdefinierte Aktion. Es kann auch Markup für Add-In-Parts enthalten. Nur diese beiden Arten von Komponenten können im Hostwebfeature enthalten sein. Diese Hostwebfeatures werden im Add-In-Manifest nicht aufgeführt. Es handelt sich jedoch im Sinn von OPC um "parts", und es besteht eine explizite OPC-Beziehung zwischen dem Add-In-Manifest und jeder dieser Dateien. Ein Beispiel für ein Add-In-Paket, das ein Hostwebfeature enthält, finden Sie unter Erstellen benutzerdefinierter Aktionen zum Bereitstellen mit SharePoint-Add-Ins.

    Hinweis

    Mandantenadministratoren haben die Möglichkeit, ein SharePoint-Add-In per Batch auf mehreren Websites zu installieren. Ein Add-In, das auf diese Weise installiert wurde, besitzt einen Mandantenbereich. Wenn das Add-in nicht per Batch installiert wurde, sondern auf jeder Website separat installiert wird, besitzt es einen Webbereich. Wenn das Hostwebfeature Menübanderweiterungen oder Add-In-Teile enthält, werden diese nicht in den Hostwebs bereitgestellt, wenn das Add-In per Batch installiert wird, sodass nur Kontextmenüelemente mit Add-Ins mit Mandantenbereich bereitgestellt werden.

    Der Add-In-Bereich sollte nicht mit dem Featurebereich verwechselt werden. Der Featurebereich bestimmt, wo die Elemente in einem Feature bereitgestellt werden. Die Optionen beinhalten Farm, WebApplication, Site (d.h. Websitesammlung) und Web. Für Features in SharePoint-Add-Ins (sowohl Hostwebfeatures als auch Features innerhalb einer WSP-Datei in einem Add-In-Paket) ist nur Web zulässig.

    Mit Add-In-Bereich ist der Bereich gemeint, in dem ein Add-In installiert wird. Mögliche Optionen sind Web, wobei in diesem Fall das Add-In auf einer oder mehreren Websites separat installiert wurde, und Mandant, wobei in diesem Fall das Add-In per Batch auf allen oder auf einer Reihe von Websites in einem Kundenmandanten installiert wurde.

    Weitere Informationen zum Mandantenbereich und Webbbereich finden Sie unter Mandantschaften und Bereitstellungsbereiche von SharePoint-Add-Ins.

  • Lokalisierungsressourcendateien (.resx): Diese Dateien sind für die Lokalisierung verschiedener Aspekte des Add-In-Manifests vorgesehen, zu denen der Titel und Aspekte der Hostwebfeatures im Add-In-Paket gehören. (Einzelne Teile des Add-In-Pakets, die sich in einem eigenen Paket befinden, wie WSP-Dateien, Azure-Websites-Pakete und Add-In-Manifeste, verfügen jeweils über eigene Lokalisierungsprozesse, die genauso ausgeführt werden wie bei Elementen, die nicht Teil eines SharePoint-Add-In sind.) Ein Beispiel zu einem Add-In-Paket, das die RESX-Dateien für ein Hostwebfeature enthält, finden Sie unter Lokalisieren von Add-Ins für SharePoint.

  • Office-Add-In-Manifeste: Optional können ein oder mehrere Office-Add-Ins Manifeste vorhanden sein, in dem jeweils ein Office-Add-In gebündelt ist. Dies kann nur im Add-In-Paket enthalten sein, wenn das Add-In in einem Share-Point-Unternehmens-Add-In-Katalog hochgeladen wird, und nicht im öffentlichen Marketplace. Weitere Informationen finden Sie unter Veröffentlichen von SharePoint-Add-Ins.

Manifestdatei von SharePoint-Add-Ins

Jedes SharePoint-Add-In enthält eine appmanifest.xml-Datei. Mit der Datei "appmanifest.xml" werden SharePoint die erforderlichen Informationen zum Add-In mitgeteilt und die wichtigsten Eigenschaften des Add-Ins definiert. Nachfolgend werden einige Elemente aufgeführt, die im Manifest angegeben werden:

  • Der interne Name, die Produkt-ID und die Version des Add-Ins.

  • Die URL der Startseite, bei der es sich um die Seite handelt, die beim Starten des Add-Ins geöffnet wird. Dies kann eine Seite im Add-In-Web, eine cloudbasierte Seite oder eine Seite auf einem Webserver des ISV sein.

    Hinweis

    Unter bestimmten Umständen gibt es möglicherweise Einschränkungen hinsichtlich Dateityp, der im StartPage-Element angegeben werden kann. Weitere Informationen finden Sie unter StartPage-Element (PropertiesDefinition complexType) (SharePoint-Add-In-Manifest). Wenn Sie mehrere Abfrageparameter im StartPage-Wert kombinieren, müssen Sie diese Parameter durch Angabe des Codes für das kaufmännische Und-Zeichen & statt & oder eines Semikolons aneinanderreihen.

  • Andere Eigenschaften des Add-Ins. Hierzu gehören der Titel und die Gebietsschemas, die von dem Add-In unterstützt werden (beides erforderlich), die URLs der Dienste, welche die Ereignisse "post-install", "post-upgrade" und "pre-uninstall" behandeln, sowie die Webvorlage, die zum Erstellen des Add-In-Webs verwendet werden soll.

  • Anforderungen von Berechtigungen zum Zugriff auf SharePoint-Ressourcen außerhalb des Add-In-Webs.

  • Eine zu Authentifizierungs- und Autorisierungszwecken zu verwendende Identifikation des Add-In-Prinzipals. Diesem Prinzipal werden die Berechtigungen gewährt. Bei einem in SharePoint gehosteten Add-In ist dies nicht erforderlich.

  • Eine Liste der für das Add-In erforderlichen Komponenten, sofern vorhanden, damit das Add-In installiert werden kann. Möglicherweise müssen zum Beispiel bestimmte Features installiert und aktiviert sein, und bestimmte Dienste müssen installiert und lizenziert werden.

Hinweis

Lediglich die Add-In-Manifestdatei ist im Add-In-Paket erforderlich. Nicht alle oben genannten Elemente müssen in dieser Datei vorhanden sein.

Detaillierte Informationen über das Add-In-Manifestmarkup finden Sie unter Schemareferenz Manifeste der SharePoint-Add-ins. Dieses Thema stellt keinen Ersatz für die dort enthaltenen Informationen, einschließlich Informationen über die erforderlichen Elemente und Attribute. Beachten Sie außerdem, dass SharePoint-Add-In-Manifeste über ein anderes Schema als Office-Add-In-Manifeste verfügen. Informationen über die letztgenannten finden Se unter Schemareferenz für Office-Add-In-Manifeste (v1.1).

Nachfolgend finden Sie ein Beispiel für die Datei „appmanifest.xml“. Beachten Sie, dass in diesem Beispiel die Startseite für das Add-In eine ASP.NET-Seite auf einem Remoteserver ist, und nicht eine Seite auf der SharePoint-Website. Die URL für die Seite enthält eine Abfragezeichenfolge, die die URL des Hostweb an die Remotewebanwendung übergibt. Der {HostUrl}-Teil der Zeichenfolge ist ein Token, das aufgelöst werden kann, wenn das Add-In gestartet wird. Das Add-In fordert eine Schreibberechtigung für alle Listen in dem Hostweb an. Der Add-In-Prinzipal, dem diese Berechtigung gewährt werden muss, ist die Remotewebanwendung.

Sie müssen entweder das SupportedLocales- oder das SupportedLanguages-Element in Ihrem Add-In-Manifest verwenden. SupportedLanguages ist veraltet. Stattdessen wird nun SupportedLocales verwendet. Das SupportedLanguages-Element funktioniert auch nach Veröffentlichung weiterhin, die Verwendung wird jedoch nicht empfohlen. Weitere Informationen über diese Elemente finden Sie unter SupportedLocales-Element (PropertiesDefinition complexType) (SharePoint-Add-In-Manifest) und SupportedLanguages-Element (PropertiesDefinition complexType) (SharePoint-Add-In-Manifest) .

Hinweis

Die Werte des Scope-Attributs im AppPermissionRequest-Element sind wie URLs strukturiert, sie stellen jedoch Literalzeichenfolgen dar. Bei keinem Teil des Scope-Werts im folgenden Beispiel handelt es sich um einen Platzhalter. Weitere Informationen über Berechtigungen finden Sie unter Add-In-Berechtigungen in SharePoint.

<?xml version="1.0" encoding="utf-8" ?>
<App xmlns="http://schemas.microsoft.com/sharepoint/2012/app/manifest"
     ProductID="{4a07f3bd-803d-45f2-a710-b9e944c3396e}"
     Version="1.0.0.0"
     SharePointMinVersion="15.0.0.0"
     Name="MySampleApp"
>
  <Properties>
    <Title>My Sample App</Title>
    <StartPage>http://MyRemoteWebApplicationServer/default.aspx/?SPHostUrl={HostUrl}</StartPage>
    <SupportedLocales>
      <SupportedLocale CultureName="en-US" />
    </SupportedLocales>        
  </Properties>

  <AppPermissionRequests>
    <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web/list" Right="Write"/>
  </AppPermissionRequests>

  <AppPrincipal>
    <RemoteWebApplication ClientId="1ee82b34-7c1b-471b-b27e-ff272accd564" />
  </AppPrincipal>
</App>

URL-Token im Add-In-Manifest

SharePoint stellt mehrere Token bereit, die im StartPage-Element und an anderen Stellen in Add-Ins und Komponenten von Add-Ins verwendet werden können, um Informationen darzustellen, die erst bekannt sind, wenn das Add-In ausgeführt wird. Die SharePoint-Infrastruktur löst diese Token auf. Einige werden am Anfang der URL und andere innerhalb einer URL verwendet, z. B. Wert des Abfrageparameters. Diese und viele weitere Token können auch in einer Vielzahl von SharePoint-Entwicklungskontexten verwendet werden.

Ausführliche Informationen zu allen Token und deren Verwendung finden Sie unter URL-Zeichenfolgen und Token in SharePoint-Add-Ins. Allgemeine Informationen zu anderen Token und URLs in SharePoint finden Sie unter URLs und Token in SharePoint.

Hinweis

Diese Token werden nicht im Scope-Attribut des AppPermissionRequest-Elements verwendet.

Siehe auch