Macros de relatórios de erros e depuração

Essas macros fornecem recursos úteis de depuração e rastreamento.

Nome	Descrição
_ATL_DEBUG_INTERFACES	Grava, na janela de saída, todos os vazamentos de interface detectados quando _Module.Term é chamado.
_ATL_DEBUG_QI	Grava todas as chamadas para QueryInterface na janela de saída.
ATLASSERT	Executa a mesma funcionalidade que a macro _ASSERTE localizada na biblioteca de runtime C.
ATLENSURE	Executa a validação de parâmetros. Chama AtlThrow, se necessário
ATLTRACENOTIMPL	Envia uma mensagem ao dispositivo de despejo informando que a função especificada não foi implementada.
ATLTRACE	Relata os avisos a um dispositivo de saída, como a janela do depurador, de acordo com os sinalizadores e os níveis indicados. Incluído para compatibilidade com versões anteriores.
ATLTRACE2	Relata os avisos a um dispositivo de saída, como a janela do depurador, de acordo com os sinalizadores e os níveis indicados.

_ATL_DEBUG_INTERFACES

Defina essa macro antes de incluir arquivos de cabeçalho de ATL para rastrear todas as chamadas AddRef e Release nas interfaces dos componentes para a janela de saída.

#define _ATL_DEBUG_INTERFACES

Comentários

A saída de rastreamento aparecerá conforme mostrado abaixo:

ATL: QIThunk - 2008 AddRef : Object = 0x00d81ba0 Refcount = 1 CBug - IBug

A primeira parte de cada traço será sempre ATL: QIThunk. Em seguida, há um valor que identifica a conversão de interface que está sendo usada. Uma conversão de interface é um objeto utilizado para manter uma contagem de referência e fornecer o recurso de rastreamento usado aqui. Uma nova conversão de interface é criada em cada chamada para QueryInterface exceto de solicitações para a interface IUnknown (nesse caso, a mesma conversão será retornada sempre para cumprir as regras de identidade do COM).

Em seguida, você verá AddRef ou Release indicando qual método foi chamado. Depois disso, você verá um valor identificando o objeto que teve a contagem de referência de interface alterada. O valor rastreado é o ponteiro this do objeto.

A contagem de referência é rastreada é a contagem de referência nessa conversão depois que AddRef ou Release foi chamado. Observe que essa contagem de referência poderá não corresponder à contagem de referência do objeto. Cada conversão mantém sua própria contagem de referência para ajudar você a cumprir totalmente as regras de contagem de referência do COM.

A informação final rastreada é o nome do objeto e a interface que está sendo afetada pela chamada AddRef ou Release.

Todos os vazamentos de interface detectados quando o servidor desligar e _Module.Term for chamado serão registrados dessa maneira:

ATL: QIThunk - 2005 LEAK : Object = 0x00d81ca0 Refcount = 1 MaxRefCount = 1 CBug - IBug

As informações fornecidas aqui são mapeadas diretamente para as informações fornecidas nas instruções de rastreamento anteriores, de modo que será possível examinar as contagens de referência durante todo o tempo de vida de uma conversão de interface. Além disso, você obtém uma indicação da contagem máxima de referência nessa conversão de interface.

Observação

_ATL_DEBUG_INTERFACES pode ser utilizado em builds de varejo.

_ATL_DEBUG_QI

Grava todas as chamadas para QueryInterface na janela de saída.

#define _ATL_DEBUG_QI

Comentários

Se uma chamada para QueryInterface falhar, a janela de saída exibirá:

nome da interface - failed

ATLASSERT

A macro ATLASSERT executa a mesma funcionalidade que a macro _ASSERTE localizada na biblioteca de runtime C.

ATLASSERT(booleanExpression);

Parâmetros

booleanExpression
Expressão (incluindo ponteiros) que é avaliada como diferente de zero ou 0.

Comentários

Em builds de depuração, o ATLASSERT avalia booleanExpression e gera um relatório de depuração quando o resultado é falso.

Requisitos

Cabeçalho: atldef.h

ATLENSURE

Essa macro é usada para validar os parâmetros passados para uma função.

ATLENSURE(booleanExpression);
ATLENSURE_THROW(booleanExpression, hr);

Parâmetros

booleanExpression
Especifica uma expressão booliana a ser testada.

RH
Especifica um código de erro a ser retornado.

Comentários

Essas macros fornecem um mecanismo para detectar e notificar o usuário sobre o uso incorreto de parâmetros.

A macro chama ATLASSERT e, se a condição falhar, chamará AtlThrow.

No caso ATLENSURE, AtlThrow é chamado com E_FAIL.

No caso ATLENSURE_THROW, AtlThrow é chamado com o HRESULT especificado.

A diferença entre ATLENSURE e ATLASSERT é que ATLENSURE gera uma exceção em builds de versão e em builds de depuração.

Exemplo

void MyImportantFunction(char* psz)
{
   ATLENSURE(NULL != psz);

   char mysz[64];
   strcpy_s(mysz, sizeof(mysz), psz);
}

Requisitos

Cabeçalho: afx.h

ATLTRACENOTIMPL

Em builds de depuração de ATL, envia a cadeia de caracteres "funcname não está implementado" ao dispositivo de despejo e retorna E_NOTIMPL.

ATLTRACENOTIMPL(funcname);

Parâmetros

funcname
[in] Uma cadeia de caracteres contendo o nome da função que não está implementada.

Comentários

Nas compilações de versão, simplesmente retorna E_NOTIMPL.

Exemplo

ATLTRACENOTIMPL(_T("IOleControl::GetControlInfo"));   

Requisitos

Cabeçalho: atltrace.h

ATLTRACE

Relata os avisos a um dispositivo de saída, como a janela do depurador, de acordo com os sinalizadores e os níveis indicados. Incluído para compatibilidade com versões anteriores.

ATLTRACE(exp);

ATLTRACE(
    DWORD category,
    UINT  level,
    LPCSTR lpszFormat, ...);

Parâmetros

exp
[in] A cadeia de caracteres e as variáveis a serem enviadas para a janela de saída ou qualquer aplicativo que intercepte essas mensagens.

category
[in] Tipo de evento ou método sobre o qual relatar. Consulte os Comentários para obter uma lista de categorias.

level
[in] O nível de rastreamento para relatar. Consulte os Comentários para obter os detalhes.

lpszFormat
[in] A cadeia de caracteres formatada a ser enviada ao dispositivo de despejo.

Comentários

Consulte ATLTRACE2 para obter uma descrição de ATLTRACE. ATLTRACE e ATLTRACE2 têm o mesmo comportamento, ATLTRACE está incluído para compatibilidade com versões anteriores.

ATLTRACE2

Relata os avisos a um dispositivo de saída, como a janela do depurador, de acordo com os sinalizadores e os níveis indicados.

ATLTRACE2(exp);

ATLTRACE2(
    DWORD category,
    UINT level,
    LPCSTR lpszFormat,  ...);

Parâmetros

exp
[in] A cadeia de caracteres a ser enviada para a janela de saída ou qualquer aplicativo que intercepte essas mensagens.

category
[in] Tipo de evento ou método sobre o qual relatar. Consulte os Comentários para obter uma lista de categorias.

level
[in] O nível de rastreamento para relatar. Consulte os Comentários para obter os detalhes.

lpszFormat
[in] A cadeia de caracteres do formato estilo printf a ser usada para criar uma cadeia de caracteres para enviar ao dispositivo de despejo.

Comentários

A forma abreviada de ATLTRACE2 grava uma cadeia de caracteres na janela de saída do depurador. A segunda forma de ATLTRACE2 também grava a saída na janela de saída do depurador, mas está sujeita às configurações da Ferramenta de Rastreamento do ATL/MFC (consulte Exemplo de ATLTraceTool). Por exemplo, se você definir o nível como 4 e a Ferramenta de Rastreamento do ATL/MFC como nível 0, você não verá a mensagem. O nível pode ser 0, 1, 2, 3 ou 4. O padrão, 0, relata apenas os problemas mais sérios.

O parâmetro da categoria lista os sinalizadores de rastreamento a serem definidos. Esses sinalizadores correspondem aos tipos de métodos para os quais você quer relatar. As tabelas abaixo listam os sinalizadores de rastreamento válidos que podem ser utilizados para o parâmetro da categoria.

Sinalizadores de rastreamento ATL

Categoria ATL	Descrição
atlTraceGeneral	Relatórios sobre todos os aplicativos ATL. O padrão.
atlTraceCOM	Relatórios sobre os métodos COM.
atlTraceQI	Relatórios sobre as chamadas QueryInterface.
atlTraceRegistrar	Relatórios sobre o registro de objetos.
atlTraceRefcount	Relatórios sobre a alteração de contagem de referência.
atlTraceWindowing	Relatórios sobre os métodos do Windows, por exemplo, relata uma ID do mapa de mensagem inválida.
atlTraceControls	Relatórios sobre os controles, por exemplo, relata quando um controle ou a janela é destruído.
atlTraceHosting	Relatórios de hospedagem de mensagens, por exemplo, relata quando um cliente em um contêiner é ativado.
atlTraceDBClient	Relatórios sobre o modelo de consumidor OLE DB, por exemplo, quando uma chamada para GetData falha, a saída pode conter o HRESULT.
atlTraceDBProvider	Relatórios sobre o modelo de provedor OLE DB, por exemplo, relata se a criação de uma coluna falhou.
atlTraceSnapin	Relatórios para o aplicativo SnapIn do MMC.
atlTraceNotImpl	Relata que a função indicada não foi implementada.
atlTraceAllocation	Relata as mensagens impressas pelas ferramentas de depuração de memória em atldbgmem.h.

Sinalizadores de rastreamento do MFC

Categoria do MFC	Descrição
traceAppMsg	Uso geral, mensagens do MFC. Sempre recomendado.
traceDumpContext	Mensagens de CDumpContext.
traceWinMsg	Mensagens do código de manipulação de mensagens do MFC.
traceMemory	Mensagens do código de gerenciamento de memória do MFC.
traceCmdRouting	Mensagens do código de roteamento de comando do Windows do MFC.
traceHtml	Mensagens do suporte para diálogo de DHTML do MFC.
traceSocket	Mensagens do suporte para soquete do MFC.
traceOle	Mensagens do suporte para OLE do MFC.
traceDatabase	Mensagens do suporte para banco de dados do MFC.
traceInternet	Mensagens do suporte para Internet do MFC.

Para declarar uma categoria de rastreamento personalizada, declare uma instância global da classe CTraceCategory conforme a seguir:

CTraceCategory MY_CATEGORY(_T("MyCategoryName"), 1);

O nome da categoria, MY_CATEGORY neste exemplo, é o nome especificado para o parâmetro da categoria. O primeiro parâmetro é o nome da categoria que aparecerá na ferramenta de rastreamento do ATL/MFC. O segundo parâmetro é o nível de rastreamento padrão. Esse parâmetro é opcional e o nível de rastreamento padrão é 0.

Para usar uma categoria definida pelo usuário:

ATLTRACE2(MY_CATEGORY, 2, _T("a message in a custom category"));

Para especificar que você quer filtrar as mensagens de rastreamento, insira as definições para essas macros em Stdafx.h antes da instrução #include <atlbase.h>.

Como alternativa, você pode definir o filtro nas diretivas do pré-processador na caixa de diálogo Páginas de Propriedades. Clique na guia Pré-processador e, em seguida, insira o global na caixa de edição Definições do Pré-processador.

Atlbase.h contém as definições padrão das macros ATLTRACE2 e essas definições serão usadas se você não definir esses símbolos antes que atlbase.h seja processado.

Nas compilações de versão, ATLTRACE2 compila para (void) 0.

ATLTRACE2 limitará o conteúdo da cadeia de caracteres a ser enviada ao dispositivo de despejo para no máximo 1023 caracteres após a formatação.

ATLTRACE e ATLTRACE2 têm o mesmo comportamento, ATLTRACE está incluído para compatibilidade com versões anteriores.

Exemplo

int i = 1;
ATLTRACE2(atlTraceGeneral, 4, "Integer = %d\n", i);
// Output: 'Integer = 1'

Confira também

Macros
Funções globais de relatório de erros e depuração