Présentation du moteur d’approvisionnement PnP
Cet article présente le moteur d’approvisionnement PnP, publié à l’origine en avril 2015 au sein du projet OfficeDev PnP et mis à jour tous les mois conformément au calendrier de publication de la bibliothèque principale PnP pour les développeurs Office.
Remarque
L’infrastructure d’approvisionnement PnP & moteur d’approvisionnement PnP sont des solutions open source avec une communauté active qui le prend en charge. Il n’existe pas de contrat SLA Microsoft pour le support technique relatif à cet outil open source.
Objectif
Commençons par l’objectif d’avoir un moteur d’approvisionnement. Avec l’introduction de Microsoft Office 365 et Microsoft Office SharePoint Online, les développeurs considèrent le nouveau modèle de complément Cloud comme une nouvelle méthode pour créer des solutions logicielles personnalisées pour Microsoft SharePoint, SharePoint Online et Office 365 en général. Bien que dans le passé les développeurs configuraient des artefacts personnalisés à l’aide de l’infrastructure de fonctionnalités basée sur le code CAML/XML, soit avec des solutions de code de confiance totale (FTC) ou des solutions bac à sable (sandbox), l’approvisionnement d’artefacts dans le nouveau modèle de complément Cloud doit toutefois être effectué par le biais de la technique de « approvisionnement à distance ». Que signifie « approvisionnement à distance » ? Cela consiste à utiliser une des API disponibles (REST or CSOM) pour approvisionner des artefacts au lieu d’utiliser l’infrastructure de fonctionnalités.
Que se passe-t-il si vous voulez modéliser et approvisionner des artefacts à l’aide d’un environnement de tests et de production, ou que se passe-t-il si vous souhaitez automatiser l’approvisionnement d’artefacts, simplement car vous voulez vendre vos personnalisations à plusieurs clients ? De même, que se passe-t-il si vous souhaitez définir un modèle de site personnalisé que vous pouvez réutiliser au sein de plusieurs instances de site, comme des sites orientés client ou orientés projet ?
En utilisant le nouveau moteur d’approvisionnement PnP, vous pouvez modéliser un site en configurant la conception des colonnes de site, des types de contenu, des définitions et des instances de liste et bien plus via votre navigateur web. Lorsque vous avez terminé la conception, vous pouvez exporter ce que vous avez fait dans un format de modèle d’approvisionnement (XML, JSON ou un format de conteneur appelé fichier PnP), et vous pouvez appliquer ce modèle à autant de sites cibles que vous le souhaitez.
Toutefois, qu’en est-il si vous voulez approvisionner d’autres artefacts, comme Microsoft Teams ? Ou des utilisateurs Azure AD ? Le moteur d’approvisionnement PnP peut effectuer le travail à votre place.
Deux types de modèles
Le moteur comprend essentiellement deux types de modèles : modèles de sites (également appelés modèles d’approvisionnement) et la version étendue : modèles de client.
Lors du lancement du moteur, le seul modèle de site était disponible. Après quelques années, nous avons lancé le modèle de client qui se distingue par sa capacité approvisionner des artefacts au-delà de la portée des sites SharePoint. Ainsi, un modèle de client permet d’approvisionner une équipe Microsoft Teams, des utilisateurs Azure AD, des conceptions de sites, des scripts de site, des thèmes de portée client, etc. À l’inverse des modèles de sites, vous pouvez créer une soit-disant « séquence » dans un modèle de client et créer des collections de sites.
En bref, un modèle de client est un modèle de site qui peut contenir des artefacts à approvisionner au niveau du client.
Créer un modèle de site
Comme indiqué précédemment, le moyen le plus simple de créer un modèle d’approvisionnement personnalisé consiste à créer une collection de sites dans SharePoint Online, à configurer vos artefacts (colonnes de site, types de contenu, listes, pages, etc.) et à enregistrer le résultat sous la forme d’un modèle d’approvisionnement.
Supposons que vous ayez défini un exemple de site avec une page d’accueil personnalisée :
En dehors de la page d’accueil personnalisée, vous avez créé quelques événements dans la liste Événements prête à l’emploi :
Pour exporter ce site comme modèle d’approvisionnement, vous pouvez utiliser le code PowerShell ou CSOM, avec certaines méthodes d’extension fournies par la bibliothèque principale PnP pour les développeurs Office.
Utilisation de cmdlets PowerShell
Remarque
Cet article décrit l’utilisation de PowerShell PnP pour exploiter le moteur d’approvisionnement. Si vous préférez utiliser C#, consultez Moteur d’approvisionnement PnP et bibliothèque principale.
Remarque
PnP PowerShell est une solution open source pour laquelle un support est assuré par la communauté active. Il n’existe pas de contrat SLA Microsoft pour le support technique relatif à cet outil open source.
Pour utiliser les cmdlets PowerShell pour SharePoint Online ou SharePoint, accédez à Vue d’ensemble PowerShell PnP et installez le module SharePoint PowerShell PnP.
Après avoir connecté votre environnement PowerShell à SharePoint Online à l’aide de la cmdlet Connect-PnPOnline, vous pouvez utiliser la cmdlet PowerShell suivante :
Get-PnPSiteTemplate -Out "PnP-Provisioning-File.xml"
L’argument –Out indique à la cmdlet l’emplacement où enregistrer le modèle d’approvisionnement.
Le résultat de l’extraction et de l’enregistrement du modèle est, selon l’extension utilisée dans la cmdlet (nous prenons actuellement en charge .xml et .pnp), un fichier. Si vous avez choisi d’enregistrer le modèle en tant que fichier XML, il ressemblera à l’exemple ci-dessous (notez que le modèle n’est pas complet et n’est qu’un exemple de structure XML) :
Remarque
Il est nécessaire de définir de nombreuses options de configuration pour extraire un modèle. Pour obtenir une explication, voir configuration du moteur d’approvisionnement PnP.
<?xml version="1.0"?>
<pnp:Provisioning xmlns:pnp="http://schemas.dev.office.com/PnP/2019/09/ProvisioningSchema">
<pnp:Preferences Generator="OfficeDevPnP.Core, Version=3.14.1910.1, Culture=neutral, PublicKeyToken=null" />
<pnp:Templates ID="CONTAINER-TEMPLATE-8F4D883BE25B442FB9F889C351D3EA0B">
<pnp:ProvisioningTemplate ID="TEMPLATE-8F4D883BE25B442FB9F889C351D3EA0B" Version="1" BaseSiteTemplate="SITEPAGEPUBLISHING#0" Scope="RootSite">
<pnp:WebSettings RequestAccessEmail="" NoCrawl="false" WelcomePage="SitePages/Home.aspx" SiteLogo="{hosturl}{site}/SiteAssets/__sitelogo___sitelogo_theperspective.png"/>
<pnp:Navigation AddNewPagesToNavigation="true" CreateFriendlyUrlsForNewPages="true">
<pnp:CurrentNavigation NavigationType="StructuralLocal">
<pnp:StructuralNavigation RemoveExistingNodes="true">
<pnp:NavigationNode Title="Who we are" Url="http://linkless.header/" IsExternal="true"/>
<pnp:NavigationNode Title="What's happening" Url="http://linkless.header/" IsExternal="true"/>
<pnp:NavigationNode Title="Find it" Url="http://linkless.header/" IsExternal="true"/>
</pnp:StructuralNavigation>
</pnp:CurrentNavigation>
</pnp:Navigation>
<pnp:Lists>
<pnp:ListInstance Title="Events" Description="" DocumentTemplate="" TemplateType="106" Url="Lists/Events" MinorVersionLimit="0" MaxVersionLimit="0" DraftVersionVisibility="0" TemplateFeatureID="00bfea71-ec85-4903-972d-ebe475780106" ContentTypesEnabled="true" EnableFolderCreation="false" DefaultDisplayFormUrl="{site}/Lists/Events/DispForm.aspx" DefaultEditFormUrl="{site}/Lists/Events/EditForm.aspx" DefaultNewFormUrl="{site}/Lists/Events/NewForm.aspx" ImageUrl="/_layouts/15/images/itevent.png?rev=44" IrmExpire="false" IrmReject="false" IsApplicationList="false" ValidationFormula="" ValidationMessage="">
</pnp:ListInstance>
<pnp:DataRows KeyColumn="Title" UpdateBehavior="Overwrite">
<pnp:DataRow>
<pnp:DataValue FieldName="Title">Thanksgiving</pnp:DataValue>
<pnp:DataValue FieldName="fAllDayEvent">true</pnp:DataValue>
<pnp:DataValue FieldName="EventDate">2019-11-28 00:00:00</pnp:DataValue>
<pnp:DataValue FieldName="EndDate">2019-11-28 23:59:00</pnp:DataValue>
</pnp:DataRow>
<pnp:DataRow>
<pnp:DataValue FieldName="Title">In the design lab with Carlos Slattery</pnp:DataValue>
<pnp:DataValue FieldName="Location">Contoso HQ</pnp:DataValue>
<pnp:DataValue FieldName="fAllDayEvent">false</pnp:DataValue>
<pnp:DataValue FieldName="EventDate">2020-01-02 10:00:00</pnp:DataValue>
<pnp:DataValue FieldName="EndDate">2020-01-02 12:00:00</pnp:DataValue>
</pnp:DataRow>
</pnp:DataRows>
</pnp:Lists>
<pnp:ClientSidePages>
<pnp:ClientSidePage PromoteAsNewsArticle="false" PromoteAsTemplate="false" Overwrite="true" Layout="Home" EnableComments="false" Title="Home" ThumbnailUrl="" PageName="Home.aspx" LCID="0">
<pnp:Header Type="Default" LayoutType="FullWidthImage" TextAlignment="Center" ShowTopicHeader="false" ShowPublishDate="false" TopicHeader="" AlternativeText="" Authors="[]" AuthorByLine="[]" AuthorByLineId="-1" />
<pnp:Sections>
<pnp:Section Order="1" Type="OneColumnVerticalSection" VerticalSectionEmphasis="Soft">
<pnp:Controls>
<pnp:CanvasControl WebPartType="News" JsonControlData="{"id": "8c88f208-6c77-4bdb-86a0-0c47b4316588", "instanceId": "1ac6db3e-eb95-4d5d-a991-28ee34772313", ..." ControlId="8c88f208-6c77-4bdb-86a0-0c47b4316588" Order="1" Column="1" />
<pnp:CanvasControl WebPartType="News" JsonControlData="{"id": "8c88f208-6c77-4bdb-86a0-0c47b4316588", "instanceId": "e5fc83c0-3350-4eea-9606-6627646a0a4b", "title": "News", "description": "..." ControlId="8c88f208-6c77-4bdb-86a0-0c47b4316588" Order="2" Column="1" />
<pnp:CanvasControl WebPartType="Custom" JsonControlData="{"id": "868ac3c3-cad7-4bd6-9a1c-14dc5cc8e823", "instanceId": "c1524d29-ab2a-44a3-809e-c01c3762c4ee", "title": "Weather", "description":..." ControlId="868ac3c3-cad7-4bd6-9a1c-14dc5cc8e823" Order="1" Column="2" />
</pnp:Controls>
</pnp:Section>
<pnp:Section Order="2" Type="OneColumn">
<pnp:Controls>
<pnp:CanvasControl WebPartType="CallToAction" JsonControlData="{"id": "df8e44e7-edd5-46d5-90da-aca1539313b8", "instanceId": "b022816d-c9de-4989-aa10-9b44bec4a872", "title": "Call to action", "description": "Call to action", "dataVersion&..." Order="1" Column="1" />
</pnp:Controls>
</pnp:Section>
<pnp:Section Order="3" Type="ThreeColumn">
<pnp:Controls>
<pnp:CanvasControl WebPartType="Image" JsonControlData="{"id": "d1d91016-032f-456d-98a4-721247c305e8", "instanceId": "984b089c-ca62-4f92-89c0-1ce0e1cb6c03", "title": "Image", "description": "Image", "dataVersion": "1.8", "..." ControlId="d1d91016-032f-456d-98a4-721247c305e8" Order="1" Column="1" />
<pnp:CanvasControl WebPartType="Text" ControlId="5755396c-b272-4c0f-8e8d-eb41d218a10e" Order="2" Column="1">
<pnp:CanvasControlProperties>
<pnp:CanvasControlProperty Key="Text" Value="<p><span class="fontColorThemePrimary"><span class="fontSizeMediumPlus"><strong>BREATHTAKING VIDEOS &amp; PHOTOS</strong></span></span></p>

<p>..." />
</pnp:CanvasControlProperties>
</pnp:CanvasControl>
<pnp:CanvasControl WebPartType="Button" JsonControlData="{"id": "0f087d7f-520e-42b7-89c0-496aaf979d58", "instanceId": "deb39e2b-11a0-4141-8ac1-1078fe7cc392", "title": "..." ControlId="0f087d7f-520e-42b7-89c0-496aaf979d58" Order="3" Column="1" />
<pnp:CanvasControl WebPartType="Image" JsonControlData="{"id": "d1d91016-032f-456d-98a4-721247c305e8", "instanceId": "e0b59b5b-8a5a-406e-9deb-6e6f9de4bd3b", "title": "Image", ..." ControlId="d1d91016-032f-456d-98a4-721247c305e8" Order="1" Column="2" />
</pnp:Controls>
</pnp:Section>
</pnp:Sections>
</pnp:ClientSidePage>
</pnp:ClientSidePages>
<pnp:Header Layout="Compact" MenuStyle="MegaMenu" BackgroundEmphasis="Strong" />
<pnp:Footer Enabled="true" RemoveExistingNodes="false" />
</pnp:ProvisioningTemplate>
</pnp:Templates>
</pnp:Provisioning>
Comme vous le voyez, les éléments XML sont relativement explicites. Le schéma XML utilisé dans l’exemple fait référence à la version 201909 du schéma d’approvisionnement PnP, qui a été définie avec la communauté PnP SharePoint et qui est accessible sur GitHub via PnP-Provisioning-Schema. Dans le même référentiel, vous trouverez également un document Markdown (MD) généré automatiquement qui décrit les principaux éléments, types et attributs permettant de définir manuellement un modèle d’approvisionnement XML.
Il vous appartient de définir l’instance ProvisioningTemplate manuellement, en utilisant un modèle site ou en rédigeant un document XML qui valide dans le cadre d’un schéma XSD d’approvisionnement PnP ou en écrivant simplement le code .NET, puis en créant la hiérarchie des objets. Vous pouvez même effectuer une combinaison de ces approches : vous pouvez concevoir le modèle d’approvisionnement à l’aide d’un site de modèle, l’enregistrer en tant que fichier XML et faire certaines personnalisations en mémoire lors de la gestion de l’instance ProvisioningTemplate dans votre code.
Appliquer un modèle d’approvisionnement
Maintenant que vous avez vu ce qu’est un modèle d’approvisionnement, vous êtes en mesure de l’appliquer à un site cible.
Imaginons que vous ayez créé une autre nouvelle collection de sites Communication dans SharePoint Online, comme illustré dans la figure suivante.
Par défaut, le site se présente comme l’illustration suivante, c’est-à-dire la disposition par défaut d’un site Communication.
Vous pouvez maintenant appliquer un modèle de site personnalisé à l’aide d’une cmdlet PowerShell PnP
Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/targetcommunicationsite"
Invoke-PnPSiteTemplate -Path "PnP-Provisioning-File.xml"
L’argument –Path fait référence au fichier de modèle source que la cmdlet applique automatiquement au site actuellement connecté (implicite par la cmdlet Connect-PnPOnline).
Remarque
En règle générale, lorsque vous appliquez un modèle de site, le site ciblé doit être créé et opérationnel. Si vous souhaitez créer le site à la volée via un modèle, vous devez créer un modèle de client. Pour plus d’informations sur les modèles de client, voir ci-dessous.
Appliquer un modèle de client
Un modèle de client est fort semblable à un modèle de site, à quelques éléments supplémentaires près, dont l’un est fondamental : la séquence.
Une séquence est une configuration d’une ou plusieurs collections de sites à créer. Consultez le modèle suivant excerpt :
<pnp:Provisioning xmlns:pnp="http://schemas.dev.office.com/PnP/2019/09/ProvisioningSchema" Author="John White" Generator="Human being" Version="1.0" Description="Home Site" DisplayName="The Perspective">
<pnp:Sequence ID="sequence">
<pnp:SiteCollections>
<pnp:SiteCollection xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="pnp:CommunicationSite" ProvisioningId="MAIN" SiteDesign="Topic" Title="My New Site" Description="" Url="/sites/mynewsite" IsHubSite="false" Owner="user@domain.com">
<pnp:Templates>
<pnp:ProvisioningTemplateReference ID="MAIN-TEMPLATE"/>
</pnp:Templates>
</pnp:SiteCollection>
</pnp:SiteCollections>
</pnp:Sequence>
<pnp:Templates ID="SITE-TEMPLATES">
<pnp:ProvisioningTemplate ID="MAIN-TEMPLATE" Version="1" BaseSiteTemplate="SITEPAGEPUBLISHING#0" Scope="RootSite">
<pnp:Header Layout="Compact" MenuStyle="MegaMenu" BackgroundEmphasis="Strong" />
Comme vous pouvez le voir, la séquence est définie au même niveau que l’élément <pnp:Templates />. Une séquence peut contenir un ou plusieurs sites et peut également définir des sous-sites. Pour chaque site, vous pouvez faire référence à un ou plusieurs modèles à appliquer une fois le site créé. Vous faites référence à un modèle par son ID. Dans cet exemple, les modèles se trouvent dans le même fichier XML.
Pour appliquer un modèle de client à un client, entrez :
Connect-PnPOnline https://yourtenant.sharepoint.com
Invoke-PnPTenantTemplate -Path "yourtenanttemplate.xml"
Pour plus d’informations sur les modèles de client, voir Modèles de client d’approvisionnement PnP
Rubriques avancées
Même s’il ne s’agit que d’un article introductif, il est important de comprendre que lorsque vous utilisez le moteur d’approvisionnement PnP, vous pouvez également approvisionner des taxonomies et utiliser des variables et des jetons qui peuvent être remplacés lors de l’exécution, en fonction de ce que vous approvisionnez (par exemple, des ID de liste, des paramètres ou des ID de terme). Vous pouvez appeler le moteur d’approvisionnement à partir de services de travail du minuteur, des compléments hébergés sur des fournisseurs, des sites externes, et bien plus encore. Enfin, vous pouvez utiliser le moteur d’approvisionnement PnP pour déplacer les artefacts des environnements de test/intermédiaires vers les environnements de production.
Consultez les autres articles qui abordent des sujets plus avancés.
Configuration requise et conclusion
Pour lire le moteur d’approvisionnement en local, la mise à jour cumulative de mars 2015 de SharePoint 2013 doit être installée, car le moteur exploite certaines fonctionnalités du modèle objet côté client, qui ne sont pas disponibles dans les versions précédentes du produit. Si vous ciblez SharePoint Online, la configuration requise est automatiquement respectée grâce au modèle Software as a Service.
Utilisez le moteur d’approvisionnement PnP, envoyez-nous des commentaires et profitez de l’avenir du modèle de complément SharePoint et de l’approvisionnement à distance !