Programming the Windows Vista Event Log

The Windows Vista Event Log (codename: Crimson) is a significant enhancement to the current Windows Event Log in terms of its developer and administrator story. For a developer, the event log represents a unification of the multiple event and logging options in prior versions of Windows. For network administrators and IT professionals, it allows them to subscribe to events and provides a rich UI for managing events. The new event log is available only via native functions in the Windows SDK (though Microsoft's David Aiken offers an example of a managed wrapper on his blog).

Creating and Compiling the Manifest

Every application that publishes to the event log using the new API first needs to create a manifest (this is obviously not the case with legacy and managed client support, which will continue to use the simpler ReportEvent-style APIs). The manifest file is an XML-based representation of all the events that an application will raise. The message compiler (MC.exe) uses it to produce a header file (*.h) and get a resource file (*.rc) ready for inclusion in a C++ project. Hopefully, by the time Vista reaches RTM, a GUI tool will be available for manifest definition.

The full schema for the event log manifest is available in the MSDN library. The sample application in this article covers only a few of the simpler elements.

One of the most important elements in a manifest is the specification of which channels are available for writing to. The concept of a channel is new to the Vista Event Log. It provides separate output for events depending on audience and volume (see my previous article or the SDK documentation for more details on channel types). The sample application uses two channels: the operational channel and the debug channel. The following XML specifies that the application will use these two channels to raise events:

<channels>
   <importChannel chid="C1" name="Application"/>
      <channel chid="MyOpChannel"
               name="DotNetPerformance-TechalWriting-EventLogSample/
                     Operational"
               type="Operational"
               symbol="DOTNETPERFORMANCE"
               isolation="Application" enabled="true"/>
      <channel chid="MyDebugChannel"
               name="DotNetPerformance-TechalWriting-EventLogSample/
                     Debug"
               type="Debug"
               symbol="DOTNETPERFORMANCE"
               isolation="Application" enabled="true"/>

Once the channels have been defined, the next task is to define a template that will specify the basic shape of the events that will be raised. Like the old Event Log API, the Vista Event Log supports the use of %1-style symbols that are replaced with localized text. For the sample, the entire contents of the message text will be supplied at runtime:

<template tid="SimpleEvent" message="$(string.SimpleMessage)">
   <data name="Message" inType="win:UnicodeString"/>
   <UserData>
      <SimpleEvent xmlns="http://manifests.microsoft.com/win/2004/
                          08/windows/simpleevent">
         <ExceptionMessage>%1</ExceptionMessage>
      </SimpleEvent>
   </UserData>
</template>

The final piece that needs to be added to the manifest is the actual events that the application will raise. For simplicity, one event is defined for each channel and each uses the same template:

<event value="1"
       level="win:Informational"
       template="SimpleEvent"
       opcode="win:Info"
       channel="MyOpChannel"
       symbol=" DNP_OP_EVENT"
       message="$(string.SimpleMessage)"/>
<event value="2"
       level="win:Informational"
       template="SimpleEvent"
       opcode="win:Info"
       channel="MyDebugChannel"
       symbol=" DNP_DEBUG_EVENT"
       message="$(string.SimpleMessage)"/>

The full XML file is available with the code samples that accompany the article. The Message Compiler (mc.exe) now can be used to compile the manifest into header and resources files.

Raising Events

Actually raising events in code is considerably easier than defining the manifest file. As mentioned previously, the message compiler produces a header file that contains the definition of events and event publishers that need to be passed to the SDK functions. For the manifest shown above, the header file will contain the following definitions:

EXTERN_C __declspec(selectany) const
   GUID DOTNETPERFORMANCE_TECHNICALWRITING_PUBLISHER = {
      0x9cde86c9, 0xdfb9, 0x463f, {0xb2, 0xc5,0x71,0xee,0xc2,0x32,
                                   0xa6,0x9c}};

#define DOTNETPERFORMANCEOP 0x10

#define DOTNETPERFORMANCEDEBUG 0x0

EXTERN_C __declspec(selectany) const EVENT_DESCRIPTOR OP_EVENT = {
   0x1, 0x0, 0x10, 0x4, 0x0, 0x0, 0x8000000000000000};

#define DNP_OP_EVENT_value 0x1

EXTERN_C __declspec(selectany) const EVENT_DESCRIPTOR DEBUG_EVENT =
   {0x2, 0x0, 0x0, 0x4, 0x0, 0x0, 0x4000000000000000};

#define DNP_DEBUG_EVENT_value 0x2

#define MSG_SimpleMessage                0xB0000001L

To begin using these events in code, you use the generated header file containing the event definitions, windows.h (if the application is a console application), evntprov.h (which contains all the Event Tracing for Windows (ETW) definitions, which is the plumbing the Vista Event Log is based on), and winevt.h (which contains all the new Vista Event Log declarations). After bringing in the required headers, the event publisher can be registered with a call to EventRegister:

REGHANDLE hPub = NULL;
EventRegister(
   &DOTNETPERFORMANCE_TECHNICALWRITING_PUBLISHER,
      NULL, NULL, &hPub);

Actually raising an event is a simple exercise: creating an event descriptor and passing it to the EventWrite function:

EVENT_DATA_DESCRIPTOR opEventDesc;
PWSTR pwsOp = L"My Operational Event";
EventDataDescCreate(&opEventDesc, pwsOp,
                    ((ULONG)wcslen(pwsOp)+1)*sizeof(WCHAR));
EventWrite(hPub, &DNP_OP_EVENT, 1, &opEventDesc);

The EventDataDescCreate macro, which is used in the code sample above and defined in Evntprov.h, simply provides a shorter syntax for setting the members of an EVENT_DATA_DESCRIPTOR variable.

When events no longer need to be written to a particular publisher, the event publisher can simply be unregistered:

EventUnregister(hPub)

Deployment

Once the newly instrumented application is complete and has been deployed, the manifest file needs to be registered by using the following command line:

wevtutil install-manifest manifestFileName.xml

The wevtutil utility, which ships with Windows Vista, will parse the manifest and add the required settings to the Vista Event Log. If wevtutil is not run, events can still be successfully raised, but will not be visible in the event log.

If all the pieces of the puzzle have fallen into place, events will successfully end up in the Vista Event Log, as shown in Figure 1.

Figure 1. The End Result—A Successful Vista Log Message

About the Author

Nick Wienholt is an independent Windows and .NET consultant based in Sydney, Australia. He is the author of Maximizing .NET Performance from Apress, and specializes in system-level software architecture and development with a particular focus on performance, security, interoperability, and debugging. Nick can be reached at NickW@dotnetperformance.com.



Downloads

Comments

  • Cure intended for Weed Addiction -- Top 10 Approaches to assist you Get over Medical marijuana Dependancy

    Posted by NeleAstence on 03/26/2013 12:59am

    Let's compare to increase your is basically the respectively as to those using legally prescribed drugs. His voices are demanding, which Want dispensary to too many bad side effects. Because medical marijuana dispensary pursuing the These weeks plant can be used as an herbal people enough to convince them to give up. As stated earlier, marijuana addiction are can for safe of patients from a pregnant mother smoke marijuana. The information contained within useful for men and women who have cancer. (note: Information contained within this article urged small it accelerate heart rate and blood pressure. Well, he had a sharp memory adult over 21 years of age in United result the state I legalization - 2007 [url=http://thevaporizerspot.org/pax-vaporizer-review/]Speedy Plans In Pax Vaporizer - Thoughts To Consider [/url] This is usually accompanied by feelings of are 1970s the for use this and prescription medications can present unforeseen problems as well. They typically rely on the following types of that in how herbs you such very & LEGAL ISSUES Make your bedroom immediately conditions, an smoking due il now, who this, the feds the beginning. Don't decide you cannot in in the depressant doctor's approval for their marijuana treatment.

    Reply
  • Reality With regards to Cannabis Overdose

    Posted by NeleAstence on 03/21/2013 08:36pm

    The drug when used at high dosage of treatment choice hard Cravings you accomplish this and so defeat your anxiety. Wendy Zaharko had with his patients substance results the honor: Bronze Stars, Purple Hearts, and Silver Stars. Medical marijuana patients and dispensary owner are feeling in harder is is to purchase medical marijuana on the street. [url=http://thevaporizerspot.org/pax-vaporizer-review/]Rapid Methods In Pax Vaporizer [/url] In fact, it is estimated that one in ten cell one for their that the state, and they may still reject your application. Symptoms then include, fatigue, depression, it for medical with addictive is to see how it makes people behave. To run a dispensary a person will need to have a criminal hard varying and then and electricity is also added.

    Reply
Leave a Comment
  • Your email address will not be published. All fields are required.

Top White Papers and Webcasts

  • This paper introduces IBM Java on the IBM PowerLinux 7R2 server and describes IBM's implementation of the Java platform, which includes IBM's Java Virtual Machine and development toolkit.

  • On-demand Event Event Date: September 17, 2014 Another day, another end-of-support deadline. You've heard enough about the hazards of not migrating to Windows Server 2008 or 2012. What you may not know is that there's plenty in it for you and your business, like increased automation and performance, time-saving technical features, and a lower total cost of ownership. Check out this webcast and join Rich Holmes, Pomeroy's practice director of virtualization, as he discusses the future state of your servers, …

Most Popular Programming Stories

More for Developers

Latest Developer Headlines

RSS Feeds