Macros de depuração e relatório de errosDebugging and Error Reporting Macros

Essas macros fornecem recursos úteis de depuração e rastreamento.These macros provide useful debugging and trace facilities.

NameName DescriçãoDescription
_ATL_DEBUG_INTERFACES_ATL_DEBUG_INTERFACES Grava, na janela saída, qualquer vazamento de interface detectado quando _Module.Term é chamado.Writes, to the output window, any interface leaks that are detected when _Module.Term is called.
_ATL_DEBUG_QI_ATL_DEBUG_QI Grava todas as chamadas para QueryInterface na janela de saída.Writes all calls to QueryInterface to the output window.
ATLASSERTATLASSERT Executa a mesma funcionalidade que a macro _ASSERTE encontrada na biblioteca de tempo de execução C.Performs the same functionality as the _ASSERTE macro found in the C run-time library.
ATLENSUREATLENSURE Executa a validação de parâmetros.Performs parameters validation. Chamada AtlThrow se necessárioCall AtlThrow if needed
ATLTRACENOTIMPLATLTRACENOTIMPL Envia uma mensagem para o dispositivo de despejo que a função especificada não está implementada.Sends a message to the dump device that the specified function is not implemented.
ATLTRACEATLTRACE Relata avisos para um dispositivo de saída, como a janela do depurador, de acordo com os sinalizadores e os níveis indicados.Reports warnings to an output device, such as the debugger window, according to the indicated flags and levels. Incluído para compatibilidade com versões anteriores.Included for backward compatibility.
ATLTRACE2ATLTRACE2 Relata avisos para um dispositivo de saída, como a janela do depurador, de acordo com os sinalizadores e os níveis indicados.Reports warnings to an output device, such as the debugger window, according to the indicated flags and levels.

_ATL_DEBUG_INTERFACES_ATL_DEBUG_INTERFACES

Defina essa macro antes de incluir qualquer arquivo de cabeçalho da ATL para rastrear todas as AddRef Release chamadas e suas interfaces de componentes para a janela de saída.Define this macro before including any ATL header files to trace all AddRef and Release calls on your components' interfaces to the output window.

#define _ATL_DEBUG_INTERFACES

ComentáriosRemarks

A saída do rastreamento será exibida conforme mostrado abaixo:The trace output will appear as shown below:

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

A primeira parte de cada rastreamento sempre será ATL: QIThunk .The first part of each trace will always be ATL: QIThunk. Next é um valor que identifica a conversão de interface específica que está sendo usada.Next is a value identifying the particular interface thunk being used. Uma conversão de interface é um objeto usado para manter uma contagem de referência e fornecer o recurso de rastreamento usado aqui.An interface thunk is an object used to maintain a reference count and provide the tracing capability used here. Uma nova conversão de interface é criada em cada chamada para QueryInterface , exceto para solicitações da IUnknown interface (nesse caso, a mesma conversão é retornada toda vez para atender às regras de identidade do com).A new interface thunk is created on every call to QueryInterface except for requests for the IUnknown interface (in this case, the same thunk is returned every time to comply with COM's identity rules).

Em seguida, você verá AddRef ou Release indicará qual método foi chamado.Next you'll see AddRef or Release indicating which method was called. Depois disso, você verá um valor que identifica o objeto cuja contagem de referência de interface foi alterada.Following that, you'll see a value identifying the object whose interface reference count was changed. O valor rastreado é o this ponteiro do objeto.The value traced is the this pointer of the object.

A contagem de referência que é rastreada é a contagem de referência nessa conversão após AddRef ou Release foi chamada.The reference count that is traced is the reference count on that thunk after AddRef or Release was called. Observe que essa contagem de referência pode não corresponder à contagem de referência do objeto.Note that this reference count may not match the reference count for the object. Cada conversão mantém sua própria contagem de referência para ajudá-lo a cumprir totalmente as regras de contagem de referência do COM.Each thunk maintains its own reference count to help you fully comply with COM's reference-counting rules.

A parte final das informações rastreadas é o nome do objeto e a interface que está sendo afetada AddRef pela Release chamada ou.The final piece of information traced is the name of the object and the interface being affected by the AddRef or Release call.

Qualquer vazamento de interface detectado quando o servidor é desligado e _Module.Term chamado será registrado da seguinte maneira:Any interface leaks that are detected when the server shuts down and _Module.Term is called will be logged like this:

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, para que você possa examinar as contagens de referência durante todo o tempo de vida de uma conversão de interface.The information provided here maps directly to the information provided in the previous trace statements, so you can examine the reference counts throughout the whole lifetime of an interface thunk. Além disso, você obtém uma indicação da contagem de referência máxima nessa conversão de interface.In addition, you get an indication of the maximum reference count on that interface thunk.

Observação

_ATL_DEBUG_INTERFACES pode ser usado em compilações de varejo._ATL_DEBUG_INTERFACES can be used in retail builds.

_ATL_DEBUG_QI_ATL_DEBUG_QI

Grava todas as chamadas para QueryInterface na janela de saída.Writes all calls to QueryInterface to the output window.

#define _ATL_DEBUG_QI

ComentáriosRemarks

Se uma chamada a QueryInterface falhar, a janela de saída será exibida:If a call to QueryInterface failed, the output window will display:

nome da interface - failedinterface name - failed

ATLASSERTATLASSERT

A macro ATLASSERT executa a mesma funcionalidade que a macro _ASSERTE encontrada na biblioteca de tempo de execução do C.The ATLASSERT macro performs the same functionality as the _ASSERTE macro found in the C run-time library.

ATLASSERT(booleanExpression);

ParâmetrosParameters

valor boolianobooleanExpression
Expressão (incluindo ponteiros) que é avaliada como zero ou 0.Expression (including pointers) that evaluates to nonzero or 0.

ComentáriosRemarks

Em builds de depuração, ATLASSERT avalia a booliana e gera um relatório de depuração quando o resultado é false.In debug builds, ATLASSERT evaluates booleanExpression and generates a debug report when the result is false.

RequisitosRequirements

Cabeçalho: atldef. hHeader: atldef.h

ATLENSUREATLENSURE

Essa macro é usada para validar os parâmetros passados para uma função.This macro is used to validate parameters passed to a function.

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

ParâmetrosParameters

valor boolianobooleanExpression
Especifica uma expressão booliana a ser testada.Specifies a boolean expression to be tested.

hhr
Especifica um código de erro a ser retornado.Specifies an error code to return.

ComentáriosRemarks

Essas macros fornecem um mecanismo para detectar e notificar o usuário sobre o uso de parâmetro incorreto.These macros provide a mechanism to detect and notify the user of incorrect parameter usage.

A macro chama ATLASSERT e se a condição falhar em chamadas AtlThrow .The macro calls ATLASSERT and if the condition fails calls AtlThrow.

No caso ATLENSURE, AtlThrow é chamado com E_FAIL.In the ATLENSURE case, AtlThrow is called with E_FAIL.

No ATLENSURE_THROW caso, AtlThrow é chamado com o HRESULT especificado.In the ATLENSURE_THROW case, AtlThrow is called with the specified HRESULT.

A diferença entre ATLENSURE e ATLASSERT é que o ATLENSURE gera uma exceção em compilações de versão, bem como em compilações de depuração.The difference between ATLENSURE and ATLASSERT is that ATLENSURE throws an exception in Release builds as well as in Debug builds.

ExemploExample

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

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

RequisitosRequirements

Cabeçalho: AFX. hHeader: afx.h

ATLTRACENOTIMPLATLTRACENOTIMPL

Nas compilações de depuração da ATL, o envia a cadeia de caracteres " FuncName não é implementado" para o dispositivo de despejo e retorna E_NOTIMPL.In debug builds of ATL, sends the string " funcname is not implemented" to the dump device and returns E_NOTIMPL.

ATLTRACENOTIMPL(funcname);

ParâmetrosParameters

funcnamefuncname
no Uma cadeia de caracteres que contém o nome da função que não está implementada.[in] A string containing the name of the function that is not implemented.

ComentáriosRemarks

Em builds de versão, simplesmente retorna E_NOTIMPL.In release builds, simply returns E_NOTIMPL.

ExemploExample

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

RequisitosRequirements

Cabeçalho: ATLTRACE. hHeader: atltrace.h

ATLTRACEATLTRACE

Relata avisos para um dispositivo de saída, como a janela do depurador, de acordo com os sinalizadores e os níveis indicados.Reports warnings to an output device, such as the debugger window, according to the indicated flags and levels. Incluído para compatibilidade com versões anteriores.Included for backward compatibility.

ATLTRACE(exp);

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

ParâmetrosParameters

expexp
no A cadeia de caracteres e as variáveis a serem enviadas à janela de saída ou a qualquer aplicativo que intercepta essas mensagens.[in] The string and variables to send to the output window or any application that traps these messages.

categorycategory
no Tipo de evento ou método no qual relatar.[in] Type of event or method on which to report. Consulte os comentários para obter uma lista de categorias.See the Remarks for a list of categories.

levellevel
no O nível de rastreamento a ser relatado.[in] The level of tracing to report. Consulte os comentários para obter detalhes.See the Remarks for details.

lpszFormatlpszFormat
no A cadeia de caracteres formatada a ser enviada ao dispositivo de despejo.[in] The formatted string to send to the dump device.

ComentáriosRemarks

Consulte ATLTRACE2 para obter uma descrição de ATLTRACE.See ATLTRACE2 for a description of ATLTRACE. ATLTRACE e ATLTRACE2 têm o mesmo comportamento, ATLTRACE está incluído para compatibilidade com versões anteriores.ATLTRACE and ATLTRACE2 have the same behavior, ATLTRACE is included for backward compatibility.

ATLTRACE2ATLTRACE2

Relata avisos para um dispositivo de saída, como a janela do depurador, de acordo com os sinalizadores e os níveis indicados.Reports warnings to an output device, such as the debugger window, according to the indicated flags and levels.

ATLTRACE2(exp);

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

ParâmetrosParameters

expexp
no A cadeia de caracteres a ser enviada à janela de saída ou a qualquer aplicativo que intercepta essas mensagens.[in] The string to send to the output window or any application that traps these messages.

categorycategory
no Tipo de evento ou método no qual relatar.[in] Type of event or method on which to report. Consulte os comentários para obter uma lista de categorias.See the Remarks for a list of categories.

levellevel
no O nível de rastreamento a ser relatado.[in] The level of tracing to report. Consulte os comentários para obter detalhes.See the Remarks for details.

lpszFormatlpszFormat
no A printf cadeia de caracteres de formato de estilo a ser usada para criar uma cadeia de caracteres a ser enviada ao dispositivo de despejo.[in] The printf-style format string to use to create a string to send to the dump device.

ComentáriosRemarks

A forma abreviada de ATLTRACE2 grava uma cadeia de caracteres na janela de saída do depurador.The short form of ATLTRACE2 writes a string to the debugger's output window. 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 ATL/MFC (consulte a amostra ATLTraceTool).The second form of ATLTRACE2 also writes output to the debugger's output window, but is subject to the settings of the ATL/MFC Trace Tool (see ATLTraceTool Sample). Por exemplo, se você definir nível como 4 e a ferramenta de rastreamento ATL/MFC para nível 0, você não verá a mensagem.For example, if you set level to 4 and the ATL/MFC Trace Tool to level 0, you will not see the message. o nível pode ser 0, 1, 2, 3 ou 4.level can be 0, 1, 2, 3, or 4. O padrão, 0, relata apenas os problemas mais graves.The default, 0, reports only the most serious problems.

O parâmetro Category lista os sinalizadores de rastreamento a serem definidos.The category parameter lists the trace flags to set. Esses sinalizadores correspondem aos tipos de métodos para os quais você deseja relatar.These flags correspond to the types of methods for which you want to report. As tabelas a seguir listam os sinalizadores de rastreamento válidos que você pode usar para o parâmetro Category .The tables below list the valid trace flags you can use for the category parameter.

Sinalizadores de rastreamento da ATLATL Trace Flags

Categoria da ATLATL Category DescriçãoDescription
atlTraceGeneral Relatórios sobre todos os aplicativos ATL.Reports on all ATL applications. O padrão.The default.
atlTraceCOM Relatórios sobre métodos COM.Reports on COM methods.
atlTraceQI Relata as chamadas de QueryInterface.Reports on QueryInterface calls.
atlTraceRegistrar Relatórios sobre o registro de objetos.Reports on the registration of objects.
atlTraceRefcount Relatórios sobre a alteração da contagem de referência.Reports on changing reference count.
atlTraceWindowing Relatórios sobre os métodos do Windows; por exemplo, relata uma ID de mapa de mensagem inválida.Reports on windows methods; for example, reports an invalid message map ID.
atlTraceControls Relatórios sobre controles; por exemplo, relata quando um controle ou sua janela é destruído.Reports on controls; for example, reports when a control or its window is destroyed.
atlTraceHosting Relata mensagens de hospedagem; por exemplo, relata quando um cliente em um contêiner é ativado.Reports hosting messages; for example, reports when a client in a container is activated.
atlTraceDBClient Relatórios sobre o modelo de consumidor OLE DB; por exemplo, quando uma chamada para GetData falha, a saída pode conter HRESULT.Reports on OLE DB Consumer Template; for example, when a call to GetData fails, the output can contain the HRESULT.
atlTraceDBProvider Relatórios sobre o modelo de provedor de OLE DB; por exemplo, relata se a criação de uma coluna falhou.Reports on OLE DB Provider Template; for example, reports if the creation of a column failed.
atlTraceSnapin Relatórios do aplicativo de snap-in do MMC.Reports for MMC SnapIn application.
atlTraceNotImpl Relata que a função indicada não está implementada.Reports that the indicated function is not implemented.
atlTraceAllocation Relata as mensagens impressas pelas ferramentas de depuração de memória em atldbgmem. h.Reports messages printed by the memory debugging tools in atldbgmem.h.

Sinalizadores de rastreamento do MFCMFC Trace Flags

Categoria do MFCMFC Category DescriçãoDescription
traceAppMsg Uso geral, mensagens do MFC.General purpose, MFC messages. Sempre recomendado.Always recommended.
traceDumpContext Mensagens de CDumpContext.Messages from CDumpContext.
traceWinMsg Mensagens do código de manipulação de mensagens do MFC.Messages from MFC's message handling code.
traceMemory Mensagens do código de gerenciamento de memória do MFC.Messages from MFC's memory management code.
traceCmdRouting Mensagens do código de roteamento de comando do Windows do MFC.Messages from MFC's Windows command routing code.
traceHtml Mensagens do suporte à caixa de diálogo DHTML do MFC.Messages from MFC's DHTML dialog support.
traceSocket Mensagens do suporte de soquete do MFC.Messages from MFC's socket support.
traceOle Mensagens do suporte a OLE do MFC.Messages from MFC's OLE support.
traceDatabase Mensagens do suporte a banco de dados do MFC.Messages from MFC's database support.
traceInternet Mensagens do suporte da Internet do MFC.Messages from MFC's Internet support.

Para declarar uma categoria de rastreamento personalizada, declare uma instância global da CTraceCategory classe da seguinte maneira:To declare a custom trace category, declare a global instance of the CTraceCategory class as follows:

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

O nome da categoria, MY_CATEGORY neste exemplo, é o nome que você especifica para o parâmetro Category .The category name, MY_CATEGORY in this example, is the name you specify to the category parameter. O primeiro parâmetro é o nome da categoria que será exibido na ferramenta de rastreamento ATL/MFC.The first parameter is the category name that will appear in the ATL/MFC Trace Tool. O segundo parâmetro é o nível de rastreamento padrão.The second parameter is the default trace level. Esse parâmetro é opcional e o nível de rastreamento padrão é 0.This parameter is optional, and the default trace level is 0.

Para usar uma categoria definida pelo usuário:To use a user-defined category:

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

Para especificar que você deseja filtrar as mensagens de rastreamento, insira as definições dessas macros em stdafx. h antes da #include <atlbase.h> instrução.To specify that you want to filter the trace messages, insert definitions for these macros into Stdafx.h before the #include <atlbase.h> statement.

Como alternativa, você pode definir o filtro nas diretivas de pré-processador na caixa de diálogo páginas de propriedades .Alternatively, you can set the filter in the preprocessor directives in the Property Pages dialog box. Clique na guia pré-processador e, em seguida, insira o global na caixa de edição definições de pré-processador .Click the Preprocessor tab and then insert the global into the Preprocessor Definitions edit box.

Atlbase. h contém definições padrão das macros ATLTRACE2 e essas definições serão usadas se você não definir esses símbolos antes de atlbase. h ser processado.Atlbase.h contains default definitions of the ATLTRACE2 macros and these definitions will be used if you don't define these symbols before atlbase.h is processed.

Em builds de versão, o ATLTRACE2 é compilado para (void) 0 .In release builds, ATLTRACE2 compiles to (void) 0.

ATLTRACE2 limita 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.ATLTRACE2 limits the contents of the string to be sent to the dump device to no more than 1023 characters, after formatting.

ATLTRACE e ATLTRACE2 têm o mesmo comportamento, ATLTRACE está incluído para compatibilidade com versões anteriores.ATLTRACE and ATLTRACE2 have the same behavior, ATLTRACE is included for backward compatibility.

ExemploExample

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

Confira tambémSee also

MacrosMacros
Funções globais de relatório de depuração e de erroDebugging and Error Reporting Global Functions