Mandantenweite Bereitstellung von SharePoint-Framework-Erweiterungen

Die Option für die mandantenweite Bereitstellung für SharePoint-Framework (SPFx)-Erweiterungen wird für Anwendungsanpasser und für Listenansichts-Befehlsgruppen unterstützt. Dies bietet Verwaltern des App-Katalogs im Mandanten eine einfache Möglichkeit, Erweiterungen zu verwalten, die standardmäßig mandantenübergreifend aktiviert oder basierend auf Web-/Listenvorlagen, die in den Websites verwendet werden.

Hinweis

SharePoint-Framework-Erweiterungen werden bei modernen Oberflächen unabhängig von der tatsächlich verwendeten Websitevorlage bei der Erstellung der Inhaltswebsite unterstützt.

Wenn Entwickler eine neue Lösung für SharePoint-Framework-Erweiterungen mithilfe der standardmäßigen Yeoman-Pakete von SharePoint-Framework erstellen, ist die Automatisierung in das Lösungspaket integriert, um die Erweiterung mandantenübergreifend zu aktivieren.

Warnung

Beginnend mit SharePoint-Framework v1. 6 werden durch standardmäßiges Erstellen von Gerüsten Beispieldateien in der SharePoint-Lösung erstellt, um Erweiterungen im Mandanten zu aktivieren, wenn Sie sich entscheiden, die Option für die mandantenweite Bereitstellung zu verwenden.

Die SharePoint Framework-Lösung muss so konfiguriert werden, dass die Option Mandantenweite Lösungsbereitstellung für SharePoint-Framework-Lösungen verwendet wird, damit Erweiterungen mithilfe der Funktion zur mandantenweiten Bereitstellung über den Mandanten hinweg automatisch aktiviert werden können. Dies bedeutet, dass das skipFeatureDeployment-Attribut in der package-solution.json auf true festgelegt werden muss.

Steuerung der mandantenweiten Bereitstellung über die Websitesammlung des App-Katalogs

Die Websitesammlung des App-Katalogs wird zum Bereitstellen von SharePoint-Add-Ins und SharePoint Framework-Komponenten auf dem Mandanten verwendet. Diese Websitesammlung wird vom Mandantenadministrator erstellt und wird verwendet, um zu verwalten, welche Anpassungen für Endbenutzer in tatsächlichen Inhaltswebsitesammlungen verfügbar sind.

Die Websitesammlung des App-Katalogs enthält eine Liste für mandantenweite Erweiterungen, die verwendet werden kann, um Aktivierungen von SharePoint Framework-Erweiterungen im Mandanten zu verwalten. Auf diese Liste kann über die Seite Websiteinhalte der App-Katalogwebsite zugegriffen werden.

Bestimmte SharePoint Framework-Erweiterungen können auf Mandantenebene aktiviert werden, indem Einträge zur Liste der mandantenweiten Erweiterungen hinzugefügt werden. Jeder Eintrag kann je nach den funktionalen Anforderungen auf bestimmte Webvorlagen oder einen Listentyp abzielen.

Diese listenspezifischen Konfigurationen werden zur Laufzeit aufgelöst, wenn Endbenutzer auf Seiten in Inhaltswebsitesammlungen zugreifen. Dies bedeutet, dass die auf diese Liste angewendeten Änderungen sowohl für vorhandene als auch für neue Websites im Mandanten verfügbar sind.

SharePoint-Framework-Lösungen können eine Automatisierung enthalten, die beim Hinzufügen der Lösung automatisch einen Eintrag in der mandantenweiten Erweiterungsliste generiert.

Wichtig

Es kann bis zu 20 Minuten dauern, bis die Funktionen aktiviert werden, nachdem der erste Eintrag zur Liste der mandantenweiten Erweiterungen auf einem bestimmten Mandanten hinzugefügt wurde.

Beschreibung der Liste der mandantenweiten Bereitstellung

Die Komponenten-ID muss im Mandanten vorhanden sein, damit ein Eintrag hinzugefügt werden kann.

Spalte	Typ	Beschreibung
Titel	Zeichenfolge	Der Titel des Eintrags. Kann eine Beschreibung für die Registrierung sein.
Komponenten-ID	Guid	Manifest-ID der Komponente. Muss im GUID-Format vorliegen, und die Komponente muss im App-Katalog vorhanden sein.
Komponenteneigenschaften	Zeichenfolge	Optionale Komponenteneigenschaften.
Webvorlage	Zeichenfolge	Kann verwendet werden, um die Erweiterung nur auf bestimmte Webvorlagen abzuzielen. In der folgenden Tabelle finden Sie mögliche Werte.
Listenvorlage	int	Listentyp als Zahl. In der folgenden Tabelle finden Sie mögliche Werte.
Ort	Zeichenfolge	Ort des Eintrags. Es gibt unterschiedliche Supportstandorte für Anwendungsanpasser und Listenansichts-Befehlsgruppen.
Sequence	int	Reihenfolge des Eintrags beim Rendern.
Host-Eigenschaften	Zeichenfolge	Zusätzliche serverseitige Konfiguration, wie z. B. die vorab zugewiesene Höhe von Platzhaltern.
Deaktiviert	Boolesch	Gibt an, ob der Eintrag aktiviert oder deaktiviert ist.

Für die Webvorlagenspalte wird technisch jede Webvorlagendefinition unterstützt. In der folgenden Tabelle sind die am häufigsten verwendeten Vorlagen definiert.

Vorlage	Webvorlagen-ID
Gruppenzugeordnete Teamwebsite	GROUP#0
Kommunikationswebsite	SITEPAGEPUBLISHING#0
Moderne Teamwebsite ohne Gruppe	STS#3
Klassische Teamwebsite	STS#0
Klassische Veröffentlichungswebsite	BLANKINTERNET#0

Für die Listenvorlagenspalte wird technisch jede Listen-ID unterstützt, jedoch werden moderne Umgebungen nur von einer Untergruppe der klassischen Listentypen unterstützt.

Liste	Listen-ID
Benutzerdefinierte Liste	100
Dokumentbibliothek	101

Nachfolgend finden Sie unterstützte Ortswerte. Diese sind für den Komponententyp spezifisch.

Wert	Komponententyp	Beschreibung
ClientSideExtension.ApplicationCustomizer	Application Customizer	Erforderlich für den Anwendungsanpasser.
ClientSideExtension.ListViewCommandSet.ContextMenu	ListView-Befehlssatz	Schaltflächen für die Listenansicht im Kontextmenü für Elemente in einer Liste anzeigen.
ClientSideExtension.ListViewCommandSet.CommandBar	ListView-Befehlssatz	Schaltflächen für die Listenansicht in der Befehlsleiste der Liste anzeigen.
ClientSideExtension.ListViewCommandSet	ListView-Befehlssatz	Schaltflächen für die Listenansicht sowohl im Kontextmenü als auch in der Befehlsleiste anzeigen.

Hinweis

Aus technischer Sicht definiert diese Liste die dynamischen Einträge, die automatisch der Web- oder Listensammlung „UserCustomAction“ hinzugefügt werden, wenn eine Seite von einer Website gerendert wird. Listeninformationen werden zwischengespeichert und ihre Inhalte werden als Teil der Seite, die zur Laufzeit gerendert wird, ausgegeben.

Automatisierung der mandantenweite Bereitstellung über das Lösungspaket

Der SharePoint-Framework-Generator fügt die Datei ./sharepoint/assets/ClientSideInstance.xml zur neuen Lösung hinzu, wenn der initial ausgewählte Komponententyp eine Erweiterung ist.

ClientSideInstance.xml wird bei der Lösungsaktivierung im App-Katalog berücksichtigt, wenn das skipFeatureDeployment-Attribut in der Datei package-solution.json auf Wahr festgelegt ist.

Diese Datei enthält standardmäßig die folgende Struktur. Das ClientSideComponentInstance-Element weist Microsoft Office SharePoint Online an, automatisch einen Eintrag zur Liste der mandantenweiten Bereitstellung hinzuzufügen, wenn das Lösungspaket dem App-Katalog hinzugefügt wird.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <ClientSideComponentInstance
      Title="MyAppCust"
      Location="ClientSideExtension.ApplicationCustomizer"
      ComponentId="917a86f2-15c1-403e-bbe1-59c6bd50d1e1"
      Properties="{&quot;testMessage&quot;:&quot;Test message&quot;}">
  </ClientSideComponentInstance>
</Elements>

Wenn Sie beim Erstellen der SharePoint-Framework Projektmappe nur SharePoint Online (neueste) als Zielumgebung ausgewählt haben, wird auch in package-solution.json auf die ClientSideInstance.xml-Datei verwiesen, sodass sie in der *.sppkg-Datei enthalten ist, wenn Sie Ihre Projektmappe packen.

Wichtig

Wenn Sie eine andere Zielumgebung ausgewählt haben, während die Datei ClientSideInstance.xml zum Projekt hinzugefügt wird, wird sie nicht in der Datei package-solution.json enthalten sein. Während der SharePoint Server 2019 (welcher das SharePoint-Framework v1.4 enthält, siehe Unterstützte Funktionen für Details) eine auf den Mandanten ausgerichtete Bereitstellung unterstützt, unterstützt es keine mandantenweite Bereitstellung (hinzugefügt in SharePoint Framework v1.6, siehe Mandantenweite Bereitstellung von Erweiterungen für Details).

Wenn in package-solution.json auf diese Datei verwiesen wird, löst das Hochladen der generierten *.sppkg-Datei in den SharePoint Server 2019 Mandanten-App-Katalog eine Ausnahme aus.

Hinweis

Wenn Sie nicht möchten, dass diese Datei in der Datei *.sppkg vorhanden ist, können Sie sie einfach aus dem Paketprozess entfernen, indem Sie die Datei package-solution.json aktualisieren.

Das ClientSideComponentInstance-Element unterstützt die folgenden Attribute.

Attribut	Erforderlich	Beschreibung
Title	Ja	Der Titel des Eintrags. Kann eine Beschreibung für die Registrierung sein.
Location	Ja	Ortseintrag für die Erweiterungsregistrierung
ComponentId	Ja	Manifest-ID der Komponente.
Properties	Ja	Optionale Eigenschaften für die Komponente. Beachten Sie, dass dies auf der XML-Ebene ein obligatorisches Attribut ist, das als leere Zeichenfolge festgelegt werden kann, wenn keine Eigenschaften erforderlich sind. Der Wert muss auch korrekt codiert werden, damit die Eigenschaftenwerte im XML-Format angegeben werden können.
ListTemplateId	Nein	Optionale Typ-ID der Listenvorlage, für die die Erweiterung aktiviert werden soll.
WebTemplateId	Nein	Optionale die Webvorlagen-ID, um den Websitetyp zu definieren, an dem die Erweiterung aktiviert werden soll.
Sequence	Nein	Optionale Aktivierungsreihenfolge Reihenfolge für die Erweiterungen. Wird verwendet, wenn mehrere Erweiterungen in demselben Bereich aktiviert werden.
HostProperties	Nein	Optionale serverseitige Konfigurationen, wie z. B. das Festlegen einer vorab zugewiesenen Höhe von Platzhaltern.

Unter der XML-Definition wird angezeigt, wie die optionalen Werte im Rahmen der Registrierung verwendet werden können.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <ClientSideComponentInstance
      Title="MyAppCust"
      Location="ClientSideExtension.ApplicationCustomizer"
      ComponentId="917a86f2-15c1-403e-bbe1-59c6bd50d1e1"
      Properties="{&quot;testMessage&quot;:&quot;Test message&quot;}"
      ListTemplateId="100"
      WebTemplateId="GROUP#0"
      Sequence="10"
      HostProperties="{&quot;preAllocatedApplicationCustomizerTopHeight&quot;:&quot;50&quot;,&quot;preAllocatedApplicationCustomizerBottomHeight&quot;:&quot;50&quot;}">
  </ClientSideComponentInstance>
</Elements>

Wenn ein Administrator dem App-Katalog eine Lösung hinzufügt, die eine ClientSideInstance.xml-Datei enthält, wird eine bestimmte Warnmeldung angezeigt, um sicherzustellen, dass die automatisierte Konfiguration bekannt ist.

Nach der Bereitstellung der Lösung kann ein Administrator die Bereitstellungseinstellungen über die Liste der mandantenweiten Erweiterung ändern.