Définition d’événements
Les fournisseurs doivent définir tous les événements qu’ils écrivent. Pour définir un événement, utilisez l’élément event .
L’attribut value est l’identificateur d’événement et doit être unique pour les événements que vous définissez. Si vous définissez les autres attributs, cela dépend des personnes qui consommeront les événements et de l’endroit où. Si les administrateurs consomment vos événements à l’aide d’un outil comme Windows observateur d'événements, vous devez définir l’attribut channel. Si le type de canal est Administration, vous devez également spécifier l’attribut level et le définir sur l’un des niveaux définis dans Winmeta.xml (win:Critical à win:Verbose).
Si l’événement contient des données spécifiques à l’événement, vous devez définir l’attribut de modèle sur l’identificateur du modèle qui définit les données spécifiques à l’événement. Les attributs de niveau, de mots clés, de tâche et d’opcode sont utilisés pour regrouper ou compartimenter des événements. Bien que ces attributs soient facultatifs, vous devez envisager de spécifier le niveau, la tâche, l’opcode et les mots clés, afin que les consommateurs puissent facilement accéder uniquement aux événements intéressants. Les attributs level et keywords peuvent également être utilisés par une session de suivi ETW pour limiter les événements écrits dans le fichier journal de suivi des événements. L’attribut keywords contient une liste délimitée par des espaces de noms mot clé définis dans le manifeste. Si plusieurs mots clés sont spécifiés, leurs valeurs de masque sont OR’ed ensemble pour créer la valeur mot clé que l’événement utilisera.
Vous devez définir l’attribut symbol pour spécifier la constante symbolique que le compilateur génère pour identifier le descripteur d’événement de l’événement. Vous utilisez le descripteur d’événement lors de l’écriture de l’événement. Si vous ne spécifiez pas le symbole, le compilateur génère un nom pour vous.
L’attribut de message contient la chaîne de message localisée qui s’affiche avec l’événement. Pour inclure des données spécifiques à l’événement dans la chaîne, ajoutez des chaînes d’insertion au texte du message. Par exemple, pour inclure le troisième élément de données dans le modèle, incluez %3.
L’exemple suivant montre un manifeste complet qui définit des événements.
<instrumentationManifest
xmlns="http://schemas.microsoft.com/win/2004/08/events"
xmlns:win="http://manifests.microsoft.com/win/2004/08/windows/events"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
>
<instrumentation>
<events>
<provider name="Microsoft-Windows-SampleProvider"
guid="{1db28f2e-8f80-4027-8c5a-a11f7f10f62d}"
symbol="PROVIDER_GUID"
resourceFileName="<path to the exe or dll that contains the metadata resources>"
messageFileName="<path to the exe or dll that contains the string resources>"
message="$(string.Provider.Name)">
<channels>
<importChannel chid="c1"
name="Microsoft-Windows-BaseProvider/Admin"
symbol="CHANNEL_BASEPROVIDER_ADMIN"
/>
<channel chid="c2"
name="Microsoft-Windows-SampleProvider/Operational"
type="Operational"
enabled="true"
/>
</channels>
<levels>
<level name="NotValid"
value="16"
symbol="LEVEL_SAMPLEPROVIDER_NOTVALID"
message="$(string.Level.NotValid)"/>
<level name="Valid"
value="17"
symbol="LEVEL_SAMPLEPROVIDER_VALID"
message="$(string.Level.Valid)"/>
</levels>
<tasks>
<task name="Disconnect"
symbol="TASK_DISCONNECT"
value="1"
message="$(string.Task.Disconnect)"/>
<task name="Connect"
symbol="TASK_CONNECT"
value="2"
message="$(string.Task.Connect)"/>
<task name="Validate"
symbol="TASK_VALIDATE"
value="3"
message="$(string.Task.Validate)"/>
</tasks>
<opcodes>
<opcode name="Initialize"
symbol="OPCODE_INITIALIZE"
value="12"
message="$(string.Opcode.Initialize)"/>
<opcode name="Cleanup"
symbol="OPCODE_CLEANUP"
value="13"
message="$(string.Opcode.Cleanup)"/>
</opcodes>
<keywords>
<keyword name="Read" mask="0x1" symbol="READ_KEYWORD"/>
<keyword name="Write" mask="0x2" symbol="WRITE_KEYWORD"/>
<keyword name="Local" mask="0x4" symbol="LOCAL_KEYWORD"/>
<keyword name="Remote" mask="0x8" symbol="REMOTE_KEYWORD"/>
</keywords>
<maps>
<valueMap name="TransferType">
<map value="1" message="$(string.TransferType.Download)"/>
<map value="2" message="$(string.TransferType.Upload)"/>
<map value="3" message="$(string.TransferType.UploadReply)"/>
</valueMap>
<bitMap name="DaysOfTheWeek">
<map value="0x1" message="$(string.DaysOfTheWeek.Sunday)"/>
<map value="0x2" message="$(string.DaysOfTheWeek.Monday)"/>
<map value="0x4" message="$(string.DaysOfTheWeek.Tuesday)"/>
<map value="0x8" message="$(string.DaysOfTheWeek.Wednesday)"/>
<map value="0x10" message="$(string.DaysOfTheWeek.Thursday)"/>
<map value="0x20" message="$(string.DaysOfTheWeek.Friday)"/>
<map value="0x40" message="$(string.DaysOfTheWeek.Saturday)"/>
</bitMap>
</maps>
<templates>
<template tid="t2">
<data name="TransferName" inType="win:UnicodeString"/>
<data name="Day" inType="win:UInt32" map="DaysOfTheWeek"/>
<data name="Transfer" inType="win:UInt32" map="TransferType"/>
</template>
<template tid="t3">
<data name="TransferName" inType="win:UnicodeString"/>
<data name="ErrorCode" inType="win:Int32" outType="win:HResult"/>
<data name="FilesCount" inType="win:UInt16" />
<data name="Files" inType="win:UnicodeString" count="FilesCount"/>
<data name="BufferSize" inType="win:UInt32" />
<data name="Buffer" inType="win:Binary" length="BufferSize"/>
<data name="Certificate" inType="win:Binary" length="11" />
<data name="IsLocal" inType="win:Boolean" />
<data name="Path" inType="win:UnicodeString" />
<data name="ValuesCount" inType="win:UInt16" />
<struct name="Values" count="ValuesCount" >
<data name="Value" inType="win:UInt16" />
<data name="Name" inType="win:UnicodeString" />
</struct>
</template>
<template tid="t4">
<data name="FilesCount" inType="win:UInt16" />
<data name="Files" inType="win:UnicodeString" count="FilesCount"/>
<data name="Path" inType="win:UnicodeString" />
</template>
</templates>
<events>
<event value="1"
level="win:Informational"
keywords="Remote Read"
task="Connect"
template="t2"
channel="c1"
symbol="TRANSFER_SCHEDULE_EVENT"
message ="$(string.Event.XferSchedule)"/>
<event value="2"
level="win:Error"
keywords="Remote Write"
task="Disconnect"
opcode="Initialize"
template="t3"
channel="c1"
symbol="DOWNLOAD_XFER_FAILED_EVENT"
message ="$(string.Event.DownloadFailed)"/>
<event value="3"
level="NotValid"
keywords="Local Write"
task="Validate"
opcode="Cleanup"
template="t4"
channel="c2"
symbol="TEMPFILE_CLEANUP_EVENT"
message ="$(string.Event.TempFilesNotDeleted)"/>
</events>
</provider>
</events>
</instrumentation>
<localization>
<resources culture="en-US">
<stringTable>
<string id="Provider.Name" value="Sample Provider"/>
<string id="Level.Valid" value="Valid"/>
<string id="Level.NotValid" value="Not Valid"/>
<string id="Task.Disconnect" value="Disconnect"/>
<string id="Task.Connect" value="Connect"/>
<string id="Task.Connect.ReadRegistry" value="ReadRegistry"/>
<string id="Task.Validate" value="Connect"/>
<string id="Task.Validate.GetRules" value="GetRules"/>
<string id="Opcode.Initialize" value="Initialize"/>
<string id="Opcode.Cleanup" value="Cleanup"/>
<string id="TransferType.Download" value="Download"/>
<string id="TransferType.Upload" value="Upload"/>
<string id="TransferType.UploadReply" value="Upload-reply"/>
<string id="DaysOfTheWeek.Sunday" value="Sunday"/>
<string id="DaysOfTheWeek.Monday" value="Monday"/>
<string id="DaysOfTheWeek.Tuesday" value="Tuesday"/>
<string id="DaysOfTheWeek.Wednesday" value="Wednesday"/>
<string id="DaysOfTheWeek.Thursday" value="Thursday"/>
<string id="DaysOfTheWeek.Friday" value="Friday"/>
<string id="DaysOfTheWeek.Saturday" value="Saturday"/>
<string id="Event.XferSchedule" value="The %1 %2 transfer will occur on %3."/>
<string id="Event.DownloadFailed" value="The %1 download job failed with %2. The job contains the following files:%n%n%4"/>
<string id="Event.TempFilesNotDeleted" value="The following temp files were not removed from %3:%n%n%2"/>
</stringTable>
</resources>
</localization>
</instrumentationManifest>