Implantar sua extensão no SharePoint (Hello World, parte 3)

Artigo
03/21/2023

Este artigo descreve como implantar o Personalizador de Aplicativos da Estrutura do SharePoint no SharePoint (SPFx) e vê-lo funcionando nas páginas modernas do SharePoint.

Antes de começar, verifique se você concluiu os procedimentos nos seguintes artigos:

Compilar sua primeira Extensão da Estrutura do SharePoint (Hello World, parte 1)
Usar espaços reservados de página do Personalizador de Aplicativos (Hello World, parte 2)

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

Há várias maneiras diferentes sobre de implantar e ativar suas extensões da SPFx em sites do SharePoint. A opção correta depende de seus requisitos e objetivos de negócios. As opções principais são as seguintes:

Ativar a extensão em um site específico usando a ativação com base em estrutura do recurso quando a solução é instalada. Esse é o único modelo que dá suporte a ativos no nível de site sendo criados ou implantados como parte da ativação da solução.
Use a opção de implantação com escopo de locatário e ative a extensão em sites específicos de APIs e interfaces do SharePoint.
Use a opção de implantação em todo o locatário para extensões do catálogo de aplicativos. Essa funcionalidade foi introduzida na Estrutura do SharePoint v1.6.

Empacotar o Personalizador de Aplicativos Olá, Mundo

Neste exemplo, ativaremos a extensão em um único site. Isso significa que usaremos a ativação baseada na Estrutura de recurso quando a solução estiver sendo instalada no site.

Na janela do console, vá para o diretório do projeto da extensão criado em Compilar sua primeira Extensão da Estrutura do SharePoint (Hello World, parte 1).
```
cd app-extension
```
Se o gulp serve ainda estiver sendo executado, interrompa a execução pressionado Ctrl+C.

Ao contrário do modo Depurar, para usar uma extensão em páginas modernas do SharePoint, você precisa implantar e registrar a extensão com o SharePoint no escopo conjunto de sites, site ou lista. O escopo define onde e como o Personalizador de Aplicativos está ativo. Nesse cenário específico, registraremos o Personalizador de Aplicativos usando o escopo do conjunto de sites.

Antes de empacotarmos nossa solução, incluiremos o código necessário para automatizar a ativação da extensão quando a solução for instalada no site. Nesse caso, usaremos elementos da Estrutura de Recursos para executar essas ações no pacote de solução, mas você também pode associar o Personalizador de Aplicativos a um site do SharePoint usando as APIs REST ou CSOM do SharePoint como parte do provisionamento do site.
Instale o pacote de solução no site em que ele deve ser instalado para que o manifesto de extensão seja permitido para execução.
Associe o Personalizador de Aplicativos ao escopo planejado. Isso pode ser feito programaticamente por meio das APIs REST ou CSOM do SharePoint ou usando a Estrutura de Recursos no pacote de solução da Estrutura do SharePoint. Você precisa associar as seguintes propriedades no objeto UserCustomAction no nível do conjunto de sites, do site ou da lista.
- ClientSideComponentId: esse é o identificador (GUID) da extensão SPFx que foi instalada no catálogo de aplicativos.
- clientSideComponentProperties: esse é um parâmetro opcional que pode ser usado para fornecer propriedades para a instância de extensão SPFx.
Você pode controlar o requisito para adicionar uma solução que contém sua extensão ao site com a configuração skipFeatureDeployment no arquivo ./config/package-solution.json. Mesmo que você não exija que a solução seja instalada no site, é necessário associar ClientSideComponentId a objetos específicos para que a extensão fique visível.

Revisar o arquivo elements.xml existente para definições do SharePoint

Nas etapas a seguir, vamos examinar a definição de CustomAction que foi criada automaticamente para a solução como parte da estruturação para ativá-la em um site quando ela é instalada.

Retorne ao pacote de solução no Visual Studio Code (ou no seu editor preferencial).
Abra o arquivo ./sharepoint/assets/elements.xml.

Revisar a estrutura XML existente no arquivo elements.xml. A propriedade ClientSideComponentId foi atualizada com base na ID exclusiva do Personalizador de Aplicativos definida no arquivo./src/extensions/helloWorld/HelloWorldApplicationCustomizer.manifest.json.

A propriedade ClientSideComponentProperties é definida como a estrutura padrão e propriedades JSON para nossa extensão. Observe como o JSON tem escape para que possamos defini-lo corretamente em um atributo XML.

A configuração usa a localização específica de ClientSideExtension.ApplicationCustomizer para definir que se trata de um Personalizador de Aplicativos. Como elements.xml está associado a um recurso com escopo da Web, essa CustomAction será automaticamente adicionada à propriedade Web.UserCustomAction do site em que a solução está sendo instalada.

Certifique-se de que a configuração corresponda às alterações feitas nas propriedades do Personalizador de Aplicativos. Defina a propriedade ClientSideComponentProperties para a seguinte cadeia de caracteres JSON codificada em HTML que contém os valores da propriedade:

{&quot;Top&quot;:&quot;Top area of the page&quot;,&quot;Bottom&quot;:&quot;Bottom area in the page&quot;}

E quanto ao arquivo ClientSideInstance.xml na pasta assets?

O arquivo ClientSideInstance.xml é usado com a Implantação de extensões da Estrutura do SharePoint para todos os locatários. Você pode usar esse arquivo para adicionar uma entrada à lista de Extensões em Todo o Locatário centralizada no site do catálogo de aplicativos do locatário se você usa a opção de implantação com escopo de locatário. Nesse tutorial, selecionamos a solução para ser instalada no nível do site, o que significa que este arquivo é ignorado quando a solução é ativada no catálogo de aplicativos.

A lista de Extensões em Todo o Locatário lista pode ser usada para ativar automaticamente extensões no locatário de um local centralizado. A implantação em todo o locatário é compatível com personalizadores do aplicativo e conjuntos de comandos do modo de exibição de lista. Você pode especificar definições de destino diferentes, como ativação com base no tipo de site ou no tipo de lista.

Para este tutorial, não precisamos deste arquivo, pois ativaremos a solução em um site específico usando o recurso de provisionamento baseado em XML.

Dica

Para saber mais, confira Implantação para todos os Locatários para Extensões da Estrutura do SharePoint.

As definições devem ser usadas na conta dentro do pipeline de build

O arquivo ./config/package-solution.json define os metadados do pacote. Para garantir que o arquivo elements.xml seja levado em conta enquanto a solução está sendo empacotada, o scaffolding padrão inclui a configuração necessária para definir uma definição de recurso do Feature Framework no pacote de solução.

A propriedade elementManifests original no arquivo ./config/package-solution.json tem esta aparência:

"assets": {
  "elementManifests": [
    "elements.xml",
    "clientsideinstance.xml"
  ]
}

Remova a entrada para clientsideinstance.xml sob elementManifests, pois ela não é necessária para este tutorial:

"assets": {
  "elementManifests": [
    "elements.xml"
  ]
}

O ./config/package-solution.json agora é semelhante ao exemplo a seguir após as edições necessárias:

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "app-extension-client-side-solution",
    "id": "65e15d73-515b-4d57-8c92-66ba5890c7b4",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "skipFeatureDeployment": true,
    "isDomainIsolated": false,
    "developer": {
      "name": "",
      "websiteUrl": "",
      "privacyUrl": "",
      "termsOfUseUrl": "",
      "mpnId": "Undefined-1.14.0"
    },
    "metadata": {
      "shortDescription": {
        "default": "app-extension description"
      },
      "longDescription": {
        "default": "app-extension description"
      },
      "screenshotPaths": [],
      "videoUrl": "",
      "categories": []
    },
    "features": [
      {
        "title": "Application Extension - Deployment of custom action",
        "description": "Deploys a custom action with ClientSideComponentId association",
        "id": "41b490c7-49f7-4db4-b7ea-c632d0fb9785",
        "version": "1.0.0.0",
        "assets": {
          "elementManifests": [
            "elements.xml"
          ]
        }
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/app-extension.sppkg"
  }
}

Implantar a extensão no SharePoint Online e hospedar o JavaScript por meio do localhost

Agora, você está pronto para implantar a solução em um site do SharePoint e para ter a CustomAction associada no nível do site.

Na janela do console, insira o seguinte comando para empacotar sua solução do lado do cliente que contém a extensão, para que possamos preparar a estrutura básica para o empacotamento:
```
gulp bundle
```
Em seguida, execute o comando a seguir para que o pacote da solução seja criado:
```
gulp package-solution
```
Esse comando cria o seguinte pacote: ./sharepoint/solution/app-extension.sppkg.
Agora, você precisa implantar no catálogo de aplicativos. Acesse o catálogo de aplicativos do seu locatário e carregue ou arraste e solte o arquivo ./sharepoint/solution/app-extension.sppkg na lista Aplicativos do SharePoint. O SharePoint exibe um painel que solicita que você habilite a solução do lado do cliente.

Não atualizamos as URLs para hospedar a solução para essa implantação, portanto, a URL ainda aponta para https://localhost:4321.
Selecione o botão de opção Habilitar somente este aplicativo e selecione o botão Habilitar aplicativo.
Voltar ao console e verifique se a solução está em execução. Se ele não estiver em execução, execute o seguinte comando na pasta de solução:
```
gulp serve --nobrowser
```
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 escolha Adicionar um aplicativo para ir para a página Aplicativos.
Na caixa Pesquisar, insira aplicativo e pressione Enter para filtrar seus aplicativos.
Escolha o aplicativo app-extension-client-side-solution para instalar a solução no site. Quando a instalação estiver concluída, navegue de volta para o site onde você instalou o aplicativo.

Agora é possível ver o cabeçalho e o rodapé sendo renderizados, assim como com os parâmetros de consulta de depuração.

Próximas etapas

Parabéns, você implantou uma extensão em uma página moderna do SharePoint a partir do Catálogo de Aplicativos!

É possível continuar compilando sua extensão Hello World no próximo tópico, Hospedar extensão a partir da CDN do Office 365 (Hello World, parte 4) onde você aprende como implantar e carregar ativos de extensão de uma CDN em vez do localhost.

Compartilhar via