Apresentação do mecanismo de provisionamento PnP
Este artigo apresenta o mecanismo de provisionamento PnP, que foi lançado em abril de 2015 no projeto OfficeDev PnP e atualizado mensalmente seguindo o cronograma de lançamento da Biblioteca Central do Office Dev PnP.
Observação
O PnP Provisioning Framework & Mecanismo de Provisionamento PnP são soluções de software livre com a comunidade ativa fornecendo suporte para ele. Não há nenhuma SLA para o suporte da ferramenta de software livre por parte da Microsoft.
O objetivo
Vamos começar pelo principal objetivo de ter um mecanismo de provisionamento. Com a introdução do Microsoft Office 365 e do Microsoft SharePoint Online, os desenvolvedores têm o novo modelo de Complemento de Nuvem como uma nova maneira de criar soluções de software personalizadas para o Microsoft SharePoint, o SharePoint Online e o Office 365 em geral. No entanto, enquanto nos desenvolvedores anteriores provisionaram artefatos personalizados usando a Estrutura de Recursos baseada em CAML/XML, com soluções de código de confiança total (FTC) ou soluções de área de segurança, o provisionamento de artefatos no novo modelo de Complemento de Nuvem deve ser feito por meio da técnica de "provisionamento remoto". O que significa fazer provisionamento remoto? Isso significa usar uma das APIs disponíveis (REST ou CSOM) para provisionar artefatos em vez de usar a Estrutura de Recursos.
E se você quiser modelar e provisionar artefatos usando um ambiente de teste e de produção, ou se quiser automatizar o provisionamento de artefatos, só porque quer vender suas personalizações para vários clientes? Da mesma forma, e se você quiser definir um modelo de site personalizado que possa reutilizar em várias instâncias de site, como sites orientados pelo cliente ou sites orientados a projetos?
Usando o novo mecanismo de provisionamento PnP você pode modelar um site configurando o design de colunas de site, tipos de conteúdo, definições de lista e instâncias, páginas e muito mais, por meio do seu navegador da Web. Quando terminar o design, você poderá exportar o que fez em um formato de modelo de provisionamento (XML, JSON ou um formato de contêiner chamado de arquivo PnP), e pode aplicar esse modelo a quantos sites de destino quiser.
Mas, e se você quiser provisionar outros artefatos como o Microsoft Teams? Ou usuários do Azure AD? O Mecanismo de Provisionamento de PnP pode fazer o trabalho por você.
Dois tipos de Modelos
Existem basicamente dois tipos de modelos que o mecanismo entende: Modelos de site (também chamados de Modelos de Provisionamento) e a versão estendida: Modelos de locatário
Quando o mecanismo foi introduzido, o único tipo de modelo disponível era o Modelo de Site. Após alguns anos, apresentamos o Modelo de Locatário, que se distingue pela capacidade de provisionar artefatos além do escopo de sites do SharePoint. Por exemplo, um modelo de locatário permite provisionar uma equipe do Microsoft Teams, usuários do Azure AD, Designs de Site e Scripts de Site, temas com escopo de locatário etc. Ao contrário dos Modelos de Site, você pode criar a chamada "Sequência" em um modelo de locatário e criar coleções de sites.
Resumindo: um modelo de locatário é um modelo de site que pode conter artefatos para provisionar ao nível do locatário.
Criar um modelo de site
Como já foi dito, a maneira mais fácil de criar um modelo de provisionamento personalizado é criar um novo conjunto de sites no SharePoint Online, configurar seus artefatos (colunas de site, tipos de conteúdo, listas, páginas etc.) e salvar o resultado como um modelo de provisionamento.
Digamos que você definiu um exemplo de site com uma página inicial personalizada:
Além da página inicial personalizada, você criou alguns eventos na Lista de eventos fora da caixa:
Para exportar esse site como um modelo de provisionamento, você pode usar o código Do PowerShell ou CSOM, com alguns métodos de extensão, fornecidos pela Biblioteca Principal do OfficeDev PnP.
Usando cmdlets do PowerShell
Observação
Este artigo se concentra em como usar o PnP do PowerShell para trabalhar com o Mecanismo de Provisionamento. Se preferir usar C#, consulte o Mecanismo de Provisionamento PnP e a Biblioteca Principal.
Observação
O PnP PowerShell é uma solução de software livre com uma comunidade ativa de suporte. Não há nenhuma SLA para o suporte da ferramenta de software livre por parte da Microsoft.
Para usar cmdlets do PowerShell para o SharePoint Online ou SharePoint, vá para Visão geral do PowerShelldo SharePoint e instale o módulo do PowerShell do SharePoint também.
Depois de ter conectado seu ambiente do PowerShell ao SharePoint Online usando o cmdlet Connect-PnPOnline, você pode usar o seguinte cmdlet do PowerShell:
Get-PnPSiteTemplate -Out "PnP-Provisioning-File.xml"
O –Out argumento instrui o cmdlet sobre onde salvar o modelo de provisionamento.
O resultado da extração e do recurso de salvar o modelo será, dependendo da extensão usada no cmdlet (no momento, damos suporte à extensão .xml e .pnp ), um arquivo. Se você selecionou para salvar o modelo como um arquivo XML, ele se parecerá com o que você vê abaixo (observe, o modelo não está completo e é apenas um exemplo de estrutura XML):
Observação
Há muitas opções de configuração para definir para extrair um modelo. Para uma explicação sobre isso, confira Configurando a configuração do Mecanismo de Provisionamento.
<?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>
Como você pode ver, os elementos XML são bastante auto-explicativos. O esquema XML usado no exemplo faz referência à versão 201909 do esquema de provisionamento de PnP, que foi definido em conjunto com a Comunidade do SharePoint Também pode ser encontrado no GitHub em PnP-Provisioning-Schema. No mesmo repositório, você também pode encontrar um documento gerado automaticamente de marcação (MD) que descreve os principais elementos, tipos e atributos disponíveis para definir manualmente um modelo de provisionamento XML.
É necessário definir manualmente o ProvisioningTemplate, usando um site de modelo, ou escrevendo um documento XML que seja validado com base no esquema XSD de provisionamento, ou simplesmente escrevendo código .NET e construindo a hierarquia de objetos. Você também pode criar o modelo de provisionamento usando um site de modelo. Em seguida, salve-o como um arquivo XML e faça algumas personalizações na memória enquanto trabalha com a instância ProvisioningTemplate no seu código.
Aplicar um modelo de provisionamento
Agora que você viu o que é um modelo de provisionamento, está pronto para aplicá-lo a um site de destino.
Digamos que você tenha criado outro novo conjunto de sites de comunicação no SharePoint Online, conforme mostrado na figura a seguir.
Por padrão, o site se parece com a figura a seguir, que é o layout padrão de um site de Comunicação.
Agora você pode aplicar um modelo de site personalizado usando um cmdlet do PnP do PowerShell
Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/targetcommunicationsite"
Invoke-PnPSiteTemplate -Path "PnP-Provisioning-File.xml"
O argumento–Path se refere ao arquivo de modelo de origem, que o cmdlet aplica automaticamente ao site atualmente conectado (implícito pelo cmdlet Connect-PnPOnline).
Observação
A regra geral é que, quando você aplica um modelo de site, o site de destino precisa ser criado e estar funcionando. Se você quiser criar o site em tempo real por meio de um modelo, será preciso criar um modelo de locatário. Confira abaixo mais informações sobre modelos de locatário.
Aplicar um modelo de locatário
Um modelo de locatário é muito semelhante a um modelo de site, com o adicional de mais alguns elementos, dos quais um é fundamental: a sequência.
Uma sequência é uma configuração de um ou mais conjunto de sites a ser criado. Confira o trecho de modelo a seguir.
<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" />
Como você pode ver, a sequência é definida no mesmo nível que o elemento <pnp:Templates />. Uma sequência pode conter um ou mais sites e também pode definir subsites. Para cada site, você pode consultar um ou mais modelos a aplicar depois que o site for criado. Você se refere a um modelo por sua ID e os modelos estão localizados neste exemplo no mesmo arquivo XML.
Para aplicar um modelo de locatário a um locatário que você inserir:
Connect-PnPOnline https://yourtenant.sharepoint.com
Invoke-PnPTenantTemplate -Path "yourtenanttemplate.xml"
Confira Modelo de Locatário de Provisionamento de PnP para obter mais informações sobre os modelos do Locatário.
Tópicos avançados
Este é apenas um artigo introdutório. É importante compreender que, ao usar o mecanismo de provisionamento de PnP, você também pode provisionar taxonomias e usar variáveis e tokens que podem ser substituídos durante a execução, com base no que você está provisionando (como IDs de lista, parâmetros ou IDs de termos). Você pode invocar o mecanismo de provisionamento de serviços de trabalho de temporizador, de complementos hospedados pelo provedor, de sites externos e muito mais. Por fim, você pode usar o mecanismo de provisionamento de PnP para mover artefatos de ambientes de teste/preparação para ambientes de produção.
Não deixe de conferir os outros artigos para mais tópicos mais avançados.
Requisitos e resumo
Para utilizar o mecanismo de PnP localmente, é necessário ter pelo menos a Atualização Cumulativa do SharePoint 2013 de março de 2015 instalada, pois o mecanismo aproveita alguns recursos do modelo de objeto do lado cliente, que não estão disponíveis em versões anteriores do produto. Se você direcionar o SharePoint Online, os requisitos serão automaticamente satisfeitos graças ao Software como um Modelo de serviço.
Experimente o mecanismo de provisionamento de PnP, deixe seus comentários e aproveite o futuro do modelo de complementos e do provisionamento remoto do SharePoint!