發佈傳統提供者的事件架構

發行項
06/13/2023

傳統提供者應該使用 Managed 物件格式 (MOF) 來發佈其事件資料的版面配置。取用者接著可以在執行時間從 WMI 讀取已發佈的配置，並用它來讀取事件資料。

如果您使用 MOF 在 WMI 中發佈事件資料的版面配置，您通常會在 root\wmi 命名空間中建立下列三種類型的 MOF 類別：

提供者 MOF 類別
一或多個事件 MOF 類別
一或多個事件種類 MOF 類別

提供者 MOF 類別

如果您發佈事件資料的版面配置，您必須建立可識別提供者的 MOF 類別。這個類別必須衍生自 EventTrace MOF 類別，而且在沒有任何屬性或方法) (空白。類別也必須包含可唯一識別提供者的 Guid 限定詞。當您呼叫 RegisterTraceGuids 函式來註冊提供者時，這是您所使用的相同 GUID。

事件 MOF 類別

事件 MOF 類別會定義提供者所提供的事件類別。這個類別衍生自提供者 MOF 類別，而且必須是空的， (沒有屬性或方法) 。類別也必須包含 Guid 限定詞，其可唯一識別其子類別所定義之事件的類別。提供者在設定EVENT_TRACE_HEADER結構的 Guid 成員時，會使用相同的GUID。

事件種類 MOF 類別

事件種類 MOF 類別會定義實際的事件資料。這個類別衍生自其父事件 MOF 類別。命名事件種類 MOF 類別時，慣例是在事件種類 MOF 類別名稱的開頭使用事件 MOF 類別名稱。例如，如果事件 MOF 類別名稱是 HWConfig，而事件種類 MOF 類別代表 CPU 資訊，您應該將事件種類命名為 MOF 類別，HWConfig_CPU。

使用事件種類 MOF 類別上的 EventType 限定詞來識別事件種類。如果多個事件種類使用相同的事件資料，則可以使用相同的 MOF 類別。提供者會在設定EVENT_TRACE_HEADER結構的Class.Type成員時，使用相同的事件種類值來識別事件。

事件種類 MOF 類別包含屬性。這些屬性的順序會定義事件資料的版面配置。下表會識別可用來定義屬性的資料類型和限定詞。如需您可以使用的屬性和類別限定詞的詳細資訊，請參閱事件追蹤 MOF 限定詞。

資料類型	限定詞	描述
sint8、 uint8	格式	宣告 1 位元組的十進位整數。若要宣告 ANSI 字元，請使用格式限定詞，並將其值設定為「c」。
sint16、 uint16	格式	宣告 2 位元組的十進位整數。若要指出數位是十六進位數位，請使用格式限定詞。例如，格式 (「x」) 。
sint32、 uint32	格式	宣告 4 位元組的十進位整數。若要指出數位是十六進位數位，請使用格式限定詞，並將其值設定為「x」。
sint64、 uint64	格式	宣告 8 位元組的十進位整數。若要指出數位是十六進位數位，請使用格式限定詞，並將其值設定為「x」。
boolean		宣告布林值。事件取用者應該將值解譯為 BOOL (4 位元組整數) 。
char16		宣告寬字元。事件取用者應該將核心事件中的 char16 陣列解譯為寬字元字串。 (使用陣列大小來複製字串。某些字串可能包含前置 Null 字元。)
object	副檔名	宣告二進位 Blob。擴充限定詞表示 Blob 中的資料類型。
string	Format、 StringTermination	宣告字串值。若要指出字串是寬字元字串，請使用格式限定詞，並將其值設定為「w」。如果您未指定格式限定詞，字串就會被視為 ANSI 字串。若要指出字串的終止方式，請使用 StringTermination 限定詞。

若要指定陣列，您可以使用方括弧 []。方括弧可以包含陣列的大小。例如：

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

您也可以使用 Max 限定詞來指定陣列的大小。例如：

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

如果您在方括弧中包含陣列的大小，MOF 編譯器就會為您產生 Max 限定詞。

請務必針對每個屬性使用 Description 限定詞。描述應該包含取用者在顯示內容值時可以使用的顯示名稱。

下列範例顯示描述提供者、事件和事件種類 MOF 類別的 MOF 檔案內容。

#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;
};

請注意，提供者、事件和事件種類 MOF 類別名稱在整個命名空間內必須是唯一的。若要避免命名衝突，您應該針對所有類別名稱使用唯一且描述性的名稱。類別屬性在其類別階層中也應該是描述性且唯一的，包含與父類別相同的屬性名稱的子類別會覆寫父類別的屬性。

定義 MOF 類別之後，請使用 MOF 編譯器來產生事件架構，並將其新增至 CIM 存放庫。取用者接著可以從存放庫讀取架構，並以程式設計方式讀取事件資料。如需 MOF 語法和使用 MOF 編譯器 (Mofcomp.exe 的完整描述，) 將 MOF 類別新增至 CIM 存放庫，請參閱 Managed 物件格式。如需使用 Wbemtest.exe 存取 CIM 存放庫的資訊，請參閱 Windows Management Instrumentation (WMI) 。

版本設定 MOF 類別

如果您新增或變更事件種類 MOF 類別，慣例是同時設定事件 MOF 類別及其子事件種類 MOF 類別的版本。若要設定目前事件 MOF 類別的版本，請將_Vn附加至類別名稱，其中 n 是從 0 開始的累加編號。如果這是類別的第一個修訂，請將_V0附加至類別名稱。您也必須將 EventVersion 限定詞新增至類別。針對 EventVersion 限定詞的值，使用您在類別名稱中使用的相同版本號碼。

新版的事件 MOF 類別必須使用與原始類別相同的名稱和 Guid 限定詞。新的類別可以選擇性地新增 EventVersion 限定詞。不包含 EventVersion 限定詞的事件 MOF 類別會被視為最新版本，或者如果類別的所有版本都包含 EventVersion 限定詞，則具有最高版本號碼的類別會被視為最新版本。提供者會使用EVENT_TRACE_HEADER結構的Class.Version成員來識別追蹤中包含的事件版本。

下列範例示範如何設定事件 MOF 類別的版本。

#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;
};