Compartilhar via

Mecanismo de provisionamento PnP e a Biblioteca Principal

  • Artigo

O mecanismo de provisionamento PnP é o coração da estrutura de provisionamento e na sua base está a biblioteca OfficeDevPnP.Core. O mecanismo de provisionamento faz parte da biblioteca Principal e aproveita as extensões de biblioteca Principal na implementação das tarefas de provisionamento.

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 código aberto por parte da Microsoft.

Composta por métodos de extensão no modelo de objeto CSOM/REST do SharePoint, a biblioteca Principais permite tarefas de provisionamento como enumerar e obter modelos de provisionamento, além de armazenar e aplicar modelos em sites novos e existentes. Ela também permite a automatização das tarefas de provisionamento e introduza a lógica codificada nas rotinas provisionamento.

Observação

Para ver um vídeo passo a passo de criação, manutenção e aplicação de um modelo de provisionamento, acesse Introdução ao mecanismo de provisionamento PnP.

Mecanismo de provisionamento PnP

O mecanismo de provisionamento PnP é a implementação estruturada de classes na biblioteca Principal para executar e automatizar tarefas de provisionamento remotas. No novo cenário Microsoft que apresenta o modelo de Suplemento do SharePoint, provisionamento soluções para o SharePoint Online, SharePoint e Office 365 que agora usam o modelo de objeto do lado cliente (CSOM) e a estrutura de provisionamento para provisionar artefatos do site.

O mecanismo de provisionamento PnP permite modelar o design das colunas do site, tipos de conteúdo, definições de lista, aparências compostas e páginas. Você pode criar esses recursos e muito mais ao apontar para os recursos existentes de design de site, ao criar o design manualmente ou usando uma combinação das duas abordagens. Opcionalmente, em seguida, você pode manter o design como um modelo de provisionamento que você pode salvar e reutilizar.

Você pode usar um dos procedimentos a seguir para extrair o design do site como um modelo de provisionamento. Use scripts do Windows PowerShell (PnP.PowerShell) ou use o código CSOM/REST que implementa métodos de extensão fornecidos pela biblioteca Principal (OfficeDevPnP.Core).

Usar o script do Windows PowerShell para extrair um modelo de provisionamento

Para usar os scripts do Windows PowerShell com o mecanismo de provisionamento, você primeiro deve baixar e instalar os cmdlets PnP do PowerShell. Tudo o que você precisa para executar o Windows PowerShell, incluindo instruções de download e instalação, e a documentação de comando do Windows PowerShell, está disponível no repositório Comandos do PowerShell PnP no GitHub.

Observação

O repositório de Comandos do PowerShell PNP contém quatro versões: uma para o SharePoint 2013, uma para o SharePoint 2016, uma para o SharePoint 2019 e uma para o SharePoint Online.

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.

A maneira recomendada de instalar o cmdlet é usando a galeria do PowerShell:

Install-Module -Name PnP.PowerShell

Caso você queira instalar uma versão do SharePoint no local, substitua 'online' no nome pela respectiva versão do SharePoint.

Estes são os links para as versões mais recentes:

Usar um código CSOM para extrair um modelo de provisionamento

Para utilizam um código CSOM/REST para extrair um modelo de provisionamento, basta criar um projeto de desenvolvimento usando o Visual Studio ou outro ambiente de desenvolvimento. Crie qualquer tipo de projeto, por exemplo, um console ou aplicativo Windows ou um Suplemento do SharePoint. Depois de criar um projeto de desenvolvimento, você deve instalar a biblioteca Principal, que está disponível como um pacote NuGet.

Observação

Instruções para localizar e instalar o pacote NuGet da biblioteca Principal e um exemplo, passo a passo, de provisionamento para Aplicativo do Console, estão disponíveis em Exemplo de provisionamento para Aplicativo do Console. Observe que a biblioteca Principal vem em duas versões: uma destinada ao SharePoint Online e outra ao SharePoint local.

Enquanto as instruções detalhadas sobre como usar o CSOM estão no exemplo de provisionamento para Aplicativo do Console, a visão geral é assim:

  1. Criar uma conexão com o SharePoint Online.

  2. Criar uma instância ClientContext e recuperar uma referência para um objetoWeb.

  3. Use o método de extensão da biblioteca Principal GetProvisioningTemplatepara extrair um objeto ProvisioningTemplate.

  4. Salve a instância de modelo de provisionamento em um local de arquivo de sua escolha usando um provedor do modelo e um formatador de serialização.

Observação

Os objetos provedores do modelo e formatadores de serialização podem ser personalizados, por isso você pode implementar qualquer armazenamento de persistência e formato de serialização que desejar. Pronto para uso, o mecanismo de provisionamento PnP fornece suporte para o sistema de arquivos do SharePoint e para os provedores de modelo de armazenamento de Blob do Microsoft Azure. Ele também dá suporte a formatadores de serialização XML e JSON.

Você pode ver um exemplo de saída de serialização XML e aprender mais sobre o esquema de serialização XML no artigo Esquema de provisionamento PnP. Você também pode obter o esquema e sua documentação no GitHub: SharePoint ou PnP-Provisionamento-Esquema. O vídeo do canal 9 Esquema do mecanismo de provisionamento PnP introduz e descreve o esquema.

É importante observar, contudo, que o mecanismo de provisionamento suporta um modelo de domínio independente do formato de serialização. Na verdade, o mecanismo de provisionamento é totalmente desmembrado de qualquer formato de serialização. Cabe a você definir manualmente a instância ProvisioningTemplate.

Aponte para um modelo de site ou redija um documento XML que valide o esquema de provisionamento PnP ou escreva o código .NET e crie a hierarquia dos objetos. Você ainda pode combinar esses métodos. Você também pode criar o modelo de provisionamento usando um site modelo, em seguida, salvar em um arquivo XML e fazer algumas personalizações na memória ao tratar a instância ProvisioningTemplate no seu código.

Código de exemplo para extrair um modelo usando o GetProvisioningTemplate

O Exemplo de provisionamento para Aplicativo do Console ilustra usando o método GetProvisioningTemplate. O exemplo, o processo de exportação provisionamento modelo ocorrerá no bloco código a seguir.

ProvisioningTemplateCreationInformation ptci = new ProvisioningTemplateCreationInformation(ctx.Web);

// Create FileSystemConnector, so that we can store composed files somewhere temporarily 
ptci.FileConnector = new FileSystemConnector(@"c:\temp\pnpprovisioningdemo", "");
ptci.PersistComposedLookFiles = true;
ptci.ProgressDelegate = delegate (String message, Int32 progress, Int32 total)
{

// Use this to simply output progress to the console application UI
Console.WriteLine("{0:00}/{1:00} - {2}", progress, total, message);
};

// Execute actual extraction of the tepmplate
ProvisioningTemplate template = ctx.Web.GetProvisioningTemplate(ptci);

Aplicar o modelo de provisionamento

Ao aplicar o modelo de provisionamento usando os métodos de extensão da biblioteca Principal, você tem um bloco de códigos semelhante ao exemplo aqui. No exemplo, o modelo é aplicado ao site de destino usando o método de extensão ApplyProvisioningTemplate do tipoWeb.

using (var context = new ClientContext(destinationUrl))
{
  context.Credentials = new SharePointOnlineCredentials(userName, password);
  Web web = context.Web;
  context.Load(web, w => w.Title);
  context.ExecuteQueryRetry();

  // Configure the XML file system provider
  XMLTemplateProvider provider =
  new XMLFileSystemTemplateProvider(
    String.Format(@"{0}\..\..\",
    AppDomain.CurrentDomain.BaseDirectory),
    "");

  // Load the template from the XML stored copy
  ProvisioningTemplate template = provider.GetTemplate(
    "<template name>.xml");

  // Apply the template to another site
  Console.WriteLine("Start: {0:hh.mm.ss}", DateTime.Now);

  // We can also use Apply-PnPProvisioningTemplate
  web.ApplyProvisioningTemplate(template);

  Console.WriteLine("End: {0:hh.mm.ss}", DateTime.Now);
}

Biblioteca Principal PnP

A biblioteca Principal (OfficeDevPnP.Core) é um modelo de objeto do CSOM/REST que dá suporte a estrutura de provisionamento PnP e habilita o mecanismo de provisionamento PnP. Ela é formada por vários namespaces, incluindo um conjunto de métodos de extensão. Esses métodos estendem o modelo de objeto do SharePoint para oferecer suporte ao provisionamento remoto e a objetos que manipulam entidades, trabalhos do timer, modelos de provisionamento e a totalidade da estrutura de provisionamento. Tabela 1 lista namespaces na biblioteca Principal.


Tabela 1. Namespaces na biblioteca OfficeDevPnP.Core

Namespace Descrição
OfficeDevPnP.Core
OfficeDevPnP.Core.AppModelExtensions Classes .NET que estendem um tipo existente com métodos adicionais.
OfficeDevPnP.Core.Entities Classes que são usadas para fornecer e recuperar objetos mais complexos dos métodos de extensões AppModelExtensions.
OfficeDevPnP.Core.Enums Um conjunto de enumerações que oferecem suporte a operações de provisionamento.
OfficeDevPnP.Core.Extensions Métodos de extensão que não estão relacionados com o SharePoint, como os métodos que ajudam a manipular cadeias de caracteres.
OfficeDevPnP.Core.Framework.ObjectHandlers.TokenDefinitions Tokens usados para substituir o conteúdo do site no objeto do modelo.
OfficeDevPnP.Core.Framework.Provisioning.Connectors Conectores são usados para se conectar a diferentes fontes de dados onde modelos e ativos são armazenados.
OfficeDevPnP.Core.Framework.Provisioning.Extensibility Código do provedor de extensibilidade. Provedores de extensibilidade podem ser usados para incluir recursos que não são suportados pelo mecanismo de forma nativa.
OfficeDevPnP.Core.Framework.Provisioning.Model Objetos do modelo de dados do modelo. Os modelos são extraídos ou desserializados para o código C# atual. Esse namespace contém classes para essa estrutura.
OfficeDevPnP.Core.Framework.Provisioning.ObjectHandlers Manipuladores de diferentes elementos do SharePoint com suporte para a extração de modelo e criação.
OfficeDevPnP.Core.Framework.Provisioning.Providers Namespace base do provedor do modelo. Provedores de modelo são usados para serializar ou desserializar modelos baseados em códigos para um formato específico.
OfficeDevPnP.Core.Framework.Provisioning.Providers.Json Provedor de modelo JSON para serializar ou desserializar modelos baseados em códigos para ou do formato JSON.
OfficeDevPnP.Core.Framework.Provisioning.Providers.Xml Provedor de modelo XML para serializar ou desserializar modelos baseados em códigos para ou do formato XML.
OfficeDevPnP.Core.Framework.Provisioning.Providers.Xml.V201503 Arquivos de esquema autogerados versão v201503 do esquema.
OfficeDevPnP.Core.Framework.Provisioning.Providers.Xml.V201505 Arquivos de esquema autogerados versão v201505 do esquema.
OfficeDevPnP.Core.Framework.Provisioning.Providers.Xml.V201508 Arquivos de esquema autogerados versão v201508 do esquema.

Confira também