Macros de Depuração e Reporte de Erros

Observação

A Active Template Library (ATL) continua a ser suportada. No entanto, já não estamos a adicionar funcionalidades nem a atualizar a documentação.

Estas macros fornecem funcionalidades úteis de depuração e rastreamento.

Nome	Description
_ATL_DEBUG_INTERFACES	Escreve, na janela de saída, quaisquer fugas de interface que sejam detetadas quando _Module.Term é chamada.
_ATL_DEBUG_QI	Escreve todas as chamadas para QueryInterface na janela de saída.
ATLASSERT	Executa a mesma funcionalidade que a macro _ASSERTE encontrada na biblioteca de tempo de execução C.
ATLENSURE	Realiza a validação de parâmetros. Ligue AtlThrow se for necessário
ATLTRACENOTIMPL	Envia uma mensagem ao dispositivo de despejo a indicar que a função especificada não está implementada.
ATLTRACE	Reporta avisos a um dispositivo de saída, como a janela do depurador, de acordo com as bandeiras e níveis indicados. Incluído para compatibilidade retroativa.
ATLTRACE2	Reporta avisos a um dispositivo de saída, como a janela do depurador, de acordo com as bandeiras e níveis indicados.

_ATL_DEBUG_INTERFACES

Defina esta macro antes de incluir quaisquer ficheiros de cabeçalho ATL para rastrear todas AddRefRelease as chamadas e chamadas das interfaces dos seus componentes até à janela de saída.

#define _ATL_DEBUG_INTERFACES

Observações

A saída do traço aparecerá conforme mostrado abaixo:

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

A primeira parte de cada traço será ATL: QIThunksempre . De seguida, há um valor que identifica o thunk particular da interface que está a ser utilizado. Um thunk de interface é um objeto usado para manter uma contagem de referências e fornecer a capacidade de traço aqui utilizada. Um novo thunk de interface é criado em cada chamada to QueryInterface , exceto para pedidos para a IUnknown interface (neste caso, o mesmo thunk é devolvido todas as vezes para cumprir as regras de identidade do COM).

A seguir, verá ou Release indicará AddRef qual método foi chamado. Depois disso, verá um valor que identifica o objeto cujo número de referências de interface foi alterado. O valor traçado é o this ponteiro do objeto.

A contagem de referências que é rastreada é a contagem de referências nesse thunk após AddRef ou Release foi chamado. Note-se que esta contagem de referências pode não corresponder à contagem de referências do objeto. Cada thunk mantém a sua própria contagem de referências para o ajudar a cumprir totalmente as regras de contagem de referências da COM.

A última informação rastreada é o nome do objeto e a interface afetada pela AddRef chamada ou.Release

Quaisquer fugas de interface que sejam detetadas quando o servidor desliga e _Module.Term é chamado serão registadas desta forma:

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

A informação aqui fornecida corresponde diretamente à informação fornecida nas instruções de traço anteriores, pelo que pode examinar as contagens de referências ao longo de toda a vida útil de um thunk de interface. Além disso, obtém uma indicação do número máximo de referências nesse thunk da interface.

Observação

_ATL_DEBUG_INTERFACES podem ser usados em construções de retalho.

_ATL_DEBUG_QI

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

#define _ATL_DEBUG_QI

Observações

Se uma chamada falhar QueryInterface , a janela de saída irá mostrar:

Nome da interface - failed

ATLASSERT

A macro ATLASSERT executa a mesma funcionalidade que a macro _ASSERTE encontrada na biblioteca de tempo de execução C.

ATLASSERT(booleanExpression);

Parâmetros

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

Observações

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

Requerimentos

Cabeçalho: atldef.h

ATLENSURE

Esta macro é usada para validar parâmetros passados a uma função.

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

Parâmetros

booleanExpression
Especifica uma expressão booleana a ser testada.

horas
Especifica um código de erro a devolver.

Observações

Estas macros fornecem um mecanismo para detetar e notificar o utilizador sobre o uso incorreto dos parâmetros.

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

No caso da ATLCENSOR, AtlThrow é chamado com E_FAIL.

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

A diferença entre ATLENSURE e ATLASSERT é que ATLENSURE lança uma exceção tanto em versões de Release como em compilações de Debug.

Example

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

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

Requerimentos

Cabeçalho: afx.h

ATLTRACENOTIMPL

Em compilações de depuração do ATL, envia a string " funcname is not implemented" para o dispositivo de dump e retorna E_NOTIMPL.

ATLTRACENOTIMPL(funcname);

Parâmetros

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

Observações

Nas versões de lançamento, simplesmente devolve E_NOTIMPL.

Example

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

Requerimentos

Cabeçalho: atltrace.h

ATLTRACE

Reporta avisos a um dispositivo de saída, como a janela do depurador, de acordo com as bandeiras e níveis indicados. Incluído para compatibilidade retroativa.

ATLTRACE(exp);

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

Parâmetros

exp
[dentro] A string e as variáveis a enviar para a janela de saída ou para qualquer aplicação que prenda estas mensagens.

categoria
[dentro] Tipo de evento ou método para reportar. Consulte as Observações para uma lista de categorias.

nível
[dentro] O nível de rastreamento a reportar. Consulte as Observações para mais detalhes.

lpszFormat
[dentro] A string formatada para enviar ao dispositivo de dump.

Observações

Veja ATLTRACE2 para uma descrição do ATLTRACE. ATLTRACE e ATLTRACE2 têm o mesmo comportamento, ATLTRACE está incluído para compatibilidade retroativa.

ATLTRACE2

Reporta avisos a um dispositivo de saída, como a janela do depurador, de acordo com as bandeiras e níveis indicados.

ATLTRACE2(exp);

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

Parâmetros

exp
[dentro] A cadeia a enviar para a janela de saída ou qualquer aplicação que prenda estas mensagens.

categoria
[dentro] Tipo de evento ou método para reportar. Consulte as Observações para uma lista de categorias.

nível
[dentro] O nível de rastreamento a reportar. Consulte as Observações para mais detalhes.

lpszFormat
[dentro] A printfcadeia de formato -style a usar para criar uma string para enviar ao dispositivo de dump.

Observações

A forma curta de ATLTRACE2 escreve uma string na janela de saída do depurador. A segunda forma de ATLTRACE2 também escreve a saída na janela de saída do depurador, mas está sujeita às definições da Ferramenta ATL/MFC Trace (ver Exemplo ATLTraceTool). Por exemplo, se definir o nível para 4 e a ferramenta ATL/MFC Trace para o nível 0, não verá a mensagem. O nível pode ser 0, 1, 2, 3 ou 4. O padrão, 0, reporta apenas os problemas mais graves.

O parâmetro de categoria lista as bandeiras de traço a definir. Estes flags correspondem aos tipos de métodos pelos quais pretende reportar. As tabelas abaixo listam as bandeiras de traço válidas que pode usar para o parâmetro da categoria .

ATL Trace Flags

Categoria ATL	Description
atlTraceGeneral	Relatórios sobre todas as candidaturas da ATL. O padrão.
atlTraceCOM	Relatórios sobre métodos COM.
atlTraceQI	Relatórios sobre chamadas QueryInterface.
atlTraceRegistrar	Relatórios sobre o registo de objetos.
atlTraceRefcount	Relatórios sobre alterações no número de referências.
atlTraceWindowing	Relatórios sobre métodos de janelas; por exemplo, reporta um ID de mapa de mensagem inválido.
atlTraceControls	Relatórios sobre controlos; por exemplo, reporta quando um controlo ou a sua janela é destruído.
atlTraceHosting	Relatórios de hospedagem de mensagens; por exemplo, reporta quando um cliente num contentor é ativado.
atlTraceDBClient	Relatórios sobre o Modelo de Consumo OLE DB; por exemplo, quando uma chamada ao GetData falha, a saída pode conter o HRESULT.
atlTraceDBProvider	Relatórios sobre o Modelo de Prestador OLE DB; por exemplo, relatórios se a criação de uma coluna falhou.
atlTraceSnapin	Relatórios para a aplicação MMC SnapIn.
atlTraceNotImpl	Relata que a função indicada não está implementada.
atlTraceAllocation	Reporta mensagens impressas pelas ferramentas de depuração de memória em atldbgmem.h.

MFC Trace Flags

Categoria MFC	Description
traceAppMsg	Mensagens de uso geral, MFC. Sempre recomendado.
traceDumpContext	Mensagens do CDumpContext.
traceWinMsg	Mensagens do código de tratamento de mensagens do MFC.
traceMemory	Mensagens do código de gestão de memória do MFC.
traceCmdRouting	Mensagens do código de encaminhamento de comandos do Windows do MFC.
traceHtml	Suporte para mensagens do diálogo DHTML do MFC.
traceSocket	Mensagens do suporte de sockets da MFC.
traceOle	Mensagens do suporte OLE da MFC.
traceDatabase	Mensagens da base de dados da MFC suportam.
traceInternet	Mensagens do suporte à Internet da MFC.

Para declarar uma categoria de traço personalizada, declare uma instância global da CTraceCategory classe da seguinte forma:

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

O nome da categoria, MY_CATEGORY neste exemplo, é o nome que especifica para o parâmetro da categoria . O primeiro parâmetro é o nome da categoria que aparecerá na Ferramenta ATL/MFC Trace. O segundo parâmetro é o nível padrão do traço. Este parâmetro é opcional, e o nível padrão do traço é 0.

Para usar uma categoria definida pelo utilizador:

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

Para especificar que queres filtrar as mensagens de rastreamento, insere definições para essas macros no Stdafx.h antes da #include <atlbase.h> instrução.

Alternativamente, pode definir o filtro nas diretivas do pré-processador na caixa de diálogo Páginas de Propriedades . Clique no separador Pré-processador e depois insira o global na caixa de edição de Definições do Pré-processador .

Atlbase.h contém definições padrão dos macros ATLTRACE2 e essas definições serão usadas se não definir estes símbolos antes de o atlbase.h ser processado.

Nas versões de release, ATLTRACE2 compila para (void) 0.

ATLTRACE2 limita o conteúdo da string a ser enviado para o dispositivo de dump a no máximo 1023 caracteres, após formatação.

ATLTRACE e ATLTRACE2 têm o mesmo comportamento, ATLTRACE está incluído para compatibilidade retroativa.

Example

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

Consulte também

Macros
Depuração e Funções Globais de Relatórios de Erros