This one’s been on my mind for a long time. I know it’s very tempting to just use System.Diagnostics.EventLog.WriteEntry to write some string to the event log. But personally I never liked the fact that you write all that static text along with the variables like actual error messages etc. Why make your life harder analyzing events later on when there’s an easy way to fix that?
Instrumentation Manifests to the Rescue!
For a while now this has actually been quite easy, using instrumentation manifests. You can read more about it here: http://msdn.microsoft.com/en-us/library/windows/desktop/dd996930(v=vs.85).aspx. These manifests allow you to define events, templates for events, messages for events, even your own event channels (so you wouldn’t need to log into that crowded “Application” channel anymore) and a lot more. But let’s look at a little example.
<?xml version="1.0" encoding="utf-8"?>
<instrumentationManifest xsi:schemaLocation="http://schemas.microsoft.com/win/2004/08/events eventman.xsd" xmlns="http://schemas.microsoft.com/win/2004/08/events" xmlns:win="http://manifests.microsoft.com/win/2004/08/windows/events" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:trace="http://schemas.microsoft.com/win/2004/08/events/trace">
<instrumentation>
<events>
<provider name="MyService" guid="{DDB3FC6E-6CC4-4871-9F27-88C1B1F19BBA}" symbol="TheEventLog"
message="$(string.MyService.ProviderMessage)"
resourceFileName="MyService.Events.dll"
messageFileName="MyService.Events.dll"
parameterFileName="MyService.Events.dll">
<events>
<event symbol="ServiceStarted" version="0" channel="Application"
value="1000" level="win:Informational"
message="$(string.MyService.event.1000.message)" />
<event symbol="ServiceStopped" version="0" channel="Application"
value="1001" level="win:Informational"
message="$(string.MyService.event.1001.message)"/>
<event symbol="ServiceConfigurationError" version="0" channel="Application"
value="1002" level="win:Error" template="ServiceException"
message="$(string.MyService.event.1002.message)"/>
<event symbol="ServiceUnhandledException" version="0" channel="Application"
value="1003" level="win:Error" template="ServiceException"
message="$(string.MyService.event.1003.message)"/>
</events>
<levels/>
<channels>
<importChannel name="Application" chid="Application"/>
</channels>
<templates>
<template tid="ServiceException">
<data name="Exception" inType="win:UnicodeString" outType="xs:string"/>
</template>
</templates>
</provider>
</events>
</instrumentation>
<localization>
<resources culture="en-US">
<stringTable>
<string id="level.Informational" value="Information"/>
<string id="level.Error" value="Error"/>
<string id="channel.Application" value="Application"/>
<string id="MyService.ProviderMessage"
value="My Windows Service"/>
<string id="MyService.event.1000.message"
value="My Windows Service has started."/>
<string id="MyService.event.1001.message"
value="My Windows Service has stopped."/>
<string id="MyService.event.1002.message"
value="My Windows Service encountered a problem with its configuration. Please fix these issues and start the service again.:%n%n%1"/>
<string id="MyService.event.1003.message"
value="My Windows Service encountered an unhandled exception:%n%n%1"/>
</stringTable>
</resources>
</localization>
</instrumentationManifest>
Let’s start at the top. Lines 5-9 define some basic information about this instrumentation provider, like a name, a unique ID and a symbol (which will come in handy later). We can also define a friendly name for events logged this way (i.e. the event source). Let’s ignore the three xyzFileName attributes for now. On lines 11-22 we’re defining four events, some of them informational (like “the service started” or “the service stopped”), some are errors (e.g. configuration errors, or unhandled exceptions). If we wanted to define our own channel, we’d do so between lines 25 and 27. For now we’re just re-using (i.e. importing) the pre-defined “Application” channel.
Event Templates
Event templates are particularly handy if you want to write parameters with your events. Lines 29-31 define a template which has exactly one parameter, which happens to be a unicode string. We’ll use it to store exceptions. We can define more than one parameter and there’s a lot of types to use, but I’ll let you explore those on your own. This template, as you can see, is referred to by the two events with IDs 1002 and 1003.
Resources
The localization gods are with us to. Our event and template definitions so far were abstract, no actual UI strings were contained. We can define those per language, as you can see starting line 37. In the resources element and its sub-elements, we define the actual strings we want to show, including any parameters. Parameters are numbered (1-based) and are referred to with %1, %2, %3 and so on. As you can see on lines 51 and 53, we’re defining the strings for the two error events with one parameter each (“%1”), to contain the exception message. If you want line breaks, you’ll achieve those with “%n”.
Compile, with some Sugar added
So now we have a fancy manifest, but what can we do with it? Well, eventually we want to log events using the definitions from this manifest, so let’s get to it. The Windows SDK comes with two very handy tools, MC.exe (the message compiler) and RC.exe (the resource compiler). We’ll use the first to compile the manifest — and generate some c# code as a side effect — then use the second to compile the output of the first into a resource which can be linked into an executable. The commands are as follows.
mc.exe -css MyService.Events manifest.man -r obj\Debug rc.exe obj\Debug\manifest.rc
MC.exe was nice enough to generate a file called manifest.cs for us. That file contains some code that you can use to log every event you defined in the manifest. This is why it was so handy to define the events (and templates): depending on how many parameters an event’s template has, the generated methods will ask you to provide just as many (typed) values for those parameters. Isn’t that great?! You’ll also find the compiled manifest.res file in obj\Debug. You can link that into its own executable (or your main assembly too, if you wanted), as follows:
csc.exe /out:MyService.Events.dll /target:library /win32res:obj\Debug\manifest.res
And you have a satellite assembly which holds the manifest you’ve built! CSC will log a warning about missing source files (because you didn’t add any .cs files to be compiled) but so far that doesn’t hurt anyone. We could probably also use link.exe but so far the C# compiler does a nice enough job.
Use that generated Code
Remember the code that was generated for us by MC.exe? Let’s go ahead and use it.
// ... TheEventLog.EventWriteServiceStarted(); // ... TheEventLog.EventWriteServiceConfigurationError(exception.Message); // ... or log the entire exception, including stack traces. // ...
Wasn’t that very easy?
Install the Event Provider
There’s still something missing though: we’ll need to install our instrumentation/event provider with the system. It’s similar to creating the event source (which in fact will happen automatically when installing the manifest). This will typically happen in your application’s/service’s installer, using a command line as follows. But before that, remember the xyzFileName attributes we talked about? These need to be updated to point to the full path of the MyService.Events.dll assembly we generated. Otherwise the following command is going to fail.
wevtutil.exe im path\to\my\manifest.man
From now on, when your app or service starts and logs those events, they’ll show up in the event viewer. For the two events we defined with parameters, the values of the parameters are essentially the only thing that’s stored along with the ID of the event. Likewise, they’ll be the only thing that’s going to be exported with the event — so the files with the exported events you’re going to ask your customers to send you are going to be a lot smaller and won’t contain the static part of the events you already know anyway!
To uninstall the manifest, just run this command:
wevtutil.exe um path\to\my\manifest.man
Both commands need to run elevated (particularly important to remember when writing your installer).
Next Steps
As a next step, you’ll probably want to add the manual steps of compiling the manifest linking into the satellite assembly to the project file as automated targets. I’ll likely write another post about that in the future too.
Summary
As you can see, writing a manifest, compiling it and using the generated code to write to the event log is quite easy. So no more excuses to write each event as one big string (which is can be a lot harder to analyze when they come back from your customers because you first need to parse the strings).