Depurar Suplementos do Office no Visual Studio

Este artigo descreve como depurar o código do lado do cliente em Suplementos do Office criados com um dos modelos de projeto de suplemento do Office no Visual Studio 2022. Para obter informações sobre como depurar o código do lado do servidor nos Suplementos do Office, confira Visão geral da depuração de Suplementos do Office – lado do servidor ou do lado do cliente?.

Observação

Você não pode usar o Visual Studio para depurar suplementos no Office no Mac. Para obter informações sobre a depuração em um Mac, consulte Depurar suplementos do Office em um Mac.

Examinar as propriedades de compilação e depuração

Antes de começar a depurar, examine as propriedades de cada projeto para confirmar que o Visual Studio abrirá o aplicativo do Office desejado e que outras propriedades de build e depuração são definidas adequadamente.

Propriedades do projeto de suplemento

Abra a janela Propriedades do projeto de suplemento para revisar as propriedades do projeto.

1. No Explorador de soluções Escolha o projeto do suplemento (não o projeto do aplicativo Web).

2. Na barra de menus, escolha Exibir, >Janela Propriedades.

A tabela a seguir descreve as propriedades do projeto.

Propriedade	Descrição
Iniciar Ação	Especifica o modo de depuração do suplemento. Isso deve ser definido como Cliente da Área de Trabalho do Office quando você quiser depurar no Microsoft 365 no Windows. Para depurar no Microsoft 365 na Web, ele deve ser definido como Microsoft Edge.
Iniciar documento (apenas suplementos Excel, PowerPoint e Word)	Especifica o documento a ser aberto quando você iniciar o projeto. Em um novo projeto, isso é definido como [Nova Pasta de Trabalho do Excel], [Novo documento de Word]ou [Nova Apresentação do PowerPoint]. Para especificar um documento específico, siga as etapas em Usar um documento existente para depurar o suplemento.
Projeto da Web	Especifica o nome do projeto Web associado ao suplemento.
Email Address (Apenas suplementos do Outlook)	Especifica o endereço de email da conta de usuário no Exchange Server ou no Exchange Online que você quer usar para testar o suplemento do Outlook. Se estiver em branco, você será solicitado para o endereço de email quando iniciar a depuração.
EWS Url (Apenas suplementos do Outlook)	Especifica a URL do Exchange Web Services (por exemplo: https://www.contoso.com/ews/exchange.aspx). Essa propriedade pode ficar em branco.
OWA Url (Apenas suplementos do Outlook)	Especifica a URL Outlook na Web (por exemplo: https://www.contoso.com/owa). Essa propriedade pode ficar em branco.
Usar autenticação multifator (Apenas suplementos do Outlook)	Especifica o valor booliano que indica se a autenticação multifator deve ser usada. O padrão é falso, mas a propriedade não tem efeito prático. Se você normalmente precisar fornecer um segundo fator para fazer logon na conta de email, será solicitado ao iniciar a depuração.
Nome de Usuário (Apenas suplementos do Outlook)	Especifica o nome da conta de usuário no Exchange Server ou no Exchange Online com a qual você deseja testar o suplemento do Outlook. Essa propriedade pode ficar em branco.
Arquivo do projeto	Especifica o nome do arquivo que contém informações de compilação, configuração e outras informações sobre o projeto.
Pasta do projeto	Especifica o local do arquivo do projeto.
Configuração de implantação ativa (presente somente ao depurar o Excel, PowerPoint ou Word na Web)	Especifica a configuração de implantação. Isso deve ser definido como Padrão.
Conexão do Servidor (presente somente ao depurar o Excel, PowerPoint ou Word na Web)	Especifica se o projeto se conecta ao serviço do SharePoint especificado na propriedade URL do Site . Isso deve ser definido como Online.
URL do site (presente somente ao depurar o Excel, PowerPoint ou Word na Web)	Especifica a URL completa e absoluta do locatário do SharePoint que você deseja hospedar as páginas de suplemento ao depurar. Por exemplo, https://mysite.sharepoint.com/

Observação

Para um suplemento do Outlook, você pode optar por especificar valores para uma ou mais propriedades de suplementos do Outlook apenas na janela Propriedades , mas isso não é necessário.

Propriedades do projeto de aplicativo Web

Abra a janela Propriedades do projeto do aplicativo Web para revisar as propriedades do projeto.

1. Em Gerenciador de Soluções, escolha o projeto do aplicativo Web.

2. Na barra de menus, escolha Exibir, >Janela Propriedades.

A tabela a seguir descreve as propriedades do projeto de aplicativo web que são mais relevantes para projetos de suplementos do Office.

Propriedade	Descrição
SSL habilitado	Especifica se o SSL está habilitado no site. Essa propriedade deve ser definida como Verdadeira para projetos de suplementos do Office.
URL SSL	Especifica a URL HTTPS segura para o site. Somente leitura.
URL	Especifica a URL HTTP para o site. Somente leitura.
Arquivo do projeto	Especifica o nome do arquivo que contém informações de compilação, configuração e outras informações sobre o projeto.
Pasta do projeto	Especifica o local do arquivo do projeto. Somente leitura. O arquivo de manifesto do Visual Studio gerado no tempo de execução é escrito para a pasta bin\Debug\OfficeAppManifests neste local.

Depurar um projeto de suplemento na área de trabalho do Windows

Esta seção descreve como iniciar e depurar um suplemento no Office da área de trabalho no Windows; ou seja, quando a propriedade Iniciar Ação do projeto de suplemento é definida como Cliente da Área de Trabalho do Office.

Iniciar o projeto de suplemento

Inicie o projeto escolhendo Depurar>Iniciar Depuração na barra de menus ou pressione o botão F5. O Visual Studio cria automaticamente a solução e inicia o aplicativo host do Office.

Quando o Visual Studio cria o projeto, ele executa as seguintes tarefas:

1. Cria uma cópia do arquivo de manifesto XML e o adiciona ao _ProjectName_\bin\Debug\OfficeAppManifests diretório. O aplicativo do Office que hospeda seu suplemento consome essa cópia quando você inicia o Visual Studio e depura o suplemento.

2. Cria um conjunto de entradas de registro no computador Windows que permite que o suplemento apareça no aplicativo do Office.

3. Cria o projeto do aplicativo Web e, em seguida, o implanta no servidor Web do IIS local (https://localhost).

4. Se este for o primeiro projeto de suplemento que você implantou no servidor Web do IIS local, você poderá ser solicitado a instalar um Certificado de Self-Signed no repositório certificado raiz confiável do usuário atual. Isso é necessário para que o IIS Express exiba o conteúdo do seu suplemento corretamente.

Observação

Se o Office usar o edge legacy webview control (EdgeHTML) para executar suplementos em seu computador Windows, o Visual Studio poderá solicitar que você adicione uma isenção de loopback de rede local. Isso é necessário para que o controle webview possa acessar o site implantado no servidor Web do IIS local. Você também pode alterar essa configuração a qualquer momento no Visual Studio, em Ferramentas>Opções>Ferramentas do Office (Web)>Depuração do Suplemento da Web. Para descobrir qual controle de visão da Web é usado em seu computador Windows, consulte Navegadores e controles webview usados pelos Suplementos do Office.

Depois, o Visual Studio faz o seguinte:

1. Modifica o elemento SourceLocation do arquivo de manifesto XML (que foi copiado para o _ProjectName_\bin\Debug\OfficeAppManifests diretório) substituindo o ~remoteAppUrl token pelo endereço totalmente qualificado da página inicial (por exemplo, https://localhost:44302/Home.html).

2. Inicia o projeto de aplicativo Web no IIS Express.

3. Valida o manifesto.

   Importante

   Se você receber erros de validação para o manifesto, pode ser que os arquivos de esquema de manifesto do Visual Studio não tenham sido atualizados para dar suporte aos recursos mais recentes. Sua primeira etapa de solução de problemas deve ser substituir um ou mais desses arquivos pelas versões mais recentes. Para obter instruções detalhadas, consulte Erros de validação de esquema de manifesto em projetos do Visual Studio.

4. Abre o aplicativo do Office e carrega o suplemento.

Depurar o suplemento

O melhor método para depurar um suplemento no Visual Studio 2022 depende se o suplemento está em execução no WebView2, que é o controle webview associado ao Microsoft Edge (Chromium) ou a um controle webview mais antigo. Para determinar qual controle de visão da Web está sendo usado, consulte Navegadores e controles de visão da Web usados pelos Suplementos do Office. Se o computador estiver usando o WebView2, consulte Usar o depurador interno do Visual Studio para depurar na área de trabalho. Para qualquer outro controle de visão da Web, consulte Usar as ferramentas de desenvolvedor do navegador para depurar na área de trabalho.

Usar o depurador interno do Visual Studio para depurar na área de trabalho

1. Defina pontos de interrupção, conforme necessário, nos arquivos JavaScript ou TypeScript de origem. Você pode fazer isso antes ou depois de iniciar o suplemento, conforme descrito na seção anterior Iniciar o projeto de suplemento. Se a configuração de um ponto de interrupção fizer com que o servidor do IIS (Serviços de Informações da Internet) seja desligado, reinicie a depuração depois de definir seus pontos de interrupção.

2. Quando o suplemento estiver em execução, use a interface do usuário do suplemento para executar o código que contém seus pontos de interrupção.

Importante

Pontos de interrupção definidos ou Office.initializeOffice.onReady não são atingidos. Para depurar esses métodos, consulte Depurar as funções inicializar e onReady.

Dica

Se você encontrar algum problema, haverá mais informações em Depurar um aplicativo JavaScript ou TypeScript no Visual Studio.

Usar as ferramentas de desenvolvedor do navegador para depurar na área de trabalho

1. Siga as etapas na seção anterior Iniciar o projeto de suplemento.

2. Inicie o suplemento no aplicativo do Office se ele ainda não estiver aberto. Por exemplo, se for um suplemento de painel de tarefas, ele terá adicionado um botão à faixa de opções Home (por exemplo, um botão Mostrar Painel de Tarefas ). Selecione o botão na faixa de opções.

   Observação

   Se o suplemento não estiver carregado pelo Visual Studio, você poderá ausudá-lo manualmente. Siga as instruções para Sideload de um Suplemento do Office para testes para sua plataforma.

   Na lista de suplementos disponíveis, localize a seçãosuplementos do desenvolvedor e selecione o seu suplemento para registrar.

   Dica

   O painel de tarefas pode aparecer em branco quando for aberto pela primeira vez. Nesse caso, ele deve renderizar corretamente quando você iniciar as ferramentas de depuração em uma etapa posterior.

3. Abra o menu de personalidade e escolha Anexar um depurador. Essa ação abre as ferramentas de depuração para o controle webview que o Office está usando para executar suplementos em seu computador Windows. Você pode definir pontos de interrupção e percorrer o código, conforme descrito em um dos seguintes artigos:

   • Depurar os suplementos usando as ferramentas de desenvolvedor para o Internet Explorer
   • Depurar suplementos usando ferramentas de desenvolvedor para Edge Legacy
   • Depurar suplementos usando ferramentas de desenvolvedor no Microsoft Edge (baseado em Chromium)

4. Para fazer alterações no código, primeiro interrompa a sessão de depuração no Visual Studio e feche o aplicativo do Office. Faça suas alterações e inicie uma nova sessão de depuração.

Depurar um projeto de suplemento no Microsoft 365 na Web

Esta seção descreve como iniciar e depurar um suplemento na área de trabalho Office na Web; ou seja, quando a propriedade Iniciar Ação do projeto de suplemento é definida como Microsoft Edge.

Iniciar o projeto de suplemento na Web

Inicie o projeto escolhendo Depurar>Iniciar Depuração na barra de menus ou pressione o botão F5. O Visual Studio cria automaticamente a solução e inicia a página de host de aplicativos do Office de sua locação do Microsoft 365.

Observação

Ao depurar um suplemento na Web, você pode obter um erro de AADSTS50011 semelhante ao seguinte:

"O URI {Full absolute URL to add-in home page} de redirecionamento especificado na solicitação não corresponde às URIs de redirecionamento configuradas para o aplicativo ... "

Isso ocorre porque novos aplicativos Web implantados no SharePoint podem levar até 24 horas para estarem disponíveis. Para tornar seu suplemento depurável imediatamente, siga as seguintes etapas:

1. Pare de depurar no Visual Studio.

2. Create um script do PowerShell com as linhas a seguir. Substitua o espaço reservado {Full absolute URL to add-in home page} pela URL de redirecionamento na mensagem de erro; por exemplo, "https://contoso-79d42f062409ae.sharepoint.com/_forms/default.aspx".

   Connect-MgGraph -Scopes Application.ReadWrite.All
   $sharepointPrincipal = Get-MgServiceprincipal -Filter "AppId eq '00000003-0000-0ff1-ce00-000000000000'"
   $sharepointPrincipal | fl
   $replyUrls = $sharepointPrincipal.ReplyUrls
   $replyUrls += "{Full absolute URL to add-in home page}"
   Update-MgServiceprincipal -ServicePrincipalId $sharepointPrincipal.Id -ReplyUrls $replyUrls
   

3. Execute o script no PowerShell.

4. Reinicie o projeto escolhendo Depurar>Iniciar Depuração na barra de menus ou pressione o botão F5.

Quando o Visual Studio cria o projeto, ele executa as tarefas a seguir.

1. Solicita credenciais de logon. Se você for solicitado a entrar repetidamente ou se receber um erro não autorizado, o Auth Básico poderá ser desabilitado para contas em seu locatário do Microsoft 365. Nesse caso, tente usar uma conta da Microsoft. Você também pode tentar definir a propriedade Usar a auth multifator como True no painel de propriedades do projeto de suplemento. Consulte Propriedades de projeto de suplemento.

2. Cria uma cópia do arquivo de manifesto XML e o adiciona ao _ProjectName_\bin\Debug\OfficeAppManifests diretório. O Microsoft 365 consome essa cópia quando você inicia o Visual Studio e depura o suplemento.

3. Cria o projeto de aplicativo Web e, em seguida, o implanta no locatário do Microsoft 365.

Depois, o Visual Studio faz o seguinte:

1. Modifica o elemento SourceLocation do arquivo de manifesto XML (que foi copiado para o _ProjectName_\bin\Debug\OfficeAppManifests diretório) substituindo o ~remoteAppUrl token pelo endereço totalmente qualificado da página inicial (por exemplo, https://contoso-79d42f062409ae.sharepoint.com/_forms/default.aspx).

2. Inicia o projeto do aplicativo Web.

3. Valida o manifesto.

   Importante

   Se você receber erros de validação para o manifesto, pode ser que os arquivos de esquema de manifesto do Visual Studio não tenham sido atualizados para dar suporte aos recursos mais recentes. Sua primeira etapa de solução de problemas deve ser substituir um ou mais desses arquivos pelas versões mais recentes. Para obter instruções detalhadas, consulte Erros de validação de esquema de manifesto em projetos do Visual Studio.

4. Abre a página host do aplicativo do Office da sua locação do Microsoft 365 no Microsoft Edge.

Depurar o suplemento na Web

O melhor método para depurar um suplemento no Visual Studio 2022 depende se o suplemento está em execução no WebView2, que é o controle webview associado ao Microsoft Edge (Chromium) ou a um controle webview mais antigo. Para determinar qual controle de visão da Web está sendo usado, consulte Navegadores e controles de visão da Web usados pelos Suplementos do Office. Se o computador estiver usando o WebView2, consulte Usar o depurador interno do Visual Studio para depurar na Web. Para qualquer outro controle de visão da Web, consulte Usar as ferramentas de desenvolvedor do navegador para depurar na Web.

Usar o depurador interno do Visual Studio para depurar na Web

1. Defina pontos de interrupção, conforme necessário, nos arquivos JavaScript ou TypeScript de origem. Você pode fazer isso antes ou depois de iniciar o suplemento, conforme descrito na seção anterior Iniciar o projeto de suplemento na Web.

2. Quando o suplemento estiver em execução, use a interface do usuário do suplemento para executar o código que contém seus pontos de interrupção.

Dica

• Às vezes, em Outlook na Web, o depurador do Visual Studio não é anexado. Se você receber erros pelos pontos de interrupção que indicam que eles não serão atingidos, use as ferramentas de desenvolvedor do navegador para anexar ao depurador do Visual Studio: depois de pressionar o F5 para iniciar a depuração e Outlook na Web tiver sido aberto, siga as quatro primeiras etapas no Usar as ferramentas do desenvolvedor do navegador para depurar na Web. (Use as instruções para o Microsoft Edge (baseado em Chromium).) Depois de definir um ponto de interrupção nas ferramentas do navegador e ele for atingido, a execução pausa o ponto de interrupção nas ferramentas do navegador e no Visual Studio. Isso indica que o depurador do Visual Studio está anexado. Neste ponto, você pode fechar as ferramentas do navegador e adicionar pontos de interrupção no Visual Studio como normalmente faria.
• Se você encontrar algum problema, haverá mais informações em Depurar um aplicativo JavaScript ou TypeScript no Visual Studio.

Usar as ferramentas de desenvolvedor do navegador para depurar na Web

1. Para um suplemento em qualquer host, exceto o Outlook, na página do aplicativo host do Office, pressione F12 para abrir a ferramenta de depuração.

2. Para um suplemento do Outlook, se o manifesto do suplemento estiver configurado para uma superfície de leitura, selecione uma mensagem de email ou item de compromisso para abri-lo em sua própria janela. Se o suplemento estiver configurado apenas para uma superfície de composição, abra uma nova mensagem, responda à mensagem ou nova janela de compromisso. Verifique se a janela apropriada tem foco e pressione F12 para canetar a ferramenta de depuração.

3. Depois que a ferramenta estiver aberta, inicie o suplemento. As etapas exatas variam dependendo do design do suplemento. Normalmente, você pressiona um botão para abrir um painel de tarefas. No Outlook, na barra de ferramentas na parte superior da janela, selecione o botão Mais aplicativos e selecione seu suplemento na chamada aberta.

   

4. Use as instruções em um dos artigos a seguir para definir pontos de interrupção e passar por código. Cada um deles tem um link para diretrizes mais detalhadas.

   • Depurar suplementos usando ferramentas de desenvolvedor para Edge Legacy
   • Depurar suplementos usando ferramentas de desenvolvedor no Microsoft Edge (baseado em Chromium)

   Dica

   Para depurar o Office.initialize código que é executado na função ou em uma Office.onReady função que é executada quando o suplemento for aberto, defina seus pontos de interrupção e feche e reabra o suplemento. Para obter mais informações sobre essas funções, consulte Inicializar seu Suplemento do Office.

5. Para fazer alterações no código, primeiro interrompa a sessão de depuração no Visual Studio e feche as páginas do Outlook. Faça suas alterações e inicie uma nova sessão de depuração.

Usar um documento existente para depurar o suplemento

Se você tiver um documento que contém os dados de teste deseja usar ao depurar seu suplemento o Excel, PowerPoint ou Word, o Visual Studio pode ser configurado para abrir esse documento quando você iniciar o projeto. Para especificar um documento existente a ser usado durante a depuração do complemento, execute as etapas a seguir.

1. No Explorador de soluções Escolha o projeto do suplemento (não o projeto do aplicativo Web).

2. Na barra de menus, escolha Projeto>Adicionar Item Existente.

3. Na caixa de diálogo Adicionar Item Existente, localize e selecione o documento que você deseja adicionar.

4. Escolha o botão Adicionar para adicionar o documento ao projeto.

5. No Explorador de soluções Escolha o projeto do suplemento (não o projeto do aplicativo Web).

6. Na barra de menus, escolha Exibir, >Janela Propriedades.

7. Na janela Propriedades, escolha a lista Iniciar Documento e selecione o documento que você adicionou ao projeto. O projeto agora está configurado para iniciar o suplemento nesse documento.

Próximas etapas

Depois do suplemento funcionar conforme desejado, veja Implantar e publicar o suplemento Office para saber mais como você pode distribuir o suplemento para os usuários.