Diagnosticar erros com assistentes de depuração gerenciados
Nota
Este artigo é específico do .NET Framework. Ele não se aplica a implementações mais recentes do .NET, incluindo o .NET 6 e versões posteriores.
Os assistentes de depuração gerenciados (MDAs) são auxílios de depuração que funcionam com o Common Language Runtime (CLR) para fornecer informações sobre o estado de tempo de execução. Os assistentes geram mensagens informativas sobre eventos de tempo de execução que, de outra forma, não podem ser intercetados. Você pode usar MDAs para isolar bugs de aplicativos difíceis de encontrar que ocorrem durante a transição entre código gerenciado e não gerenciado.
Você pode habilitar ou desabilitar todos os MDAs adicionando uma chave ao registro do Windows ou definindo uma variável de ambiente. Você pode habilitar MDAs específicos usando as definições de configuração do aplicativo. Você pode definir definições de configuração adicionais para alguns MDAs individuais no arquivo de configuração do aplicativo. Como esses arquivos de configuração são analisados quando o tempo de execução é carregado, você deve habilitar o MDA antes que o aplicativo gerenciado seja iniciado. Não é possível habilitá-lo para aplicativos que já foram iniciados.
A tabela a seguir lista os MDAs fornecidos com o .NET Framework:
Por padrão, o .NET Framework ativa um subconjunto de MDAs para todos os depuradores gerenciados. Você pode exibir o conjunto padrão no Visual Studio escolhendo Configurações de Exceção do Windows>no menu Depurar e expandindo a lista Assistentes de Depuração Gerenciados.
Habilitar e desabilitar MDAs
Você pode habilitar e desabilitar MDAs usando uma chave do Registro, uma variável de ambiente e definições de configuração do aplicativo. Você deve habilitar a chave do Registro ou a variável de ambiente para usar as definições de configuração do aplicativo.
Gorjeta
Em vez de desabilitar MDAs, você pode impedir que o Visual Studio exiba a caixa de diálogo MDA sempre que uma notificação MDA for recebida. Para fazer isso, escolha Configurações de exceção do Windows>no menu Depurar, expanda a lista Assistentes de depuração gerenciados e marque ou desmarque a caixa de seleção Quebrar quando lançado para o MDA individual.
Chave do Registo
Para habilitar o MDAs, adicione o HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\. NETFramework\MDA subchave (tipo REG_SZ, valor 1) no registro do Windows. Copie o exemplo a seguir em um arquivo de texto chamado MDAEnable.reg. Abra o Editor do Registro do Windows (RegEdit.exe) e, no menu Arquivo , escolha Importar. Selecione o arquivo MDAEnable.reg para habilitar os MDAs nesse computador. Definir a subchave para o valor da cadeia de caracteres de 1 (não o valor DWORD de 1) permite a leitura das configurações do MDA a partir do arquivo ApplicationName.suffix.mda.config. Por exemplo, o arquivo de configuração do MDA para o bloco de notas seria chamado notepad.exe.mda.config.
Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework]
"MDA"="1"
Se o computador estiver executando um aplicativo de 32 bits em um sistema operacional de 64 bits, a chave MDA deve ser definida da seguinte forma:
Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\.NETFramework]
"MDA"="1"
Consulte Definições de configuração específicas do aplicativo para obter mais informações. A configuração do Registro pode ser substituída pela variável de COMPLUS_MDA ambiente. Consulte Variável de ambiente para obter mais informações.
Para desativar o MDAs, defina a subchave MDA como 0 (zero) usando o Editor do Registro do Windows.
Por padrão, alguns MDAs são habilitados quando você executa um aplicativo anexado a um depurador, mesmo sem adicionar a chave do Registro. Você pode desativar esses assistentes executando o arquivo MDADisable.reg conforme descrito anteriormente nesta seção.
Variável de Ambiente
A ativação do MDA também pode ser controlada pela variável COMPLUS_MDAde ambiente , que substitui a chave do Registro. A COMPLUS_MDA cadeia de caracteres é uma lista delimitada por ponto-e-vírgula de nomes MDA ou outras cadeias de caracteres de controle especiais que não diferencia maiúsculas de minúsculas. Iniciar sob um depurador gerenciado ou não gerenciado habilita um conjunto de MDAs por padrão. Isso é feito antecipando implicitamente a lista delimitada por ponto-e-vírgula de MDAs habilitados por padrão em depuradores para o valor da variável de ambiente ou chave do Registro. As cadeias de controle especiais são as seguintes:
0- Desativa todos os MDAs.1- Lê as configurações do MDA de ApplicationName.mda.config.managedDebugger- Ativa explicitamente todos os MDAs que são ativados implicitamente quando um executável gerenciado é iniciado sob um depurador.unmanagedDebugger- Ativa explicitamente todos os MDAs que são ativados implicitamente quando um executável não gerenciado é iniciado sob um depurador.
Se houver configurações conflitantes, as configurações mais recentes substituem as configurações anteriores:
COMPLUS_MDA=0desabilita todos os MDAs, incluindo aqueles habilitados implicitamente em um depurador.COMPLUS_MDA=gcUnmanagedToManagedhabilitagcUnmanagedToManagedalém de quaisquer MDAs que estão implicitamente habilitados em um depurador.COMPLUS_MDA=0;gcUnmanagedToManagedhabilita,gcUnmanagedToManagedmas desabilita MDAs que, de outra forma, seriam habilitados implicitamente em um depurador.
Definições de configuração específicas do aplicativo
Você pode habilitar, desabilitar e configurar alguns assistentes individualmente no arquivo de configuração do MDA para o aplicativo. Para habilitar o uso de um arquivo de configuração de aplicativo para configurar MDAs, a chave do Registro MDA ou a COMPLUS_MDA variável de ambiente deve ser definida. O arquivo de configuração do aplicativo normalmente está localizado no mesmo diretório que o arquivo executável (.exe) do aplicativo. O nome do arquivo assume a forma ApplicationName.mda.config, por exemplo, notepad.exe.mda.config. Os assistentes habilitados no arquivo de configuração do aplicativo podem ter atributos ou elementos projetados para controlar o comportamento desse assistente.
O exemplo a seguir mostra como habilitar e configurar o marshaling:
<mdaConfig>
<assistants>
<marshaling>
<methodFilter>
<match name="*"/>
</methodFilter>
<fieldFilter>
<match name="*"/>
</fieldFilter>
</marshaling>
</assistants>
</mdaConfig>
O Marshaling MDA emite informações sobre o tipo gerenciado que está sendo empacotado para um tipo não gerenciado para cada transição gerenciada para não gerenciada no aplicativo. O Marshaling MDA também pode filtrar os nomes dos campos method e structure fornecidos nos elementos filho methodFilter e fieldFilter , respectivamente.
O exemplo a seguir mostra como habilitar vários MDAs usando suas configurações padrão:
<mdaConfig>
<assistants>
<illegalPrepareConstrainedRegion />
<invalidCERCall />
<openGenericCERCall />
<virtualCERCall />
</assistants>
</mdaConfig>
Importante
Ao especificar mais de um assistente em um arquivo de configuração, você deve listá-los em ordem alfabética. Por exemplo, se você quiser habilitar o virtualCERCall e os invalidCERCall MDAs, você deve adicionar a <invalidCERCall /> entrada antes da <virtualCERCall /> entrada. Se as entradas não estiverem em ordem alfabética, uma mensagem de exceção de arquivo de configuração inválida não tratada será exibida.
Exceções MDA
Quando um MDA está habilitado, ele fica ativo mesmo quando seu código não está sendo executado em um depurador. Se um evento MDA é gerado quando um depurador não está presente, a mensagem de evento é apresentada em uma caixa de diálogo de exceção sem tratamento, embora não seja uma exceção sem tratamento. Para evitar a caixa de diálogo, remova as configurações de habilitação do MDA quando o código não estiver sendo executado em um ambiente de depuração.
Quando seu código é executado no ambiente de desenvolvimento integrado (IDE) do Visual Studio, você pode evitar a caixa de diálogo de exceção que aparece para eventos MDA específicos. Para fazer isso, no menu Depurar, escolha Configurações de exceção do Windows>. Na janela Configurações de exceção, expanda a lista Assistentes de depuração gerenciados e desmarque a caixa de seleção Quebrar quando lançado para o MDA individual. Você também pode usar essa caixa de diálogo para habilitar a exibição de caixas de diálogo de exceção MDA.
Saída MDA
A saída MDA é semelhante ao exemplo a seguir, que mostra a PInvokeStackImbalance saída do MDA:
Uma chamada para a função PInvoke 'MDATest! MDATest.Program::StdCall' desequilibrou a pilha. Isso é provável porque a assinatura PInvoke gerenciada não corresponde à assinatura de destino não gerenciada. Verifique se a convenção de chamada e os parâmetros da assinatura PInvoke correspondem à assinatura não gerenciada de destino.
