Bereitstellen von SharePoint-Objekten mit dem Lösungspaket
Manchmal müssen Sie möglicherweise eine SharePoint-Liste oder Dokumentbibliothek zusammen mit Ihrem clientseitigen Lösungspaket bereitstellen, damit die Liste oder Bibliothek für Ihre clientseitigen Komponenten wie Webparts verfügbar ist. SharePoint-Framework Toolkette können Sie SharePoint-Elemente mit Ihrem clientseitigen Lösungspaket packen und bereitstellen. Diese Elemente werden dann bereitgestellt, wenn die clientseitige Lösung an einem Standort installiert wird.
Details zu den Bereitstellungsoptionen finden Sie auch in diesem SharePoint PnP-Webcast im YouTube-Kanal „Microsoft 365 Platform Communtiy Patterns & Practices (PnP)“:
Bereitstellen von Elementen mithilfe von JavaScript-Code
Es ist zwar möglich, SharePoint-Elemente mithilfe von JavaScript-Code in Ihrer Komponente zu erstellen, z. B. Webparts, aber es ist auf den Kontext des aktuellen Benutzers beschränkt, der diese Komponente verwendet. Wenn der Benutzer nicht über ausreichende Berechtigungen zum Erstellen oder Ändern von SharePoint-Elementen verfügt, stellt der JavaScript-Code diese Elemente nicht bereit. In solchen Fällen müssen Sie die Elemente zusammen mit Ihrem Lösungspaket packen und bereitstellen, wenn Sie SharePoint-Elemente in einem Kontext mit erhöhten Rechten bereitstellen möchten.
Bereitstellen von SharePoint-Elementen in Ihrer Lösung
Die folgenden SharePoint-Ressourcen können zusammen mit Ihrem clientseitigen Lösungspaket bereitgestellt werden:
- Felder
- Inhaltstypen
- Listeninstanzen
- Listeninstanzen mit benutzerdefiniertem Schema
Felder
Ein Feld oder eine Websitespalte stellt ein Attribut oder einen Teil von Metadaten dar, die der Benutzer für die Elemente in der Liste oder dem Inhaltstyp verwalten möchte, zu dem er die Spalte hinzugefügt hat. Es handelt sich um eine wiederverwendbare Spaltendefinition oder Vorlage, die Sie mehreren Listen auf mehreren SharePoint-Websites zuweisen können. Mit Websitespalten können Sie Überarbeitungen verringern und die Konsistenz der Metadaten zwischen Websites und Listen sicherstellen.
Angenommen, Sie definieren beispielsweise eine Website namens "Customer". Benutzer können diese Spalte ihren Listen hinzufügen und in ihren Inhaltstypen darauf verweisen. Dadurch wird sichergestellt, dass die Spalte – zumindest zu Beginn – dieselben Attribute aufweist, unabhängig davon, wo sie angezeigt wird.
Sie können in der Dokumentation Field-Element (Field) die Informationen über das Schema und die Attribute nachlesen, um ein neues Feld in Ihrer Lösung zu definieren.
Nachfolgend sehen Sie ein Beispiel für ein neues DateTime-Feld:
<Field ID="{1511BF28-A787-4061-B2E1-71F64CC93FD5}"
Name="DateOpened"
DisplayName="Date Opened"
Type="DateTime"
Format="DateOnly"
Required="FALSE"
Group="Financial Columns">
<Default>[today]</Default>
</Field>
Inhaltstypen
Ein Inhaltstyp ist eine wieder verwendbare Sammlung von Metadaten (Spalten), Verhaltensweisen und anderen Einstellungen für eine Kategorie von Elementen oder Dokumenten in einer SharePoint-Liste oder Dokumentbibliothek. Mit Inhaltstypen können Sie Einstellungen für eine Kategorie von Informationen auf zentrale und wiederverwendbare Weise verwalten.
Stellen Sie sich beispielsweise eine Geschäftssituation vor, in der Sie über drei verschiedene Arten von Dokumenten verfügen: Spesenabrechnungen, Bestellungen und Rechnungen. Alle drei Arten von Dokumenten haben einige Merkmale gemeinsam; zum einen handelt es sich um Finanzdokumente, die Daten mit Werten in Währungen enthalten. Jeder Dokumenttyp hat jedoch eigene Datenanforderungen, eine eigene Dokumentvorlage und einen eigenen Workflow.
Eine Lösung für dieses Geschäftsproblem besteht darin, vier Inhaltstypen zu erstellen. Der erste Inhaltstyp, Finanzdokument, könnte Datenanforderungen kapseln, die für alle Finanzdokumente in der Organisation gelten. Die verbleibenden drei Elemente , Spesenabrechnung, Bestellung und Rechnung, könnten gemeinsame Elemente vom Finanzdokument erben. Darüber hinaus können sie Merkmale definieren, die für jeden Typ eindeutig sind, z. B. einen bestimmten Satz von Metadaten, eine Dokumentvorlage, die beim Erstellen eines neuen Elements verwendet werden soll, und einen bestimmten Workflow für die Verarbeitung eines Elements.
Sie können in der Dokumentation ContentType-Element (ContentType) die Informationen über das Schema und die Attribute nachlesen, um einen neuen Inhaltstyp in Ihrer Lösung zu definieren.
Nachfolgend sehen Sie ein Beispiel für einen Inhaltstyp:
<ContentType ID="0x010042D0C1C200A14B6887742B6344675C8B"
Name="Cost Center"
Group="Financial Content Types"
Description="Financial Content Type">
<FieldRefs>
<FieldRef ID="{1511BF28-A787-4061-B2E1-71F64CC93FD5}" />
<FieldRef ID="{060E50AC-E9C1-4D3C-B1F9-DE0BCAC300F6}" />
</FieldRefs>
</ContentType>
Listeninstanzen
Listen sind ein wichtiges, zugrunde liegendes Feature einer SharePoint-Website. Team können damit Informationen sammeln, nachverfolgen und freigeben. Viele Clientanwendungen basieren auf Listen, die in der Website zur Datenspeicherung erstellt wurden, um ihre Verhaltensweisen zu implementieren. Eine Listeninstanz ist eine vordefinierte SharePoint-Liste, die einen bekannten Bezeichner aufweist. Sie können Elemente anpassen und zu diesen Listen hinzufügen, zusätzliche Listen aus den bereits verfügbaren Listenvorlagen erstellen und benutzerdefinierte Listen mit den ausgewählten Einstellungen und Spalten erstellen.
SharePoint bietet mehrere Listenvorlagen wie Kontaktliste, Kalender, Aufgabenliste und vieles mehr. Sie können diese Vorlagen verwenden, um neue Listeninstanzen für Ihre Webparts oder andere Komponenten zu erstellen. Beispielsweise können Sie eine Listeninstanz Finance Documents basierend auf der Dokumentbibliotheksvorlage definieren, um zugeordnete Dokumente mit Ihrem Webpart zu speichern.
Sie können in der Dokumentation ListInstance-Element (List Instance) die Informationen über das Schema und die Attribute nachlesen, um eine neue Listeninstanz in Ihrer Lösung zu definieren.
Es folgt ein Beispiel für eine Listeninstanzdefinition:
<ListInstance
FeatureId="00bfea71-e717-4e80-aa17-d0c71b360101"
Title="Finance Records"
Description="Finance documents"
TemplateType="101"
Url="Lists/FinanceRecords">
</ListInstance>
Listeninstanzen mit benutzerdefiniertem Schema
Sie können eine benutzerdefinierte Listenschemadefinition verwenden, um Ihre Felder, Inhaltstypen und Ansichten zu definieren, die in Ihrer Listeninstanz verwendet werden. Sie verwenden das CustomSchema-Attribut im ListInstance-Element, um auf ein benutzerdefiniertes Schema für die Listeninstanz zu verweisen.
Sie können beispielsweise die Listeninstanz Finanzdokumente mit dem Inhaltstyp Finanzdokument definieren, der die Datenanforderungen kapseln könnte, die alle Finanzdokumente in der Organisation gemeinsam haben.
Nachfolgend sehen Sie ein Beispiel einer Listeninstanzdefinition, die ein benutzerdefiniertes Schema verwendet:
<ListInstance
CustomSchema="schema.xml"
FeatureId="00bfea71-de22-43b2-a848-c05709900100"
Title="Cost Centers"
Description="Cost Centers"
TemplateType="100"
Url="Lists/CostCenters">
</ListInstance>
Dies ist die benutzerdefinierte Schemadefinition, die einen Inhaltstyp für die zuvor definierte Listeninstanz definiert:
<List xmlns:ows="Microsoft SharePoint" Title="Basic List" EnableContentTypes="TRUE" FolderCreation="FALSE" Direction="$Resources:Direction;" Url="Lists/Basic List" BaseType="0" xmlns="http://schemas.microsoft.com/sharepoint/">
<MetaData>
<ContentTypes>
<ContentTypeRef ID="0x010042D0C1C200A14B6887742B6344675C8B" />
</ContentTypes>
<Fields></Fields>
<Views>
<View BaseViewID="1" Type="HTML" WebPartZoneID="Main" DisplayName="$Resources:core,objectiv_schema_mwsidcamlidC24;" DefaultView="TRUE" MobileView="TRUE" MobileDefaultView="TRUE" SetupPath="pages\viewpage.aspx" ImageUrl="/_layouts/images/generic.png" Url="AllItems.aspx">
<XslLink Default="TRUE">main.xsl</XslLink>
<JSLink>clienttemplates.js</JSLink>
<RowLimit Paged="TRUE">30</RowLimit>
<Toolbar Type="Standard" />
<ViewFields>
<FieldRef Name="LinkTitle"></FieldRef>
<FieldRef Name="SPFxAmount"></FieldRef>
<FieldRef Name="SPFxCostCenter"></FieldRef>
</ViewFields>
<Query>
<OrderBy>
<FieldRef Name="ID" />
</OrderBy>
</Query>
</View>
</Views>
<Forms>
<Form Type="DisplayForm" Url="DispForm.aspx" SetupPath="pages\form.aspx" WebPartZoneID="Main" />
<Form Type="EditForm" Url="EditForm.aspx" SetupPath="pages\form.aspx" WebPartZoneID="Main" />
<Form Type="NewForm" Url="NewForm.aspx" SetupPath="pages\form.aspx" WebPartZoneID="Main" />
</Forms>
</MetaData>
</List>
Erstellen von SharePoint-Elementen in Ihrer Lösung
Das Lösungspaket verwendet SharePoint-Features zum Verpacken und Bereitstellen der SharePoint-Elemente. Ein Feature ist ein Container, der ein oder mehrere bereitzustellende SharePoint-Elemente enthält. Ein Feature enthält eine Feature.xml-Datei und mindestens eine Elementmanifestdatei. Diese XML-Dateien werden auch als Featuredefinitionen bezeichnet.
Ein clientseitiges Lösungspaket enthält in der Regel ein Feature. Dieses Feature wird aktiviert, wenn die Lösung auf einem Standort installiert ist. Es ist wichtig zu beachten, dass die Websiteadministratoren Ihr Lösungspaket und nicht das Feature installieren.
Ein Feature wird in erster Linie mithilfe der folgenden XML-Dateien erstellt:
Elementmanifestdatei
Die Elementmanifestdatei enthält die SharePoint-Elementdefinitionen und wird ausgeführt, wenn das Feature aktiviert wird. Beispielsweise befinden sich die XML-Definitionen zum Erstellen eines neuen Felds, Inhaltstyps oder einer Listeninstanz im Elementmanifest.
Nachfolgend finden Sie in Beispiel einer Elementmanifestdatei, die ein neues DateTime-Feld definiert.
<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<Field ID="{1511BF28-A787-4061-B2E1-71F64CC93FD5}"
Name="DateOpened"
DisplayName="Date Opened"
Type="DateTime"
Format="DateOnly"
Required="FALSE"
Group="Financial Columns">
<Default>[today]</Default>
</Field>
</Elements>
Elementdatei
Alle unterstützten Dateien, die das Elementmanifest begleiten, sind Elementdateien. Das Listeninstanzschema ist beispielsweise eine Elementdatei, die einer Listeninstanz zugeordnet ist, die in einem Elementmanifest definiert ist.
Nachfolgend sehen Sie ein Beispiel für ein benutzerdefiniertes Listeninstanzschema:
<List xmlns:ows="Microsoft SharePoint" Title="Basic List" EnableContentTypes="TRUE" FolderCreation="FALSE"
Direction="$Resources:Direction;" Url="Lists/Basic List" BaseType="0" xmlns="http://schemas.microsoft.com/sharepoint/">
<MetaData>
<ContentTypes>
<ContentTypeRef ID="0x010042D0C1C200A14B6887742B6344675C8B" />
</ContentTypes>
</MetaData>
</List>
Upgradeaktionendatei
Wie der Name schon sagt, ist dies die Datei, die alle Upgradeaktionen enthält, wenn die Lösung auf der Website aktualisiert wird. Als Teil der Upgradeaktionen könnte die Aktion angeben, dass auch ein oder mehrere Elementmanifeste eingeschlossen werden. Wenn für das Upgrade beispielsweise ein neues Feld hinzugefügt werden muss, ist die Felddefinition als Elementmanifest verfügbar und in der Upgradeaktionendatei zugeordnet.
Nachfolgend sehen Sie ein Beispiel für eine Datei mit Upgradeaktionen, die eine Elementmanifestdatei während des Upgrades anwendet:
<ApplyElementManifests>
<ElementManifest Location="9c0be970-a4d7-41bb-be21-4a683586db18\elements-v2.xml" />
</ApplyElementManifests>
Konfigurieren des SharePoint-Features
Um die XML-Dateien einzuschließen, müssen Sie zunächst die Featurekonfiguration in der Konfigurationsdatei package-solution.json im Ordner config in Ihrem Projekt definieren. Package-solution.json enthält die wichtigsten Metadateninformationen zu Ihrem clientseitigen Lösungspaket und wird referenziert, wenn Sie den gulp-Task ausführen, der package-solution Ihre Projektmappe in eine Datei packt.sppkg.
{
"solution": {
"name": "hello-world-client-side-solution",
"id": "26364618-3056-4b45-98c1-39450adc5723",
"version": "1.1.0.0",
"features": [{
"title": "hello-world-client-side-solution",
"description": "hello-world-client-side-solution",
"id": "d46cd9d6-87fc-473b-a4c0-db9ad9162b64",
"version": "1.1.0.0",
"assets": {
"elementManifests": [
"elements.xml"
],
"elementFiles":[
"schema.xml"
],
"upgradeActions":[
"upgrade-actions-v1.xml"
]
}
}]
},
"paths": {
"zippedPackage": "solution/hello-world.sppkg"
}
}
Das features-JSON-Objekt enthält die Metadaten über das Feature, wie in der folgenden Tabelle gezeigt.
| Eigenschaft | Beschreibung |
|---|---|
| id | Eindeutiger Bezeichner (GUID) des Features |
| title | Der Titel des Features |
| description | Beschreibung des Features |
| assets | Ein Array von XML-Dateien, die in dem Feature verwendet werden |
| elementManifests | Ein Array von Elementmanifestdateien, definiert in der assets-Eigenschaft |
| elementFiles | Ein Array von Elementdateien, definiert in der assets-Eigenschaft |
| upgradeActions | Ein Array von Upgradeaktionsdateien, definiert in der assets-Eigenschaft |
Erstellen der Feature-XML-Dateien
Die Toolkette sucht in Ihrem clientseitigen Lösungsprojekt nach den XML-Dateien, wie in der Konfiguration unter einem bestimmten Ordner definiert – sharepoint\assets.
Durch die in der package-solution.json definierten Konfigurationen werden die XML-Dateien hier ihrer entsprechenden Feature-XML-Datei zugeordnet, wenn der gulp-Task in package-solution ausgeführt wird.
Verpacken von SharePoint-Elementen
Nachdem Sie Ihr Feature in der package-solution.json definiert und die entsprechenden Feature-XML-Dateien erstellt haben, können Sie den folgenden gulp-Task verwenden, um die SharePoint-Elemente zusammen mit Ihrem .sppkg-Paket zu verpacken.
gulp package-solution
Dieser Befehl verpackt eine oder mehrere clientseitige Komponentenmanifeste, z. B. Webparts, zusammen mit den Feature-XML-Dateien, auf die in der package-solution.json-Konfigurationsdatei verwiesen wird.
Hinweis
Sie können das --ship-Flag verwenden, um minimierte Versionen Ihrer Komponenten zu verpacken.
Aktualisieren von SharePoint-Elementen
Sie können neue SharePoint-Elemente einschließen oder vorhandene SharePoint-Elemente aktualisieren, wenn Sie Ihre clientseitige Lösung aktualisieren. Da bei der Bereitstellung von SharePoint-Elementen Features verwendet werden, verwenden Sie die XML-Datei upgradeActions , um eine Liste der Upgradeaktionen zu definieren.
Das upgradeActions-JSON-Objektarray in der package-solution.json verweist auf die Feature-XML-Dateien, die den Upgradeaktionen für Ihr Feature zugeordnet sind. Zumindest definiert eine Upgradeaktionsdatei die XML-Datei des Elementmanifests, die beim Upgrade des Features ausgeführt wird.
Wenn Sie ein Upgrade für eine SharePoint-Framework-Lösung durchführen, müssen Sie auch die Versionsattribute für die Lösung und das Feature aktualisieren, in dem die Upgradeaktionen enthalten sind. Eine Erhöhung der Lösungsversion zeigt sharePoint-Endbenutzern an, dass eine neue Version des Pakets verfügbar ist. Eine Erhöhung der Featureelementversion stellt sicher, dass die in den Upgradeaktionen definierten Aufgaben im Rahmen des Lösungsupgrades verarbeitet werden.
Nachfolgend sehen Sie ein Beispiel für eine Datei mit Upgradeaktionen, die eine Elementmanifestdatei während des Upgrades anwendet:
<ApplyElementManifests>
<ElementManifest Location="9c0be970-a4d7-41bb-be21-4a683586db18\elements-v2.xml" />
</ApplyElementManifests>
Dies ist die entsprechende element-v2.xml, die ein neues Währungsfeld definiert, das während des Upgrades definiert wird:
<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<Field ID="{060E50AC-E9C1-4D3C-B1F9-DE0BCAC300F6}"
Name="Amount"
DisplayName="Amount"
Type="Currency"
Decimals="2"
Min="0"
Required="FALSE"
Group="Financial Columns" />
</Elements>
Unterelemente
Upgradeaktionen in clientseitigen Lösungen unterstützen die folgenden Unterelemente:
AddContentTypeField
Fügt ein neues Feld zu einem vorhandenen bereitgestellten Inhaltstyp hinzu. Gibt die Änderung des Websiteinhaltstyps an alle untergeordneten Listen und Inhaltstypen innerhalb der Website weiter. Beispiel:
<AddContentTypeField
ContentTypeId="0x010100A6F9CE1AFE2A48f0A3E6CB5BB770B0F7"
FieldId="{B250DCFD-9310-4e2d-85F2-BE2DA37A57D2}"
PushDown="TRUE" />
ApplyElementManifests
Fügt einem vorhandenen Feature ein neues Element hinzu. Wenn ein Feature aktualisiert wird, stellt alle nicht deklarativen Elemente bereit, auf die in den angegebenen Elementmanifesten verwiesen wird.
VersionRange
Gibt einen Versionsbereich an, auf den die angegebenen Upgradeaktionen angewendet werden.