Kristof Verbiest - Bite-size C#

Silverlight: loading a WriteableBitmap from file

2010-12-24T09:51:00.003+01:00

I’ve just spent quite some time trying to do something that seems very simple: embedding an image in a Silverlight application and loading this image into a WriteableBitmap (because I need to read the values of the individual pixels).

My first attempt was to add the image to my project as a resource and use the following code:

Uri uri = new Uri("Images/Texture.jpg", UriKind.Relative);

BitmapImage imageSource = new BitmapImage(uri);

WriteableBitmap bitmap = new WriteableBitmap(imageSource);  // EXCEPTION

However, an exception is thrown on the last line. Luckily the internet came to the rescue, and these two great site suggest basically the same solution:

Using BitmapCreateOptions.None to make sure the bitmap begins to load immediately.
Subscribing to events to know when the image has actually loaded.

However the proposed solution did not work in my case because the image fails to load with an AG_E_NETWORK_ERROR error.

In the end I took a different approach: I load the resource using Application.GetResourceStream so I’m sure that the data is completely loaded before it is handed to the WriteableBitmap. This is the code:

StreamResourceInfo sri = Application.GetResourceStream(new Uri("Images/Texture.jpg", UriKind.Relative));

BitmapImage src = new BitmapImage();

src.SetSource(sri.Stream);

WriteableBitmap image = new WriteableBitmap(src);

In my case it has the advantage of being synchronous which makes the overall code much simpler (but I understand that asynchronous behavior may often be better in a web-context).

When adding your image to your Silverlight project, the build action should be set to ‘Content’ instead of ‘Resource’. This means that the image will not be included in the dll, but it will be stored in the xap-file. You can check this by renaming the xap-file to zip and looking at the content.

So there are some non-intuitive steps involved when trying to accomplish this simple task. Hopefully this post can be helpful if someone else has this problem.

Saving and restoring GDI+ state

2008-12-05T16:18:00.001+01:00

When you create complex drawing code, you probably will split this over multiple methods and pass the Graphics-object between these methods. But because the Graphics-object contains state, all changes that you apply in a method will be propagated to the other methods as well. Often this is not what you want.

The common way to work around this is to reset all the changes that you made at the end of the method:

        1: void PaintBackGround(Graphics g)

       2: {

       3:     SmoothingMode oldSmoothingMode = g.SmoothingMode;

       4:     try

       5:     {

       6:         g.SmoothingMode = SmoothingMode.AntiAlias;

       7:         ...

       8:     }

       9:     finally

      10:     {

      11:         g.SmoothingMode = oldSmoothingMode;

      12:     }

      13: }

But if your code changes a lot of properties this will become cumbersome. In these cases it is simpler to save and restore the entire Graphics-state like this:

       1: void PaintBackGround(Graphics g)

       2: {

       3:     GraphicsState oldState = g.Save();

       4:     try

       5:     {

       6:         g.SmoothingMode = SmoothingMode.AntiAlias;

       7:         ...

       8:     }

       9:     finally

      10:     {

      11:         g.Restore(oldState);

      12:     }

      13: }

Creating a single-instance application

2008-11-26T13:08:00.001+01:00

A lot has been written on the internet on how to create a single-instance application in C#. The proposed implementations fall into three categories:

Check if a process with the same name is already running (using GetProcessesByName). This is plain wrong because it needs administrator privileges. Furthermore it will not work if there is another process that happens to have the same name as your process.
Using the Microsoft.VisualBasic namespace (as explained here). This probably works OK (I have never done this), but it feels a bit wrong. Note that this approach is promoted in the book ‘Windows Forms 2.0 Programming’.
Using a Mutex.

Personally I think that the last approach is best, but there are some details that you need to get correct if you want to rely on this. This is the pattern that I propose:

        1: static class Program

       2: {

       3:     static Mutex s_Mutex;

       4:  

       5:     /// <summary>

       6:     /// The main entry point for the application.

       7:     /// </summary>

       8:     [STAThread]

       9:     static void Main()

      10:     {

      11:         bool instantiated;

      12:         // WARNING: you need to replace the GUID in this string!

      13:         s_Mutex = new Mutex(false, "Local\\MyAppName{A6F214AB-669D-41B2-9F30-8DD5E5AC9AE1}", out instantiated);

      14:         if (!instantiated)

      15:         {

      16:             MessageBox.Show("The application is already running");

      17:             return;

      18:         }

      19:  

      20:         Application.EnableVisualStyles();

      21:         Application.SetCompatibleTextRenderingDefault(false);

      22:         Application.Run(new Form1());

      23:     }

      24: }

The pattern is applied to a Winforms application, but of course it can be applied to any type of application.

For those who don’t know what a mutex is: it is a Windows kernel-object that can be used for synchronization between threads and processes. The proposed pattern tries to create a mutex with a certain name and checks if this mutex already existed. If it did, this means that our process was already started.

Here are the details that are important:

The mutex must be declared static, because we have to make sure that the garbage collector will never dispose it.
The name of the mutex should contain a GUID, which ensures that no other application uses the same name. If you don’t know how to create a GUID, click here.
The mutex is local, which means that every user that is logged on can create his own instance. If you don’t want this, simply ommit the ‘Local\\’.
The mutex contains the name of the application. As a general guideline, I think that named kernel objects should have a descriptive name. This makes it easier when debugging problems: using tools such as SysInternal’s WinObj, you can look at the state of all the kernel objects. If your object has a proper name this will be much simpler.

GDI+ objects should be disposed

2008-11-19T08:47:00.001+01:00

When a Winforms-control needs to do custom painting, this is typically done by overriding the OnPaint-method like this:

        1: protected override void OnPaint(PaintEventArgs e)

       2: {

       3:     base.OnPaint(e);

       4:  

       5:     Graphics g = e.Graphics;

       6:  

       7:     // WARNING: this code should be avoided because it does not dispose the GDI+ objects

       8:     g.FillRectangle(new SolidBrush(Color.Black), this.ClientRectangle);

       9:     TextRenderer.DrawText(g, "Hello world!", new Font(FontFamily.GenericSansSerif, 10f), new Point(10, 10), Color.White);

      10:     g.DrawLine(new Pen(Color.White), new Point(0, 0), new Point(100,100));

      11: }

On the internet you will find lots of example code that does custom drawing like this. The problem is that every time this code is executed (and in GUI this can be a lot!), a bunch of GDI+ objects are created that are not disposed. Eventually the garbage collector will kick in and will dispose all these objects. This is to be avoided however:

This puts a lot of stress on the garbage collector.
These objects will be cleaned up in two fazes which will impact performance even more.
GDI+ handles are limited resources, but the garbage collector is only invoked if your application needs more memory. It is not unlikely that your code uses a lot of GDI+ handles but does not consume a lot of memory. This may mean that the garbage collector never executes, and your code may consume a huge amount of GDI+ handles.
This issue was especially problematic before GC.AddMemoryPressure() was added in .NET 2.

The obvious solution is to dispose the GDI+ objects when they are not needed anymore:

       1: protected override void OnPaint(PaintEventArgs e)

       2: {

       3:     base.OnPaint(e);

       4:  

       5:     Graphics g = e.Graphics;

       6:  

       7:     // Much better: less stress on the garbage collector

       8:     using (SolidBrush brush = new SolidBrush(Color.Black))

       9:     using (Font font = new Font(FontFamily.GenericSansSerif, 10f))

      10:     using (Pen pen = new Pen(Color.White))

      11:     {

      12:         g.FillRectangle(brush, this.ClientRectangle);

      13:         TextRenderer.DrawText(g, "Hello world!", font, new Point(10, 10), Color.White);

      14:         g.DrawLine(pen, new Point(0, 0), new Point(100,100));

      15:     }

      16: }

This code is good but we can make it even better. Note that every time the code is executed, new GDI+ objects are created and disposed. In this particular case this is a waste because the objects will be identical every time. It would be better to create the objects only once, and reuse them every time.

It seems that the Winforms-designers at Microsoft also had this idea, because they already cache the commonly used brushes and pens in the Brushes and Pens classes. For the Font-object we need to do this ourselves:

       1: static readonly Font s_Font = new Font(FontFamily.GenericSansSerif, 10f);

       2:  

       3: protected override void OnPaint(PaintEventArgs e)

       4: {

       5:     base.OnPaint(e);

       6:  

       7:     Graphics g = e.Graphics;

       8:  

       9:     g.FillRectangle(Brushes.Black, this.ClientRectangle);

      10:     TextRenderer.DrawText(g, "Hello world!", s_Font, new Point(10, 10), Color.White);

      11:     g.DrawLine(Pens.White, new Point(0, 0), new Point(100,100));

      12: }

Notice that our Font-instance is declared as static because it can be reused when there are many instances of our control.

Of course this technique can only be used if the GDI+ objects are the same every time. If they are highly dynamic then you will have to create a new object every time (this may occur if you are drawing a part of an animation). But don’t forget to dispose these objects with the using-statement.

A Winforms-control should not subscribe to its own events

2008-11-12T08:01:00.001+01:00

Each Winforms-control defines many events that can be used to receive all kinds of notifications. Often I see that a control subscribes to its own events, for example:

        1: // this code is added by the designer in the InitializeComponent() method

       2: this.Load += new System.EventHandler(this.Form1_Load);

       3:  

       4: private void Form1_Load(object sender, EventArgs e)

       5: {

       6:     ...

       7: }

This will work OK, but events are conceptually not so simple. They are needed when you need a loose coupling between the publisher and the subscriber. This makes no sense if the publisher and the subscriber are the same control.

There is an alternative that is much simpler: for each event, there is also a virtual method that can be overridden:

       1: protected override void OnLoad(EventArgs e)

       2: {

       3:     base.OnLoad(e);

       4:  

       5:     ...

       6: }

This alternative will also have a slightly better performance. However, you should not forget to call the base-implementation (luckily, this call will be added automatically by IntelliSense). The base-implementation will raise the event, so if you omit this then the other parts of the code will not receive this event from your control.

Casting an array of value types

2008-11-05T10:32:00.001+01:00

Warning ahead: this article explains a dirty trick that should only be used in very specific circumstances (when memory conditions are low). I’ve personally seen this used when loading a large image from file (as a byte array) and needing to pass this array to a piece of legacy code that only accepts an array of shorts. Due to the size of the image, it was not feasible to copy the data.

Casting arrays of value types can be problematic. Image that you need to cast a large array of unsigned integers to an array of signed integers.

Our first experiment might be like this:

        1: static int[] Cast(uint[] input)

       2: {

       3:     int[] result = new int[input.Length];

       4:     

       5:     Array.Copy(input, result, input.Length);    // throws ArrayTypeMismatchException

       6:  

       7:     return result;

       8: }

This does not work. We get an ArrayTypeMismatchException because the two types are not compatible (the rules for compatible types are explained here).

The solution is to use the Marshal.Copy() method. This requires unsafe code however.
Here is an example:

       1: static unsafe int[] Cast(uint[] input)

       2: {

       3:     int[] result = new int[input.Length];

       4:  

       5:     fixed(uint* pInput = input)

       6:     {

       7:         Marshal.Copy(new IntPtr(pInput),result,0, input.Length);

       8:     }

       9:  

      10:     return result;

      11: }

This seems to work, but instead of casting the array we really made a copy of the array. The differences are subtle but can be important:

the copy requires its own memory. If the array is very large, this can be a problem. I’ve encountered situations (e.g. in image processing) where this was not acceptable.
when the copy is modified, the original array is left untouched. This is not what should happen when we cast a variable.

Using a dirty trick it is possible to cast an array of value types without copying the data. Look at this sample code:

       1: // WARNING: this is a dirty trick. Use at your own risk!

       2: static int[] Convert(uint[] input)

       3: {

       4:     Converter converter = new Converter();

       5:     converter.UInts = input;

       6:     return converter.Ints;

       7: }

       8:  

       9: [StructLayout(LayoutKind.Explicit)]

      10: struct Converter

      11: {

      12:     [FieldOffset(0)]

      13:     public int[] Ints;

      14:  

      15:     [FieldOffset(0)]

      16:     public uint[] UInts;

      17: }

We’re using a Converter-struct that uses some interop-magic to define two fields that map to the same location in memory. Now we can access the same data as an int[] or as an uint[]. The data is not copied in any way!

Note that this is a dirty trick: we fool the compiler into thinking that the type of the array is changed but it really is not. You can verify this by calling GetType() on the returned array: it will return System.UInt32[].

This trick can be used in other situations as well, for instance to access an array of integers as an array of bytes (without copying the data).

Warning: if the size of the array to be converted is reasonably small, you should just copy the data! Only use this trick if you really cannot afford to copy the data! This trick violates the type-safety of the runtime and is not guarantee to work in all situations or in future versions of .NET!

Removing items from a collection

2008-10-29T08:11:00.001+01:00

A common coding pattern is removing items from a collection based on the value of the items. The simplest way to do this is to enumerate the collection, and remove all the items that you don't want.

Code example:

        1: List<string> colors = new List<string>();

       2: colors.Add("red");

       3: colors.Add("green");

       4: colors.Add("blue");

       5:  

       6: foreach (string color in colors) // WARNING: this code will throw an exception

       7: {

       8:     if (color == "green") colors.Remove("green");

       9: }

However, doing this will throw this exception: System.InvalidOperationException: Collection was modified; enumeration operation may not execute. It seems that the enumerator is invalid after the collection has been modified.

There are several ways to work around this behavior.

1 Store the items to be removed in a temporary collection

This approach is really simple: instead of immedeately removing the items, we keep them in a separate collection. In the end, after the original list has been enumerated, we remove all these items.

Code example:

       1: List<string> colors = new List<string>();

       2: colors.Add("red");

       3: colors.Add("green");

       4: colors.Add("blue");

       5:  

       6: List<string> itemsToRemove = new List<string>();

       7: foreach (string color in colors)

       8: {

       9:     if (color == "green") itemsToRemove.Add("green");

      10: }

      11:  

      12: foreach (string itemToRemove in itemsToRemove) colors.Remove(itemToRemove);

In most situations this approach works very well. Only in very large collections, the itemsToRemove collection may become very big and consume a lot of memory. In my experience this is seldom the case.

2 Iterate the collection from back to front

This alternative uses a for-loop to iterate the collection from the back to the front.

Code example:

       1: List<string> colors = new List<string>();

       2: colors.Add("red");

       3: colors.Add("green");

       4: colors.Add("blue");

       5:  

       6: for (int counter = colors.Count - 1; counter >= 0; counter--)

       7: {

       8:     if (colors[counter] == "green") colors.RemoveAt(counter);

       9: }

Here we do not need a temporary collection. It is also slightly more efficient because we can remove the item based on its index. This means that the collection does not have to search for the item that has to be removed (as was the case in the first approach).

3 Using a predicate

The third alternative is only available from .NET 2 onwards. The List-collection implements a RemoveAll() method that takes a predicate as a parameter. Simply put, a predicate is a delegate that is used for filtering. In this case, the predicate returns true for each item that needs to be removed.

In this code example, the predicate is implemented as an anonymous method:

       1: List<string> colors = new List<string>();

       2: colors.Add("red");

       3: colors.Add("green");

       4: colors.Add("blue");

       5:  

       6: colors.RemoveAll(delegate(string color)

       7: {

       8:     return color == "green";

       9: });

This approach has some benefits:

It is self-documenting.
We don’t have to worry about the performance, we can assume that the RemoveAll() method is implemented in the most efficient way. If the internals of the collection-class would later change, the RemoveAll() method will likely be changed as well to keep the best performance.

A type-safe pattern to implement ICloneable and similar interfaces

2008-10-22T08:03:00.001+02:00

The ICloneable interface contains a single method Clone() that returns a clone of the object.

However the return value is defined as type ‘System.Object’, which means that the user still has to cast this to the actual type:

        1: Test t = new Test();

       2: Test t2 = t.Clone() as Test;    // cast needed

This is cumbersome and error-prone because the cast may fail at runtime.

Use the following pattern to provide a type-safe implementation of this interface:

       1: class Test : ICloneable

       2: {

       3:     int m_Amount;  // just some example data...

       4:     Font m_Font;

       5:     string m_Name;

       6:  

       7:     #region ICloneable Members

       8:  

       9:     // Provide a type-safe implementation

      10:     public Test Clone()

      11:     {

      12:         Test clone = new Test();

      13:         clone.m_Amount = m_Amount;

      14:         clone.m_Font = m_Font.Clone() as Font;

      15:         clone.m_Name = m_Name;

      16:         return clone;

      17:     }

      18:  

      19:     // Provide an "Explicit Interface Method Implementation"

      20:     object ICloneable.Clone()

      21:     {

      22:         return Clone();

      23:     }

      24:  

      25:     #endregion

      26: }

This example implements a type-safe Clone() method, so the user does not have to cast the result. But we still have to implement the interface-method that returns a System.Object. This is done through explicit interface method implementation.

This pattern is easier for the user of the class, and it has the benefit that the compiler will now guarantee that the returned object is always of the correct type.

Beware of the stopwatch

2008-10-15T08:31:00.001+02:00

In a comment on my last post, craniac argued that the StopWatch-class should be used for measuring time intervals.

Sadly, measuring a time interval is not as easy as it sounds. There are several mechanisms, I will explain 3 of them and point out their strengths and weaknesses.

1. DateTime.UtcNow

        1: DateTime begin = DateTime.UtcNow;

       2:  

       3: ...

       4:  

       5: DateTime end = DateTime.UtcNow;

       6: Console.WriteLine("Measured time: " + (end-begin).TotalMilliseconds + " ms.");

This is the fastest mechanism because under the hood it only reads a counter from memory (the code above takes only 76 nanoseconds to execute on my machine). However the resolution is not so great: only 10 milliseconds on recent version of Windows. If you want to measure a piece of code that takes shorter to execute, you will have to execute it e.g. 1000 times and measure how long this takes, then divide the result by 1000.

Another disadvantage is that this is not reliable if the system-time changes. This should be a very rare situation, but could for instance happen through synchronization with a time server.

2. Stopwatch

       1: Stopwatch watch = new Stopwatch();

       2: watch.Start();

       3:  

       4: ...

       5:  

       6: watch.Stop();

       7: Console.WriteLine("Measured time: " + watch.Elapsed.TotalMilliseconds + " ms.");

This mechanism is a bit slower than the previous one (10 times slower on my machine) so for short intervals this may have an impact on the result. However there are some serious issues:

This can be unreliable on a PC with multiple processors. Due to a bug in the BIOS, Start() and Stop() must be executed on the same processor to get a correct result.
This is unreliable on processors that do not have a constant clock speed (most processors can reduce the clock speed to conserve energy). This is explained in detail here.

I suspect that you can get a reliable result if you run it on a single-processor machine and disable any power-saving options in the BIOS. I haven’t tested this though.

On the upside, it has the hightest possible resolution (which depends on the hardware it runs on).

3. Process.TotalProcessorTime

       1: TimeSpan begin = Process.GetCurrentProcess().TotalProcessorTime;

       2:  

       3: ...

       4:  

       5: TimeSpan end = Process.GetCurrentProcess().TotalProcessorTime;

       6: Console.WriteLine("Measured time: " + (end - begin).TotalMilliseconds + " ms.");

This mechanism is different from the previous ones because it does not measure how much time has passed, but it measures how long your process has kept the CPU busy. This is great for performance measurements:

The timings are not distorted by other processes that consume a lot of CPU.
You can measure the impact that your code has on the overall performance of the system. On laptops, this also gives an indication towards the battery-power that is consumed by your process. This can be important for applications that run for a long time (such as services and other background tasks).

To interpret the measured time correctly, you should realize that time that is spent while your code is waiting (e.g. in a Sleep) will not be counted. On the other hand, if your process is keeping multiple processors busy, the time of each processor will be added (if a dual-core processor is kept 100% busy, the ‘TotalProcessorTime’ will increment with 2 each second!).

Note that this mechanism has the worst performance: the code above takes 19264 nanoseconds on my PC. This is 250 times slower than using DateTime.UtcNow!

So there is not one-size-fits-all solution to measure a time interval. Personally, if I want to measure how long a piece of code takes to execute, I run it in a loop (e.g. one million times) and measure it using DateTime.UtcNow.

Sometimes it is better to use DateTime.UtcNow instead of DateTime.Now

2008-10-08T09:03:00.001+02:00

When you want to measure how long a certain action takes, you should use DateTime.UtcNow instead of DateTime.Now:

        1: DateTime begin = DateTime.UtcNow;

       2:  

       3: ...

       4:  

       5: DateTime end = DateTime.UtcNow;

       6: MessageBox.Show("Time taken: " + (end-begin).TotalMilliseconds);

Reasons:

DateTime.UtcNow is more efficient than DateTime.Now (on my PC: 21 nanoseconds versus 575 nanoseconds).
More importantly: DateTime.Now will get you into trouble if Daylight Saving Time is enabled. For instance, it is possible that begin contains 02:59:00 and end contains 02:01:00 (while only two minutes have elapsed).

Of course, both mechanisms are incorrect if the user changes his clock (manually or through synchronziation with a time server).

Avoid invoking a virtual method in a constructor

2008-10-01T10:08:00.001+02:00

You should be very careful when invoking a virtual method in the constructor of a class that is not sealed.

Reason: when the virtual method is overriden in a derived class, this method will be invoked even before the constructor of the derived class has been invoked! This probably was not anticipated by the developer of the derived class!

Take for instance this example:

        1: abstract class Base

       2: {

       3:     public Base() // This constructor calls a virtual method

       4:     {

       5:         Initialize();

       6:     }

       7:  

       8:     protected abstract void Initialize();

       9: }

      10:  

      11: class Derived : Base

      12: {

      13:     FileStream m_File;

      14:  

      15:     public Derived()

      16:     {

      17:         m_File = new FileStream(@"c:\temp\test.txt", FileMode.Open);

      18:     }

      19:  

      20:     protected override void Initialize()

      21:     {

      22:         MessageBox.Show(m_File.Length.ToString());    // NullReferenceException! m_File has not been constructed yet!

      23:     }

      24: }

When an instance of Derived is created, first the constructor of the base class is called. This will result in Derived.Initialize() being called before the constructor of Derived has executed!

Because this is very contra-intuitive, it is best not to invoke virtual methods from a constructor altogether. Except when the class is sealed of course, because then there can be no derived class.

Prevent indentation by combining using-statements

2008-09-24T08:15:00.001+02:00

C# code tends to be heavily indented:

All code is indented at least three levels deep (namespace, class, method).
The usage of constructs such as using and try-finally adds further indentation.

Especially in GDI+ drawing code, the usage of using-statements can make the code much more difficult to read:

        1: protected override void OnPaint(PaintEventArgs e)

       2: {

       3:     base.OnPaint(e);

       4:  

       5:     using (Pen thickBlack = new Pen(Color.Black, 5f))

       6:     {

       7:         using (Pen thickRed = new Pen(Color.Red, 5f))

       8:         {

       9:             using (LinearGradientBrush backGround = new LinearGradientBrush(...)

      10:             {

      11:                 // start painting here...

      12:             }

      13:         }

      14:     }

      15: }

This can be simplified by combining the using-statements like this:

       1: protected override void OnPaint(PaintEventArgs e)

       2: {

       3:     base.OnPaint(e);

       4:  

       5:     using (Pen thickBlack = new Pen(Color.Black, 5f))

       6:     using (Pen thickRed = new Pen(Color.Red, 5f))

       7:     using (LinearGradientBrush backGround = new LinearGradientBrush(...)

       8:     {

       9:         // start painting here...

      10:     }

      11: }

As you can see this reduces indentation, making the code easier to read and understand.

Prevent unnecessary indentation

2008-09-17T08:44:00.001+02:00

Code that is heavily indented is difficult to read (especially if the method does not fit on a single screen anymore).

Instead of this code …

        1: void Test(string input)

       2: {

       3:   if (input != null)

       4:   {

       5:     if (input.Length > 0)

       6:     {

       7:       …

       8:     }

       9:   }

      10: }

… write this code:

       1: void Test(string input)

       2: {

       3:   if (input == null) return;

       4:   if (input.Length == 0) return;

       5:  

       6:   …

       7: }

How to use consistent version numbering across multiple projects

2008-09-05T15:47:00.001+02:00

If you have many C# projects, you may want all your assemblies to have the same version numbers. Remember that the version numbers are defined in the ‘AssemblyInfo.cs’ file in each project.

There are several mechanisms to achieve this:

Programmatically change all the ‘AssemblyInfo.cs’-files to update the version number.
You could write a tool that updates the version number of all your projects. This tool could then be integrated in your build process. This is cumbersome and often not so simple if your projects are checked in a source control system.
Define the version-numbers in a single file that is used by all your projects. This technique is explained in this article.
Define the version-numbers in a separate assembly that is referenced by all projects.

In this post I will elaborate on the third mechanism (because I’ve never seen this explained anywhere else).

Create a new C# project (called Metadata.csproj) that contains all the metadata that is shared across your projects. This project is very simple and contains only 1 class:

        1: namespace KristofVerbiest

       2: {

       3:     public static class ProjectMetadata

       4:     {

       5:         public const string FileVersion = "1.5.0.1";

       6:         public const string CompanyName = "Kristof Verbiest";

       7:         public const string Copyright = "Copyright © Kristof Verbiest 2008";

       8:     }

       9: }

Now you can reference this assembly from all your other C# projects, and you can use the data from the ‘AssemblyInfo.cs’ files like this:

       1: [assembly: AssemblyFileVersion(ProjectMetadata.FileVersion)]

       2: [assembly: AssemblyCompany(ProjectMetadata.CompanyName)]

       3: [assembly: AssemblyCopyright(ProjectMetadata.CopyRight)]

Note that the ‘Metadata.dll’ assembly is used by the compiler to fill in the correct metadata. However this assembly is not needed at runtime! So you don’t need to deploy this assembly to your users, it is only needed by the compiler.

Assume that someone who is less experienced than you needs to understand your code

2008-09-03T11:29:00.001+02:00

Transparency is an important aspect in a project where many developers are working on the same software.

Some developers like to show of how smart they are using complex constructs that are difficult to understand. This is unnecessary and not fair towards their colleagues.

Some examples:

Unnecessary usage of the ?: operator and the null coalescing operator. These operators are not commonly known and should only be used if they improve the readability of the code.
Complex expressions whose output depends on the operator precedence rules.
Usage of anonymous methods.
Usage of regular expressions. Regular expressions can be very powerful, but they have the nasty habbit that they tend to be easier to write than to read.
Consider rewriting your logic using simple string actions. If you really need to use regular expressions, you should document them very well.

If you encounter a situation where one of these techniques really makes sense then of course you should use it. But you should also add some documentation why you are doing it (and maybe include a link to a website that explains the technique).

Good code is self-documenting

2008-08-27T09:33:00.001+02:00

Picking a good name for a class/method is often very difficult. But if the names are chosen carefully the code often needs no further documentation.

For instance compare these two simple examples (they are functionally equivalent):

        1: /// <summary>

       2: /// Summary for Bounds class

       3: /// </summary>

       4: public class Bounds

       5: {

       6:   public int m_A;    // lower bound

       7:   public int m_B;    // upper bound

       8:  

       9:   /// <summary>

      10:   /// Creates a new Class1 instance

      11:   /// </summary>

      12:   /// <param name="a">the lower bound</param>

      13:   /// <param name="b">the upper bound</param>

      14:   public Bounds(int a, int b)

      15:   {

      16:     // m_A should be the smallest value

      17:     m_A = Math.Min(a, b);

      18:     // m_B should be the biggest value

      19:     m_B = Math.Max(a, b);

      20:   }

      21:   …

      22: }

       1: public class Bounds

       2: {

       3:   public int m_LowerBound;

       4:   public int m_UpperBound;

       5:  

       6:   /// <remarks>It is OK to provide a & b in the wrong order.</remarks>

       7:   public Bounds(int a, int b)

       8:   {

       9:     // The rest of this class assumes that m_Lowerbound <= m_Upperbound,

      10:     // so we fix it here

      11:     m_LowerBound = Math.Min(lowerBound, upperBound);

      12:     m_UpperBound = Math.Max(lowerBound, upperBound);

      13:   }

      14:   …

      15: }

Although the second example has less comments, I feel that it is better documented because it is self-describing:

The default class-comment that is inserted by Visual Studio is useless. The name of the class is already sufficient documentation.
The second example has good names for the fields; further comments are not necessary.
The first example has comments about stuff that is very obvious (every developer should already know what a constructor does).
The first example explains the sorting of the parameters but every developer can see what is going on. The second example instead explains why the parameters need to be sorted.

If your code is written cleanly then you don’t have to document what it is doing. But you may have to document why it is doing it.

Don’t use a dedicated thread to wait on a kernel object

2008-08-20T09:51:00.001+02:00

One of the code patterns in the previous post showed that you don’t need a dedicated thread to execute a piece of code at regular intervals.

Likewise you don’t need a dedicated thread to wait on a kernel object (such as a mutex or an event). You can use the threadpool to do this:

        1: class Test

       2: {

       3:   // This method returns an event. Whenever the event will be set (by the caller of this 

       4:   // method), the 'EventWasSet' method will be executed.

       5:   public WaitHandle GetEvent()

       6:   {

       7:     AutoResetEvent m_Event = new AutoResetEvent(false);

       8:     ThreadPool.RegisterWaitForSingleObject(m_Event, EventWasSet, null, Timeout.Infinite,false);

       9:     return m_Event;

      10:   }

      11:  

      12:   void EventWasSet(object state, bool timeOut)

      13:   {

      14:     // This code will be executed on the threadpool when the event is set

      15:   }

      16: }

The RegisterWaitForSingleObject() method makes sure that the given method will be executed on a threadpool thread when the kernel object is signaled.

Timers: executing a task at regular intervals

2008-08-13T09:22:00.001+02:00

When you want to execute a piece of code at regular intervals, you should not start a dedicated thread to do this. Instead you should use a timer.

If the task you want to perform involves GUI interaction, it is best to use the Windows.Forms.Timer class. An example:

        1: class Test

       2: {

       3:   System.Windows.Forms.Timer m_Timer = new System.Windows.Forms.Timer();

       4:  

       5:   public void StartTimer()

       6:   {

       7:     m_Timer.Interval = 1000;    // tick every 1000 ms

       8:     m_Timer.Tick += Timer_Tick;

       9:     m_Timer.Start();

      10:   }

      11:  

      12:   void Timer_Tick(object sender, EventArgs e)

      13:   {

      14:     // This code will execute every second on the GUI thread

      15:   }

      16: }

If the code does not involve GUI interaction, it is best to use a threadpool-timer. However you need to be careful: if your code takes longer to execute than the interval of the timer, you will cause threadpool starvation! This occurs if the maximum amount of threadpool-threads is reached. This will cause serious problems for the complete process because all code that uses the threadpool (including .NET Remoting) will be blocked.

As a workaround you can set the timer to execute only once, and reset it every time it has executed:

       1: class Test

       2: {

       3:   System.Threading.Timer m_Timer;

       4:  

       5:   public void StartTimer()

       6:   {

       7:     // set timer to be executed only once

       8:     m_Timer = new System.Threading.Timer(Timer_Tick,null,1000,0);

       9:   }

      10:  

      11:   void Timer_Tick(object state)

      12:   {

      13:     try

      14:     {

      15:       // This code will execute every second on a threadpool thread

      16:     }

      17:     finally

      18:     {

      19:       // reset the timer

      20:       m_Timer.Change(1000, 0);

      21:     }

      22:   }

      23: }

So there is no need to start a dedicated thread just to perform a piece of code at regular intervals.

Event subscriptions may lead to memory leaks

2008-08-05T16:35:00.001+02:00

Even though the .NET runtime has a garbage collector that cleans up unused objects and frees the memory, it is still possible to write code that contains a memory leak. Often this is very subtle and the memory leak is not apparent at first sight.

One of these subtle memory-leaks may occur if your code subscribes to an event, but never unsubscribes. Whenever a subscriber subscribes to an event that is published by the publisher, the publisher will hold a reference to the subscriber.

I tried to visualize this in this diagram:

The publisher will hold this reference as long as the event is not unsubscribed. So as long as the publiser is alive, the garbage collector will not collect the subscriber-objects. This leads to a memory leak (or sometimes worse, if the subscriber holds other resources such as files or threads).

Typically this occurs when the publisher is a static object (which lives as long as the process lives).

So whenever you subscribe to an event, think whether it is necessary to unsubscribe from this event (especially if the publisher has a long lifetime).

Of course the same thing occurs in every situation where a static (or long-lived) object has a reference to other (short-lived) objects. Always consider when this reference should be removed again!

Don’t start a dedicated thread to perform a simple task

2008-08-05T16:06:00.001+02:00

When you want to perform a piece of code asynchronously it is tempting to start a dedicated thread to execute this code. However, starting a new thread has a big performance overhead. For simple tasks this overhead cannot be justified (the CPU-time needed to start the thread might be much bigger than the actual processing that will occur in the thread). Microsoft recognizes this and provides the Threadpool which is much better for executing tasks asynchronously.

I decided to write a small benchmark to find out just how bad it is to start a dedicated thread for a simple task. The code of the task is very simple: increment a counter and check the value of this counter. This task has to be executed 1,000,000 times. Of course this is not actual code that you would write; it is just the simplest task that I could think of to execute asynchronously.
Because the counter will be accessed from multiple threads it needs to be protected by a lock. In this particular code it is possible to avoid the lock using the System.Threading.Interlocked class. I have decided not to do this because the use of a normal lock makes the benchmark much more relevant towards real-world scenarios.

Here is the version of the code that uses a dedicated thread for each task (error-handling code and the code that was used to measure the performance has been removed for clarity):

        1: class Program 

       2: { 

       3:         const int c_Loops = 1000000; 

       4:         static uint s_Counter;        // the counter that will be incremented by every task 

       5:         static object s_Lock = new object();        // needed because the counter is accessed from multiple threads 

       6:         static AutoResetEvent s_TestFinished = new AutoResetEvent(false);        // signals when the test is finished 

       7:  

       8:         static void Main(string[] args) 

       9:         { 

      10:                 for (int counter = 0; counter < c_Loops; counter++) 

      11:                 { 

      12:                         Thread t = new Thread(new ThreadStart(SmallTask)); 

      13:                         t.Start(); 

      14:                 } 

      15:                 s_TestFinished.WaitOne();        // we wait until the last task has finished 

      16:         } 

      17:  

      18:         static void SmallTask() 

      19:         { 

      20:                 // This method executes on a dedicated thread 

      21:                 lock (s_Lock) 

      22:                 { 

      23:                         s_Counter++; 

      24:                         if (s_Counter == c_Loops) s_TestFinished.Set();        // notify the main thread that the test is finished 

      25:                 } 

      26:         } 

      27: }

These are the performance measurements (taken on a dual-core processor):

Total time to execute all the tasks: 18312 ms
% time in user-mode: 47%

As you can see it takes quite some time to execute all the tasks. Only about half of this time is spent in user mode, the rest is spent in kernel mode.

Now let's rewrite this code using the threadpool. Only minimal changes are needed (they are shown in red):

       1: class Program 

       2: { 

       3:         const int c_Loops = 100000; 

       4:         static uint s_Counter;        // the counter that will be incremented by every task 

       5:         static object s_Lock = new object();        // needed because the counter is accessed from multiple threads 

       6:         static AutoResetEvent s_TestFinished = new AutoResetEvent(false);        // signals when the test is finished 

       7:  

       8:         static void Main(string[] args) 

       9:         { 

      10:                 for (int counter = 0; counter < c_Loops; counter++) 

      11:                 { 

      12:                         ThreadPool.QueueUserWorkItem(new WaitCallback(SmallTask));

      13:                 } 

      14:                 s_TestFinished.WaitOne();        // we wait until the last task has finished 

      15:         } 

      16:  

      17:         static void SmallTask(object state) 

      18:         { 

      19:                 // This method executes on a threadpool thread 

      20:                 lock (s_Lock) 

      21:                 { 

      22:                         s_Counter++; 

      23:                         if (s_Counter == c_Loops) s_TestFinished.Set(); 

      24:                 } 

      25:         } 

      26: }

These are the performance measurements:

Total time to execute all the tasks: 218 ms.
% time in user-mode: 98%

So we see that by using the Treadpool we have increased the performance 82 times! Also, almost all time is spent in user-mode.

Conclusion: when executing simple tasks asynchronously, starting a dedicated thread for each task has a very big performance impact.

An even better pattern to raise events

2008-08-05T15:44:00.001+02:00

In a previous post, I explained a subtle bug in the way that events are raised in most code. This suble bug might cause a race condition that results in unexpected behavior when the code is executed in multiple threads.

You can read the details here.

From .NET 2 onwards, there is an even simple pattern to solve this problem:

        1: class Publisher

       2: {

       3:   public event EventHandler SomethingHappened = delegate { }; // cannot be null, important for thread safety

       4:  

       5:   void Test()

       6:   {

       7:     SomethingHappened(this, new EventArgs());

       8:   }

       9: }

The trick is that the event is initialized to an empty delegate (this was not possible before .NET 2.0). When invoked, this empty delegate does nothing. However it guarantees that the event will never become null, so the race condition cannot occur.

So using this pattern it is always safe to raise the event and it is even not necessary anymore to check if the event is null.

Avoid Invoke(), prefer BeginInvoke()

2007-02-27T14:50:00.001+01:00

This is another post in a series that deals with asynchronous behaviour (see also here and here).

The difference between Control.Invoke() and Control.BeginInvoke() is:

BeginInvoke() will schedule the asynchronous action on the GUI thread. When the asynchronous action is scheduled, your code continues. Some time later (you don't know exactly when) your asynchronous action will be executed.
Invoke() will execute your asynchronous action (on the GUI thread) and wait until your action has completed.

A logical conclusion is that a delegate you pass to Invoke() can have out-parameters or a return-value, while a delegate you pass to BeginInvoke cannot (you have to use EndInvoke to retrieve the results).

My advice is: always use BeginInvoke() if you can. Reasons:

Because Invoke() causes one thread to wait for another thread, it is likely to cause deadlocks. Imagine that your application has a dedicated worker thread that uses Invoke() to execute some work on the GUI thread. Now image that during this work, your GUI code needs to execute something on the worker-thread. It will be blocked forever because your worker-thread is already busy waiting for your GUI-thread.
In this simple example it might be easy to spot the problem. In a big application developed by many people it will not always be this easy. Therefore it is better to find a pattern that avoids blocking altogether.

Note that in this example you might think that a threadpool solves your problem, because then you have multiple workerthreads. However the problem will still occur under high load, this is called threadpool starvation and it is a very complex problem. Because it only occurs under high load, it is a very dangerous thing that is very difficult to debug.
Invoke() will cause forced threadswitches that will decrease the scalability of your application.

First consider BeginInvoke: when it is called, a delegate is scheduled to be executed on the other thread. However your current thread will continue until the operating system decides that it's done enough work. Only then will the other thread (GUI thread) be executed, and your delegate will be run. If other delegates were also scheduled using BeginInvoke(), they will be executed as well.

Now consider Invoke: when you call it, the OS immedeately has to stop your current thread and schedule the other thread.
When more than one Invoke()-statement is done, a threadswitch will be needed every single time (whereas multiple BeginInvoke-requests can be bundled in one threadswitch).
Excessive threadswitches will seriously hurt performance when your application is under a high load.

Conclusion: avoid using Invoke().

Don't confuse Control.BeginInvoke() with Delegate.BeginInvoke()

2007-02-15T13:25:00.001+01:00

In my last article I used the BeginInvoke() method to execute a delegate on the GUI thread.

Here is the definition of the delegate (this is just an example):

delegate void Invoker(string parameter);

And here you see where the delegate is used:

// Execute on the GUI thread
this.BeginInvoke(new Invoker(SetTitleSafe), title);

Some people may confuse this with the BeginInvoke-method on a delegate, like this:

Invoker i = new Invoker(SetTitleSafe);
// Execute on a threadpool thread
i.BeginInvoke();

Note however that these are two completely different concepts!

Control.BeginInvoke is used to execute code on the GUI thread, while Delegate.BeginInvoke is used to execute code on a threadpool thread. For more information, click here.

One important difference is that when you invoked Control.BeginInvoke you are not obliged to call Control.EndInvoke. However, when you call Delegate.BeginInvoke you should also call Delegate.EndInvoke, otherwise you will have a memory leak!

This obligation to call EndInvoke may likely complicate your code. Mike Woodring has written a nice helper-class that will help you with this. Or you can also use Threadpool.QueueUserWorkItem (this is also used in the back by Delegate.BeginInvoke).

Simple pattern to invoke GUI from another thread

2007-02-13T14:56:00.001+01:00

If you are making a GUI application and you are using multiple threads, there is one very important rule: GUI controls can only be accessed from the GUI thread. This is inherent to Windows development and is not a limitation of .NET.

Let me first say that although this seems to be an annoyance for the developer, this is actually a great thing! It means that while you are developing a GUI application you generally don't have to worry about threading issues (locks, deadlocks) because you know that all GUI-access is done from a single thread.

But of course there are situations where you want to start background processing on a seperate thread and access the GUI from this thread. Take for instance this simple example:

public void SetTitleUnsafe(string title)
{
    // When invoked from another thread, this next statement is illegal:
    this.Text = title;
}

If you call this method from a thread that is not a GUI thread, everything may seem to go well at first sight. But because we violated the very important rule, the behaviour of our application is now undefined. Things may (and will) start to go wrong very unpredictably, sometimes much later when there is no obvious relationship with the violation that was made. This makes this problem very hard to find. Among the things that could happen is GUI-events to become 'lost' and the GUI to become unresponsive.

Luckily, form Visual Studio 2005 onward you get a nice error-message when you violate this rule while the debugger is attached:

So now you at least get an immedeate notification that you made a mistake. This one of the reasons why I advise to run your code from Visual Studio (using F5) while you are developing.

To get around our threading-violation, Winforms provides these helper-methods: BeginInvoke, EndInvoke, Invoke, InvokeRequired. But even with these methods available it may not be obvious how to use them in a correct and simple way.

That's why I present this pattern:

delegate void Invoker(string parameter);

public void SetTitleSafe(string title)
{
    if (this.InvokeRequired)
    {
        // Execute the same method, but this time on the GUI thread
        this.BeginInvoke(new Invoker(SetTitleSafe), title);

        // we return immedeately
        return;
    }

    // From here on it is safe to access methods and properties on the GUI
    // For example:
    this.Text = title;
}

As you can see, you will need to define a delegate that matches your method (or use an existing delegate that is defined elsewhere, such as the System.Windows.Forms.MethodInvoker). This is how the pattern works:

When the method is called from a thread that is not the GUI thread, InvokeRequired will be true. The method will be wrapped in a delegate and passed to the BeginInvoke method (together with the parameters). We return immedeately. BeginInvoke guarantees that some time later our method will be called on the GUI thread.
When the method is called on the GUI thread, InvokeRequired returns false so we just go forward and access the GUI in any way we like.

This is in my opinion the simplest and shortest pattern that is always correct.

From .NET 2.0 onwards the same pattern can be written using an anonymous method but that is less readable in my opinion, so I prefer to keep this pattern.

Also in .NET 2.0 you can use the BackgroundWorker class that handles all the details behind your back. But the same principle still applies: never access GUI from another thread!

Rethrow an exception using throw;

2007-02-02T17:15:00.000+01:00

It is not uncommon that you want to rethrow an exception in a catch-block. This happens if you need to cleanup some state in the catch-handler, but you still want to inform the application that something has gone wrong.

You often see this implemented as such:

static void SomeMethod()
{
    try
    {
        MethodThatCanThrowAnException();
    }
    catch (Exception ex)
    {
        // Do stuff (cleanup)
        throw ex; // WRONG - DO NOT USE THIS!
    }
}

There is a subtle problem with this: rethrowing the existing exception-object will reset its stacktrace. Whoever catches this exception and examines the stacktrace will think that it was caused by your code.

It is better to do this:

static void SomeMethod()
{
    try
    {
        MethodThatCanThrowAnException();
    }
    catch (Exception ex)
    {
        // Do stuff (cleanup)
        throw; // does not reset the stacktrace
    }
}

Now whoever catches this exception will see the complete stacktrace and can see the originator who caused the exception. This might save a lot of time for whoever has to debug the problem.

Another valid possibility is to throw a new exception, but set its InnerException propery to the original exception like this:

catch (NullReferenceException ex)
{
// Do stuff (cleanup)
throw new ObjectNotInitializedException(ex);
}
Whoever catches this exception can view a separate stacktrace for your exception and the InnerException. I would use this second pattern if the new exception that you throw contains more information about the cause of the problem than the inner-exception. For instance if the inner-exception is a NullReferenceException, your exception can give more context (e.g. the object is not yet initialized).

Kristof