Depurar soluções da Estrutura do SharePoint em páginas modernas do SharePoint

Ao criar soluções da Estrutura do SharePoint, é possível testá-las em páginas modernas do SharePoint. Para criar extensões da Estrutura do SharePoint, o teste em páginas modernas é a única opção porque neste momento o SharePoint Workbench não oferece suporte ao carregamento de extensões. No entanto, testes em páginas modernas também podem ser usados para depurar web parts, aumentando as vantagens para os desenvolvedores.

Importante

Embora não haja restrições técnicas para depurar soluções locais da Estrutura do SharePoint em páginas modernas do SharePoint, você deve ter cuidado ao usar essa estratégia no locatário de produção. Com esse recurso, você executa um código que não foi testado e verificado de acordo com as políticas da organização e que pode ser prejudicial aos dados de produção.

Depurar extensões da Estrutura do SharePoint em páginas modernas do SharePoint

No momento, a extensão da Estrutura do SharePoint pode ser depurada somente em páginas modernas do SharePoint. O SharePoint Workbench não oferece suporte ao teste de extensões. Dependendo da versão da Estrutura do SharePoint em uso, existem maneiras diferentes de depurar extensões em páginas modernas.

Depurar extensões usando configuração de veiculação

Quando você adiciona uma extensão da Estrutura do SharePoint ao projeto, o gerador Yeoman da Estrutura do SharePoint amplia a configuração desse projeto. Usando essa configuração, é possível iniciar automaticamente uma página moderna do SharePoint no navegador da Web com todos os parâmetros necessários para depurar a extensão nessa página já presente.

Como funciona

Quando você adiciona uma nova extensão da Estrutura do SharePoint ao projeto, o gerador Yeoman da Estrutura do SharePoint adiciona uma nova entrada ao arquivo config/serve.json nesse projeto. Um exemplo de entrada tem a seguinte aparência:

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/spfx-serve.schema.json",
  "port": 4321,
  "https": true,
  "serveConfigurations": {
    "default": {
      "pageUrl": "https://contoso.sharepoint.com/sites/mySite/SitePages/myPage.aspx",
      "customActions": {
        "d7678bd7-b58a-44fc-b9fa-a621a89edcad": {
          "location": "ClientSideExtension.ApplicationCustomizer",
          "properties": {
            "testMessage": "Test message"
          }
        }
      }
    },
    "helloWorld": {
      "pageUrl": "https://contoso.sharepoint.com/sites/mySite/SitePages/myPage.aspx",
      "customActions": {
        "d7678bd7-b58a-44fc-b9fa-a621a89edcad": {
          "location": "ClientSideExtension.ApplicationCustomizer",
          "properties": {
            "testMessage": "Test message"
          }
        }
      }
    }
  }
}

Ao lado da configuração padrão, o gerador Yeoman da Estrutura do SharePoint cria uma entrada para cada extensão que você adiciona ao projeto. Cada entrada contém uma URL da página moderna que deve ser usada para testar a extensão específica, a lista de extensões que devem ser carregadas e, para cada extensão, a lista de propriedades que devem ser definidas nelas. Para usar a configuração de veiculação específica, execute na linha de comando:

gulp serve --config=<name>

por exemplo:

gulp serve --config=helloWorld

Depois de executar esse comando, o gulp inicia o navegador da Web com a página moderna especificada na configuração. A página mostra um pop-up pedindo para confirmar que você agora carregará scripts de depuração.

Após a confirmação, a página é carregada com as extensões que você especificou na configuração de veiculação.

Desabilitando scripts de depuração

Por padrão, quando os scripts de depuração são ativados e permitidos uma vez em uma página, eles serão permitidos em toda a sessão do navegador. Para desativar o carregamento dos scripts de depuração sem encerrar a sessão do navegador ou excluir manualmente os dados da sessão, inclua o parâmetro de URL reset=true na solicitação.

Depurar extensões construindo manualmente a URL de depuração

Se você está trabalhando com uma versão da Estrutura do SharePoint anterior à 1.3.0 e quer depurar uma extensão em uma página moderna, é preciso construir manualmente a URL com os parâmetros necessários. Primeiro, inicie o servidor gulp local, na linha de comando, alterando o diretório de trabalho para a pasta do projeto e executando:

gulp serve --nobrowser

Em seguida, no navegador da Web, navegue até a página moderna na qual você deseja testar a extensão. Após o carregamento da página, copie a URL. Dependendo do tipo de extensão que você quer testar, existem diferentes parâmetros que precisam ser adicionados à URL.

Depurar o Personalizador de Aplicativos

Para depurar o Personalizador de Aplicativo, adicione o seguinte ao URL da sua página moderna:

Cuidado

O recuo de quebras & de linha foi adicionado ao snippet a seguir para legibilidade. O texto a seguir deve estar em uma única linha sem espaços em branco.

?loadSPFX=true
&debugManifestsFile=https://localhost:4321/temp/manifests.js
&customActions={"<extensionId>":{
    "location":"<extensionType>",
    "properties":<propertiesJSON>
}}

Por exemplo:

https://contoso.sharepoint.com/sites/team-a/sitepages/news.aspx
    ?loadSPFX=true
    &debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={
        "e5625e23-5c5a-4007-a335-e6c2c3afa485":{
          "location":"ClientSideExtension.ApplicationCustomizer",
          "properties":{
            "testMessage":"Hello as property!"
          }
        }
    }

Veja a seguir os parâmetros de cadeia de consulta que você precisa adicionar:

Parâmetro	Descrição
loadSPFX=true	Garante que a Estrutura do SharePoint seja carregada na página. Por razões de desempenho, a estrutura não carrega, exceto se pelo menos uma extensão for registrada. Como nenhum componente está registrado, você deve carregar explicitamente a estrutura.
debugManifestsFile	Especifica que você deseja carregar componentes que são atendidos localmente. O carregador procura apenas por componentes no catálogo de aplicativos (para sua solução implantada) e o servidor de manifesto do SharePoint (para as bibliotecas do sistema).
customActions	Simula uma ação personalizada. Ao implantar e registrar esse componente em um site, você criará esse objeto CustomAction e descreverá todas as diferentes propriedades que pode definir nele.

O parâmetro customActions possui os seguintes tokens que devem ser substituídos:

Token	Descrição
<extensionId>	Use o GUID da extensão como a chave para associar à ação personalizada. Isso deve corresponder ao valor de ID da extensão, que está disponível no arquivo de extensão manifest.json.
<extensionType>	O tipo de ação personalizada. Use ClientSideExtension.ApplicationCustomizer para a extensão do Personalizador de Aplicativos.
<propertiesJSON>	Um objeto JSON opcional que contém propriedades que estão disponíveis por meio do membro this.properties.

Com os parâmetros adicionados à URL, recarregue a página no navegador da Web. A página mostra um pop-up pedindo para confirmar que você agora carregará scripts de depuração.

Após a confirmação, a página é carregada com as extensões que você especificou na configuração de veiculação.

Depurar o personalizador de campos

Para depurar o personalizador de campo, adicione o seguinte ao URL da sua página moderna:

Cuidado

O recuo de quebras & de linha foi adicionado ao snippet a seguir para legibilidade. O texto a seguir deve estar em uma única linha sem espaços em branco.

?loadSPFX=true
&debugManifestsFile=https://localhost:4321/temp/manifests.js&fieldCustomizers={
    "<fieldName>":{
      "id":"<fieldCustomizerId>",
      "properties":<propertiesJSON>
    }
}

Por exemplo:

https://contoso.sharepoint.com/sites/team-a/Lists/Orders/AllItems.aspx
  ?loadSPFX=true
  &debugManifestsFile=https://localhost:4321/temp/manifests.js
  &fieldCustomizers={
    "Percent":{
      "id":"45a1d299-990d-4917-ba62-7cb67158be16",
      "properties":{
        "sampleText":"Hello!"
      }
    }
  }

Veja a seguir os parâmetros de cadeia de consulta que você precisa adicionar:

Parâmetro	Descrição
loadSPFX=true	Garante que a Estrutura do SharePoint seja carregada na página. Por razões de desempenho, a estrutura não carrega, exceto se pelo menos uma extensão for registrada. Como nenhum componente está registrado, você deve carregar explicitamente a estrutura.
debugManifestsFile	Especifica que você deseja carregar componentes que são atendidos localmente. O carregador procura por componentes apenas no catálogo de aplicativos (para sua solução implantada) e no servidor de manifesto do SharePoint (para as bibliotecas do sistema).
fieldCustomizers	Indica quais campos em sua lista devem ter sua renderização controlada pelo Personalizador de Campos. O parâmetro ID especifica o GUID da extensão que deve ser usado para controlar a renderização do campo. O parâmetro de propriedades é uma cadeia de texto opcional que contém um objeto JSON que é desserializado em this.properties para sua extensão.

O parâmetro fieldCustomizers possui os seguintes tokens que devem ser substituídos:

Token	Descrição
<fieldName>	O nome interno do campo.
<fieldCustomizerId>	O GUID da extensão do Personalizador de Campos associado a esse campo.
<propertiesJSON>	Os valores de propriedades definidos na extensão. Neste exemplo, sampleText é uma propriedade definida pela extensão.

Com os parâmetros adicionados à URL, recarregue a página no navegador da Web. A página mostra um pop-up pedindo para confirmar que você agora carregará scripts de depuração.

Após a confirmação, a página é carregada com as extensões que você especificou na configuração de veiculação.

Depurar o conjunto de comandos de exibição de lista

Para depurar um conjunto de comandos do modo de exibição de lista, adicione o seguinte ao URL a sua página moderna:

Cuidado

O recuo de quebras & de linha foi adicionado ao snippet a seguir para legibilidade. O texto a seguir deve estar em uma única linha sem espaços em branco.

?loadSPFX=true
&debugManifestsFile=https://localhost:4321/temp/manifests.js
&customActions={"<extensionId>":{
  "location":"<extensionType>",
  "properties":<propertiesJSON>
}}

Por exemplo:

https://contoso.sharepoint.com/sites/team-a/Lists/Orders/AllItems.aspx
  ?loadSPFX=true
  &debugManifestsFile=https://localhost:4321/temp/manifests.js
  &customActions={"a8047e2f-30d5-40fc-b880-b2890c7c16d6":{
    "location":"ClientSideExtension.ListViewCommandSet.CommandBar",
    "properties":{
      "sampleTextOne":"One item is selected in the list.",
      "sampleTextTwo":"This command is always visible."
    }
  }}

Veja a seguir os parâmetros de cadeia de consulta que você precisa adicionar:

Parâmetro	Descrição
loadSPFX=true	Garante que a Estrutura do SharePoint seja carregada na página. Por razões de desempenho, a estrutura não carrega, exceto se pelo menos uma extensão for registrada. Como nenhum componente está registrado, você deve carregar explicitamente a estrutura.
debugManifestsFile	Especifica que você deseja carregar componentes que são atendidos localmente. O carregador procura apenas por componentes no catálogo de aplicativos (para sua solução implantada) e o servidor de manifesto do SharePoint (para as bibliotecas do sistema).
customActions	Simula uma ação personalizada. Você pode definir muitas propriedades neste objeto CustomAction que afetam a aparência e o local do botão. Falaremos sobre eles mais adiante.

O parâmetro customActions possui os seguintes tokens que devem ser substituídos:

Token	Descrição
<extensionId>	GUID da extensão.
<extensionType>	Onde os comandos são exibidos. Os valores possíveis são: ClientSideExtension.ListViewCommandSet.ContextMenu: O menu de contexto do(s) item(ns), ClientSideExtension.ListViewCommandSet.CommandBarO menu do conjunto de comandos superior em uma lista ou biblioteca. ClientSideExtension.ListViewCommandSet: tanto o menu de contexto quanto a barra de comandos (corresponde a SPUserCustomAction.Location="CommandUI.Ribbon").
<propertiesJSON>	Um objeto JSON opcional que contém propriedades que estão disponíveis por meio do membro this.properties.

Com os parâmetros adicionados à URL, recarregue a página no navegador da Web. A página mostra um pop-up pedindo para confirmar que você agora carregará scripts de depuração.

Após a confirmação, a página é carregada com as extensões que você especificou na configuração de veiculação.

Depurar web parts da Estrutura do SharePoint em páginas modernas do SharePoint

Para testar as versões locais das web parts no lado do cliente da Estrutura do SharePoint em páginas modernas do SharePoint no locatário, primeiro inicie o servidor gulp local, alterando o diretório de trabalho para a pasta do projeto e executando na linha de comando:

gulp serve --nobrowser

Em seguida, no navegador da Web, navegue até a página moderna na qual você deseja testar as web parts. Depois que a página for carregada, adicione o seguinte ao URL:

?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js

Por exemplo:

Cuidado

O recuo de quebras & de linha foi adicionado ao snippet a seguir para legibilidade. O texto a seguir deve estar em uma única linha sem espaços em branco.

https://contoso.sharepoint.com/sites/team-a/sitepages/news.aspx
  ?loadSPFX=true
  &debugManifestsFile=https://localhost:4321/temp/manifests.js

A página será recarregada e mostrará um pop-up pedindo para confirmar que você agora carregará scripts de depuração.

Depois de confirmar que deseja carregar as Web Parts que está desenvolvendo, você pode editar a página e, na caixa de ferramentas, selecionar qualquer uma das Web Parts locais.

Adição de valor dos testes de web parts da Estrutura do SharePoint em páginas modernas

Ao criar web parts da Estrutura do SharePoint, é possível testá-las usando o workbench local. Isso não é apenas conveniente, mas também eficiente: cada vez que você alterar algo no seu código, o ambiente de trabalho local irá recarregar automaticamente e mostrar suas últimas alterações.

Em alguns casos, como ao criar web parts que se comunicam com o SharePoint, não é possível usar o workbench local do SharePoint porque você precisa acessar as APIs do SharePoint que podem ser chamadas apenas no contexto de um site do SharePoint. Nesses casos, em vez de usar o ambiente de trabalho local, você pode usar a bancada de trabalho hospedada no SharePoint, que pode ser acessada adicionando /_layouts/15/workbench.aspx ao URL do seu site, por exemplo https://contoso.sharepoint.com/sites/team-a/_layouts/15/workbench.aspx.

Restrições da interface do usuário

O workbench da Estrutura do SharePoint imita convenientemente a tela de páginas modernas do SharePoint. Mas ele não imita todos os aspectos dela. A largura da tela é diferente, nem todas as cores de tema são refletidas, e o workbench não permite testar a experiência completa em que uma web part abrange toda a largura do navegador da Web sem qualquer margem horizontal ou preenchimento.

Funciona com outras web parts e extensões?

Usando o workbench do SharePoint, só é possível testar web parts da sua solução. Mas, e se você quisesse ver como a web part funciona com outras web parts na página? Testar a solução local em páginas modernas usando a abordagem descrita neste artigo é muito mais eficiente do que empacotar o projeto, implantá-lo no catálogo de aplicativos e adicionar a web part à página.

Depurar as Web Parts da Estrutura do SharePoint - uma abordagem alternativa

Se você criar sua solução de Web Part sem o argumento--ship conforme a seguir:

gulp bundle
gulp package-solution

os pacotes gerados referenciarão o código do computador local (https://localhost:4321). É possível implantar a solução no catálogo de aplicativos como faria normalmente.

Em seguida, você pode iniciar seu servidor local executando:

gulp serve --nobrowser

Agora você pode voltar a um site do SharePoint onde a solução foi implantada e adicionar as Web Parts a qualquer página, moderna ou clássica, e o código da web part será carregado a partir do seu ambiente de desenvolvimento local. Você pode depurar suas Web Parts da mesma forma que faria se você correu o gulp serve e adicionou sua Web Part ao Workbench.

Essa abordagem só deve ser utilizada quando você estiver no modo de desenvolvimento. Se você implantar um aplicativo no catálogo de aplicativos que aponta para o seu host local, ele não será executado se o seu ambiente de desenvolvimento não estiver em execução.

Confira também

• Depurar soluções da Estrutura do SharePoint no Visual Studio Code
• Testar web parts da Estrutura do SharePoint facilmente em páginas modernas (Waldek Mastykarz, Rencore)
• Como testar e depurar soluções SPFx no ambiente de produção sem causar impacto (Elio Struyf)
• Gerador Yeoman para a Estrutura do SharePoint
• Visão geral da Estrutura do SharePoint