Provisionar ativos do SharePoint oriundos da web part do SharePoint do lado do cliente

Artigo
04/08/2023

Os ativos do SharePoint podem ser provisionados como parte da solução da Estrutura do SharePoint e são implantados em sites do SharePoint quando a solução está instalada nele.

Antes de começar, conclua as etapas nos artigos a seguir para garantir que você compreenda o fluxo básico da criação de uma web part personalizada do lado do cliente:

Você também pode seguir estas etapas assistindo a este vídeo no Canal do YouTube da Comunidade (PnP) da Plataforma Microsoft 365:

Criar um novo projeto de Web Part

Crie um novo diretório de projeto em seu local favorito:
```
md asset-deployment-webpart
```
Vá para o diretório do projeto:
```
cd asset-deployment-webpart
```
Crie uma nova solução de web part do lado do cliente por meio do Gerador Yeoman do SharePoint:
```
yo @microsoft/sharepoint
```
Quando solicitado, insira os seguintes valores (selecione a opção padrão para todos os avisos omitidos abaixo):

Qual é o seu nome de solução?: asset-deployment-webpart
Que tipo de componente para o cliente você deseja criar?: WebPart
Qual é o nome da sua Web part?: AssetDeployment
Qual é o modelo que você gostaria de usar?: nenhuma estrutura JavaScript

Neste ponto, o Yeoman instalará as dependências necessárias e manterá a estrutura dos arquivos da solução. Isso pode levar alguns minutos. O Yeoman estrutura o projeto até incluir sua web part AssetDeployment.

Em seguida, faça o seguinte para abrir o projeto de Web part no Visual Studio Code:
```
code .
```

Criar estrutura de pastas para ativos do SharePoint

Primeiro, precisamos criar uma pasta denominada assets na qual colocamos todos os ativos de estrutura de recurso usados para o provisionamento de estruturas do SharePoint quando um pacote é instalado.

Crie uma pasta denominada sharepoint na raiz da solução.
Crie uma pasta denominada assets como uma subpasta para a pasta sharepoint.

A estrutura da solução deve ser semelhante à seguinte imagem:

Criar arquivos de framework de recurso para a implantação inicial

Para fornecer recursos do SharePoint para os sites com os elementos da estrutura de recurso, precisamos criar os arquivos XML necessários à pasta "assets". Os elementos suportados para os pacotes de solução do SharePoint Framework são os seguintes:

Colunas Campos/Site
Tipos de conteúdo
Instâncias de lista
Instâncias de lista com um esquema personalizado

Adicione um arquivo elementos.xml para definições do SharePoint

Nas etapas a seguir, vamos definir a estrutura necessária a ser provisionada.

Crie um novo arquivo elements.xml na pasta sharepoint\assets.

Copie a seguinte estrutura XML para elements.xml.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">

    <Field ID="{060E50AC-E9C1-4D3C-B1F9-DE0BCAC300F6}"
            Name="SPFxAmount"
            DisplayName="Amount"
            Type="Currency"
            Decimals="2"
            Min="0"
            Required="FALSE"
            Group="SPFx Columns" />

    <Field ID="{943E7530-5E2B-4C02-8259-CCD93A9ECB18}"
            Name="SPFxCostCenter"
            DisplayName="Cost Center"
            Type="Choice"
            Required="FALSE"
            Group="SPFx Columns">
        <CHOICES>
        <CHOICE>Administration</CHOICE>
        <CHOICE>Information</CHOICE>
        <CHOICE>Facilities</CHOICE>
        <CHOICE>Operations</CHOICE>
        <CHOICE>Sales</CHOICE>
        <CHOICE>Marketing</CHOICE>
        </CHOICES>
    </Field>

    <ContentType ID="0x010042D0C1C200A14B6887742B6344675C8B"
            Name="Cost Center"
            Group="SPFx Content Types"
            Description="Sample content types from web part solution">
        <FieldRefs>
            <FieldRef ID="{060E50AC-E9C1-4D3C-B1F9-DE0BCAC300F6}" />
            <FieldRef ID="{943E7530-5E2B-4C02-8259-CCD93A9ECB18}" />
        </FieldRefs>
    </ContentType>

    <ListInstance
            CustomSchema="schema.xml"
            FeatureId="00bfea71-de22-43b2-a848-c05709900100"
            Title="SPFx List"
            Description="SPFx List"
            TemplateType="100"
            Url="Lists/SPFxList">
    </ListInstance>

</Elements>

Há algumas coisas a serem observadas a partir deste XML:

Estamos disponibilizando dois campos para o site, um tipo de conteúdo e uma instância de lista com esquema personalizado.
As definições usam o esquema padrão Feature Framework, que é conhecido entre os desenvolvedores do SharePoint.
Os campos personalizados estão sendo referenciados no tipo de conteúdo introduzido.
Usamos o atributo CustomSchema no elemento ListInstance para definir o arquivo de tempo de provisionamento de schema.xml para a lista. Dessa maneira, a lista ainda se baseia no modelo de lista pronto (lista personalizada normal '100' neste caso), mas podemos estabelecer uma definição alternativa de provisionamento durante o provisionamento inicial.
Ao provisionar instâncias de lista usando Recursos você deve fornecer a ID do Recurso associada à definição da lista específica. Ao usar o atributoFeatureId você deve fornecer a ID do Recurso que contém a Definição da Lista. Por exemplo: se você estiver provisionando uma instância de uma lista personalizada, o atributo FeatureId deve ser definido como {00bfea71-de22-43b2-a848-c05709900100}.

Para mais detalhes sobre o esquema de manifestação de elementos em destaque, veja: usando os recursos do SharePoint Foundation.

Adicione um arquivo schema.xml para definir a estrutura da lista

Na etapa anterior, fizemos referência ao arquivo schema.xml no atributo CustomSchema do elemento ListInstance, então precisamos incluir tal arquivo no nosso pacote.

Crie um novo arquivo schema.xml na pasta sharepoint\assets.

Copie a seguinte estrutura XML para schema.xml.

<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>

Há algumas coisas a serem observadas a partir deste XML:

O tipo de conteúdo personalizado implantado usando o arquivo elements.xml é referenciado no elemento ContentTypeRef.
Os campos personalizados de nome SPFxAmount e SPFxCostCenter são referenciados no elemento FieldRef.

Para obter mais informações sobre o schema Schema.xml confira: Entendendo os arquivos Schema.xml.

As definições devem ser usadas no pipeline de build

Neste ponto, criamos os arquivos para provisionar os ativos do SharePoint utilizando o esquema de recursos da solução quando ela é implantada. A próxima etapa é incluí-los no arquivo de pacote do SharePoint *.sppkg .

Abra o package-solution.json na pasta config.

O arquivo package-solution.json define os metadados do pacote, conforme mostrado no código a seguir:

Certifique-se de que os novos arquivos de estrutura de recursos estejam incluídos no pacote SharePoint.

Incluir uma definição das características do Quadro de Recursos para o pacote de soluções. Incluir uma definição de JSON para o recurso necessário na estrutura da solução, como mostra o código a seguir:

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    //...
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "isDomainIsolated": false,
    // >>> START
    //     add the following to the package-solution.json file
    "features": [{
      "title": "asset-deployment-webpart-client-side-solution",
      "description": "asset-deployment-webpart-client-side-solution",
      "id": "00000000-0000-0000-0000-000000000000",     // <-- Update new GUID
      "version": "1.0.0.0",
      "assets": {
        "elementManifests": [
          "elements.xml"
        ],
        "elementFiles":[
          "schema.xml"
        ]
      }
    }]
    // <<< END
  },
  "paths": {
    "zippedPackage": "solution/asset-deployment-webpart.sppkg"
  }
}

Há algumas coisas a serem observadas a partir deste XML:

Certifique-se de definir um GUID exclusivo para a id propriedade na feature propriedade.
Você pode tecnicamente ter múltiplas características no pacote porque a features propriedade é uma matriz. No entanto, isto não é recomendado.
elements.xml é referenciado em elementManifests para que seja devidamente embalado para a definição do recurso como um arquivo de manifesto de elementos.
Você pode ter vários arquivos element.xml na definição, e eles seriam executados na ordem em que são mencionados na definição JSON. Normalmente, você deve evitar o uso de vários arquivos element.xml porque isso aumenta a complexidade desnecessariamente. Você pode definir todos os ativos necessários em um arquivo element.xml único.

Implantar e testar o provisionamento de ativos

Agora você está pronto para implantar a solução para SharePoint. Como estamos provisionando ativos diretamente para os sites SharePoint quando a solução é instalada, você não pode testar a capacidade em um Workbench local ou online.

No console, execute o seguinte comando para empacotar sua solução do lado do cliente que contém a web part, para ter a estrutura básica para o empacotamento:
```
gulp bundle
```
Execute o comando a seguir para criar o pacote da solução:
```
gulp package-solution
```
O comando cria o pacote asset-deployment-webpart.sppkg na pasta sharepoint/solution.
Antes de testar o pacote no SharePoint, vamos dar uma olhada rápida nas estruturas padrão criadas para o pacote em relação aos elementos da estrutura de recurso definidos.

Volte para o lado Visual Studio Code e expanda a pasta sharepoint/solution/debug, que contém as estruturas XML brutas a serem incluídas no pacote *.sppkg real.
Implante o pacote que foi gerado no catálogo de aplicativos.

No navegador, navegue até o catálogo de aplicativos do seu inquilino.
Atualize ou arraste e solte oasset-deployment-webpart.sppkg localizado na pasta sharepoint/solution para o catálogo de aplicativos. O SharePoint exibe uma caixa de diálogo e solicita que você confie na solução do lado do cliente para implantar.

Observação

O SharePoint valida o pacote publicado quando ele é implantado. Você só verá o diálogo de confiança se o pacote for válido para implantação. Você também pode ver o status desta validação na coluna Pacote de aplicativo válido no catálogo de aplicativos.
Vá para o site onde você deseja testar o provisionamento de ativos do SharePoint. Pode ser qualquer conjunto de sites no locatário em que você implantou o pacote de solução.
Selecione o ícone de engrenagem na barra de navegação no canto superior direito e então escolha Adicionar um aplicativo para ir para a página de Aplicativos.
Na caixa Pesquisar, insira deployment e selecione ENTER para filtrar seus aplicativos.
Selecione o aplicativo asset-deployment-webpart-client-side-solution para instalar o aplicativo no site. Quando a instalação estiver concluída, atualize a página selecionando F5. Observe como a Lista SPFx personalizada foi provisionada ao site como parte da implantação do pacote de solução.
Selecione Lista SPFx para ir para a lista. Observe como os campos personalizados Quantidade e Centro de custo ficam visíveis automaticamente no modo de exibição padrão da lista.

Definir as ações de atualização para a nova versão

Sempre que você compila uma nova versão da sua solução do SharePoint Framework, pode haver algumas alterações necessárias nos ativos do SharePoint provisionados. Aproveite o suporte à ação de atualização do Feature Framework quando uma nova versão do pacote estiver sendo implantada.

As soluções da Estrutura do SharePoint oferecem suporte às seguintes definições de ação de atualização do Feature Framework:

ApplyElementManifest
AddContentTypeField

Para mais informações sobre as definições de ação de atualização do Feature Framework, veja: Processo de atualização de suplementos do SharePoint.

Adicionar um novo arquivo element.xml para a nova versão

Volte para sua solução no Visual Studio Code.
Crie um novo arquivo elements-v2.xml na pasta sharepoint\assets.

Copie a seguinte estrutura XML em elements-v2.xml, que define uma nova lista do SharePoint a ser provisionada com o nome Nova lista.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <ListInstance
    FeatureId="00bfea71-de22-43b2-a848-c05709900100"
    Title="New List"
    Description="New list provisioned from v2"
    TemplateType="100"
    Url="Lists/NewList">
  </ListInstance>
</Elements>

Importante

Não faça mudanças no GUID neste XML. Isso aponta para a GUID onde o tipo de lista é definido.

Também precisamos de uma definição para ações de atualização do Feature Framework, então crie um novo arquivo upgrade-actions-v2.xml na pasta sharepoint\assets.
Copie a seguinte estrutura XML no upgrade-actions-v2.xml. A referência GUID do recurso no caminho refere-se à pasta criada automaticamente na pasta sharepoint/solution/debug e deve ser atualizada com base na sua solução. Esse GUID também corresponde ao GUID do recurso, que definimos no arquivo package-solution.json.
```
<ApplyElementManifests>
  <ElementManifest Location="{feature-guid}\elements-v2.xml" />
</ApplyElementManifests>
```

Importante

O {feature-guid} deve corresponder ao GUIA do recurso que você adicionou ao arquivo package-solution.json.

Implantar a nova versão para SharePoint

Em seguida, precisamos atualizar tanto a versão de solução quanto a versão de recurso responsável pelo provisionamento do ativo.

Importante

A versão da solução indica ao SharePoint que há uma nova versão da solução do SharePoint Framework disponível. A versão do recurso assegura que as ações de atualização sejam executadas de acordo quando o pacote de solução é atualizado nos sites existentes.

Abra o arquivo package-solution.json da pasta de configuração e atualize os valores da versão da solução e do recurso para 2.0.0.0.

Também precisamos incluir elements-v2.xml na seção elementManifest e incluir o elemento upgradeActions com um ponteiro ao arquivo criado upgrade-actions-v2.xml.

Aqui está o arquivo completo package-solution.json com as mudanças necessárias. Os identificadores da sua solução podem ser ligeiramente diferentes, então concentre-se em adicionar apenas as partes ausentes.

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    //...
    "version": "2.0.0.0",
    "includeClientSideAssets": true,
    "isDomainIsolated": false,
    "features": [{
      "title": "asset-deployment-webpart-client-side-solution",
      "description": "asset-deployment-webpart-client-side-solution",
      "id": "{feature-guid}",
      "version": "2.0.0.0",
      "assets": {
        "elementManifests": [
          "elements.xml",
          "elements-v2.xml"
        ],
        "elementFiles":[
          "schema.xml"
        ],
        "upgradeActions":[
          "upgrade-actions-v2.xml"
        ]
      }
    }]
    //...
  }
}

Importante

Incluímos também o arquivo elements-v2.xml na seção elementManifest. Isso garante que, quando você instalar esse pacote em um site limpo como uma versão 2.0, o resultado final corresponderá aos pacotes atualizados.

Na janela do console, execute o seguinte comando para reempacotar sua solução do lado do cliente que contém a web part, para que possamos preparar a estrutura básica para o empacotamento:
```
gulp bundle
```
Execute o comando a seguir para criar o pacote da solução:
```
gulp package-solution
```
O comando cria uma versão do pacote de solução na pasta sharepoint/solution. Observe que você pode confirmar facilmente na pasta sharepoint/solution/debug se os arquivos XML atualizados estão incluídos no pacote de solução.
Em seguida, você precisa implantar a nova versão que foi gerada no catálogo de aplicativos. Vá para o catálogo de aplicativos do seu locatário.
Atualize ou arraste e solte oasset-deployment-webpart.sppkg localizado na pasta sharepoint/solution para o catálogo de aplicativos. O SharePoint solicita que você confirme a substituição da versão existente.
Escolha Substituir para atualizar a versão mais recente no catálogo de aplicativos.
Selecione Implantar para confiar na versão mais recente.

A coluna Versão do aplicativo para asset-deployment-webpart-client-side-solution foi atualizada para 2.0.0.0.

Atualize uma instância existente no site

Com o pacote atualizado no catálogo de aplicativos, podemos passar para o site de conteúdo SharePoint e fazer a atualização para a instância existente.

Vá para o site em que você implantou a primeira versão da solução da Estrutura do SharePoint.
Acesse a página Conteúdo do site.
Selecione Detalhes no menu de contexto da solução asset-deployment-webpart-client-side-solution.

Isso apresenta os detalhes atuais sobre a solução instalada da Estrutura do SharePoint. Esta página também mostra agora o texto Há uma nova versão deste aplicativo. Obtê-la agora. para indicar que existe uma nova versão disponível.
Selecione o botão BAIXAR para iniciar o processo de atualização do pacote.

Se você mudar para a experiência clássica, poderá ver mais detalhes na ação de atualização real aplicada na solução da Estrutura do SharePoint.

Observação

Como a Estrutura do SharePoint usa a mesma infraestrutura de aplicativo dos suplementos do SharePoint, o status de atualização indica que a atualização pode ocorrer para um suplemento ou um aplicativo.

A atualização pode demorar um pouco, mas quando o status da solução muda para normal novamente atualize a página de conteúdo do site para confirmar se essa nova lista chamada Nova lista foi provisionada como parte do processo de atualização.

Agora, atualizamos com sucesso esta instância para a versão mais recente. Esta opção de estrutura de recursos para o provisionamento de ativos SharePoint é semelhante ao modelo SharePoint Add-in. A principal diferença é que os ativos estão sendo provisionados diretamente para o site normal do SharePoint porque não existe um conceito chamado aplicativo/suplemento Web com soluções do SharePoint Framework.