Implantação para todos os Locatários para Extensões da Estrutura do SharePoint

A opção Implantação em Todos os Locatários de Extensões da Estrutura do SharePoint (SPFx) é compatível com personalizadores de aplicativos e conjuntos de comandos do modo de exibição de lista. É uma opção fácil para os gerenciadores de catálogo de aplicativos de locatários gerenciarem quais extensões são ativadas por padrão no locatário ou com base nos modelos de web/lista usados nos sites.

Observação

As extensões da Estrtura do SharePoint são compatíveis com experiências modernas, seja qual for o modelo de site real usado quando o site de conteúdo foi criado.

Quando os desenvolvedores criam uma nova solução de extensão da Estrutura do SharePoint usando os pacotes Yeoman padrão da Estrutura do SharePoint, a automação é incluída no pacote de soluções para ativar a extensão no locatário.

Aviso

A partir da Estrutura do SharePoint v1.6, a estrutura padrão cria automaticamente os arquivos de exemplo na Solução do SharePoint para ativar a extensão nos locatários, caso você queira usar a opção de implantação com escopo de locatário.

A solução da Estrutura do SharePoint deverá ser configurada para usar a implantação da solução com escopo de locatário para soluções da Estrutura do SharePoin, para poder ativar automaticamente as extensões nos locatários usando a funcionalidade de Implantação em Todos os Locatários. Ou seja, o atributo skipFeatureDeployment no package-solution.json precisa ser definido como true.

Controle da implantação em todos os locatários no conjunto de sites de catálogo de aplicativos

O conjunto de sites de catálogo de aplicativos é usado para implantar suplementos do SharePoint e componentes da Estrutura do SharePoint no locatário. Esse conjunto de sites é criado pelo administrador de locatários e é usado para gerenciar quais personalizações estão disponíveis para usuários finais em conjuntos de sites de conteúdo real.

O conjunto de sites de catálogo de aplicativos contém uma lista de extensões em todos os locatários que pode ser usada para gerenciar as ativações da Extensão da Estrutura do SharePoint no locatário. Essa lista pode ser acessada na página conteúdos do site do site de catálogo de aplicativos.

As Extensões da Estrutura do SharePoint específicas podem ser ativadas no nível do locatário ao adicionar as entradas na lista Extensão em todos os locatários. Cada entrada pode ser direcionada para o modelo de web específico ou para um tipo de lista, dependendo dos requisitos funcionais.

Essas configurações específicas de lista são resolvidas no tempo de execução quando os usuários finais acessarem páginas em conjuntos de sites de conteúdo. Isso significa que as alterações aplicadas a essa lista estão disponíveis para sites novos e existentes no locatário.

As soluções de Estrutura do SharePoint podem conter automação que adiciona automaticamente as entradas na lista de Extensão em Todos os Locatários quando a solução é adicionada

Importante

Leva até 20 minutos para que a funcionalidade seja ativada após a primeira entrada ser adicionada à lista Extensões em Todos os Locatários de um locatário específico.

Descrição da lista de implantação em todos os locatários

A ID do componente deve existir no locatário para que seja possível adicionar uma entrada a ela.

Coluna	Tipo	Descrição
Título	String	Título da entrada. Pode ser entrada descritiva para o registro.
ID do componente	Guid	ID de manifesto do componente. Deve estar no formato GUID e o componente deve existir no catálogo de aplicativos.
Propriedades do componente	String	Propriedades do componente opcional.
Modelo da Web	String	Pode ser usada na extensão de destino apenas no modelo da Web específico. Veja os valores possíveis na tabela abaixo.
Modelo de lista	int	Lista o tipo como um número. Veja os valores possíveis na tabela abaixo.
Local	String	Local da entrada. Existem diferentes locais de suporte para personalizadores de aplicativos e Conjuntos de comandos de exibição de lista.
Sequência	int	Sequência da entrada na renderização.
Propriedades do Host	Cadeia de caracteres	Configurações adicionais do lado do servidor, como a altura alocada para os espaços reservados.
Desabilitado	Boolean	A entrada está ativada ou desativada.

Para a coluna Modelo da Web, qualquer definição de modelo da Web é tecnicamente compatível. A tabela a seguir define os modelos mais comumente usados.

Modelo	ID do modelo da Web
Site da equipe associado ao grupo	GROUP#0
Site de Comunicação	SITEPAGEPUBLISHING#0
Site de equipe moderno sem um grupo	STS#3
Site de equipe clássico	STS#0
Site de publicação clássico	BLANKINTERNET#0

Para a coluna Modelo da lista, qualquer ID da lista é tecnicamente compatível, mas apenas o subconjunto de tipos de lista clássicos proporciona suporte a experiências modernas.

Lista	Id da lista
Lista personalizada	100
Biblioteca de documentos	101

Os valores de local com suporte são os seguintes. Eles são específicos para o tipo de componente.

Valor	Tipo de componente	Descrição
ClientSideExtension.ApplicationCustomizer	Personalizador de aplicativos	Necessário para personalizador de aplicativo.
ClientSideExtension.ListViewCommandSet.ContextMenu	Conjunto de comandos ListView	Mostra os botões de Exibição da lista no Menu de contexto para itens em uma lista.
ClientSideExtension.ListViewCommandSet.CommandBar	Conjunto de comandos ListView	Mostra os botões de Exibição de lista na Barra de comandos da lista.
ClientSideExtension.ListViewCommandSet	Conjunto de comandos ListView	Mostra os botões de Exibição de lista na barra de comando e no menu de contexto.

Observação

Tecnicamente, essa lista define as entradas dinâmicas que serão automaticamente adicionadas à coleção UserCustomAction da Web ou da lista quando uma página de um site for renderizada. As informações da lista são armazenadas em cache e a saída de conteúdo faz parte da renderização da página no tempo de execução.

Automatizar a implantação em todo o locatário no pacote de soluções

O gerador da Estrutura do SharePoint adiciona o arquivo ./sharepoint/assets/ClientSideInstance.xml a novas soluções quando o tipo de componente inicial selecionado é uma extensão.

O ClientSideInstance.xml é considerado na ativação da solução no Catálogo de Aplicativos se o atributo skipFeatureDeployment estiver definido como verdadeiro no arquivo package-solution.json.

Este arquivo contém por padrão a seguinte estrutura. O elemento ClientSideComponentInstance instrui o SharePoint para adicionar automaticamente uma entrada na lista de Implantação em todos os locatários quando o pacote de solução for adicionado ao catálogo de aplicativos.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <ClientSideComponentInstance
      Title="MyAppCust"
      Location="ClientSideExtension.ApplicationCustomizer"
      ComponentId="917a86f2-15c1-403e-bbe1-59c6bd50d1e1"
      Properties="{&quot;testMessage&quot;:&quot;Test message&quot;}">
  </ClientSideComponentInstance>
</Elements>

Se você selecionou o SharePoint Online apenas (mais recente) como o ambiente de destino selecionado quando a solução Estrutura do SharePoint foi criada, o arquivo ClientSideInstance.xml também será referenciado no package-solution.json, para que ele seja incluído dentro do arquivo *.sppkg, quando você empacota sua solução.

Importante

Se você selecionar outro ambiente de destino, enquanto o arquivo ClientSideInstance.xml for adicionado ao projeto, ele não será incluído no arquivo package-solution.json. Embora o SharePoint Server 2019 (que inclui a Estrutura do SharePoint v1.4, confira Recursos compatíveis com para obter detalhes) dê suporte à implantação com escopo de locatário, mas não ofereça suporte à implantação para todos os locatários (adicionado à Estrutura do SharePoint v1.6, consulte a Implantação de extensões para todos os locatários para obter detalhes).

Se esse arquivo for referenciado no package-solution.json, carregar o arquivo *.sppkg gerado no catálogo de aplicativos de locatário SharePoint Server 2019 gerará uma exceção.

Observação

Se você não quiser que esse arquivo esteja presente no arquivo *.sppkg , poderá remover isso facilmente do processo de empacotamento atualizando o arquivo package-solution.json .

O elemento ClientSideComponentInstance é compatível com os seguintes atributos.

Atributo	Obrigatório	Descrição
Title	Sim	Título da entrada. Pode ser entrada descritiva para o registro.
Location	Sim	Entrada de local para o registro de extensão
ComponentId	Sim	ID de manifesto do componente
Properties	Sim	Propriedades opcionais do componente. Observe que este atributo é obrigatório no nível xml, que pode ser definido como string vazia, caso nenhuma propriedade seja necessária. O valor também precisa ser codificado corretamente para que os valores de propriedades possam ser fornecidos no formato xml.
ListTemplateId	Não	A ID do tipo de modelo de lista opcional para a qual a extensão deve ser ativada
WebTemplateId	Não	A ID do modelo da Web opcional que define o tipo de site no qual a extensão deve ser ativada
Sequence	Não	Ordem de sequência de ativação opcional para as extensões. Usado se várias extensões forem ativadas no mesmo escopo.
HostProperties	Não	Configurações opcionais do lado do servidor, como a definição de altura pré-configurada para espaços reservados.

A definição xml abaixo mostra como os valores opcionais podem ser usados como parte do registro.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <ClientSideComponentInstance
      Title="MyAppCust"
      Location="ClientSideExtension.ApplicationCustomizer"
      ComponentId="917a86f2-15c1-403e-bbe1-59c6bd50d1e1"
      Properties="{&quot;testMessage&quot;:&quot;Test message&quot;}"
      ListTemplateId="100"
      WebTemplateId="GROUP#0"
      Sequence="10"
      HostProperties="{&quot;preAllocatedApplicationCustomizerTopHeight&quot;:&quot;50&quot;,&quot;preAllocatedApplicationCustomizerBottomHeight&quot;:&quot;50&quot;}">
  </ClientSideComponentInstance>
</Elements>

Quando um administrador adiciona uma solução que tem um arquivo ClientSideInstance.xml dentro dele ao Catálogo de Aplicativos, uma mensagem de aviso específica é mostrada para garantir que a presença da configuração automatizada seja conhecida.

Após a implantação da solução, o administrador pode alterar as configurações de implantação da lista de Extensão em Todos os Locatários.