Depurar apenas o código do usuário com Apenas Meu Código

Apenas Meu Código é um recurso de depuração do Visual Studio que percorre automaticamente as chamadas para o sistema, a estrutura e outros códigos que não são de usuários. Na janela Pilha de Chamadas, Apenas Meu Código recolhe essas chamadas em quadros [Código Externo].

Apenas Meu Código funciona de maneira diferente em projetos .NET e C++.

Habilitar ou desabilitar Apenas Meu Código

Para a maioria das linguagens de programação, Apenas Meu Código está habilitado por padrão.

• Para habilitar ou desabilitar Apenas Meu Código no Visual Studio, emFerramentas>Opções (ouDepurar>Opções) >Depuração>Geral, selecione ou desmarque Habilitar Apenas Meu Código.

Observação

Habilitar Apenas Meu Código é uma configuração global aplicada a todos os projetos do Visual Studio em todas as linguagens.

depuração Apenas Meu Código

Durante uma sessão de depuração, a janela Módulos mostra quais módulos de código o depurador está tratando como Meu Código (código do usuário), juntamente com seu status de carregamento de símbolo. Para obter mais informações, confira Familiarize-se mais com a forma como o depurador se anexa ao seu aplicativo.

Na janela Pilha de Chamadas ou Tarefas, Apenas Meu Código recolhe o código que não é de usuário em um quadro de código anotado esmaecido rotulado [External Code].

Dica

Para abrir Módulos, Pilha de Chamadas, Tarefas ou a maioria das outras janelas de depuração, você deve estar em uma sessão de depuração. Durante a depuração, em Depurar>Windows, selecione as janelas que você quer abrir.

Para exibir o código em um quadro [Código Externo] recolhido, clique com o botão direito na janela Pilha de Chamadas ou Tarefa e selecione Mostrar Código Externo no menu de contexto. As linhas de código externas expandidas substituem o quadro [Código Externo].

Observação

Mostrar Código Externo é uma configuração atual do criador de perfil de usuário que se aplica a todos os projetos em todos as linguagens abertas pelo usuário.

Clicar duas vezes em uma linha de código externa expandida na janela Pilha de Chamadas realça em verde a linha de código de chamada no código-fonte. Para DLLs ou outros módulos não encontrados ou carregados, uma página de símbolo ou origem não encontrada pode ser aberta.

A partir do Visual Studio 2022 versão 17.7, você pode descompilar automaticamente o código .NET clicando duas vezes no código externo na janela Pilha de chamadas. Para mais informações, consulte Gere código-fonte de assemblies .NET durante a depuração.

Apenas Meu Código do .NET

Em projetos .NET, Apenas Meu Código usa arquivos de símbolo (.pdb) e otimizações de programa para classificar o código de usuário e de não usuário. O depurador do .NET considera binários otimizados e arquivos .pdb não carregados como um código não usuário.

Três atributos do compilador também afetam o que o depurador do .NET considera ser código de usuário:

• DebuggerNonUserCodeAttribute informa ao depurador que o código ao qual ele é aplicado não é código do usuário.
• DebuggerHiddenAttribute oculta o código do depurador, mesmo que Apenas Meu Código esteja desativado.
• DebuggerStepThroughAttribute informa ao depurador para percorrer o código ao qual é aplicado, em vez de depurar o código.

O depurador do .NET considera todos os outros códigos como código de usuário.

Durante a depuração do .NET:

• Depurar>Intervir (ou F11) em etapas de código que não é de usuário sobre o código para a próxima linha de código do usuário.
• Depurar>Circular (ou Shift+F11) no código que não é de usuário é executado para a próxima linha de código do usuário.

Se não houver mais código de usuário, a depuração continuará até que ele termine, atinja outro ponto de interrupção ou gere um erro.

Se o depurador intervir no código que não é de usuário (por exemplo, você usa Depurar>Interromper Tudo e pausar no código que não é de usuário), a janela Sem Origem será exibida. Em seguida, você pode usar um comando Depurar>Etapa para ir para a próxima linha de código do usuário.

Se uma exceção sem tratamento ocorre no código de não usuário, o depurador é interrompido na linha do código de usuário na qual a exceção foi gerada.

Se as exceções de primeira opção estiverem habilitadas para a exceção, a linha do código do usuário que chama será realçada em verde no código-fonte. A janela Pilha de Chamadas exibe o quadro anotado rotulado [Código Externo].

Apenas Meu Código do C++

A partir do Visual Studio 2017 versão 15.8, também há suporte para Apenas Meu Código para depuração passo a passo de código. Esse recurso também requer o uso da opção do compilador /JMC (depuração Apenas Meu Código). A opção está habilitada por padrão em projetos C++. Para a janela Pilha de Chamadas e o suporte à pilha de chamadas em Apenas Meu Código, a opção /JMC não é necessária.

Para ser classificado como código de usuário, o PDB do binário que contém o código do usuário deve ser carregado pelo depurador (use a janela Módulos para verificar isso).

Para o comportamento da pilha de chamadas, como na janela Pilha de Chamadas, Apenas Meu Código em C++ considera apenas essas funções como código que não é de usuário:

• Funções com informações de origem retiradas no respectivo arquivo de símbolos.
• Funções nas quais os arquivos de símbolos indicam que não há nenhum arquivo de origem que corresponde ao quadro de pilhas.
• Funções especificadas em arquivos *.natjmc na pasta %VsInstallDirectory%\Common7\Packages\Debugger\Visualizers.

Para comportamento da depuração passo a passo de código, Apenas Meu Código em C++ considera apenas essas funções como código que não é de usuário:

• Funções para as quais o arquivo PDB correspondente não foi carregado no depurador.
• Funções especificadas em arquivos *.natjmc na pasta %VsInstallDirectory%\Common7\Packages\Debugger\Visualizers.

Observação

Para dar suporte à depuração de passo a passo de código em Apenas Meu Código, o código C++ deve ser compilado usando os compiladores MSVC no Visual Studio 15.8 Preview 3 ou posterior, e a opção do compilador /JMC deve ser habilitada (está habilitada por padrão). Para obter detalhes adicionais, confira Personalizar o comportamento de depuração passo a passo de código e pilha de chamadas em C++ e esta postagem no blog. Para o código compilado usando um compilador mais antigo, os arquivos .natstepfilter são a única maneira de personalizar a depuração passo a passo de código, que é independente de Apenas Meu Código. Confira Personalizar o comportamento da depuração passo a passo de C++.

Durante a depuração do C++, o código não usuário é ignorado por padrão. Durante a depuração do C++:

• Depurar>Intervir (ou F11) em etapas de código não usuário sobre o código ou executadas para a próxima linha de código do usuário, se Intervir for chamado do código não usuário.
• Depurar>Sair (ou Deslocar+F11) em execuções de código não usuário para a próxima linha de código do usuário (fora do quadro de pilha atual).

Se não houver mais código de usuário, a depuração continuará até que ele termine, atinja outro ponto de interrupção ou gere um erro.

Se o depurador intervir em um código que não é de usuário (por exemplo, usar Depurar>Interromper Tudo e pausar em um código que não é de usuário), a depuração passo a passo continuará no código que não é de usuário.

Se o depurador atingir uma exceção, ele será interrompido na exceção, seja no código do usuário ou que não é do usuário. As opções Sem tratamento do usuário na caixa de diálogo Configurações de Exceção são ignoradas.

Personalizar a pilha de chamadas de C++ e o comportamento da depuração passo a passo de código

Para projetos em C++, você pode especificar os módulos, os arquivos de origem e as funções que a janela Pilha de Chamadas trata como código que não é de usuário especificando-os em arquivos *.natjmc. Essa personalização também se aplica à depuração passo a passo de código se você estiver usando o compilador mais recente (confira Apenas Meu Código em C++).

• Para especificar código de não usuário para todos os usuários do computador do Visual Studio, adicione o arquivo .natjmc à pasta %VsInstallDirectory%\Common7\Packages\Debugger\Visualizers.
• Para especificar código que não é de usuário para um usuário individual, adicione o arquivo .natjmc à pasta %USERPROFILE%\Meus Documentos\<versão do Visual Studio>\Visualizadores.

Um arquivo .natjmc é um arquivo XML com essa sintaxe:

<?xml version="1.0" encoding="utf-8"?>
<NonUserCode xmlns="http://schemas.microsoft.com/vstudio/debugger/jmc/2015">

  <!-- Modules -->
  <Module Name="ModuleSpec" />
  <Module Name="ModuleSpec" Company="CompanyName" />

  <!-- Files -->
  <File Name="FileSpec"/>

  <!-- Functions -->
  <Function Name="FunctionSpec" />
  <Function Name="FunctionSpec" Module ="ModuleSpec" />
  <Function Name="FunctionSpec" Module ="ModuleSpec" ExceptionImplementation="true" />

</NonUserCode>

Atributos do elemento de módulo

Atributo	Descrição
Name	Obrigatórios. O caminho completo do módulo ou dos módulos. Você pode usar os caracteres curinga do Windows ? (zero ou um caractere) e * (zero ou mais caracteres). Por exemplo, <Module Name="?:\3rdParty\UtilLibs\*" /> informa o depurador para tratar todos os módulos em \3rdParty\UtilLibs em qualquer unidade como código externo.
Company	Opcional. O nome da empresa que publica o módulo inserido no arquivo executável. Você pode usar esse atributo para resolver a ambiguidade dos módulos.

Atributos do elemento de arquivo

Atributo	Descrição
Name	Obrigatórios. O caminho completo do arquivo ou arquivos de origem a serem tratados como código externo. Você pode usar os caracteres curinga do Windows ? e * quando especificar o caminho.

Atributos do elemento de função

Atributo	Descrição
Name	Obrigatórios. O nome totalmente qualificado da função a ser tratada como código externo. ou pode usar os caracteres ? curinga do Windows e * ao especificar o caminho.
Module	Opcional. O nome ou o caminho completo do módulo que contém a função. Você pode usar esse atributo para resolver a ambiguidade de funções com o mesmo nome.
ExceptionImplementation	Quando definido como true, a pilha de chamadas exibe a função que lançou a exceção em vez dessa função.

Personalizar o comportamento da depuração passo a passo de C++ independentemente das configurações de Apenas Meu Código

Em projetos C++, você pode especificar funções para percorrer listando-as como funções NoStepInto em arquivos *.natstepfilter. As funções listadas em arquivos *.natstepfilter não dependem das configurações de Apenas Meu Código. Uma função NoStepInto informa ao depurador para percorrer a função, mesmo que ela chame algumas funções StepInto ou outro código de usuário. Ao contrário das funções listadas em .natjmc, o depurador entrará na primeira linha de código do usuário dentro da função NoStepInto.

• Para especificar o código que não é de usuário para todos os usuários do Visual Studio, adicione o arquivo .natstepfilter à pasta %VsInstallDirectory%\Common7\Packages\Debugger\Visualizers.
• Para especificar o código que não é de usuário para um usuário individual, adicione o arquivo .natstepfilter à pasta %USERPROFILE%\Meus Documentos\>versão do Visual Studio\Visualizadores<.

Observação

Algumas extensões de terceiros podem desabilitar a funcionalidade .natstepfilter.

Um arquivo .natstepfilter é um arquivo XML com esta sintaxe:

<?xml version="1.0" encoding="utf-8"?>
<StepFilter xmlns="http://schemas.microsoft.com/vstudio/debugger/natstepfilter/2010">
    <Function>
        <Name>FunctionSpec</Name>
        <Action>StepAction</Action>
    </Function>
    <Function>
        <Name>FunctionSpec</Name>
        <Module>ModuleSpec</Module>
        <Action>StepAction</Action>
    </Function>
</StepFilter>

Elemento	Descrição
Function	Obrigatórios. Especifica uma ou mais funções como funções de não usuário.
Name	Obrigatórios. Uma expressão regular formatada como ECMA-262 que especifica o nome completo da função a ser correspondida. Por exemplo: <Name>MyNS::MyClass::.*</Name> informa ao depurador que todos os métodos em MyNS::MyClass devem ser considerados como código de não usuário. A correspondência diferencia maiúsculas e minúsculas.
Module	Opcional. Uma expressão regular formatada como ECMA-262 que especifica o caminho completo do módulo que contém a função. A correspondência não diferencia maiúsculas de minúsculas.
Action	Obrigatórios. Um destes valores que diferenciam maiúsculas e minúsculas: NoStepInto – instrui o depurador a depurar parcialmente a função. StepInto – instrui o depurador a intervir na função, substituindo qualquer outro NoStepInto pela função correspondente.

Informações adicionais sobre arquivos .natstepfilter e .natjmc

• A partir do Visual Studio 2022 versão 17.6, você pode adicionar arquivos .natjmc e .natstepfilter diretamente à solução ou ao projeto.

• Erros de sintaxe nos arquivos .natstepfilter e .natjmc não são relatados na janela Saída do depurador.

• Diferente dos arquivos .natvis, os arquivos .natstepfilter e .natjmc não são recarregados a quente. Em vez disso, esses arquivos são recarregados perto do início da sessão de depuração.

• Para funções de modelo, o uso de <.*> ou <.* no nome pode ser útil.

Apenas Meu Código do JavaScript

O Apenas Meu Código do JavaScript controla a depuração e a exibição da pilha de chamadas categorizando o código em uma destas classificações:

classificação	Descrição
MyCode	Código do usuário que você possui e controla.
LibraryCode	Código que não é de usuário de bibliotecas que você usa regularmente e das quais seu aplicativo depende para funcionar corretamente (por exemplo, jQuery).
UnrelatedCode	Código que não é de usuário em seu aplicativo que você não possui, e seu aplicativo não depende para funcionar corretamente. Por exemplo, um SDK de publicidade que exibe anúncios pode ser UnrelatedCode.

O depurador JavaScript classifica o código como usuário ou não usuário nesta ordem:

1. As classificações padrão.

   • O script executado passando uma cadeia de caracteres à função eval fornecida pelo host é MyCode.
   • Script que é executado passando uma cadeia de caracteres para o construtor Function é LibraryCode.
   • O script em uma referência de estrutura, como o WinJS ou o SDK do Azure, é LibraryCode.
   • Script que é executado passando uma cadeia de caracteres para as funções setTimeout, setImmediate ou setInterval é UnrelatedCode.

2. Classificações no arquivo mycode.json do projeto atual.

Cada etapa de classificação substitui as etapas anteriores.

Todos os demais códigos são classificados como MyCode.

Você pode modificar as classificações padrão e classificar arquivos e URLs específicos como código de usuário ou que não é de usuário, adicionando um arquivo .json chamado mycode.json à pasta raiz de um projeto JavaScript. Confira Personalizar Apenas Meu Código JavaScript.

Durante a depuração do JavaScript:

• Se uma função não for um código que não é de usuário, Depurar>Intervir (ou F11) se comportará da mesma forma que Depurar>Depuração Parcial (ou F10).
• Se uma etapa começar em um código que não é de usuário (LibraryCode ou UnrelatedCode), a depuração temporária se comportará como se Apenas Meu Código não estivesse habilitado. Quando você voltar ao código de usuário, a depuração de Apenas Meu Código será habilitada novamente.
• Quando uma etapa de código do usuário resulta na saída do contexto de execução atual, o depurador para na próxima linha de código do usuário executado. Por exemplo, se um retorno de chamada for executado em código LibraryCode, o depurador continuará até que a próxima linha de código de usuário seja executada.
• Depuração Circular (ou Shift+F11) é interrompido na próxima linha do código do usuário.

Se não houver mais código de usuário, a depuração continuará até que ele termine, atinja outro ponto de interrupção ou gere um erro.

Os pontos de interrupção definidos no código são sempre atingidos, mas o código é classificado.

• Se a palavra-chave debugger ocorrer em LibraryCode, o depurador sempre será interrompido.
• Se a palavra-chave debugger ocorrer em UnrelatedCode, o depurador não será interrompido.

Se ocorrer uma exceção sem tratamento no código MyCode ou LibraryCode, o depurador sempre será interrompido.

Se ocorrer uma exceção sem tratamento em UnrelatedCode e MyCode ou LibraryCode estiver na pilha de chamadas, o depurador será interrompido.

Se exceções de primeira chance estiverem habilitadas para a exceção e a exceção ocorrer em LibraryCode ou UnrelatedCode:

• Se a exceção for tratada, o depurador não será interrompido.
• Se a exceção não for tratada, o depurador será interrompido.

Personalizar Apenas Meu Código JavaScript

Para categorizar código de usuário e de não usuário para um único projeto do Visual Studio, adicione um arquivo .json denominado mycode.json à pasta raiz do projeto.

O arquivo mycode.json não precisa listar todos os pares de valores de chave. Os valores MyCode, Libraries e Unrelated podem ser matrizes vazias.

Os arquivos Mycode.json usam esta sintaxe:

{
    "Eval" : "Classification",
    "Function" : "Classification",
    "ScriptBlock" : "Classification",
    "MyCode" : [
        "UrlOrFileSpec",
        . . .
        "UrlOrFileSpec"
    ],
    "Libraries" : [
        "UrlOrFileSpec",
        . .
        "UrlOrFileSpec"
    ],
    "Unrelated" : [
        "UrlOrFileSpec",
        . . .
        "UrlOrFileSpec"
    ]
}

Eval, Function e ScriptBlock

Os pares chave-valor Eval, Function e ScriptBlock determinam como o código gerado dinamicamente é classificado:

Nome	Descrição
Eval	Script que é executado passando uma cadeia de caracteres à função eval fornecida pelo host. Por padrão, o script Eval é classificado como MyCode.
Função	Script que é executado passando uma cadeia de caracteres para o construtor Function. Por padrão, o script Function é classificado como LibraryCode.
Bloco de script	Script que é executado passando uma cadeia de caracteres para a função setTimeout, setImmediate ou setInterval. Por padrão, o script ScriptBlock é classificado como UnrelatedCode.

Você pode alterar o valor para um destas palavras-chave:

• MyCode classifica o script como MyCode.
• Library classifica o script como LibraryCode.
• Unrelated classifica o script como UnrelatedCode.

MyCode, Libraries e Unrelated

Os pares chave-valor MyCode, Libraries e Unrelated especificam as URLs ou os arquivos que você deseja incluir em uma classificação:

Nome	Descrição
MyCode	Uma matriz de URLs ou arquivos classificados como MyCode.
Bibliotecas	Uma matriz de URLs ou arquivos classificados como LibraryCode.
Unrelated	Uma matriz de URLs ou arquivos classificados como UnrelatedCode.

A URL ou cadeia de caracteres de arquivo que contém um ou mais caracteres *, que correspondem a zero ou mais caracteres. * é o mesmo que a expressão regular .*.