Category Archives: C Sharp

Delegates Made Easy in C#

During my discussion of SQL Server Compact Edition, I mentioned Delegates. I thought I’d take a moment to cover what a delegate is, and how you can effectively use them in your application.

Let’s say you send an employee to the mall, and tell him “OK, when you get to the mall I will tell you which store to go in, because right now I haven’t decided yet.” A delegate is somewhat like that. You can tell your application that you are going to call a method with a certain signature, but you will tell it the name of the method at run time instead of compile time. (The signature, in case you haven’t heard the term, is the name and return type of the method plus the list of the data types of the parameters you pass.)

Let’s create a simple example. Create a new windows form app. Put on a label, a text box, and two buttons. When done, it should look something like this:

Now add a class, and name it “TheDoSomethingClass”. Once it’s created, we’ll need to put a declaration at the class level:  

    public delegate void DoDelegate(string msg);


We are creating a new variable type called DoDelegate. It’s descended from a Delegate, and has one parameter. It has to be pubic, so we can later create a variable of the DoDelegate type.

Next, we’ll add one method to the class, and pass in our delegate type.  

    public void DoSomething(DoDelegate doit)


      for(int i=0; i < 3000;i++)

      if (doit != null)


        doit(“Count=” + i.ToString());




This method has one parameter, “doit”. Notice that doit is of type DoDelegate. I created a little loop, just so we can see some action. Next, I check to see if the doit variable is null. This is very important, traditionally a delegate is never required but optional for use in your class. Thus you should always check to see if it’s null before attempting to use it. In the next line we actually call the doit method, and pass in it’s parameter, in this case a single string.

Now let’s look at how to use our delegate. Let’s return to our form, and add a new method. This method will be called ShowInLabel, accept a single string which it will display in the label control. I also added a DoEvents, just to get the label to update immediately.  

    private void ShowInLabel(string theMessage)


      label1.Text = theMessage;



Now for the final step which ties everything together. In the click event for the button next to the label, we need to add two lines of code. The first line will instantiate a new object from our TheDoSomethingClass class. The second line will call the DoSomething method.  

    private void btnLabel_Click(object sender, EventArgs e)


      TheDoSomethingClass dsc = new TheDoSomethingClass();


         new TheDoSomethingClass.DoDelegate(ShowInLabel));



Notice something important: in the second line we create a new variable of type DoDelegate. Perhaps if I do it in 3 lines it will make it slightly clearer.


      TheDoSomethingClass dsc = new TheDoSomethingClass();

      TheDoSomethingClass.DoDelegate myNewDoDelegate

        = new TheDoSomethingClass.DoDelegate(ShowInLabel);



As part of the constructor, we pass it the name of a method that has the same signature as the delegate. In this case, ShowInLabel has the same signature (one parameter, a string) as the delegate was declared with. The Delegate’s signature and the signature of the method you want to assign to it must match or you’ll get an error.

Now let’s flex our power a little. Create another method with a different name, but the same signature. This one we’ll call ShowInTextBox, and like the other we have to have one string as a parameter. In this method we will update the text box instead of the label with the passed in message.  

    private void ShowInTextBox(string theMessage)


      textBox1.Text = theMessage;



Now in the click event for the button associated with the text box, we’ll repeat the code from the other button with one exception. In the constructor, we’ll pass in the name of the new method.  

    private void btnTextBox_Click(object sender, EventArgs e)


      TheDoSomethingClass dsc = new TheDoSomethingClass();


        new TheDoSomethingClass.DoDelegate(ShowInTextBox));


DoDelegate method what so ever, yet it was able to call a completely different method.

You can also store the delegate, in case you want to use it for several methods in your class, or manipulate it a bit easier. Put this code in your class (note I squished down the get/set to save a bit of space, I don’t normally code that ugly.) I added a private variable to hold our delegate, a property get / setter, and a new method that will take advantage of it.  

    private DoDelegate _TheDelegate;


    public DoDelegate TheDelegate



      { return _TheDelegate; }


      { _TheDelegate = value; }



    public void DoSomethingElse()


      for (int i = 0; i < 3000; i++)

        if (_TheDelegate != null)


          _TheDelegate(“Count=” + i.ToString());



Now to call it, all we have to do is go back to our form and add this code to a button click event:

      TheDoSomethingClass dsc = new TheDoSomethingClass();


        = new TheDoSomethingClass.DoDelegate(ShowInLabel);



        = new TheDoSomethingClass.DoDelegate(ShowInTextBox);


Note here I changed the delegate between calls, I could have also coded more methods that used the same call. Also note if I had tried calling DoSomethingElse before assigning a delegate, the program would have run just fine I just wouldn’t have been shown any messages, thanks to the if ( _TheDelegate != null) statement.

Now that I’ve shown you how a delegate works, let’s take a moment to discuss some times when you might want to use it. The first example I can think of is to support an add in architecture. You can dynamically load DLLs at run time, and when you do you can query it to see if it supports a certain delegate type, perhaps one for communicating a message like our example. If so, you can assign that delegate to the message handler for your particular app. Not only does this mean you can use multiple add-ins with the same app, it also means you could support multiple apps with one add-in.

Here’s another example from my personal experiences. I have a winforms app that can connect to multiple database. (Each of our sites has it’s own database.) Most users only need to connect to one, so I save the database they were last connected to in the settings file. When the user reloads the app, I reconnect to the same database.

When my app loads, there are a lot of lists of values I retrieve to populate drop down combos. During load, however the only form visible is my splash screen. Using delegates in my load routine I have all progress messages from my data layer displayed on the splash screen.

During the course of using my program, the user can choose to hook to a different site, and hence a different database, which means I have to reload all those lists of values again. This time though, I don’t have the splash screen up. True, I could show it again, but it would look really goofy.

Instead, in my load routine I instead pass a delegate to the data layer that instead will display progress messages on the status bar control at the bottom of the form.

The beauty of this is that the data layer has no clue where or if it is displaying messages, nor should it have to care. I can also reuse this data layer DLL in other apps down the road, should the need arise, and take advantage of the status messages it provides.

In my example I have kept it simple and used a single parameter for my delegate. Know that you are not restricted; you can use multiple parameters if you wish. The important thing to remember is your signatures must match. The return type and number of parameters for your delegate (DoDelegate) must match the signature of the methods you assign to it (ShowInLabel, ShowInTextBox).

When designing your classes, especially those destined for DLL libraries that could get multiple use, consider adding some delegates as a way to inform your consumer of the progress of your methods.

There you go, a short step by step for delegates in C#. If you think of some new uses for delegates, drop a comment and let us know.

Loading a SQL Server Compact Edition Table From a DataTable in C#

Of all the situations you can be in using SSCE, I think one of the most common will be to pull data from a larger database provider and populate a table in your local SSCE database. While SSCE does have some nifty replication support, it only works with SQL Server. Like many of you I have to support data coming from many different places, such as Oracle, Access, and XML to name but a few.

The easiest way to pull the data is to get it into an ADO.Net DataTable, but what then? I sure didn’t want to have to create the insert statements by hand each time, plus I wanted to be able to reuse my routines. Being a lazy individual, I wanted a routine I could pass any DataTable into and push the data into my SSCE table.

I started with a blank class, and created a few class level variables. One was out of a SqlCeConnection which I named _connection. I also had two strings to hold the database name and password. Next, I created a “ConnectionString” method, identical to what I described a few days ago.

    private string ConnectionString()


      return string.Format(

        “DataSource=\”{0}\”; Password='{1}'”

        , this._CacheDatabase

        , this._Password);



I then created an Open method, which is pretty simple:


    public void Open()


      if (_connection == null)

        _connection = new SqlCeConnection(this.ConnectionString());


      if (_connection.State == ConnectionState.Closed)




OK, now for the grand finale.



    public void Populate(DataTable myDataTable

      , string tableName)


      // If the datatable has no rows, we’re wasting

      // our time, get outta dodge.

      if (myDataTable.Rows.Count == 0)





      // Make sure database is open for business



      // Use a string builder to hold our insert clause

      StringBuilder sql = new StringBuilder();

      sql.Append(“insert into “ + tableName + ” (“);


      // Two more, one for the list of field names,

      // the other for the list of parameters

      StringBuilder fields = new StringBuilder();

      StringBuilder parameters = new StringBuilder();


      // This cycles thru each column in the datatable,

      // and gets it’s name. It then uses the column name

      // for the list of fields, and the column name in

      // all lower case for the parameters

      foreach (DataColumn col in myDataTable.Columns)



        parameters.Append(“@” + col.ColumnName.ToLower());


        if (col.ColumnName !=


                 – 1].ColumnName)


          fields.Append(“, “);

          parameters.Append(“, “);



      sql.Append(fields.ToString() + “) “);

      sql.Append(“values (“);

      sql.Append(parameters.ToString() + “) “);


      // We now have our Insert statement generated.

      // At this point we are ready to go through

      // each row and add it to our SSCE table.

      int rowCnt = 0;

      string totalRows = myDataTable.Rows.Count.ToString();


      foreach (DataRow row in myDataTable.Rows)


        SqlCeCommand cmd

          = new SqlCeCommand(sql.ToString(), _connection);


        foreach (DataColumn col in myDataTable.Columns)



            + col.ColumnName.ToLower()

            , row[col.ColumnName]);


        // Optional: I created a delegate called message delegate,

        // and assign it to the class level variable Cachemessage

        // It’s a simple method that takes one string and displays

        // the results in a status bar. If you want to simplify

        // things, just remove this entire section (down to

        // the try).


        if (_CacheMessage != null)


          if ((rowCnt % 100) == 0)

            _CacheMessage(“Loading “ + tableName

              + ” Row “ + rowCnt.ToString()

              + ” of “ + totalRows);





          // Here’s where all the action is

          // sports racers! This is what sends

          // our insert statement to our local table.



        catch (Exception ex)


          // You’ll probably want to be a bit more

          // elegant here, but for an example it’ll do.

          throw ex;





My code comments elaborate pretty well on what’s going on, a quick read should be all you need. Only two things to really point out. First, I create a delegate to send a progress message. I’ll go into more on delegates another day, if need be, there’s a ton of info on them out on the web. Let me show you the declarations I used for my delegates so you can repeat them in your class:


    private CacheMessageHandler _CacheMessage;


    public void Messenger(CacheMessageHandler messageRoutine)


      _CacheMessage = messageRoutine;



I created a method in the calling program called ShowStatus. Very simple, takes one string as a parameter and displays it somewhere to the user. (I chose a status bar, you might use a label). All I had to do was call the Messenger method like so: 


         new MyClass.CacheMessageHandler(ShowStatus))


In retrospect I could also have created a CacheMessage property, I just didn’t think of it at the time. If you paste in the declarations you should be able to use the method even though you never use the delegate (note I check to see if _CacheMessage is null) but if you have issues, just delete that small section, it’s not that important to the process of loading the table.

The other major thing, and a gold star to you if you already noticed this: in order for this method to work, the column names in your DataTable must match exactly with the column names in your SSCE table!

Personally this seems like a small price to pay, and frankly if you are replicating data it will make your debugging and programming life much easier as you work through bugs. I do this as a standard, which is why this kind of routine fits well into my environment.

This wraps up (for now) my exploration of SQL Server Compact Edition. If you have decided to leverage SSCE in your own apps, please leave a comment, let us all know what your experiences have been, problems, benefits, and the like.

Inserting Rows Into A SQL Server Compact Edition Table in C#

Now that we have some tables, you naturally want to put some data into them. As you might have guessed from my last post, you perform data manipulation (insert, update, delete) just like you do when creating the table and use the SqlCeCommand object. Only this time there’s a twist.

First, because I wanted to load several rows I created a method to load a single row and pass in the parameters to my “CoolPeople” table. Here’s the small bit of code that handles it:  

        LoadARow(“Carl”, “Franklin”, @”http:\\”);

        LoadARow(“Richard”, “Campbell”, @”http:\\”);

        LoadARow(“Leo”, “Laporte”, @”http:\\”);

        LoadARow(“Steve”, “Gibson”, @”http:\\”);

        LoadARow(“Arcane”, “Code”, @”http:\\”);


I then wrote a routine that would take the passed in data and insert it into the database. As with my create table example yesterday, I’m using the command object. This time though, I am adding parameters to the command.

If you look in the SQL, you see I have three parameters, noted by the @ sign. @first, @last, and @url. When SSCE creates the insert statement for the database, it will then look for three parameters and replace these three @ placeholders with the values you put into the parameters.

Sure, you could concatenate it all together in a string, but then you have to worry about things like the “O’Malley Issue” and SQL Injection attacks. (See Bill Vaughn’s book “Hitchhiker’s Guide to Visual Studio and SQL Server, 7th edition for a complete discussion on these topics, or browse the web. There’s lots of info so I won’t take up further space now.)

Here’s the entire LoadARow routine. Note that my choosing to name the method parameters the same as the SSCE command parameters is entirely a coincidence, it simply makes it self documenting and is not a requirement.


    private void LoadARow(string first, string last, string url)


      SqlCeConnection cn = new SqlCeConnection(ConnectString());


      if (cn.State == ConnectionState.Closed)





      SqlCeCommand cmd;


      string sql = “insert into CoolPeople “

        + “(LastName, FirstName, URL) “

        + “values (@lastname, @firstname, @url)”;




        cmd = new SqlCeCommand(sql, cn);

        cmd.Parameters.AddWithValue(“@lastname”, first);

        cmd.Parameters.AddWithValue(“@firstname”, last);

        cmd.Parameters.AddWithValue(“@url”, url);


        lblResults.Text = “Row Added.”;


      catch (SqlCeException sqlexception)


        MessageBox.Show(sqlexception.Message, “Oh Crap.”

          , MessageBoxButtons.OK, MessageBoxIcon.Error);


      catch (Exception ex)


        MessageBox.Show(ex.Message, “Oh Crap.”

          , MessageBoxButtons.OK, MessageBoxIcon.Error);








After creating the SqlCeCommand object by passing in the sql string and the connection object, I can then add the parameters with a single line for each. By using the Parameters object of the command object, I can call the AddWithValue method, and simply pass in the parameter name as a string and the value for that parameter. Once you add all the parameters, simply call the ExecuteNonQuery method and the data is inserted!

This method can be a basis for all your future work with SSCE. Everything you need to do revolves around the command object and sending SQL commands to the database. Need to delete a record? Just change the SQL from an insert to a delete, pass the correct parameters and you are in business. Update? Same thing.

Using the code I’ve shown in this series you can create your own SSCE applications, and store data locally. Lest you think this is the wrap up, I have one more cool method to show you, but that’ll be for tomorrow!

Create a Table in SQL Server Compact Edition with C#

Before we create a table in SSCE, you need to understand that SSCE only supports a subset of the data types provided in full SQL Server. The specific list is: bigint, integer, smallint, tinyint, bit, numeric (p, s), money, float, real, datetime, national character(n) (Synonym:nchar(n)), national character varying(n) (Synonym:nvarchar(n)), ntext, nchar, binary(n), varbinary(n), image, uniqueidentifier, ROWGUIDCOL , and IDENTITY [(s, i)].

The last two, strictly speaking are not data types but properties of the data column. SSCE was designed to be small and lightweight (hence the Compact name). To keep it small, many of the datatypes were eliminated.

A full list, with detailed explanations can be found at on the MSDN site: or

Now that you know what’s available, let’s talk about how to create a table. In keeping with it’s theme of compactness, SSCE doesn’t include classes for manipulating the structures inside a SSCE database directly. Instead, you have to do everything through SQL DDL (Data Definition Language) statements. You know, Create Table, Drop Table, etc.

The code below shows the fairly simple steps involved. First you need to open a connection to the database. You do this by creating a SqlCeConnection object and passing in the connection string. The connection string has the same format I described in my previous post on creating the database.

Next, we create a string to hold some SQL (sql), and create a SqlCeCommand object (cmd). Finally we call the ExecuteNonQuery method of the command object to kick off the SQL. Here’s the code, with some try / catch logic thrown in to trap for errors.


      SqlCeConnection cn = new SqlCeConnection(ConnectString());


      if (cn.State==ConnectionState.Closed)





      SqlCeCommand cmd;


      string sql = “create table CoolPeople (“

        + “LastName nvarchar (40) not null, “

        + “FirstName nvarchar (40), “

        + “URL nvarchar (256) )”;


      cmd = new SqlCeCommand(sql, cn);





        lblResults.Text = “Table Created.”;


      catch (SqlCeException sqlexception)


        MessageBox.Show(sqlexception.Message, “Oh Fudge.”,

          MessageBoxButtons.OK, MessageBoxIcon.Error);


      catch (Exception ex)


        MessageBox.Show(ex.Message, “Fooey.”, MessageBoxButtons.OK,








There’s a few things I’d like to point out. First, the connection. In this simple example, I opened and closed the connection in the same routine. For talking to large databases, especially when doing so from a web app, this methodology makes a lot of sense. You keep the connection open for a brief time and reduce the load on your server.

With SSCE however that need does not exist. The database is local with one connection, so you save nothing by the brief open / close connection, and instead slow yourself down. With SSCE I would recommend you open the connection when your application launches, and close it when it exists. Pass it to the classes that need it. You will gain a lot of speed doing so, and minimal cost in terms of memory.

The other thing to note, within the line that instantiates the new SqlCeConnection I have a method called ConnectString(). To make life easy for my demo I encapsulated the connection string in a method that returns a string. You could place your connection in a string, method, or whatever is convenient for you. I already documented the code to create a connection string in yesterday’s post on creating a database, so I won’t bore you with it again.

Would you like to see the database? Cool. Open up SQL Server Management Studio (I’m guessing you have SQL Express or SQL Server Developer Edition installed). When it opens, pick SQL Server Mobile as the database type. Under Database File, click the Browse for more… option and navigate to the sdf file you created, and click on OK. Enter in the password, and click OK again to open the database.

Now you can do many of the normal things you’d do with a SQL Server database. Click on the Tables in the tree and you should see it expand and show our “CoolPeople” table. You can drill down further to see all the fields.

OK, we’ve created our table, the next step will be to load it. But that’s for the next post!

Create a SQL Server Compact Edition Database with C#

Before I start on the coding route, I found one other component you might want to download for SSCE. It’s not absolutely needed, but makes life in VS much easier. It’s the SSCE Developer SDK. It has the Northwind sample database, CAB files for installing SSCE on mobile devices, and MSI for installing the help files, and more. Grab it at the URL below and install all the goodies. or

OK, let’s have a little fun. First thing I did was create a test app using a Windows Forms application. Next thing you need to do is create a reference to the SSCE. Click on Project, Add Reference. According to all directions I’ve read, all you have to do is be on the .Net tab, scroll down to System.Data.SqlServerCe, click on it and click OK. Found it?

Nah, I couldn’t find it either. So here’s the part the instructions don’t tell you. Go click on the Browse tab. Now navigate to C:\Program Files\Microsoft SQL Server Compact Edition\v3.1. Now pick the System.Dadta.SqlServerCe.dll, click on it, then click on OK to pull in the reference. (That little nugget will save you a lot of hair pulling, and if you did find it then good for you, just click on it and keep going.)

Now let’s write some code. First, go to the head of the class, whoops I mean header of your class and let’s create a using reference.  

using System.Data.SqlServerCe;

using System.IO;

While I was at it I also set a reference to the System.IO namespace since we’ll want to check for the databases existence. Now in a method somewhere, let’s setup a few variables. Then we’ll check to see if the database already exists. Since this is just a sample, I’m going to delete it. This would be a valid action if the database was just a temporary cache for reports. In your situation you might want to return an error, or just exit gracefully without causing any problems.


      string connectionString;

      string fileName = “ArcaneCode.sdf”;

      string password = “arcanecode”;


      if (File.Exists(fileName))





      connectionString = string.Format(

        “DataSource=\”{0}\”; Password='{1}'”, fileName, password);


You can see the last thing I did was establish the connection string. Some very important things you need to note. First, the DataSource must be surrounded with double quotes. The password, on the other hand, must be surrounded with single quotes.

In this example I’m just giving the database an SDF name, and letting it drop in the current directory. You could hard code a full path, or put it in a variable.

OK, we’ve got everything setup. Turns out it’s quite easy to create a new database. First, we create a new instance of a SqlCeEngine, and initialize it by passing the connection string into the constructor. Then, it’s as simple as calling the CreateDatabase method of the engine.  

      SqlCeEngine en = new SqlCeEngine(connectionString);



And that’s all there is to it. Looking in our bin debug folder we see the new database:


[Picture of ArcaneCode.sdf]


Of course an empty database doesn’t do us a lot of good, so in the next installment we’ll start creating some tables, and maybe even put a little data in them.

Getting Started with SQL Server Compact Edition

What is SQL Server Compact Edition?

As I blogged about last week (, Microsoft has released SQL Server Compact Edition. SSCE is not new, although it carries a new name and new, expanded functionality. It’s roots extend back to the SQL Server for CE and SQL Server Mobile framework.

Microsoft recognized the need for a robust, secure database that can bridge the gap between the mobile world and the server world, and at the same time meet a need for the desktop environment. SSCE is, at its heart, a database, and nothing else.

Unlike its bigger relatives, from SQL Server Express on up, it does not run as a service. Instead, it’s a set of DLLs that you call from within your programming environment. It’s designed to have a very small footprint, the DLLs take less than 2 megabytes of space.

With SSCE you can create a database that resides in a single file, with a default extension of sdf. You can create tables, indexes and that’s about it. No stored procedures, only one user can be in the database at a time.

I know it doesn’t sound like much, but it fits an important need. First off, the database can be password protected and encrypted, to make it secure. Second, it is transportable. The database can run on both mobile devices like smart phones or PDAs, and on the desktop. You can easily move the file around, back it up, even e-mail it. After all it’s a single file, and since SSCE doesn’t run as a service it’s not locked when your app isn’t running.

SSCE also supports replication, you can replicate between it and a full blown SQL Server install. SQL Server Integration Services also works with it, making it easy to move data between your SSCE database and larger systems.

Haven’t I seen this before?

For a little while SQL Server Compact Edition was known as SQL Server Everywhere. Frankly I liked the Everywhere name better, but that’s just my opinion. I mention this because there have been some articles and books (Programming SQL Server 2005 by Andrew Brust and Stephen Forte, for example) that talk about the Everywhere edition.

The important thing to note is SQL Server Everywhere and SQL Server Compact Edition are the same thing.

Places to use SQL Server Compact Edition

So when do you use SSCE? Well, if you want to develop a database app that will run on a mobile device, this is your only choice. (Well, outside of developing a web app, but we’re talking an app that will run totally independently of external influences).

If you are developing a Windows based application, for a single user, and you need a local database just to hold some data, SSCE is a good choice. For example, a salesman could have an application with his companies product table and sales tables loaded. He could take his laptop to the field, place orders, then have the app resync when he returns to the office.

In my own case, I have an app that generates graphs from a specific dataset. This data is gathered from multiple databases. To create one chart takes about 1 to 2 minutes depending on how many users, amount of data, etc. That doesn’t sound like much, but they look at 12 to 18 reports every morning, that’s a lot of time for a Vice President, Plant Manager, and six other top guys to sit around waiting. Instead I’ll be using SSCE to cache the data locally. It takes about 3 minutes to pull down the data, but after that each chart generates in about one third of a second. Quite an improvement!

If you need multiple users, to store your data on the network, or have stored procedures, you will need to move up the food chain to something like SQL Server Express. If you need more info, there is an excellent article at that contrasts the differences between SSCE and SQL Server Express.

What do I need?

OK, you’ve decided to take the plunge and look into SSCE. Well first, you need to get SSCE and install on your development system. I provided a link in last week’s post, but in case you missed it you can download SSCE from

Next, you need to install Visual Studio Service Pack 1. VS SP1 will correct add some intellisense and correct some naming issues (for example the reference shows as SQL Server Mobile prior to installing SP1). In addition it’s probably a good idea to install SP1 anyway, to correct various issues. You can get your copy from or

Next, you will want the SQL Server Compact Edition Books On Line (that’s a mouthful, we’ll call it SSCE BOL from now on). You can get these at or These have essential documentation for understanding SSCE.

Update (April 24, 2007): It turns out there is a fourth component you will want, the SQL Server Compact Edition Tools for Visual Studio 2005, Service Pack 1. See my post on April 24th ( for details and where to download it from. If you want you can go ahead and finish this post first, as you will install this component as the final step.

How do I learn this stuff?

First off, the SSCE BOL is a good resource, it has lots of links and information on how to use SSCE. I admit though it’s laid out like a help file, for learning it isn’t laid out in a logical chapter by chapter manner.

Microsoft has some “How To” tutorials at or . They come in both C# and VB.Net flavors, and step you through various topics.

There are two spots on Microsoft that are launching points for SSCE. The main site off the SQL Server area is (or The MSDN site is (or

SQL Server Guru Bill Vaughn has written an excellent E-Book on SSCE. Of all the resources I’ve mentioned this is probably the best, although you do have to purchase it (dirt cheap). Bill’s site for his Hitchhiker’s Guides is, the E-Book I’m speaking of is at At 20 bucks it’s well worth the investment. (Standard disclaimer, I don’t make any money off sales of the book, Bill’s site, or anything else associated with the Hitchhiker’s guides. )

Finally, I’ll spend a few days talking about what I’ve learned from all these sources, showing you what I’ve done with this new technology. Hopefully I’ll help you shortcut some of the learning pains I’ve gone through.


Event Logging – Putting It All Together

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 . 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.  

    public static void Log(string LogName, string Source,

      string Message, EventLogEntryType EventType, int EventID,

      short CategoryID, byte [] RawData)


      EventLog evt = new EventLog(LogName);

      evt.Source = Source;

      evt.WriteEntry(Message, EventType, EventID, CategoryID, RawData);


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

or .

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:  

    public static void LogMessage(string LogName, string Source,

      string Message)


      Log(LogName, Source, Message, EventLogEntryType.Information);


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.  

    public static string ReadLog(string LogName, DateTime OldestValue)


      StringBuilder returnValue = new StringBuilder();

      EventLog el = new EventLog();


      el.Log = LogName;


      foreach (EventLogEntry myEntry in el.Entries)


        if (myEntry.TimeGenerated >= OldestValue)






      return returnValue.ToString();


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.  

    private static string formatEntry(EventLogEntry myEntry)


      StringBuilder returnValue = new StringBuilder();


      // Detect what type of entry it is

      string entryType = “Unknown”;


      switch (myEntry.EntryType)


        case EventLogEntryType.Information:

          entryType = “Information”;



        case EventLogEntryType.Error:

          entryType = “Error”;



        case EventLogEntryType.Warning:

          entryType = “Warning”;



        case EventLogEntryType.SuccessAudit:

          entryType = “Success Audit”;



        case EventLogEntryType.FailureAudit:

          entryType = “Failure Audit”;




      // Add the various elements together

      returnValue.AppendLine(“Source: “ + myEntry.Source);

      returnValue.AppendLine(“Entry Type:” + entryType);

      returnValue.AppendLine(“Message: “ + myEntry.Message);

      returnValue.AppendLine(“Entry Generated at “

        + myEntry.TimeGenerated.ToString());

      // .Net reports that EventID is now depricated. So although we

      // pass in EventID in the WriteEntry method, to get it out we

      // use InstanceID. (You can use EventID, but you get a compiler

      // warning message about the depreciation.)

      returnValue.AppendLine(“Event ID: “

        + myEntry.InstanceId.ToString());

      returnValue.AppendLine(“Category ID: “

        + myEntry.CategoryNumber.ToString());

      returnValue.AppendLine(“Machine Name: “ + myEntry.MachineName);


      // Append Data, if we have any

      if (myEntry.Data.Length > 0)


        returnValue.Append(“Data: “);

        foreach (byte dataByte in myEntry.Data)


          // Convert each byte into a two character

          // hexidecimal string

          returnValue.Append(string.Format(“{0:X2} “, dataByte));


        returnValue.AppendLine(“”); // End the line of the data



      returnValue.AppendLine(” “);  // Blank Line


      // All done, return to the calling method

      return returnValue.ToString();



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) (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!

Event Logging – Clearing the Event Log

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.

      EventLog el = new EventLog();

      el.Log = “ArcaneCode”;


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.  

    public static void SetToOverwriteAsNeeded()


      EventLog el = new EventLog();

      el.Log = “ArcaneCode”;

      el.ModifyOverflowPolicy(OverflowAction.OverwriteAsNeeded, 0);


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.


    public static void SetLogTo1K()


      EventLog el = new EventLog();

      el.Log = “ArcaneCode”;

      el.MaximumKilobytes = 1024;     


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.

Event Logging – Reading the Event Log

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.

    public static string ReadLog()


      StringBuilder returnValue = new StringBuilder();

      EventLog el = new EventLog();


      el.Log = “ArcaneCode”;


      foreach(EventLogEntry myEntry in el.Entries)


        returnValue.AppendLine(myEntry.Source + “: “

          + myEntry.Message + ” “ + myEntry.TimeGenerated.ToString());



      return returnValue.ToString();


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….

Event Logging – Writing to the Event Log

First off, let me say thanks to our BSDA ( 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:

      EventLog evt = new EventLog(“ArcaneCode”);

      string message = “This is where the error message goes. “
        + “For support info see;

      evt.Source = “ArcaneCodeApplication”;

      evt.WriteEntry(message, EventLogEntryType.Information);

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:

[Picture of MMC Console]

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.

[Picture of Event Properties]

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.

Static Methods

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:

  public class StaticTest


    public string CombineName(string first, string last)


      return first + ” “ + last;



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

      StaticTest st;

      st = new StaticTest();

      string fullName = st.CombineName(“Arcane”, “Code”);

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.

    public static string CombineName(string first, string last)


      return first + ” “ + last;


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:

      string fullName = StaticTest.CombineName(“Arcane”, “Code”);


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.

Boxing and Unboxing

I want to begin the series by covering some “advanced basics”. You can find a million “Hello World” tutorials, so I want to avoid those and cover topics frequently overlooked in beginners books. Boxing is just such a topic.

As you may be aware, there are two kinds of variables in .Net, value types and reference types. A value type is stored in an area of memory called the stack, which is a very fast place to get to. Value types are simple data types like integers, doubles, and so on. Things the compiler can always guarantee the size of.

Reference types, on the other hand have a variable size, and thus don’t fit nicely on the stack. So .Net puts them in a memory location called the heap, and stores a reference to the stack.

It’s a lot like having a post office box. For small items, like letters, you just go to the post office box and remove them, quick and easy. Let’s say you get a huge package, maybe that spiffy new laptop has finally arrived. Obviously that laptop won’t fit in your post office box, so the mail service puts a little yellow slip that says “you’ve got a package, it’s stored in this location, come get it”.

The post office box in this case would be the stack. Letters are like value types, small, fast to get to, and usually one of a few predictable sizes. The little yellow slip saying you’ve got a package would be a reference type, it’s pointing to a specific spot in the heap of packages stored in the back room.

Now, boxing occurs whenever you try to put a value type, such as an integer, into a reference type, such as an object.

      int myLetter = 42;

      object myBox = (object)myLetter;

Because .Net doesn’t know in advance how big the myBox object will be, it has to make it a reference type. Placing an int into it makes no difference. .Net will happily take the value 42, place it on the heap, and store a reference to the memory location in the myBox variable.

As you might guess, extending our PO Box analogy would have the post office take the letter out of your PO Box, shove it in a big box, put it in the back and stick one of those yellow slips in your slot.

This entire process is called Boxing. The reverse, putting a refernce type back into an value type is called Unboxing.

      object myBox = 42;

      int myLetter = (int)myBox;

Boxing and unboxing are very slow processes. Additionally, they are fraught with danger. What if we’d tried this instead?

      object myBox = 3.1415719;

      int myLetter = (int)myBox;

Gold star to anyone who blurted out “run time error” or “invalid cast exception”. There is no implicit type checking when moving from a value type back to a reference. You will have to add additional code to be sure that no errors happen.

In general you should try to avoid boxing and unboxing, and instead use generics (more on them later). Occasionally you can’t avoid it, for example:

      int recordCount;

      // Some code here that loads records and increments recordCount

      MessageBox.Show(“You loaded “ + recordCount.ToString()

         + ” records.”);

You may not realize it, but when you call ToString, you are creating a boxing operation, converting our nice value type int into a reference type string. As I mentioned, sometimes you can’t avoid these types of operations. Which brings us to the obvious question, when is it “safe” to box?

Typically when you perform a widening operation, moving a smaller variable into a larger one, you’re OK. For instance, moving an int into a double or string is safe because you are taking a smaller data type and moving it to a larger one. Much like taking an envelope out of your post office box, and placing into one of those large overnight mailers, or a shipping carton.

A narrowing conversion on the other hand is when you take a big variable and try to shove it into a smaller one, such as a double into an int. These are dangerous and you should be sure what you are doing before attempting.

By the way, not all widening operations are necessarily a boxing operation. Going from int to double is widening, but not boxing because there are two value types involved. Moving from int to string is both widening and boxing, as you are going from a value to a reference type. Whichever the case, just know that both are “safe” things to do. You can rest easy knowing this particular type of operation is safe.

Boxing is one of those arcane pieces of knowledge, understanding it will help you to be a better programmer so you will know when using it appropriately, and when to avoid it.