Based on my posts the last few days, we now have enough information to put together a spiffy class we can reuse in our projects. First, let me talk about a few design decisions I made.

All of the methods are static. If you are not familiar with what a static method is, see my post https://arcanecode.wordpress.com/2007/01/15/static-methods/ . I did this to make it easy to use the class, and so I wouldn’t have to a) make the class a global object or b) be constantly creating a new instance of the class. The downside is I always have to pass in the log name each time you call a routine.

As an alternative, you could elect to alter the class by making each routine non static, then creating a Log property to set and forget the log name, and finally creating an instance of the class and making it global throughout your app.

Next, in the class you’ll see I kept the line wrap fairly small, this was simply to make it easier to reproduce in the blog. Normally I’d use much longer line lengths.

I like overloads, so I used a lot of them in the class, to make it as flexible as possible. I also commented each routine (although the overloads only get one set of comments since except for a parameter they are identical). OK, let’s look at the main routine.  

If you compare the WriteEntry method here to what I had in my post a few days ago, you’ll notice some extra parameters. In my introduction to WriteEntry I already mentioned Message and EventType, Message being the main message that’s logged and EventType being an enum that indicates if this is an Informational message, Warning, or Error.

EventID is a generic, positive integer that you can use in your program in anyway you see fit. My suggestion would be to create a unique number for each place in your code that you log a message. Then it’s very easy to jump to the exact spot in your code the message was generated.

CategoryID is another number you can use as you please. You can create your own categories for the type of message, or perhaps use the category to indicate which class the message came from. The category ID must be a positive short value.

Note that it is possible to tie the category ID to a string. The string is located in a resource file, compiled in your DLL. I elected not to do that for this simple logger class, however if you want to read more about it take a look at http://msdn2.microsoft.com/en-us/library/system.diagnostics.eventloginstaller.categoryresourcefile.aspx

or http://shrinkster.com/lav .

The final parameter is RawData, which is an array of bytes. You probably won’t use this too often, but if you had a blob of data in memory or from a database you could write it out.

I mentioned I liked overloads, so does the .Net Framework. There are various overloads to WriteEntry, so I created overloads for the Log method to correspond as it dropped parameters. The simplest version of Log only passes Log Name, Source, Message, and EventType as parameters.

To make things a little simpler and more self documenting, I then created LogMessage, LogWarning, and LogError methods. These have the same signature as the Log method, except they don’t have the EventType parameter. Instead they set this internally in the method. They then call the Log method. Here’s one example, the simplest version of LogMessage:  

OK, that covers the gambit of routines to log the error. For reading the error I have two versions of a method called ReadLog. The first is almost a clone of the one I blogged about two days ago, except the LogName is passed in as a parameter instead of being hard coded.

For the second version I added a parameter called OldestValue. This parameter indicates the oldest date we want to include in our return string, and goes forward to today from there. Let’s take a look.  

You can see, all I needed was a simple if clause to check to see if I should include this record. You could choose to add a third method to do a date range, I decided not to on the logic that 99% of the time the error probably occurred today, and your oldest value might be yesterday or the day before.

I also made one other enhancement; you can see I have the returnValue append the results of a method called formatEntry. The other ReadLog method also uses this, I wanted to create one spot to format the data we read from the event log.  

First I determine what type of event was logged using the switch statement. Next I grab all the important data exposed by the EventLogEntry object. Many you will recognize as the values you passed in from the Log method so I won’t reiterate. A few though are new.

TimeGenerated simply indicates the date/time the item was generated. I could have used the TimeWritten, but felt the TimeGenerated to be the more valuable and accurate of the two.

MachineName is another self evident property, if a user runs your same app on many PCs it can be helpful to know which one the event was generated on.

InstanceID is a bit odd, when we write the data out using WriteEntry .Net had no complaints. However when I tried to read it back in using the EventID property, the compiler produced a warning that EventID has been depreciated and replaced with InstanceID. The short story, EventID and InstanceID are the same thing, for reading back use InstanceID.

Finally, the logger class has three more methods: Clear, SetToOverwriteAsNeeded, and SetLogSizeInKB. These are identical to the routines I showed you in yesterdays post, except I pass in the log name as a parameter.

Well, that was quite a bit of work, but now we have a class that will make it easy to write and read events to the Windows Event Log. Of course I can already think of new routines and methods, perhaps a ReadLogAsXML? Or the previously mentioned ability to read a date range instead of from a single date. Sounds like good homework!

Meanwhile, I have uploaded the class in plain text at EventLogger.cs.txt, just remove the .txt when you save it (I added the .txt so you could view in your browser). For those who’d like an entire test app, I’ve zipped up the project, just shoot me an e-mail at arcanecode (at) gmail.com (since wordpress won’t let me upload zips). It comes with a form that tests all the features of the event logger class.

OK, no more excuses, go start logging today!

As you might expect, an application with heavy use will quickly generate a lot of log entries. If you want to clear out the log, you only have one choice, the Clear method.

This will clear ALL of the entries in the log you specify with the Log property. Now, you may be thinking “Hey, I want to keep a few, the last couple of days anyway.” Sorry Charlie, it’s an all or nothing deal.

Fortunately, keeping the event log cleaned out is something you don’t have to worry about. By default Windows will take care of it for you. You do, however, have a little bit of control over the process with some properties and methods the EventLog exposes.

The first thing you should look at is the OverflowAction property. It is an enumerated property that tells Windows what to do when the log gets full. Its possible values are:

OverflowAction.DoNotOverwrite – The least useful of the three, this tells Windows once the log is full, quit writing to it. All new events are lost, thrown away like an empty Sausage McGriddle wrapper.

OverflowAction.OverwriteAsNeeded – Nothing is overwritten until the log is full. Once full, the oldest entry is removed, replaced by the newest entry. This is the safest one to use.

OverflowAction.OverwriteOlder – This is the default. If the log is full, Windows looks for events older than the value found in MinimumRetentionDays. If it finds events that are older, it overwrites them. If it does not, the new event is discarded.

As stated, the MinimumRetentionDays shows the number of days to retain, but you have to be careful. If we are in DoNotOverwrite mode, the MinimumRetentionDays is set to -1. If we are in OverwriteAsNeeded mode, the value is 0 (zero). Only if we are in OverwriteOlder mode will this have a positive value greater than zero.

To change the mode your log works in, use the ModifyOverflowPolicy method. It takes two parameters, the OverflowAction and an integer indicating the number of retention days. In cases other than OverwriteOlder, the retention days parameter is ignored. Here’s a sample. Since I’m passing in OverwriteAsNeeded, I just passed in a 0 for the retention days since it’s ignored.  

For my money this is the safest way to go, as you ensure that your newest events will never get discarded.

Before we leave, there’s one more property you should look at. Let’s say your application, for whatever reason generates a lot of log entries. They are rolling out faster than you want them to. The solution then is to make the log bigger through the MaximumKilobytes property.

By default, the MaximumKilobytes for a log will be 512. Setting it straight forward, just set the value to a new size in Kilobytes.

So now you know how to clear the log, and more importantly how to control the size and retention policy for your event log. Tomorrow we’ll build on what we’ve learned to create a real word event logger.

Yesterday we created some code that wrote messages to the event log, and showed how to use the Microsoft Management Console (MMC) to review those messages. For the average user though, running the MMC may be a bit out of their normal comfort bounds. Instead, we need to be able to access the log from within our application. Again, the .Net Framework makes this easy.

First you’ll need to create an EventLog object, as we did with the writing. Then set the log property to the log we write to. Finally you will need to loop through the Entries collection of the EventLog, looking at each EventLogEntry object. Here’s a quick method I put together.

The EventLogEntry class has a lot of informative properties, here I’ve grabbed the three most important, Source, Message, and TimeGenerated. Source and Message are just as you wrote to the log. TimeGenerated is important as it lets you know when the message was generated. Not only will this tell you when the user had the issue, you can also use it to limit the amount messages you export.

In a real world situation I would have passed in the code, and probably passed in a date as well to limit the number of entries I returned. But this gives us a good starting point for building our event logger helper class. Stay tuned….

First off, let me say thanks to our BSDA (http://www.bsda.info/) President, last week he gave a quick intro to event logging that inspired this piece. If you are a new developer, you may be wondering what Event Logging is.

Let’s face it, users are the worst in the world about telling you what happened.

User: “I had an error with your app.”

You: “OK, what was the error message?”

User: “I dunno, just something about an error.”

You: “Uh, did you write down the message?”

User: “No, but it looked real bad. I think you need to fix it right away. Gotta go!”

Fortunately, Windows has a built in way to track messages that your application generates, called the Event Log. In .Net 2.0 it turns out logging is very simple, just a few lines of code.

First, set a reference to the System.Diagnostics in your class, that’s where the event objects live. Now paste in a few simple lines of code:

The first line creates a new event log entry under the name ArcaneCode. You’d probably want to put the name of your application in this area. The next line creates the message to log, in a real app this would probably be passed in as a string from an error handler or tracer.

The Source property is for designating the area that had the problem. In a “real world” app I would probably put the class and method that generated the event log request here, perhaps passed into a routine as a string. For this example though it’s just hard coded.

The final line actually writes the entry, after all the setup has been done. The first parameter is obvious; it’s the message to log. The second parameter indicates the type of event this is. The EventLogEntryType enumerator has five choices; Information, Warning, and Error being the most common.

To see if this got to the log, we need to look in the Microsoft Management Console. Click Start, Run from your Start menu, then type in mmc and press enter. Once the Console opens, pick File, Add/Remove Snap-in from the menu. Down at the bottom of the screen you’ll see a button that says “Add”. Click it, then in the list that appears find one called “Event Viewer”. Pick it, click Add, then Close. Then click OK. You should see something like this:

You can see the entry for “ArcaneCode”. Click it and you’ll see all of the events generated by your program. Double click on one of the events (or right click and pick properties) will show you all of the detailed info including the date / time, and that spiffy error message you passed in.

You can see that having a place to log messages to could make application debugging much easier once your app winds up in production. It will also be handy for debugging things like web or windows services, things that lack a user interface.

Care should be taken with what you log. It’s easy to go overboard and log every little thing. In my book, you should always log any error message that the application cannot handle. Then you should move into the critical areas of your app that are “problem spots”. Finally, if the user does something that will have a major impact on your database, such as electing to delete every customer record, you’ve found a good candidate for an event to log.

Of course, putting data into the event log is one thing. You can hardly expect your user to have the ability to go into the management console every time they have an error. That’s why the .Net Framework also has a way to get the events back out of the system, and it’s just as easy as putting them in. We’ll cover that in the next post, then go on to build a nifty event logging class you can use in your own applications.

Another often overlooked topic is the usefulness of static methods. Simply put, a static method is a method you can call without having to first create an object from a class.

In a traditional class, to use a method you first have to create an instance of it. Let’s say our class looks like this:

To use our simple class, we do something like this:

Looking at the ComineName method, you see it’s pretty simple. It doesn’t use any of the classes internal variables, call other methods, or anything else special. Seems like a lot of overhead to use a simple method. Fortunately, .Net provides a way we can call this method without having to create an object from it’s class. As you may have guessed, it’s the static keyword. A quick change to our method declaration is all that’s required.

Now it’s much easier to call our method. We can get rid of the variable declaration all together. Then, instead of referencing an instance of our class, we reference the class name itself. Three lines of code is reduced to:

Notice that the st.CombineName became StaticTest.CombineName. I find that when working with new developers this becomes the most confusing thing about static methods, namely you use the class name instead of a variable when addressing static methods of the class.

Static methods do have a few restrictions. First, they are not allowed to reference any of the class’s variables or properties. This makes sense, as they are running outside of a specific instance of the class. They also cannot use the “this” keyword. Again, this makes sense as this refers to a specific instance (i.e. an object) of a class, and inside a static method there is no instance to access.

The .Net Framework is loaded with static methods, take the string for example. Type in string and hit the period, an you’ll be amazed at how many methods appear. All of these are static methods that are part of the string class.

When writing your methods, take a look and see if they could be implemented statically. If you don’t have to reference other variables or properties of the class, you may have a good candidate for a static method.