Depurar projetos do Office

Você pode depurar projetos do Office usando as mesmas ferramentas do Microsoft Visual Studio usadas para outros projetos do Visual Studio. Os recursos do depurador do Visual Studio, como a capacidade de inserir pontos de interrupção e exibir variáveis na janela Locais , também estão disponíveis quando você depura projetos do Office. Para obter mais informações sobre as ferramentas de depuração do Visual Studio, consulte Depurar no Visual Studio.

Aplica-se a: As informações neste tópico se aplicam a projetos no nível do documento e projetos de suplemento VSTO. Consulte os recursos disponíveis pelo aplicativo do Office e pelo tipo de projeto.

Iniciar e parar o depurador

Você pode começar a depurar um projeto do Office da mesma forma que começa a depurar outros projetos do Visual Studio; por exemplo, você pode pressionar a tecla F5 . Quando você inicia a depuração de um projeto de Suplemento VSTO, um novo processo para o aplicativo do Office de destino é iniciado e o Suplemento VSTO é carregado.

Quando você começa a depurar um projeto no nível do documento, o documento ou pasta de trabalho é aberto em um novo processo do Word ou do Excel.

Quando você interrompe o depurador, o depurador encerra abruptamente o processo do aplicativo, ou desanexa se você tiver o depurador configurado para desanexar. Todos os outros documentos abertos no processo de aplicativo do Office encerrado também são fechados sem aviso e quaisquer alterações não salvas são perdidas. Isso pode incluir todos os documentos ou pastas de trabalho abertos enquanto o depurador está em execução.

Normalmente, é melhor desanexar-se do processo antes de parar o depurador, para que você possa sair do aplicativo do Office de forma habitual. Você também pode se desanexar do processo primeiro se ainda quiser trabalhar com um documento aberto ou uma planilha depois de parar o depurador.

Se você estiver depurando uma personalização no nível do documento para o Word, parar repetidamente o depurador e fazer com que o Word feche repentinamente pode levar o modelo Normal a ficar corrompido. Se isso acontecer, você poderá excluir o modelo Normal corrompido e ele será recriado automaticamente na próxima vez que você abrir o Word. No entanto, todas as macros armazenadas no modelo Normal não são recriadas.

Depurar suplementos do VSTO do Office 2013 usando o Office 2013 ou o Office 2016

Se você estiver usando o Visual Studio 2015 e tiver as duas versões do Office instaladas lado a lado, o Visual Studio iniciará o Office 2016. Se você estiver usando o Visual Studio 2013, o Visual Studio iniciará o Office 2013.

Se você quiser depurar seu Suplemento VSTO usando outra versão do Microsoft Office, como o 2013 ou 2016, abra o Designer de Projeto e, na guia Depurar, escolha o botão Iniciar programa externo. Em seguida, navegue até o local do executável de aplicativo do Office apropriado.

Comportamento de F10 e F11

Quando você começa a depurar um projeto do Office, F10 e F11 não têm o mesmo comportamento de quando você começa a depurar outros projetos do Visual Basic ou C#. Em projetos do Visual Basic ou C#, o depurador para na função principal; em projetos do Office, o Visual Studio não tem controle sobre a função principal do aplicativo do Office. No entanto, durante a depuração, F10 e F11 têm as mesmas funções que em projetos do Visual Basic e C#.

Exibir exceções

Devido à maneira como o código gerenciado interage com código não gerenciado, o Visual Studio não exibe erros gerados por aplicativos do Microsoft Office. Por exemplo, se um Suplemento VSTO criado usando as ferramentas de desenvolvimento do Office no Visual Studio gerar uma exceção, o aplicativo do Microsoft Office continuará sem exibir um erro. Para ver esses erros, defina o depurador para parar em exceções do tempo de execução da linguagem comum. Para obter mais informações, consulte Gerenciar exceções com o depurador.

Se você definir o depurador para interromper em exceções de tempo de execução de linguagem comum, todas as exceções agora serão interrompidas no depurador, incluindo aquelas que você já lidou e algumas exceções de primeira chance do próprio tempo de execução, que podem não ser relevantes para o seu projeto. Erros referentes ao msosec não encontrado aparecem em todos os projetos, mas são seguros de ignorar. Essas exceções msosec não afetarão sua solução.

Você também pode usar Try...Catch instruções nos seus métodos para capturar exceções.

Por padrão, o Visual Studio também não exibe erros de depuração Just-in-Time para projetos do Office; no entanto, você pode habilitar esse recurso para ver os erros que ocorrem. Para obter mais informações, consulte Depuração Just-In-Time no Visual Studio.

Argumentos de linha de comando

Se a ação Iniciar na página de propriedades de depuração estiver definida como Iniciar Projeto, o Visual Studio não usará argumentos de linha de comando ao depurar o projeto, mesmo se você tiver especificado argumentos de linha de comando como opções de início. Se você quiser usar argumentos de linha de comando ao iniciar a depuração, deverá selecionar uma Ação inicial diferente de Iniciar Projeto.

Controle do código-fonte

As propriedades de depuração não são compartilhadas entre vários usuários sob controle do código-fonte. Os projetos Visual Basic e C# armazenam as propriedades de depuração em um arquivo específico do usuário (ProjectName.vbproj.user ou ProjectName.csproj.user), e esse arquivo não está sob controle de versão. Se mais de uma pessoa estiver envolvida na depuração, cada uma deverá inserir as configurações de depuração manualmente.

Depurar conjuntos de dados armazenados em cache em um projeto no nível do documento

Sempre que você cria um projeto, o conjunto de dados é esvaziado e recriado. Se você quiser depurar um conjunto de dados armazenado em cache, será necessário abrir o documento fora do Visual Studio e anexar o depurador.

Depurar projetos de documentos do Word com base no formato de documento do Word 97-2003 (*.doc)

Para depurar um projeto do Documento do Word com base no formato de documento do Word 97-2003 (/.doc*), você deve adicionar a pasta do projeto à lista de Documentos Confiáveis. Para obter mais informações sobre como fazer isso, consulte Conceder confiança a documentos.

Depurar suplementos desabilitados

Os aplicativos do Microsoft Office podem desabilitar suplementos VSTO que se comportam inesperadamente. Um aplicativo do Microsoft Office desabilita suplementos VSTO para impedir que o código problemático seja carregado sempre que o aplicativo é iniciado. No entanto, também é fácil causar um comportamento inesperado durante a depuração típica. Para obter informações sobre como reabilitar suplementos VSTO, consulte Como habilitar novamente um suplemento VSTO que foi desabilitado.

Há dois tipos de desabilitação que os aplicativos do Microsoft Office usam para suplementos VSTO: a desabilitação rígida e a desabilitação suave.

Desabilitação permanente

A desativação forçada pode ocorrer quando um Suplemento VSTO provoca o fechamento inesperado do aplicativo. Essa situação também poderá ocorrer no computador de desenvolvimento se você interromper a execução do depurador enquanto o manipulador de eventos no suplemento VSTO estiver ativo. Quando um suplemento VSTO é rigidamente desabilitado, ele aparece na lista Itens Desabilitados no aplicativo.

Se um aplicativo do Office desativar definitivamente um Suplemento VSTO criado com o uso de ferramentas de desenvolvimento do Office no Visual Studio, o aplicativo desativa apenas o Suplemento VSTO que causou a falha. Outros suplementos VSTO criados usando as ferramentas de desenvolvimento do Office no Visual Studio para esse aplicativo do Office continuarão sendo carregados.

Desativação temporária

A desativação branda pode ocorrer quando um Complemento VSTO produz um erro que não faz com que o aplicativo feche inesperadamente. Por exemplo, um aplicativo pode suavemente desabilitar um suplemento VSTO se gerar uma exceção não tratada enquanto o manipulador de eventos Startup estiver em execução. Quando um suplemento VSTO é semidesabilitado, ele aparece na lista de Suplementos de Aplicativo Inativos no aplicativo, e o aplicativo altera o valor da entrada do Registro LoadBehavior para o Suplemento VSTO para indicar que ele está descarregado. Para obter mais informações sobre a entrada do Registro LoadBehavior, consulte as entradas do Registro de suplementos VSTO.

Solucionar problemas de erros de instalação usando o Visualizador de Eventos

O runtime do Visual Studio Tools for Office escreve mensagens no Visualizador de Eventos do Windows para todas as exceções lançadas quando você instala ou desinstala soluções do Office. Você pode usar essas mensagens para resolver problemas de instalação e implantação.

Solucionar problemas de erros de inicialização usando um arquivo de log e mensagens de erro

O runtime das Ferramentas do Visual Studio para Office pode gravar todos os erros que ocorrem durante a inicialização em um arquivo de log ou exibir cada erro em uma caixa de mensagem. Por padrão, essas opções são desativadas. Você pode ativar as opções criando variáveis de ambiente.

Para exibir cada erro em uma caixa de mensagem, crie uma variável de ambiente nomeada VSTO_SUPPRESSDISPLAYALERTS e defina-a como 0 (zero). Você pode suprimir as mensagens excluindo a variável de ambiente ou definindo-a como 1 (uma).

Para gravar os erros em um arquivo de log, crie uma variável de ambiente nomeada VSTO_LOGALERTS e defina-a como 1 (uma). O Visual Studio Tools for Office runtime cria o arquivo de log na pasta que contém o manifesto de implantação do Add-in do VSTO ou na pasta que contém o documento ou pasta de trabalho associado à personalização. Se isso falhar, o runtime das Ferramentas do Visual Studio para Office criará o arquivo de log na pasta %TEMP% local. Para suplementos VSTO no nível do aplicativo, o nome padrão é nome do suplemento.vsto.log. Para projetos no nível do documento, o nome do arquivo de log é nome do documento.extensão.log, como em ExcelWorkbook1.xlsx.log. Para interromper erros de log, exclua a variável de ambiente ou defina-a como 0 (zero).

Conteúdo relacionado

• Criar soluções do Office
• Como habilitar novamente um suplemento VSTO que foi desabilitado
• Programar complementos VSTO