Depurar Suplementos do Office no Visual Studio

Este artigo descreve como depurar 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 código do lado do servidor em Suplementos do Office, consulte Visão geral da depuração de Suplementos do Office - Lado do servidor ou 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 iniciar a depuração, examine as propriedades de cada projeto na solução para confirmar se o Visual Studio abrirá o aplicativo do Office desejado e se outras propriedades de compilação e depuração estã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 do 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 deixado em branco, será solicitado o endereço de email quando você iniciar a depuração.
EWS Url
(Apenas suplementos do Outlook)		 Especifica a URL dos Serviços Web do Exchange (por exemplo: https://www.contoso.com/ews/exchange.aspx). Esta propriedade pode ser deixada em branco.
OWA Url
(Apenas suplementos do Outlook)		 Especifica a URL do Outlook na Web (por exemplo: https://www.contoso.com/owa). Esta propriedade pode ser deixada 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 é false, mas a propriedade não tem efeito prático. Se você normalmente precisa fornecer um segundo fator para fazer logon na conta de email, será solicitado quando 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. Esta propriedade pode ser deixada 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 durante a depuração do 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 durante a depuração do 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 durante a depuração do 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 durante a depuração. Por exemplo, https://mysite.sharepoint.com/

Observação

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

Propriedades do projeto de aplicativo Web

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

  1. No Gerenciador de Soluções, escolha o projeto de 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 na área de trabalho do Office 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

Importante

Devido à desativação do EWS (Serviços Web do Exchange) para o Exchange Online a partir de outubro de 2026 (consulte o Blog da Equipe do Exchange), a depuração F5 não funcionará mais para suplementos da Web do Outlook direcionados ao Exchange Online. Você precisará fazer o sideload manual do suplemento no Outlook. Para obter instruções, consulte Fazer sideload de suplementos do Outlook e Fazer sideload de um suplemento na Web ao usar o Visual Studio. Essas etapas também abrangem a atualização do manifesto antes do sideload.

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

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

  1. Cria uma cópia do arquivo de manifesto somente do suplemento e a 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 do Registro no computador Windows que permite que o suplemento apareça no aplicativo do Office.

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

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

Depois, o Visual Studio faz o seguinte:

  1. Modifica o elemento SourceLocation do arquivo de manifesto somente do suplemento (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. A 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 Manifestar erros de validação de esquema em projetos do Visual Studio.

  4. Abre o aplicativo do Office e faz o sideload de seu suplemento.

Depurar o suplemento

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 do suplemento. Se a configuração de um ponto de interrupção faz com que o servidor do IIS (Serviços de Informações da Internet) seja desligado, reinicie a depuração depois de definir os 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 initialize e onReady.

Dica

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

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

  1. Siga as etapas da seção anterior Iniciar o projeto do suplemento.

  2. Inicie o suplemento no aplicativo do Office se ele ainda não estiver aberto. Por exemplo, se for um suplemento do painel de tarefas, ele terá adicionado um botão (por exemplo, um botão Mostrar Painel de Tarefas ) à faixa de opções Página Inicial ou a uma guia de faixa de opções personalizada instalada com o suplemento. Selecione o botão na faixa de opções.

  3. Abra o menu de personalidade e escolha Anexar um depurador. Esta ação abre as ferramentas de depuração do controle de modo de exibição da Web 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 no artigo Depurar suplementos usando ferramentas de desenvolvedor no Microsoft Edge.

  4. Para fazer alterações no código, primeiro interrompa a sessão de depuração no Visual Studio e feche o aplicativo 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 no área de trabalho do Office na Web, ou seja, quando a propriedade Iniciar Ação do projeto de suplemento está 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 a solução automaticamente e inicia a página host do aplicativo Office de sua locação do Microsoft 365.

Observação

Ao depurar um suplemento na Web, você pode receber 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 aos URIs de redirecionamento configurados 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. Interrompa a depuração no Visual Studio.

  2. Crie 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 compila o projeto, ele executa as tarefas a seguir.

  1. Prompts para que você insira credenciais de logon. Se você for solicitado a entrar repetidamente ou se receber um erro informando que não está autorizado, a Autenticação Básica poderá ser desabilitada 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 autenticação multifator como True no painel de propriedades do projeto do suplemento. Consulte Propriedades do projeto de suplemento.

  2. Cria uma cópia do arquivo de manifesto somente do suplemento e a 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. Compila o projeto de aplicativo Web e, em seguida, implanta-o na locação do Microsoft 365.

Depois, o Visual Studio faz o seguinte:

  1. Modifica o elemento SourceLocation do arquivo de manifesto somente do suplemento (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 de 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. A 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 Manifestar erros de validação de esquema em projetos do Visual Studio.

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

Dica

Se, por algum motivo, o Visual Studio não fizer o sideload completo do suplemento e nenhuma das correções anteriores funcionar, você poderá carregá-lo manualmente. Siga as etapas em Fazer sideload de um suplemento para o Microsoft 365. Quando você for instruído a navegar até o manifesto, navegue até o arquivo XML no diretório de pastas _ProjectName_\bin\Debug\OfficeAppManifests .

Depurar o suplemento na Web

Use 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 do 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, no 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 F5 para iniciar a depuração e o Outlook na Web for aberto, siga as quatro primeiras etapas em Usar as ferramentas de desenvolvedor do navegador para depurar na Web. Depois de definir um ponto de interrupção nas ferramentas do navegador e ele for atingido, a execução será pausada no 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 faria normalmente.
  • Se você encontrar problemas, há mais informações em Depurar um aplicativo JavaScript ou TypeScript no Visual Studio.

Use as ferramentas de desenvolvedor do navegador para depurar na Web

  1. Para um suplemento em qualquer host, exceto no 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, uma nova mensagem ou uma nova janela de compromisso. Verifique se a janela apropriada está em foco e pressione F12 para escrever a ferramenta de depuração.

  3. Depois que a ferramenta estiver aberta, inicie o suplemento. As etapas exatas variam de acordo com o design do seu 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, em seguida, selecione seu suplemento no balão que se abre.

    O botão Mais aplicativos e o balão que ele abre com o nome e o ícone do suplemento visíveis junto com outros ícones de aplicativo.

  4. Defina pontos de interrupção e percorra o código seguindo as instruções no artigo Depurar suplementos usando ferramentas de desenvolvedor no Microsoft Edge.

    Dica

    Para depurar o Office.initialize código executado na função ou em uma Office.onReady função executada quando o suplemento é aberto, defina os pontos de interrupção e, em seguida, 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 em seu código, primeiro interrompa a sessão de depuração no Visual Studio e feche a página do Office na Web. 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.

  • Last updated on