Provisionar ativos do SharePoint com seu pacote de solução
Às vezes, você pode precisar provisionar uma lista ou biblioteca de documentos do SharePoint com seu pacote de solução do lado do cliente para que essa lista ou biblioteca fique disponível para os componentes do lado do cliente, como web parts. A cadeia de ferramentas da Estrutura do SharePoint permite empacotar e implantar itens do SharePoint com o seu pacote de solução do lado do cliente. Esses itens são então provisionados quando a solução do lado do cliente é instalada em um site.
Você também pode encontrar detalhes sobre as opções de provisionamento neste webcast PnP do SharePoint disponível no Canal do YouTube da Comunidade (PnP) da Plataforma Microsoft 365:
Provisionar itens usando um código JavaScript
Embora seja possível criar itens do SharePoint usando um código JavaScript no seu componente, como web parts, isso está limitado ao contexto do usuário atual que usa esse componente. Se o usuário não tiver permissões suficientes para criar ou modificar itens do SharePoint, o código JavaScript não provisionará esses itens. Nesses casos, quando quiser provisionar itens do SharePoint em um contexto elevado, você deverá empacotar e implantar os itens com o seu pacote de solução.
Provisionar itens do SharePoint na sua solução
Os seguintes ativos do SharePoint podem ser provisionados com o pacote de solução do lado do cliente:
- Campos
- Tipos de conteúdo
- Instâncias de lista
- Instâncias de lista com um esquema personalizado
Campos
Um campo ou uma coluna de site representa um atributo, ou um metadado, que o usuário deseja gerenciar para os itens no tipo de lista ou conteúdo ao qual ele adicionou essa coluna. Trata-se de uma definição de coluna reutilizável, ou modelo, que você pode atribuir a várias listas em vários sites do SharePoint. Colunas de site diminuem o retrabalho e ajudam você garantir a consistência dos metadados entre sites e listas.
Por exemplo, suponha que você defina uma coluna de site denominada Cliente. Os usuários podem adicionar essa coluna às suas listas e referenciá-la em seus tipos de conteúdo. Isso garante que a coluna tenha os mesmos atributos — pelo menos para começar — onde quer que ela apareça.
Você pode consultar o esquema e os atributos na documentação do Elemento Field (Field) para definir um novo campo na sua solução.
Veja a seguir um exemplo de um novo campo DateTime:
<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>
Tipos de conteúdo
Um tipo de conteúdo é uma coleção reutilizável de metadados (colunas), comportamentos e outras configurações para uma categoria de itens ou documentos em uma lista ou biblioteca de documentos do SharePoint. Tipos de conteúdo permitem que você gerencie as configurações para uma categoria de informações de forma centralizada e reutilizável.
Por exemplo, imagine uma situação de negócios em que você tem três diferentes tipos de documento: relatórios de despesas, ordens de compra e faturas. Todos os três tipos de documentos têm algumas características em comum: por um lado, são documentos financeiros e contêm dados com valores em moeda. No entanto, cada tipo de documento tem seus próprios requisitos de dados, seu próprio modelo de documento e seu próprio fluxo de trabalho.
Uma solução para esse problema de negócios é criar quatro tipos de conteúdo. O primeiro tipo de conteúdo, Documento Financeiro, pode englobar os requisitos de dados que são comuns a todos os documentos financeiros da organização. Os três restantes, Relatório de Despesas, Ordem de Compra e Fatura, podem herdar elementos comuns de Documento Financeiro. Além disso, eles podem definir características que são exclusivas para cada tipo, como um conjunto específico de metadados, um modelo de documento a ser usado na criação de um novo item e um fluxo de trabalho específico para o processamento de um item.
Você pode consultar o esquema e os atributos na documentação do Elemento ContentType (ContentType) para definir um novo tipo de conteúdo na sua solução.
Veja a seguir um exemplo de tipo de conteúdo:
<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>
Instâncias de lista
Listas são um recurso chave e subjacente de um site do SharePoint. Elas permitem que as equipes coletem, acompanhem e compartilhem informações. Muitos aplicativos dependem de listas criadas no local para o armazenamento de dados implementar seus comportamentos. Uma instância de lista é uma lista predefinida do SharePoint que tem um identificador conhecido. É possível personalizar e adicionar itens a essas listas, criar listas adicionais dos modelos de lista que já estão disponíveis e criar listas personalizadas apenas com as definições e as colunas que você escolher.
O SharePoint fornece vários modelos de lista, como uma lista de contatos, um calendário, uma lista de tarefas e muito mais. Você pode usar esses modelos para criar novas instâncias de lista para suas web parts ou outros componentes. Por exemplo, é possível definir uma instância de lista Documentos de Finanças com base no modelo Biblioteca de Documentos para armazenar documentos associados à web part.
Você pode consultar o esquema e os atributos na documentação do Elemento ListInstance (Instância de Lista) para definir uma instância de lista na sua solução.
Veja a seguir um exemplo de definição de instância de lista:
<ListInstance
FeatureId="00bfea71-e717-4e80-aa17-d0c71b360101"
Title="Finance Records"
Description="Finance documents"
TemplateType="101"
Url="Lists/FinanceRecords">
</ListInstance>
Instâncias de lista com um esquema personalizado
Você pode usar uma definição de esquema de lista personalizado para definir os campos, tipos de conteúdo e exibições usados em sua instância de lista. É possível usar o atributo CustomSchema do elemento ListInstance para fazer referência a um esquema personalizado para a instância de lista.
Por exemplo, é possível definir uma instância de lista Documentos de Finanças com um tipo de conteúdo Documento Financeiro capaz de encapsular os requisitos de dados que são comuns a todos os documentos financeiros da organização.
Veja a seguir um exemplo de definição de instância de lista que usa um esquema personalizado:
<ListInstance
CustomSchema="schema.xml"
FeatureId="00bfea71-de22-43b2-a848-c05709900100"
Title="Cost Centers"
Description="Cost Centers"
TemplateType="100"
Url="Lists/CostCenters">
</ListInstance>
Essa é a definição de esquema personalizado que define um tipo de conteúdo para a instância de lista definida anteriormente:
<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>
Criar itens do SharePoint na sua solução
O pacote de solução usa Recursos do SharePoint para empacotar e provisionar os itens do SharePoint. Um recurso é um contêiner que inclui um ou mais itens do SharePoint para provisionamento. Um recurso contém um arquivo Feature.xml e um ou mais arquivos de manifesto de elementos. Esses arquivos XML também são conhecidos como definições de recurso.
Normalmente, um pacote de solução do lado do cliente contém um único recurso. Esse recurso é ativado quando a solução é instalada em um site. É importante observar que os administradores de site instalam seu pacote de solução, e não o recurso.
Um recurso é construído basicamente usando os arquivos XML a seguir.
Arquivo de manifesto do elemento
O arquivo de manifesto do elemento contém as definições de itens do SharePoint e é executado quando o recurso é ativado. Por exemplo, as definições de XML para criar um novo campo, um tipo de conteúdo ou uma instância de lista estão no manifesto do elemento.
Veja a seguir um exemplo de arquivo de manifesto do elemento que define um novo campo DateTime.
<?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>
Arquivo de elemento
Todos os arquivo suportados que acompanham o manifesto do elemento são arquivos de elemento. Por exemplo, o esquema de instância de lista é um arquivo de elemento que está associado a uma instância de lista definida em um manifesto do elemento.
Veja a seguir um exemplo de esquema de instância de lista personalizado:
<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>
Arquivo de ações de upgrade
Como o nome sugere, esse é o arquivo que inclui quaisquer ações de upgrade quando a solução é atualizada no site. Como parte das ações de upgrade, a ação também poderia especificar a inclusão de um ou mais manifestos do elemento. Por exemplo, se o upgrade exigir a adição de um novo campo, a definição de campo estará disponível como um manifesto do elemento e será associada ao arquivo de ações de upgrade.
Veja a seguir um exemplo de arquivo de ações de upgrade que aplica um arquivo de manifesto do elemento durante o upgrade:
<ApplyElementManifests>
<ElementManifest Location="9c0be970-a4d7-41bb-be21-4a683586db18\elements-v2.xml" />
</ApplyElementManifests>
Configurar o recurso do SharePoint
Para incluir os arquivo XML, você precisa primeiro definir a configuração do recurso no arquivo de configuração package-solution.json, abaixo da pasta config no seu projeto. O arquivo package-solution.json contém as principais informações de metadados sobre o pacote de solução do lado do cliente e é referenciado quando você executa a tarefa gulp package-solution, que empacota a solução em um arquivo .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"
}
}
O objeto JSON features contém os metadados sobre o recurso, como mostrado na tabela a seguir.
| Propriedade | Descrição |
|---|---|
| id | Identificador exclusivo (GUID) do recurso |
| title | Título do recurso |
| description | Descrição do recurso |
| assets | Uma matriz de arquivos XML usados no recurso |
| elementManifests | Definido dentro da propriedade assets, uma matriz de arquivos de manifesto de elemento |
| elementFiles | Definido dentro da propriedade assets, uma matriz de arquivos de elemento |
| upgradeActions | Definido dentro da propriedade assets, uma matriz de arquivos de ação de upgrade |
Criar os arquivos XML do recurso
A cadeia de ferramentas procura os arquivos XML, conforme definidos na configuração abaixo uma pasta especial, sharepoint\assets, no seu projeto de solução do lado do cliente.
As configurações definidas no package-solution.json são o que mapeia os arquivos XML aqui para seu arquivo XML de recurso apropriado quando a tarefa gulp package-solution é executada.
Empacotar itens do SharePoint
Depois de ter definido seu recurso no package-solution.json e criado os respectivos arquivos XML do recurso, você poderá usar a tarefa gulp a seguir para empacotar os itens do SharePoint com o pacote .sppkg.
gulp package-solution
Esse comando empacota um ou mais manifestos do componente do lado do cliente, como web parts, com os arquivos XML do recurso referenciados no arquivo de configuração package-solution.json.
Observação
Você pode usar o sinalizador --ship para empacotar versões minimizadas dos componentes.
Fazer upgrade de itens do SharePoint
Você pode incluir novos itens do SharePoint ou atualizar itens do SharePoint existentes ao fazer upgrade da sua solução do lado do cliente. Como o provisionamento de itens do SharePoint usa recursos, você usará o arquivo XML UpgradeActions do recurso para definir uma lista de ações de upgrade.
A matriz de objetos JSON upgradeActions em package-solution.json referencia os arquivos XML do recurso associados às ações de upgrade para o seu recurso. Pelo menos um arquivo de ação de upgrade define o arquivo XML de manifesto do elemento que é executado durante o upgrade do recurso.
Ao atualizar uma solução da Estrutura do SharePoint, você também precisa atualizar os atributos da versão para a solução e o recurso, onde as ações de upgrade foram incluídas. Um aumento de versão da solução indica aos usuários finais do SharePoint que há uma nova versão disponível do pacote. Um aumento de versão do elemento do recurso garante que as tarefas definidas nas ações de upgrade estejam sendo processadas como parte do upgrade da solução.
Veja a seguir um exemplo de arquivo de ação de upgrade que aplica um arquivo de manifesto do elemento durante o upgrade:
<ApplyElementManifests>
<ElementManifest Location="9c0be970-a4d7-41bb-be21-4a683586db18\elements-v2.xml" />
</ApplyElementManifests>
Esse é o element-v2.xml correspondente que define um novo campo Moeda a ser provisionado durante o upgrade:
<?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>
Subelementos
As ações de upgrade em soluções do lado do cliente dão suporte aos subelementos a seguir.
AddContentTypeField
Adiciona um novo campo a um tipo de conteúdo provisionado existente. Propaga a alteração do tipo de conteúdo de site para todas as listas e tipos de conteúdo filho dentro do site. Por exemplo:
<AddContentTypeField
ContentTypeId="0x010100A6F9CE1AFE2A48f0A3E6CB5BB770B0F7"
FieldId="{B250DCFD-9310-4e2d-85F2-BE2DA37A57D2}"
PushDown="TRUE" />
ApplyElementManifests
Adiciona um novo elemento a um recurso existente. Quando um recurso é atualizado, ele provisiona todos os elementos não declarativos que são referenciados nos manifestos do elemento especificados.
VersionRange
Especifica um intervalo de versões ao qual as ações de upgrade são aplicáveis.