Depurar Suplementos do Office no Visual Studio

  • Artigo

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

Observação

Não pode utilizar o Visual Studio para depurar suplementos no Office no Mac. Para obter informações sobre a depuração num Mac, consulte Depurar Suplementos do Office num Mac.

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

Antes de começar a depurar, reveja as propriedades de cada projeto para confirmar que o Visual Studio abrirá a aplicação do Office pretendida e que 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 rever 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. Esta definição deve ser definida como Cliente de Ambiente de Trabalho do Office quando pretender depurar no Microsoft 365 no Windows. Para depurar no Microsoft 365 na Web, 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. Num novo projeto, está definido como [Novo Livro do Excel], [Novo Documento do Word], ou [Nova Apresentação do PowerPoint]. Para especificar um determinado documento, siga os passos em Utilizar 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 for deixado em branco, ser-lhe-á pedido o endereço de e-mail quando iniciar a depuração.
EWS Url
(Apenas suplementos do Outlook)		 Especifica o 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 o 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 booleano que indica se a autenticação multifator deve ser utilizada. A predefinição é falsa, mas a propriedade não tem nenhum efeito prático. Se normalmente tiver de fornecer um segundo fator para iniciar sessão na conta de e-mail, ser-lhe-á pedido 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 Implementação Ativa
(presente apenas ao depurar o Excel,
PowerPoint ou Word na Web)		 Especifica a configuração da implementação. Esta opção deve ser definida como Predefinição.
Ligação do Servidor
(presente apenas ao depurar o Excel,
PowerPoint ou Word na Web)		 Especifica se o projeto se liga ao serviço SharePoint especificado na propriedade URL do Site . Esta opção deve ser definida como Online.
URL do site
(presente apenas ao depurar o Excel,
PowerPoint ou Word na Web)		 Especifica o URL completo e absoluto do inquilino do SharePoint que pretende alojar as páginas de suplementos ao depurar. Por exemplo https://mysite.sharepoint.com/

Observação

Para um suplemento do Outlook, pode optar por especificar valores para um ou mais dos suplementos do Outlook apenas propriedades na janela Propriedades , mas não é necessário fazê-lo.

Propriedades do projeto de aplicativo Web

Abra a janela Propriedades do projeto de aplicação Web para rever as propriedades do projeto.

  1. No Explorador de Soluções, escolha o projeto de aplicação 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 no ambiente de trabalho do Windows

Esta secção descreve como iniciar e depurar um suplemento no Office para ambiente de trabalho no Windows; ou seja, quando a propriedade Iniciar Ação do projeto de suplemento está definida como Cliente de Ambiente de Trabalho do Office.

Iniciar o projeto de suplemento

Inicie o projeto ao selecionar Depurar>Iniciar Depuração na barra de menus ou prima o botão F5. O Visual Studio cria automaticamente a solução e inicia a aplicação anfitriã do Office.

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

  1. Cria uma cópia do ficheiro de manifesto apenas do suplemento e adiciona-o ao _ProjectName_\bin\Debug\OfficeAppManifests diretório. A aplicação do Office que aloja o seu suplemento consome esta cópia quando inicia o Visual Studio e depura o suplemento.

  2. Cria um conjunto de entradas de registo no seu computador Windows que permite que o suplemento seja apresentado na aplicação do Office.

  3. Compila o projeto de aplicação Web e, em seguida, implementa-o no servidor Web do IIS local (https://localhost).

  4. Se este for o primeiro projeto de suplemento que implementou no servidor Web do IIS local, poderá ser-lhe pedido para instalar um Certificado de Self-Signed no arquivo de Certificados de Raiz Fidedigna do utilizador atual. Isso é necessário para que o IIS Express exiba o conteúdo do seu suplemento corretamente.

Observação

Se o Office utilizar o controlo Edge Legacy Webview (EdgeHTML) para executar suplementos no seu computador Windows, o Visual Studio poderá pedir-lhe para adicionar uma isenção de loopback de rede local. Isto é necessário para que o controlo webview possa aceder ao site implementado 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 saber que controlo webview é utilizado no seu computador Windows, consulte Browsers e controlos webview utilizados pelos Suplementos do Office.

Depois, o Visual Studio faz o seguinte:

  1. Modifica o elemento SourceLocation do ficheiro de manifesto apenas do suplemento (que foi copiado para o _ProjectName_\bin\Debug\OfficeAppManifests diretório) ao substituir o ~remoteAppUrl token pelo endereço completamente 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 receber erros de validação do manifesto, poderá ser que os ficheiros de esquema de manifesto do Visual Studio não tenham sido atualizados para suportar as funcionalidades mais recentes. O primeiro passo de resolução de problemas deve ser substituir um ou mais destes ficheiros pelas versões mais recentes. Para obter instruções detalhadas, veja Erros de validação do esquema de manifesto em projetos do Visual Studio.

  4. Abre a aplicação do Office e efetua sideloads do seu 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 controlo webview associado ao Microsoft Edge (Chromium) ou a um controlo webview mais antigo. Para determinar que controlo webview está a ser utilizado, consulte Browsers e controlos webview utilizados pelos Suplementos do Office. Se o seu computador estiver a utilizar o WebView2, consulte Utilizar o depurador incorporado do Visual Studio para depurar no ambiente de trabalho. Para qualquer outro controlo de webview, consulte Utilizar as ferramentas de programador do browser para depurar no ambiente de trabalho.

Utilizar o depurador incorporado do Visual Studio para depurar no ambiente de trabalho

  1. Defina pontos de interrupção, conforme necessário, nos ficheiros JavaScript ou TypeScript de origem. Pode fazê-lo antes ou depois de iniciar o suplemento, conforme descrito na secção anterior Iniciar o projeto de suplemento. Se a definição de um ponto de interrupção fizer com que o servidor dos Serviços de Informação Internet (IIS) seja encerrado, reinicie a depuração depois de definir os pontos de interrupção.

  2. Quando o suplemento estiver em execução, utilize a IU do suplemento para executar o código que contém os pontos de interrupção.

Importante

Os pontos de interrupção são definidos ou Office.initializeOffice.onReady não são atingidos. Para depurar estes métodos, veja Depurar as funções inicializar e onReady.

Dica

Se encontrar problemas, existem mais informações em Depurar uma aplicação JavaScript ou TypeScript no Visual Studio.

Utilizar as ferramentas de programador do browser para depurar no ambiente de trabalho

  1. Siga os passos na secção anterior Iniciar o projeto de suplemento.

  2. Inicie o suplemento na aplicação do Office, se ainda não estiver aberto. Por exemplo, se for um suplemento do painel de tarefas, terá adicionado um botão ao friso Base (por exemplo, um botão Mostrar Painel de Tarefas). Selecione o botão no friso.

    Observação

    Se o seu suplemento não for sideloaded pelo Visual Studio, pode efetuar o sideload manualmente. Siga as instruções para Sideload an Office Add-in for testing for your platform (Sideload an Office Add-in for testing for your platform).

    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 é aberto pela primeira vez. Se for o caso, deverá ser composta corretamente quando iniciar as ferramentas de depuração num passo posterior.

  3. Abra o menu de personalidade e, em seguida, selecione Anexar um depurador. Esta ação abre as ferramentas de depuração para o controlo webview que o Office está a utilizar para executar suplementos no seu computador Windows. Pode definir pontos de interrupção e percorrer o código, conforme descrito num dos seguintes artigos:

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

Depurar um projeto de suplemento no Microsoft 365 na Web

Esta secção descreve como iniciar e depurar um suplemento no Office para ambiente de trabalho 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 ao selecionar Depurar>Iniciar Depuração na barra de menus ou prima o botão F5. O Visual Studio cria automaticamente a solução e inicia a página de anfitrião de aplicações do Office do seu inquilino do Microsoft 365.

Observação

Quando estiver a depurar um suplemento na Web, poderá obter um erro de AADSTS50011 semelhante ao seguinte:

"O URI {Full absolute URL to add-in home page} de redirecionamento especificado no pedido não corresponde aos URIs de redirecionamento configurados para a aplicação... "

Isto ocorre porque as novas aplicações Web implementadas no SharePoint podem demorar até 24 horas a estarem disponíveis. Para tornar o seu suplemento depurável imediatamente, siga os seguintes passos:

  1. Pare a depuração no Visual Studio.

  2. Crie um script do PowerShell com as seguintes linhas. Substitua o marcador {Full absolute URL to add-in home page} de posição pelo 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 ao selecionar Depurar>Iniciar Depuração na barra de menus ou prima o botão F5.

Quando o Visual Studio cria o projeto, executa as seguintes tarefas.

  1. Pede-lhe as credenciais de início de sessão. Se lhe for pedido para iniciar sessão repetidamente ou se receber um erro de que não está autorizado, a Autenticação Básica poderá estar desativada para contas no seu inquilino do Microsoft 365. Nesse caso, tente usar uma conta da Microsoft. Também pode tentar definir a propriedade Utilizar autenticação multifator como Verdadeiro no painel de propriedades do projeto do suplemento. Veja Propriedades do projeto de suplemento.

  2. Cria uma cópia do ficheiro de manifesto apenas do suplemento e adiciona-o ao _ProjectName_\bin\Debug\OfficeAppManifests diretório. O Microsoft 365 consome esta cópia quando inicia o Visual Studio e depura o suplemento.

  3. Compila o projeto de aplicação Web e, em seguida, implementa-o no inquilino do Microsoft 365.

Depois, o Visual Studio faz o seguinte:

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

  2. Inicia o projeto de aplicação Web.

  3. Valida o manifesto.

    Importante

    Se receber erros de validação do manifesto, poderá ser que os ficheiros de esquema de manifesto do Visual Studio não tenham sido atualizados para suportar as funcionalidades mais recentes. O primeiro passo de resolução de problemas deve ser substituir um ou mais destes ficheiros pelas versões mais recentes. Para obter instruções detalhadas, veja Erros de validação do esquema de manifesto em projetos do Visual Studio.

  4. Abre a página de anfitrião de aplicações do Office do seu inquilino 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 controlo webview associado ao Microsoft Edge (Chromium) ou a um controlo webview mais antigo. Para determinar que controlo webview está a ser utilizado, consulte Browsers e controlos webview utilizados pelos Suplementos do Office. Se o seu computador estiver a utilizar o WebView2, consulte Utilizar o depurador incorporado do Visual Studio para depurar na Web. Para qualquer outro controlo de webview, consulte Utilizar as ferramentas de programador do browser para depurar na Web.

Utilizar o depurador incorporado do Visual Studio para depurar na Web

  1. Defina pontos de interrupção, conforme necessário, nos ficheiros JavaScript ou TypeScript de origem. Pode fazê-lo antes ou depois de iniciar o suplemento, conforme descrito na secção anterior Iniciar o projeto de suplemento na Web.

  2. Quando o suplemento estiver em execução, utilize a IU do suplemento para executar o código que contém os pontos de interrupção.

Dica

  • Por vezes, no Outlook na Web, o depurador do Visual Studio não é anexado. Se receber erros dos pontos de interrupção que indicam que não serão atingidos, utilize as ferramentas de programador do browser para anexar ao depurador do Visual Studio: depois de premir F5 para iniciar a depuração e o Outlook na Web ter sido aberto, siga os primeiros quatro passos em Utilizar as ferramentas de programador do browser para depurar na Web. (Utilize as instruções para o Microsoft Edge (baseado em Chromium).) Depois de definir um ponto de interrupção nas ferramentas do browser e este ser atingido, a execução é colocada em pausa no ponto de interrupção nas ferramentas do browser e no Visual Studio. Isto indica que o depurador do Visual Studio está anexado. Neste momento, pode fechar as ferramentas do browser e adicionar pontos de interrupção no Visual Studio como faria normalmente.
  • Se encontrar problemas, existem mais informações em Depurar uma aplicação JavaScript ou TypeScript no Visual Studio.

Utilizar as ferramentas de programador do browser para depurar na Web

  1. Para um suplemento em qualquer anfitrião, exceto o Outlook, na página da aplicação anfitriã do Office, prima 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 e-mail ou item de compromisso para o abrir na sua própria janela. Se o suplemento estiver configurado apenas para uma superfície de composição, abra uma nova mensagem, responda a mensagem ou nova janela de compromisso. Certifique-se de que a janela adequada tem o foco e prima F12 para colocar a ferramenta de depuração na caneta.

  3. Depois de a ferramenta estar aberta, inicie o suplemento. Os passos exatos variam consoante a estrutura do suplemento. Normalmente, prime 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 aplicações e, em seguida, selecione o seu suplemento na nota de aviso que é aberta.

    O botão Mais aplicações e a nota de aviso que abre com o nome e o ícone do suplemento visíveis juntamente com outros ícones da aplicação.

  4. Utilize as instruções num dos seguintes artigos para definir pontos de interrupção e percorrer o código. Cada um deles tem uma ligação para orientações mais detalhadas.

    Dica

    Para depurar o Office.initialize código que é executado na função ou numa função Office.onReady que é 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 estas funções, consulte Inicializar o seu Suplemento do Office.

  5. Para fazer alterações ao código, primeiro pare a sessão de depuração no Visual Studio e feche as páginas do Outlook. Faça as 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.