Diagnosticar erros com assistentes de depuração gerenciados

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 escolhendoConfigurações de Exceção do > 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.

Chave de registo

Para habilitar MDAs, adicione a subchave HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\MDA (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 .mda.config ApplicationName.suffix . 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 Application-Specific definições de configuração para obter mais informações. A configuração do registro pode ser substituída pela variável de ambiente COMPLUS_MDA. 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 ativados quando se executa uma aplicação anexada 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, que não diferencia maiúsculas de minúsculas, é uma lista delimitada por ponto-e-vírgula de nomes MDA ou outras cadeias de caracteres de controle especiais. Iniciar sob um depurador gerenciado ou não gerenciado ativa um conjunto de MDAs por padrão. Isto é feito ao antepor implicitamente a lista delimitada por ponto e vírgula de MDAs ativados por padrão em depuradores ao valor da variável de ambiente ou chave de registo. 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 gerido é iniciado num depurador.

• unmanagedDebugger - Ativa explicitamente todos os MDAs que são ativados implicitamente quando um executável não gerido é iniciado por um depurador.

Se houver configurações conflitantes, as configurações mais recentes substituem as configurações anteriores:

• COMPLUS_MDA=0 desativa todos os MDAs, incluindo aqueles ativados implicitamente num depurador.

• COMPLUS_MDA=gcUnmanagedToManaged ativa gcUnmanagedToManaged além de quaisquer MDAs que são ativados implicitamente num depurador.

• COMPLUS_MDA=0;gcUnmanagedToManaged habilita gcUnmanagedToManaged, mas desativa MDAs que, de outra forma, seriam habilitados implicitamente com um debugger.

Application-Specific definições de configuração

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 gerido que está a ser convertido para um tipo não gerido, em cada transição de gerido para não gerido na aplicação. O Marshaling MDA também pode filtrar os nomes dos campos de método e estrutura 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>

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 numa caixa de diálogo de exceção não tratada, ainda que não seja uma exceção não tratada. 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, escolhaConfigurações de exceção do>. Na janela Configurações de exceção, expanda a lista Assistentes de depuração geridos e desmarque a caixa de seleção Interromper 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 saída contida no PInvokeStackImbalance 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.

Ver também

• Depuração, rastreamento e criação de perfil