3.1.1.14 Publisher Resource, Message, and Parameter Files

The server MUST keep the resource files for all the publishers who register themselves to the server. It is the publisher's responsibility to register itself to the server, registering a publisher to the server is not in the scope of this protocol. The publisher resource files are DLL files that are generated by the publishers when they designate events. In order to designate events, the publisher needs to specify the channel, provider, and events information in a manifest. For each event, it also needs to specify the level, opcode, task, keyword, and event description information. All this information is written into an instrumentation manifest file. For information on writing the manifest file, see [MSDN-WAIM]. Next, the information is compiled and saved into the publisher resource file. All publishers MUST have a DLL file with a name like publishername.dlll that saves all the events and channels as well as its own name. This file MUST also store the description strings for those events and channels.

The description strings can be localizable. To make localized sets of strings, all the description strings are moved from the publisher resource file (as specified in section 3.1.1.13) and packed into a localized string table and then moved into a corresponding language-specific resource files resource file for each language (as specified in [MSDN-MUIResrcMgmt]). The publisher resource file only saves a messageId, which is used as an index to locate the real string in the language-specific resource file for each description string. Then all the levels descriptions are packed into a level table with the level information and the messageId. Similarly, all the opcodes, tasks, keywords, event descriptions, and channels are packed as tables in the language-specific resource file.

The following shows a typical instrumentation part of a publisher resource file:

[Publisher Information]

<Publisher Identifier><MessageId for publisher name string><Publisher helper link string>

[Channel Information]

<Channel Identifier 1><Channel 1 name><MessageId for channel 1 description string>

<Channel Identifier n><Channel n name><MessageId for channel n description string>

[Events information]

<Event 1 Identifier><version><MessageId for event 1 description string>

<Level Value of Event 1><Level Name of Event 1><MessageId for level description string>

<Opcode Value of Event 1><Opcode Name of Event 1><MessageId for opcode description string>

<Task Value of Event 1><Task Name of Event 1><MessageId for task description string>

<Keyword Value of Event 1><Keyword Name of Event 1><MessageId for keyword description string>

<event 1 definition template>

<channel identifier>

<publisher identifier>

…

<Event m Identifier><version><MessageId for event m description string>

<Level Value of Event m><Level Name of Event m><MessageId for level description string>

<Opcode Value of Event m><Opcode Name of Event m><MessageId for opcode description string>

<Task Value of Event m><Task Name of Event m><MessageId for task description string>

<Keyword Value of Event m><Keyword Name of Event m><MessageId for keyword description string>

<event m definition template>

<channel identifier>

<publisher identifier>

In a publisher's language-specific resource file, the real strings are saved and indexed by the messageId.

All the information in this section for a publisher is also called publisher metadata, and the part of each event in Events information is called event metadata.

Published resource files are DLL or EXE files, as specified in [PE-COFF]. The format of publisher resource files is outside the scope of this protocol.

By default, the server SHOULD provide a default publisher and that publisher can provide common channels, events, and so forth. The default publisher is built in with the server and does not have to be installed. The format of its resource file is the same as any publisher resource file. Although recommended, the server does not have to provide a default publisher.

The publisher resource file only saves the message Id of any string. The server SHOULD have another file that saves all the real strings. That would be a publisher message file, which takes the following form:

<MessageId 1><The language neutral string 1>

…

<MessageId n><The language-neutral string n>

These language-neutral strings can then be translated into different languages and put into localized string tables (section 3.1.1.13).

The publisher parameter file has the same format as the publisher message file and can take this form:

<Value 1><String 1>

…

<Value n><String n>

The strings in the publisher parameter file cannot be localized. It is used for parameter substitution. For example, if a publisher defines the description string of an event as "The system has found %%2", when the server tries to expand the string with the EvtRpcMessageRender method (section 3.1.4.31), it sees %%2 and knows that this part is replaced with a real string from the publisher's parameter file. It then uses 2 as the index and finds the string for the value 2 in the parameter file and replaces %%2 with that string.