Qualificatori MOF di Traccia eventi

Usare i qualificatori definiti in questa sezione durante la creazione della classe MOF del provider, la classe MOF evento, la classe MOF del tipo di evento e le proprietà della classe MOF del tipo di evento. Per un esempio che include alcuni di questi qualificatori, vedere Pubblicazione dello schema eventi.

Qualificatori di classe MOF provider

Nella tabella seguente sono elencati i qualificatori che è possibile specificare in una classe MOF del provider.

Qualifier Tipo di dati Descrizione
Guid Stringa Obbligatorio. Guid stringa che identifica in modo univoco un provider. For example, Guid("{3F92E6E0-9886-434e-85DB-0D11D3904C0A}"). Si tratta dello stesso GUID usato quando si chiama la funzione RegisterTraceGuids per registrare il provider.

 

Qualificatori di classe MOF dell'evento

Nella tabella seguente sono elencati i qualificatori che è possibile specificare in una classe di evento (classe padre che raggruppa classi di tipo di evento correlate).

Qualifier Tipo di dati Descrizione
Guid Stringa Obbligatorio. Guid stringa che identifica una classe di eventi. For example, Guid("{3F92E6E0-9886-434e-85DB-0D11D3904C0A}"). I provider di eventi usano il Guid per impostare la EVENT_TRACE_HEADER. Membro Guid , in modo che i consumer possano determinare la classe di eventi che ricevono.
EventVersion Integer Questo qualificatore è facoltativo per la versione più recente di una classe di traccia eventi ed è necessario per tutte le versioni precedenti della classe. La versione più recente della classe non specifica il qualificatore EventVersion o ha il numero di versione più alto. I numeri di versione iniziano con 0, ad esempio EventVersion(0). In genere, quando si crea una nuova versione della classe, si rinomina anche la versione precedente in <classname>_Vn, dove n è un numero incrementale a partire da 0. Per un esempio, vedere FileIo e FileIo_V0.

 

Qualificatori di classe MOF del tipo di evento

Nella tabella seguente sono elencati i qualificatori che è possibile specificare su una classe di tipo di evento (la classe che definisce i dati delle proprietà dell'evento).

Qualifier Valore Descrizione
EventType Integer Obbligatorio. Identifica la classe del tipo di evento. Ad esempio, EventType(1). Il provider di eventi usa lo stesso valore del tipo di evento per impostare EVENT_TRACE_HEADER. Class.Type. Se la stessa classe MOF viene usata per più tipi di evento (perché usano gli stessi dati dell'evento), specificare il valore del tipo di evento come matrice di interi, ad esempio EventType{12,15}.
EventTypeName Stringa Facoltativa. Descrive il tipo di evento. Ad esempio, EventTypeName("Start"). Se la stessa classe MOF viene usata per più tipi di eventi (perché usano gli stessi dati dell'evento), specificare il valore del nome del tipo di evento come matrice di stringhe, ad esempio EventTypeName{"Start", "End"}. Gli elementi della matrice EventTypeName corrispondono direttamente alla matrice EventType.

 

Qualificatori delle proprietà

Nella tabella seguente sono elencati i qualificatori che è possibile specificare in una proprietà.

Qualifier Descrizione
Bitmap Specifica le posizioni bit mappate ai valori stringa. Se si specifica questo qualificatore, è necessario specificare anche il qualificatore BitValues .
BitValues Valori stringa. Se viene specificato anche il qualificatore BitMap , le stringhe corrispondono direttamente ai valori del qualificatore BitMap . In caso contrario, si supponga che il valore della proprietà sia un indice in base uno nelle stringhe di valore (bit uno corrisponde alla prima stringa nell'elenco).
Estensione Fornisce informazioni aggiuntive su come usare (interpretare) i dati. Il valore dell'estensione è senza distinzione tra maiuscole e minuscole. Includere il valore nelle virgolette, ad esempio Extension("Guid"). I valori di estensione possibili sono:
Guid
Indica che i dati delle proprietà sono un Guid. Il tipo di dati MOF deve essere oggetto. Il payload deve essere una struttura GUID .
IPAddr e IPAddrV4
I dati sono un indirizzo IP V4. Il tipo di dati MOF deve essere oggetto. Il payload dovrebbe essere un lungo senza segno. Ogni byte del long senza segno rappresenta una delle quattro parti dell'indirizzo IP (p1.p2.p3.p4). Il byte a basso ordine contiene il valore per p1, il byte successivo contiene il valore per p2 e così via.
Prima di Windows Vista: L'estensione IPAddrV4 non è supportata.
IPAddrV6
I dati sono un indirizzo IP V6. Il tipo di dati MOF deve essere oggetto. Il payload deve essere una struttura IN6_ADDR .
Prima di Windows Vista: L'estensione IPAddrV6 non è supportata.
NoPrint
Indica che il consumer non deve stampare questi dati.
Porta
I dati identificano un numero di porta. Il tipo di dati MOF deve essere oggetto. Il payload dovrebbe essere un breve senza segno.
RString
I caratteri di nuova riga sono stati sostituiti con spazi. Il payload deve essere una stringa ANSI con terminazione null.
RWString
I caratteri di nuova riga sono stati sostituiti con spazi. Il payload deve essere una stringa di caratteri null con terminazione null.
Sid
I dati rappresentano un SID BLOB binario. Il tipo di dati MOF deve essere oggetto.
Il SID è di lunghezza variabile. Il valore contenuto nei primi 4 byte (ULONG) indica se il BLOB contiene un SID. Se i primi 4 byte (ULONG) del BLOB sono diversi da zero, il BLOB contiene un SID. La prima parte del BLOB contiene il TOKEN_USER (la struttura è allineata su un limite di 8 byte) e la seconda parte contiene il SID. Per risolvere la parte SID del BLOB:
  • Impostare un puntatore a byte all'inizio del BLOB
  • Moltiplicare le dimensioni del puntatore per il registro eventi per 2 e aggiungere il prodotto al puntatore di byte (il membro PointerSize di TRACE_LOGFILE_HEADER contiene il valore della dimensione del puntatore)

È possibile utilizzare la macro seguente per determinare la lunghezza del SID.
#define SeLengthSid( Sid ) \
  (8 + (4 * ((SID *)Sid)->SubAuthorityCount))
SizeT
Indica che la proprietà contiene un valore del puntatore. La dimensione del valore del puntatore dipende dal sistema operativo usato per registrare l'evento; il payload conterrà un valore a 4 byte per sistemi a 32 bit o un valore a 8 byte per i sistemi a 64 bit. Il tipo di dati MOF deve essere oggetto.
I consumer devono ignorare il tipo di dati e il qualificatore Format se la proprietà include l'estensione SizeT . Per determinare le dimensioni dei dati da leggere per la proprietà, usare:
Prima di Windows Vista: Il valore PointerSize potrebbe non essere accurato. Ad esempio, in un computer a 64 bit, un'applicazione a 32 bit registra puntatori a 4 byte; Tuttavia, la sessione imposterà PointerSize su 8.
Variante
I dati rappresentano un BLOB. I primi quattro byte (uint32) indicano le dimensioni del BLOB. Il tipo di dati MOF deve essere oggetto.
WmiTime
Converte il timestamp in ora di sistema. Il tipo di dati MOF deve essere oggetto. Il payload deve essere un intero senza segno a 64 bit.
Prima di Windows Vista: Non disponibile.
Formato Definisce il formato dei dati della proprietà. Ad esempio, l'inclusione di Format("w") in una proprietà stringa indica che la stringa è una stringa wide. I valori possibili sono:
Termine Descrizione
C
Visualizzare il valore della proprietà come carattere ASCII. È possibile usare questo qualificatore con tipi di dati uint8 .
s
Considerare la matrice di caratteri come stringa con terminazione Null. La stringa è una stringa di caratteri wide se il tipo di dati è char16; in caso contrario, la stringa è una stringa di caratteri ASCII.
W
Il valore della proprietà è una stringa di caratteri wide. È possibile usare questo qualificatore con tipi di dati stringa .
X
Visualizzare il valore della proprietà come numero esadecimale. È possibile usare questo qualificatore con tipi di dati integer a 16, 32 e 64 bit.

 

Puntatore

Indica che la proprietà contiene un valore del puntatore. La dimensione del valore del puntatore dipende dal sistema operativo usato per registrare l'evento; il payload conterrà un valore a 4 byte per sistemi a 32 bit o un valore a 8 byte per i sistemi a 64 bit. Il tipo di dati MOF deve essere oggetto.

I consumer devono ignorare il tipo di dati e il qualificatore Format se la proprietà include l'estensione SizeT . Per determinare le dimensioni dei dati da leggere per la proprietà, usare:

Prima di Windows Vista: Il valore PointerSize potrebbe non essere accurato. Ad esempio, in un computer a 64 bit, un'applicazione a 32 bit registra puntatori a 4 byte; Tuttavia, la sessione imposterà PointerSize su 8.

Si noti che alcuni eventi usano PointerType anziché Puntatore; non usare PointerType.

StringTermination Indica la modalità di terminazione della proprietà stringa. Ad esempio, StringTermination("NullTerminated") indica che la proprietà stringa è con terminazione Null. I valori possibili sono:
Contato

La lunghezza della stringa viene incorporata all'inizio della stringa come valore USHORT .

NotCounted

La stringa non è con terminazione Null e la lunghezza della stringa non è incorporata all'inizio della stringa. In questo caso, la stringa deve essere l'ultimo elemento e occupare tutto lo spazio alla fine dei dati dell'evento.

NullTerminata

La stringa è con terminazione Null. Se non si specifica il qualificatore StringTermination , si presuppone che la stringa sia con terminazione Null.

ReverseCounted

La lunghezza della stringa viene incorporata all'inizio della stringa come valore USHORT in formato big-endian.

ValueDescriptions Fornisce descrizioni per ogni valore nel qualificatore Valori . Le funzioni TdhEnumerateProviderFieldInformation e TdhQueryProviderFieldInformation restituiscono queste descrizioni quando si tenta di recuperare le informazioni relative a parole chiave e livello. Le descrizioni sono facoltative. Se non vengono fornite le descrizioni, le funzioni restituiscono NULL. Per altri dettagli, vedere Impostazione del livello e abilitazione dei valori dei flag per un provider .
ValueMap Specifica i valori integer di indice o flag che eseguono il mapping ai valori stringa. Se si specifica questo qualificatore, è necessario specificare anche il qualificatore Valori e, facoltativamente, il qualificatore ValueType . Si noti che ETW non supporta l'opzione WMI di avere stringhe per i valori di mapping dei valori.

Nell'esempio seguente viene illustrato come usare i qualificatori ValueMap, Values e ValueType.

ValueType("flag"),
ValueMap {"0x01", "0x02", "0x04", "0x08"},
Values {"ValueMapFlag1", "ValueMapFlag2", "ValueMapFlag4", "ValueMapFlag8"}]
Valori Valori stringa. Se viene specificato anche il qualificatore ValueMap , le stringhe corrispondono direttamente ai valori nel qualificatore ValueMap . In caso contrario, si supponga che il valore della proprietà sia un indice in base zero nelle stringhe di valore.
ValueType Indica se i valori valueMap sono valori di indice integer o flag di bit. Se non si specifica questo qualificatore, verranno considerati valori di indice integer. Per specificare che i valori sono valori di indice integer, usare ValueType("index"). Per specificare che i valori sono valori di flag di bit, usare ValueType("flag").
WmiDataId Ogni proprietà deve contenere il qualificatore WmiDataId . WmiDataId definisce l'ordine in cui il consumer legge i dati dell'evento. Il valore di WmiDataId inizia a 1 e incrementa per ogni proprietà della classe . Ad esempio, WmiDataId(1).
XMLFragment Indica che i dati sono in formato XML e pronti per la visualizzazione senza formattazione ulteriore.

 

Specifica del livello e abilita i valori dei flag per un provider

Per documentare il livello e abilitare i flag usati da un controller per abilitare il provider, includere le proprietà "Level" e "Flags" nella classe MOF del provider. I nomi delle proprietà Level e Flags fanno distinzione tra maiuscole e minuscole. Le proprietà devono includere i qualificatori Values e ValueMap , che specificano il livello possibile e abilitano i valori dei flag. ValueMap per i valori del flag di abilitazione devono essere valori bit (flag). Il qualificatore ValueDescriptions è facoltativo, ma è consigliabile usarlo per fornire descrizioni per ogni valore possibile. Le descrizioni vengono usate quando un utente chiama le funzioni TdhEnumerateProviderFieldInformation e TdhQueryProviderFieldInformation per ottenere il livello possibile e abilitare i valori di flag (parole chiave) per il provider.

Di seguito viene illustrata una classe provider che specifica il livello possibile e abilita i valori dei flag.

[Dynamic,
 Description("IIS_Trace") : amended,
 guid("{3a2a4e84-4c21-4981-ae10-3fda0d9b0f83}"),
 locale("MS\\0x409")]
class IIS_Trace : EventTrace
{
    [Description ("Enable Flags") : amended,
        ValueDescriptions{
             "Allow_tracing_only_selected_requests ",
             "IIS_authentication_events ",
             "IIS_security_events ",
             "IIS_filter_events ",
             "IIS_static_file_events ",
             "IIS_CGI_events ",
             "IIS_compression_events ",
             "IIS_cache_events ",
             "IIS_request_notifications_events ",
             "IIS_module_events ",
             "IIS_FastCGI_events "},
        DefineValues{
             "UseUrlFilter",
             "IISAuthentication",
             "IISSecurity",
             "IISFilter",
             "IISStaticFile",
             "IISCGI",
             "IISCompression",
             "IISCache",
             "IISRequestNotification",
             "IISModule",
             "IISFastCGI"},
        Values{
             "UseUrlFilter",
             "IISAuthentication",
             "IISSecurity",
             "IISFilter",
             "IISStaticFile",
             "IISCGI",
             "IISCompression",
             "IISCache",
             "IISRequestNotification",
             "IISModule",
             "IISFastCGI"},
        ValueMap{
             "0x00000001",
             "0x00000002",
             "0x00000004",
             "0x00000008",
             "0x00000010",
             "0x00000020",
             "0x00000040",
             "0x00000080",
             "0x00000100",
             "0x00000200",
             "0x00001000"}: amended
    ]
    uint32 Flags;

    [Description ("Levels") : amended,
        ValueDescriptions{
            "Abnormal exit or termination",
            "Severe errors that need logging",
            "Warnings such as allocation failure",
            "Includes non-error cases",
            "Detailed traces from intermediate steps" } : amended,
         DefineValues{
            "TRACE_LEVEL_FATAL",
            "TRACE_LEVEL_ERROR",
            "TRACE_LEVEL_WARNING"
            "TRACE_LEVEL_INFORMATION",
            "TRACE_LEVEL_VERBOSE" },
        Values{
            "Fatal",
            "Error",
            "Warning",
            "Information",
            "Verbose" },
        ValueMap{
            "0x1",
            "0x2",
            "0x3",
            "0x4",
            "0x5" },
        ValueType("index")
    ]
    uint32 Level;
};