Diagnosticar erros com assistentes de depuração gerenciada

Os MDAs (Assistentes de depuração gerenciada) são recursos de depuração que trabalham com o CLR (Common Language Runtime) para fornecer informações sobre o estado do tempo de execução. Os assistentes geram mensagens informativas sobre eventos de runtime que não podem ser interceptados de outro modo. É possível 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.

É possível 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 definições de configuração do aplicativo. É possível 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 da inicialização do aplicativo gerenciado. Não será possível habilitá-lo para aplicativos já iniciados.

A tabela a seguir lista os MDAs que acompanham o .NET Framework:

Por padrão, o .NET Framework ativa um subconjunto de MDAs para todos os depuradores gerenciados. É possível exibir o conjunto padrão no Visual Studio ao escolher Windows>Configurações de Exceção no menu Depurar e expandindo a lista Assistentes de Depuração Gerenciada.

Habilitar e desabilitar MDAs

É possível habilitar e desabilitar MDAs usando uma chave do Registro, uma variável de ambiente e as 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 do Registro

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 MDAs nesse computador. A definição da subchave com o valor de cadeia de caracteres 1 (e não o valor DWORD 1) habilita a leitura das configurações do MDA por meio do arquivo ApplicationName.suffix.mda.config. Por exemplo, o arquivo de configuração do MDA para o Bloco de Notas teria o nome de 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 do MDA deverá ser definida da seguinte forma:

Windows Registry Editor Version 5.00

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

Confira 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 ambiente COMPLUS_MDA. Confira Variável de ambiente para obter mais informações.

Para desabilitar MDAs, defina a subchave do 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 desabilitar esses assistentes executando o arquivo MDADisable.reg, como descrito antes nesta seção.

Variável de ambiente

A ativação do MDA também pode ser controlada pela variável de ambiente COMPLUS_MDA, 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 ativados implicitamente quando um executável não gerenciado é iniciado em um depurador.

Se houver configurações conflitantes, as mais recentes substituirão as 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

É possível 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 ambiente COMPLUS_MDA deve estar definida. O arquivo de configuração de aplicativo costuma ficar localizado no mesmo diretório do arquivo executável do aplicativo (.exe). 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 de 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 as configurações padrão:

<mdaConfig>
  <assistants>
    <illegalPrepareConstrainedRegion />
    <invalidCERCall />
    <openGenericCERCall />
    <virtualCERCall />
  </assistants>
</mdaConfig>

Exceções de MDA

Quando um MDA está habilitado, ele permanece ativo mesmo quando o código não está sendo executado em um depurador. Se um evento de MDA for acionado quando um depurador não estiver presente, a mensagem do evento será apresentada em uma caixa de diálogo de exceção sem tratamento, ainda que não seja uma exceção sem tratamento. Para evitar a caixa de diálogo, remova as configurações de habilitação de 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, será possível evitar a exibição da caixa de diálogo da exceção para eventos de MDA específicos. Para fazer isso, no menu Depurar, escolha Windows>Configurações de Exceção. 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. Também é possível 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 à do exemplo a seguir, que mostra a saída do MDA PInvokeStackImbalance:

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.

Confira também

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