Publicando seu esquema de evento para um provedor clássico

  • Artigo

Os provedores clássicos devem usar o MOF (Managed Object Format) para publicar o layout de seus dados de evento. Em seguida, os consumidores podem ler o layout publicado do WMI em runtime e usá-lo para ler os dados do evento.

Se você usar o MOF para publicar o layout dos dados de evento no WMI, normalmente criará os três tipos de classes MOF a seguir no namespace root\wmi:

Classes MOF do provedor

Se você publicar o layout dos dados do evento, deverá criar uma classe MOF que identifique seu provedor. Essa classe deve derivar da classe MOF EventTrace e deve estar vazia (sem propriedades ou métodos). A classe também deve incluir o qualificador Guid que identifica exclusivamente o provedor. Esse é o mesmo GUID que você usa ao chamar a função RegisterTraceGuids para registrar seu provedor.

Classes MOF de evento

Uma classe MOF de evento define uma classe de eventos que o provedor fornece. Essa classe deriva da classe MOF do provedor e deve estar vazia (sem propriedades ou métodos). A classe também deve incluir o qualificador Guid que identifica exclusivamente a classe de eventos que suas classes filho definem. O provedor usa esse mesmo GUID ao definir o membro Guid da estrutura EVENT_TRACE_HEADER .

Classes MOF de tipo de evento

Uma classe MOF do tipo de evento define os dados reais do evento. Essa classe deriva de sua classe MOF de evento pai. Ao nomear a classe MOF do tipo de evento, a convenção é usar o nome da classe MOF do evento no início do nome da classe MOF do tipo de evento. Por exemplo, se o nome da classe MOF do evento for HWConfig e o tipo de evento classe MOF representar informações de CPU, você deverá nomear o tipo de evento classe MOF, HWConfig_CPU.

Use o qualificador EventType na classe MOF do tipo de evento para identificar o tipo de evento. Se vários tipos de evento usarem os mesmos dados de evento, eles poderão usar a mesma classe MOF. O provedor usa o mesmo valor de tipo de evento para identificar o evento ao definir o membro Class.Type da estrutura EVENT_TRACE_HEADER .

A classe MOF do tipo de evento contém propriedades. A ordem dessas propriedades define o layout dos dados do evento. A tabela a seguir identifica os tipos de dados e qualificadores que você pode usar para definir as propriedades. Para obter mais informações sobre os qualificadores de propriedade e classe que você pode usar, consulte Qualificadores de MOF de Rastreamento de Eventos.

Tipo de dados Qualificadores Descrição
sint8, uint8 Formato Declara um inteiro decimal de 1 byte. Para declarar um caractere ANSI, use o qualificador Format e defina seu valor como "c".
sint16, uint16 Formato Declara um inteiro decimal de 2 bytes. Para indicar que o número é um número hexadecimal, use o qualificador Formatar . Por exemplo, format("x").
sint32, uint32 Formato Declara um inteiro decimal de 4 bytes. Para indicar que o número é um número hexadecimal, use o qualificador Format e defina seu valor como "x".
sint64, uint64 Formato Declara um inteiro decimal de 8 bytes. Para indicar que o número é um número hexadecimal, use o qualificador Format e defina seu valor como "x".
booleano Declara um valor booliano. O consumidor do evento deve interpretar o valor como BOOL (inteiro de 4 bytes).
char16 Declara um caractere largo. O consumidor do evento deve interpretar matrizes char16 em eventos de kernel como cadeias de caracteres largos. (Use o tamanho da matriz para copiar a cadeia de caracteres. Algumas cadeias de caracteres podem conter caracteres NULL à esquerda.)
object Extensão Declara um blob binário. O qualificador Extensão indica o tipo de dados no blob.
cadeia de caracteres Format, StringTermination Declara um valor de cadeia de caracteres. Para indicar que a cadeia de caracteres é uma cadeia de caracteres largos, use o qualificador Format e defina seu valor como "w". A cadeia de caracteres será considerada uma cadeia de caracteres ANSI se você não especificar o qualificador Format . Para indicar como a cadeia de caracteres é encerrada, use o qualificador StringTermination .

 

Para especificar uma matriz, você pode usar colchetes, []. Os colchetes podem incluir o tamanho da matriz. Por exemplo:

[WmiDataId(1), read] uint8 MyGuid[16];

Você também pode usar o qualificador Max para especificar o tamanho de uma matriz. Por exemplo:

[WmiDataId(1), Max(16), read] uint8 MyGuid[];

Se você incluir o tamanho da matriz entre colchetes, o compilador MOF gerará o qualificador Max para você.

É importante que você use o qualificador Descrição para cada propriedade. A descrição deve conter um nome de exibição que o consumidor pode usar ao exibir os valores da propriedade.

O exemplo a seguir mostra o conteúdo de um arquivo MOF que descreve uma classe MOF de provedor, evento e tipo de evento.

#pragma namespace("\\\\.\\root\\wmi")

[dynamic: ToInstance, Description("Defines my event provider"),
 Guid("{7C214FB1-9CAC-4b8d-BAED-7BF48BF63BB3}")]
class MyProvider : EventTrace
{
};

[dynamic: ToInstance, Description("Defines a category of events that my provider logs."): Amended,
 Guid("{B49D5931-AD85-4070-B1B1-3F81F1532875}")]
class MyCategory : MyProvider
{
};

[dynamic: ToInstance, Description("Defines an event within the category of events that my provider logs."): Amended,
 EventType(1)]
class MyCategory_MyEvent : MyCategory
{
    [WmiDataId(1), Description("Cost factor"): Amended, read] sint32 Cost;
    [WmiDataId(2), Description("Index values"): Amended, read] uint32 Indices[3];
    [WmiDataId(3), Description("Signature"): Amended, read, StringTermination("NullTerminated"), Format("w")] string Signature;
    [WmiDataId(4), Description("Is complete copy"): Amended, read] boolean IsComplete;
    [WmiDataId(5), Description("Class identifier"): Amended, read, Extension("Guid")] object ID;
};

Observe que os nomes de classe MOF do provedor, evento e tipo de evento devem ser exclusivos dentro de todo o namespace. Para evitar conflitos de nomenclatura, você deve usar um nome exclusivo e descritivo para todos os nomes de classe. As propriedades de classe também devem ser descritivas e exclusivas dentro de sua hierarquia de classe— uma classe filho que contém o mesmo nome de propriedade que uma classe pai substitui a propriedade da classe pai.

Depois de definir suas classes MOF, use o compilador MOF para gerar o esquema de evento e adicioná-lo ao repositório CIM. Os consumidores podem ler o esquema no repositório e ler programaticamente os dados do evento. Para obter uma descrição completa da sintaxe MOF e usar o compilador MOF (Mofcomp.exe) para adicionar suas classes MOF ao repositório CIM, consulte Managed Object Format. Para obter informações sobre como usar Wbemtest.exe para acessar o repositório CIM, consulte Instrumentação de Gerenciamento do Windows (WMI).

Classe MOF de controle de versão

Se você adicionar ou alterar uma classe MOF do tipo de evento, a convenção será para a versão da classe MOF do evento e de seu tipo de evento filho classes MOF. Para fazer a versão da classe MOF do evento atual, acrescente _Vn ao nome da classe, em que n é um número incremental começando em 0. Se essa for a primeira revisão para a classe , acrescente _V0 ao nome da classe. Você também deve adicionar o qualificador EventVersion à classe . Use o mesmo número de versão usado no nome da classe para o valor do qualificador EventVersion .

A nova versão da classe MOF do evento deve usar o mesmo nome e o qualificador Guid da classe original. Opcionalmente, a nova classe pode adicionar o qualificador EventVersion . A classe MOF do evento que não contém o qualificador EventVersion é considerada a versão mais recente ou, se todas as versões da classe contiverem um qualificador EventVersion , a classe com o número de versão mais alto será considerada a versão mais recente. O provedor usa o membro Class.Version da estrutura EVENT_TRACE_HEADER para identificar a versão do evento incluído no rastreamento.

O exemplo a seguir mostra como fazer a versão de uma classe MOF de evento.

#pragma namespace("\\\\.\\root\\wmi")
#pragma classflags("forceupdate")

[dynamic: ToInstance, Description("Defines my event provider"),
 Guid("{7C214FB1-9CAC-4b8d-BAED-7BF48BF63BB3}")]
class MyProvider : EventTrace
{
};

[dynamic: ToInstance, Description("Defines a category of events that my provider logs."),
 Guid("{B49D5931-AD85-4070-B1B1-3F81F1532875}"),
 EventVersion(1)]
class MyCategory : MyProvider
{
};

[dynamic: ToInstance, Description("Defines an event within the category of events that my provider logs."): Amended,
 EventType(1),
 EventName("MyEvent")]
class MyCategory_MyEvent : MyCategory
{
    [WmiDataId(1), Description("Cost factor"): Amended, read] sint32 Cost;
    [WmiDataId(2), Description("Index values"): Amended, read] uint32 Indices[3];
    [WmiDataId(3), Description("Signature"): Amended, read, StringTermination("NullTerminated"), Format("w")] string Signature;
    [WmiDataId(4), Description("Is complete copy"): Amended, read] boolean IsComplete;
    [WmiDataId(5), Description("Identifier"): Amended, read, Extension("Guid")] object ID;
    [WmiDataId(6), Description("Buffer Size"): Amended, read] uint32 Size;
};

[dynamic: ToInstance, Description("Defines a category of events that my provider logs."): Amended,
 Guid("{B49D5931-AD85-4070-B1B1-3F81F1532875}"),
 EventVersion(0)]
class MyCategory_V0 : MyProvider
{
};

[dynamic: ToInstance, Description("Defines an event within the category of events that my provider logs."): Amended,
 EventType(1)]
class MyCategory_V0_MyEvent : MyCategory_V0
{
    [WmiDataId(1), Description("Cost factor"): Amended, read] sint32 Cost;
    [WmiDataId(2), Description("Index values"): Amended, read] uint32 Indices[3];
    [WmiDataId(3), Description("Signature"): Amended, read, StringTermination("NullTerminated"), Format("w")] string Signature;
    [WmiDataId(4), Description("Is complete copy"): Amended, read] boolean IsComplete;
    [WmiDataId(5), Description("Identifier"): Amended, read, Extension("Guid")] object ID;
};