Diagnosticar erros com assistentes de depuração gerenciada

Os MDAs (assistentes de depuração gerenciados) são auxiliares de depuração que funcionam com o CLR (Common Language Runtime) para fornecer informações sobre o estado de runtime. Os assistentes geram mensagens informativas sobre eventos de runtime que não podem ser interceptados de outro modo. Você pode usar MDAs para isolar bugs de aplicativo difíceis de localizar 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íficas usando as configurações de aplicativo. Você pode definir configurações adicionais para alguns MDAs individuais no arquivo de configuração do aplicativo. Como esses arquivos de configuração são analisados quando o runtime é carregado, você deve habilitar o MDA antes do início do aplicativo gerenciado. Não é possível habilitá-lo para aplicativos que já foram iniciados.

A tabela a seguir lista os MDAs que são enviados 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 asConfigurações de Exceção do > no menu Depurar e expandindo a lista Assistentes de Depuração Gerenciada.

Habilitar e desabilitar MDAs

Você pode habilitar e desabilitar MDAs usando uma chave do Registro, uma variável de ambiente e configurações de aplicativo. Você deve habilitar a chave do Registro ou a variável de ambiente para usar as configurações do aplicativo.

Chave do Registo

Para habilitar MDAs, adicione a subchaveHKEY_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 MDAs nesse computador. Definir a subchave para o valor string 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 nomeado 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 deverá ser definida da seguinte maneira:

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\.NETFramework]
"MDA"="1"

Consulte Application-Specific Configuraçõ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 a Variável de Ambiente para obter mais informações.

Para desabilitar 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 vinculado a um depurador, mesmo sem adicionar uma chave do Registro. Você pode desabilitar 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 cadeia de caracteres COMPLUS_MDA é uma lista delimitada por ponto-e-vírgula, que não diferencia maiúsculas de minúsculas, de nomes de MDA ou outras cadeias de caracteres de controle especiais. A inicialização em um depurador gerenciado ou não gerenciado habilita um conjunto de MDAs por padrão. Isso é feito implicitamente precedendo a lista separada por ponto-e-vírgula de MDAs habilitados por padrão nos depuradores ao valor da variável de ambiente ou da chave do Registro. As cadeias de caracteres de controle especiais são as seguintes:

• 0 - Desativa todos os MDAs.

• 1 – Lê as configurações do MDA por meio de ApplicationName.mda.config.

• managedDebugger – Ativa explicitamente todos os MDAs ativados implicitamente quando um executável gerenciado é iniciado em um depurador.

• unmanagedDebugger – Ativa explicitamente todos os MDAs que são ativados implicitamente quando um executável não gerenciado é iniciado em um depurador.

Se houver configurações conflitantes, as configurações mais recentes substituirão as configurações anteriores:

• COMPLUS_MDA=0 desabilita todos os MDAs, incluindo aqueles habilitados implicitamente em um depurador.

• COMPLUS_MDA=gcUnmanagedToManaged habilita gcUnmanagedToManaged, além de todos os MDAs habilitados implicitamente em um depurador.

• COMPLUS_MDA=0;gcUnmanagedToManaged habilita gcUnmanagedToManaged, mas desabilita os MDAs que seriam, de outro modo, 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 do MDA ou a variável de COMPLUS_MDA ambiente devem ser definidas. 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 usa o formulário 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 MDA Marshaling emite informações sobre o tipo gerenciado em que o marshaling está sendo realizado para um tipo não gerenciado para a transição gerenciado/não gerenciado no aplicativo. O MDA Marshaling também pode filtrar os nomes do método e os campos de 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 de MDA

Quando um MDA está habilitado, ele está ativo mesmo quando seu código não está sendo executado em um depurador. Se um evento MDA for gerado quando um depurador não estiver presente, a mensagem de evento será 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 em execução em um ambiente de depuração.

Quando o código é executado no IDE (ambiente de desenvolvimento integrado) do Visual Studio, você pode evitar a caixa de diálogo de exceção exibida para eventos específicos do MDA. 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 Gerenciada e desmarque a caixa de seleção Interromper quando Gerado 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 do MDA.

Saída do MDA

A saída do MDA é semelhante ao exemplo a seguir, que mostra a saída do PInvokeStackImbalance MDA:

Uma chamada para a função PInvoke 'MDATest!MDATest.Program::StdCall' desequilibrou a pilha. Isso provavelmente ocorre 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.

Consulte também

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