.NET Collections and Generics in C#

This post is based on Chapter 10 of Andrew Troelsen’s “Pro C# 2008 and the .Net Platform” available from Apress.

Right – yet another wondrous adventure with Mr. Troelsen awaits us, this time he will explain just what collections and generics can do for us. As always, this is a brief outline, if you really want to know, and be a better developer – we highly recommend getting hold of Mr. Troelsen’s book! It is quite simply very good, bordering on superb.


So collections are tools for containing objects. An array is the most simple container, but as you will know this has some serious limitations for adding, removing and resizing. So, to the rescue comes the Systems.Collections namespace. Troelsen gives us an outline of the interfaces in here:

System.Collections Interface Meaning in Life
ICollection Defines general characteristics (e.g., size, enumeration, thread safety) for all nongeneric collection types.
IComparer Allows two objects to be compared.
IDictionary Allows a nongeneric collection object to represent its contents using name/value pairs.
IDictionaryEnumerator Enumerates the contents of a type supporting IDictionary.
IEnumerable Returns the IEnumerator interface for a given object.
IEnumerator Enables foreach style iteration of subtypes.
IHashCodeProvider Returns the hash code for the implementing type using a customized hash algorithm.
IList Provides behavior to add, remove, and index items in a list of objects. Also, this interface defines members to determine whether the implementing collection type is read-only and/or a fixed-size container.

Also, we should know that these are organised as follows:


So, what we can see is that the ICollection is the most basic interface, and also we have a lot of enumeration going on (see our previous post on this).
Let’s look at all this in some more detail:

ICollection is described in the table above. The IDictionary uses name/value pairs of object type to organise objects, so you could for example store objects of any type (the value) and retrieve these by an ID or string Key – or indeed another object. The IDictionaryIterator simply returns a strongly typed iterator with a Entry property of type DictionaryEntry for each value that is retrieved (so you get stuff like Key/Value – both of type object.
The IList gives you add/remove and index functionality.

So what classes implement these indexes? Troelsen gives us this table:

System.Collections Class Meaning in Life Key Implemented Interfaces
ArrayList Represents a dynamically sized array of objects. IListICollectionIEnumerable, and ICloneable
Hashtable Represents a collection of objects identified by a numerical key. Custom types stored in a Hashtable should always override System. Object.GetHashCode(). IDictionaryICollectionIEnumerable, andICloneable
Queue Represents a standard first-in, first-out (FIFO) queue. ICollectionICloneable, and IEnumerable
SortedList Like a dictionary; however, the elements can also be accessed by ordinal position (e.g., index). IDictionaryICollectionIEnumerable, andICloneable
Stack A last-in, first-out (LIFO) queue providing push and pop (and peek) functionality. ICollectionICloneable, and IEnumerable

So Troelsen wisely recommends that we focus on the interfaces that are implemented here to gain an understanding of what each class brings to the table. Also, he quickly outlines three core classes, ArrayList, Queue and Stack – and leaves the rest to the 3.5 documentation.

You might have noticed that ArrayList is the only in the above table that implements IList. So we’ve kind of already covered this.

The Queue type is a bit more interesting, this basically works on a first-in-first-out basis, much like shopping in your local corner store. So you got Enqueue() and  Dequeue() methods, both handling objects. You can call Peek() to access the next object without popping this off the queue. Note though that you cannot use this to null check – use Count > 0 in stead.

And finally the Stack class is of course a last-in-first-out container, much like the company you work in. If you’re still working that is of course, if not, you probably did not enjoy that attempt at humour.  So this works much like the Queue class, except we now have Push() and Pop() methods. Count and Peek() still works the same way.

Finally note that we have a load of additional collections in the System.Collections.Specialized namespace. A quick overview from Mr. Troelsens most excellent book:

Member of System.Collections.Specialized Meaning in Life
BitVector32 A simple structure that stores Boolean values and small integers in 32 bits of memory.
CollectionsUtil Creates collections that ignore the case in strings.
HybridDictionary Implements IDictionary by using a ListDictionary while the collection is small, and then switching to a Hashtable when the collection gets large.
ListDictionary Implements IDictionary using a singly linked list. Recommended for collections that typically contain ten items or fewer.
NameValueCollection Represents a sorted collection of associated String keys and String values that can be accessed either with the key or with the index.
StringCollection Represents a collection of strings.
StringDictionary Implements a hashtable with the key strongly typed to be a string rather than an object.
StringEnumerator Supports a simple iteration over a StringCollection.

The Trouble With Boxing and Typed Collections

So, next up we’ll be moving onto Generics, but to understand the point of all this, first we must understand the problem of not using generics – that is, the problem of using the System.Object base class to treat all object in a consistent way (because although it sounds good, it’s really not).

So, what is boxing? Well, boxing is a process that allows you to convert a value type to a reference type, on-the-fly so to speak. And this happens a lot more than you think.
Unboxing is of course the opposite, so we have a reference type and we convert it back into a value type, an example I think:

			//A value type
			int x = 24;
			//Box it into an object (reference type)
			object objX = x;
			//Unbox it back into a value type
			int anotherX = (int)objX;

So, why does this happen more often than I think? – you might well ask. Well, working with collections of objects is the answer, another example we think again:

			ArrayList myListOfObjects = new ArrayList();
			//The Arraylist Add() method expects an object, so here we're boxing each one of these ints:
			//Now we want them back as ints:
			for (int i = 0; i < myListOfObjects.Count; i++)
				 //...so we have to unbox each one:

As you see, this process relies heavily on boxing and unboxing, and why is that a problem? Well two things:

Firstly we obviously have a type safety issue, we are casting objects back into a set type, and any exceptions from this are not known until runtime. In the above simple example this is not a problem, but in complex systems dealing with many different value types, this is a very real concern.

Secondly there is a serious performance issue – the steps involved in boxing and unboxing are:

  1. Allocate a new object on the heap.
  2. Copy the value of the stack based value type into this object.
  3. When unboxing we have to copy the value of the heap object back into a new stack variable.
  4. Finally we end up with a load of objects lying around in the heap waiting for the garbage collector.

Again the above example would never cause any issues, but imagine you have a list with several thousand objects and you start to see the problem.

So what’s the solution? Well for a long time Typed Collections was the best solutions around. I won’t go into much detail on these (because they are not the answer my friends!) Basically you create a custom collection type for each specific type that you need to deal with. So for instance you might have a OrderCollection and a ProductCollection. The basic idea is that you wrap an ArrayList with strongly typed access methods. However, this only solves the type safety issue – but at the same time it also saddles us with a very labour intensive process and a likely maintenance nightmare. Furthermore, as these are nothing but wrappers around more general collection types, we still encounter the same boxing/unboxing issues.
So not much of a solution at all. Who will save me you ask? Generics will save you, that’s who.

Generics to The Rescue

Yes, indeed we are in need of rescuing, so let’s send in the proverbial cavalry.

So in a nutshell generic collections (System.Collections.Generic) allows you to create typed collections on-the-fly (i.e. specify the type at the point of creation) and at also removes the need for boxing and unboxing value types.

How so? Well magic really – or not. Basically we have a List<T> (T is used by convention, for type) which defines a load of operations that are common for typed collections, and collections generally. In our code we supply something like List<Orders> = new List<Orders>(); – and the compiler then replaces the T with Orders and viola! We have a typed collection – which we can create and use in a generic way.
What great fun.

So, other stuff we can do is to create our own generic methods – but you probably won’t really need to so we’ll skip over that bit. Also note that if you have a generic method that takes parameters, you can optionally leave out the type in the <> and rely on the compiler to do some type inference – which you could probably have some fun with using polymorphism.

Further more you can also create generic classes, again I’ll skip over that a bit lightly as it’s really quite specialised. However note that the default keyword is overloaded and when used in generics this can be used to set a generic parameter to it’s default value. So for instance an int would be zero etc etc.

Finally following along with this line of possibilities, you can of course also create a Custom Generic Collection – and once again you are quite unlikely to do this and it almost defies the whole point of generics. Like normal typed collections this is nothing but a wrapper around a generic List<T> collection.
One advantage to be gained is that you would be able to add your own specialised add/insert/remove methods – so thinking about it this might not be completely away with the fairies, but nevertheless I will leave the details out of this.

One interesting aspect of custom generic classes is the use of the where keyword, like this:

		// MyGenericClass derives from Object, while
		// contained items must be a class implementing IDrawable
		// and support a default ctor.
		public class MyGenericClass<T> where T : class, IDrawable, new()

This is obviously interesting from a polymorphic point of view, and you can now do all kinds of operations on this generic collection. The options for the where keyword are:

Generic Constraint Meaning in Life
where T : struct The type parameter <T> must have System.ValueType in its chain of inheritance.
where T : class The type parameter <T> must not have System.ValueType in its chain of inheritance (e.g., <T> must be a reference type).
where T : new() The type parameter <T> must have a default constructor. This is very helpful if your generic type must create an instance of the type parameter, as you cannot assume the format of custom constructors. Note that this constraint must be listed last on a multiconstrained type.
where T :NameOfBaseClass The type parameter <T> must be derived from the class specified by NameOfBaseClass.
where T :NameOfInterface The type parameter <T> must implement the interface specified by NameOfInterface. Multiple interfaces can be separated as a comma-delimited list.

A very useful feature.

Generic Inheritance

Finally – finally, note that you can also inherit from generic classes and collections (you may define virtual and abstract methods as well), and also that you can indeed create generic interfaces and implement these.

Some well known .NET interfaces (IEnumerable, IClonable and IComparable)

This post is based on chapter 9 of Andrew Troelsen’s “Pro C# 2008 and the .Net Platform” available from Apress.

Any type that implements IEnumerable can be used by the foreach statement.
You have two choices if you want to implement IEnumerable – either maintain a member of type ArrayList (or similar) that already implements IEnumerable, and expose this, or you can roll your own.

To roll your own, you need a method called GetEnumerator() which returns an object of the IEnumerator type – so just to be clear: the IEnumerable interface stipulates that you must return an object of type IEnumerator, from a method called GetEnumerator().
You can start handcrafting this, but really what you do is use the “yield return” keyword. So for instance you might have an array (which does not support IEnumerable) – and you can simply place a for loop inside the GetEnumerator() and yield each object out.
What yield does is it stores the current locaton, and restarts execution from this point next time the method is called – which is exactly what an iterator is.

IClonable objects are able to return an identical copy of themselves via the Clone() method. Note that best practise is to return a deep copy of the object (i.e. a new object with the exact same state) as opposed to a shallow copy (a copy of the reference, pointing to the same object on the heap).
Note that the object type has a method MemberwiseClone that can be used for this eaxact purpose – note that if yuu have a type containing only value types you can use this for a deep copy – however if your type has any reference types, you must create a new object to obtain a proper deep copied clone.

IComparable objects are indeed comparable. Wonders never cease. This is most often used in things like Array.Sort(array) calls. To implement this, you need to supply a CompareTo(object obj) method, which should return an int.
Less than zero indicates your object is before the object passed in,  Zero means it’s equal and larger than zero it’s after.
So you can do what you like here, compare strings, Ids, dates – whatever makes sense for your object, just return a signed integer value. However do note that all the types I just mentioned (strings, ints and dates) all implement IComparable so make sure you simply pass the call through where possible (i.e. don’t start writing convuluted if/else staments to compare to ints).

Note that you can build custom comparers (say if you wanted more than one way to compare a given object) by creating a class that implements the IComparer interface. You must then supply a method that has a Compare(obj a, obj b) method. So you could perhaps have two of these for say a Product class – on to compare SKU and one to compare the name.
A neat (and recommended) way of doing this, is to create these IComparer implementations, and then expose them through the Product class. So you get something like this:

		public class Product
			//Use C# 2008 auto-implemented properties:
			public int SKU { get; set; }
			public string Name { get; set; }

			public static IComparer SortBySKU
				get { return (IComparer)new ProductSKUComparer(); }

			public static IComparer SortByName
				get { return (IComparer)new ProductNameComparer(); }

		public class ProductSKUComparer : IComparer
			public int Compare(object x, object y)
				return ((Product)x).SKU.CompareTo(((Product)y).SKU);

		public class ProductNameComparer : IComparer
			public int Compare(object x, object y)
				return ((Product)x).Name.CompareTo(((Product)y).Name);

		public class TestIt
			public TestIt()
				Product[] products = { new Product(), new Product(), new Product() };
				//Assume we have names and SKU on these products:
				Array.Sort(products, Product.SortBySKU);
				Array.Sort(products, Product.SortByName);

OOP: C# Interface Details

This post is based on chapter 9 of Andrew Troelsen’s “Pro C# 2008 and the .Net Platform” available from Apress.

So we covered the basics of these in the previous post, let’s look at some more details about these.

In the example in the previous post note that the interface is public – this of course makes a lot of sense, but what about the method signatures – these have no access modifiers and no implementation… the reason is of course that interface members are implicitly public and abstract – however it is a syntax error to actually apply either of these to the members.

So when implementing, as in previous example, you use the : operator. If you are inheriting from another class this must be listed first, and then you can list as many comma seperated interfaces as you like. Note that you should always name your interfaces with a leading capital I – no requirement, but your fellow OO coders will spank you into infinity if you do not. And don’t think you can get free spanking like this – they will notice if you like it and think of something else, like putting tuna in your keyboard. Dophin friendly of course.

So, one of the happy things about interfaces is of course that they (like abstract classes) can be used polymorphically. If/when you do this, always cast with the as operator and then null check the result – more here:  http://msdn.microsoft.com/en-us/library/cscsdfbt.aspx or you can use the is operator and then perform your cast if true: http://msdn.microsoft.com/en-us/library/scekt9xw.aspx.
Which is best? Well I personally like the as – as this not only checks but does half the job for you – I’ve not been able to dig out anything on performance, but at a guess the as operator covers over a try/catch like structure, where as the is would probably use seome lightweight reflection – so use as.

Following on from the above, also consider using interface types as methods parameters, this will allow you to write clean generic code that focuses on general (extendable) behaviours rather than specific implementations. So forexample we could pass any FridayNightReveller into a method accepting an IEnjoyADrink interface type – and work with this without concerning ourselves with the specific implementation – and what’s more important, we can easily extend the list of behaviours (i.e. the group of classes implementing the behavious defined by the interface) without changing any other code (Strategy Pattern).

Within VS2008 you also have some advanced options when working with interfaces. First of the refactoring meny allows you to extract and interface from a block of selected code – so you might have one behaviour and need another similar.
Also you can use the automatic options after typing the : operator followed by an interface name to automaticall implement an interface (you get a stub).

In some rare circumstances you might have a class implementing >1 interface and end up with a name clash (so e.g. two interfaces with a PerformCalculation() metod – in this case you can implement each method prefixed with the interface type so: InterfaceOne.PerformCalculation() and InterfaceTwo.PerformCalculation()
This is known as Explicit Interface Implementation – likely you’ll never use it.

Note that you can build interface hierachies – where one interface implements from another. An interface will of course never implement the parents methods, but simply extend (i.e. add to) the defined members. Note that multiple interface extension is allowed – so your interface can of course extend >1 other interfaces!

OOP: Interfaces in C#

This post is based on Chapter 9 of Andrew Troelsen’s “Pro C# 2008 and the .Net Platform” available from Apress.

The main purpose of interfaces is to enable us to build types (i.e. classes) that support multiple behaviours. On a more general note they are also at the heart of many OO Design Patterns as they allow you to program to an interface in stead of an implementation – we will return to what that means later on, but just know that if you really want to do OO design, classic inheritance is only the most basic step, and interfaces are a crucial tool for moving on from here.

So, what is an interface? Well an interface defines a behaviour that a class may choose to implement (indeed the java syntax uses “implements” for this, where as C# uses the : also used for inheritance). You can only inherit from one class in the .NET family of languages (see http://en.wikipedia.org/wiki/Multiple_inheritance for some issues around multiple inheritance), but you can implement as many interfaces as you like.

So what is the difference between abstract classes and interfaces, and when should you use what? Well for one thing interfaces have absolutely no implementation – they are simply a description of a behaviour – it’s the implementing class’ job to… implement the actual behaviour, in whatever way it see fit. So I might have two interfaces which defines the following:

	public interface IEnjoyBeer
		void DrinkABeer();

	public interface IActLikeADrunkenLoon
		void DanceOnTheTableInYourPants();
		void ArguePassionatelyWithPeopleAboutThingsYouKnowNothingAbout();

Now we can then define a class that chooses to implement both these – and hence must supply an implementation of all the defined members:

	public class DrunkAsASkunk : IEnjoyBeer, IActLikeADrunkenLoon
		public void DrinkABeer() { Console.WriteLine("Drinking a beer"); }

		public void DanceOnTheTableInYourPants() { Console.WriteLine("Dancing on table in pants!"); }

		public void ArguePassionatelyWithPeopleAboutThingsYouKnowNothingAbout() { Console.WriteLine("Arguing Passionately"); }

In contrast to this, we could do the same with an abstract base class, but we would have to roll both behaviours into one class (no multipl. inherit), which will give you a hint of the limitations of classic inheritance. Note also that we use the virtual method in the base class here to provide a default implementation for drinking a beer:

	public abstract class DrinkLotsOfBeerAndActLikeADrunkenLoon
		public virtual void DrinkABeer() { Console.WriteLine("Drinking a beer"); }
		public abstract void DanceOnTheTableInYourPants();
		public abstract void ArguePassionatelyWithPeopleAboutThingsYouKnowNothingAbout();

	public class DrunkAsSkunk2 : DrinkLotsOfBeerAndActLikeADrunkenLoon
		public override void DanceOnTheTableInYourPants() { Console.WriteLine("Dancing on table in pants!"); }

		public override void ArguePassionatelyWithPeopleAboutThingsYouKnowNothingAbout() { Console.WriteLine("Arguing Passionately"); }

What great examples – no idea how this came to me… Anyways – let’s discuss some aspects of the two examples.

In the last example we have an abstract type that drinks beer and acts like a loon – which doesn’t really ring true, I see an endless number of these types being instantiated across town every weekend, so already we have a hint of a design flaw here. Another good question would be “what about people who enjoy beer without acting like drunken loons?” Or indeed people who act like drunken loons for other reasons than enjoying beer…

In contrast to this, let’s look at the first example using interfaces. So first off the IEnjoyBeer interface makes sense as a separate behaviour – because enjoying beer does not necessarily entail acting like a drunken loon – but, of course for some types it does, but the point is: you have the option to implement either one or both behaviours! You could also have a type that acted like a drunken loon but did not enjoy beer.  Either way – having options is important!

Note also that interfaces are available across class hierarchies – so where inheritance has this fairly rigid tree-like structure, interfaces on the other hand can be plugged in anywhere and at any level.

That is not an exhaustive discussion of interfaces – and we will return to these later when we look at the Strategy pattern in the up and coming OO Design Patterns series – but for now do note that we are not saying that you should use interfaces in stead of inheritance, the two actually compliment each other – we will cover this later, but what you should do is remove variable behaviour from your inheritance structure and instead place this in interfaces. The next step from this will then be moving the implementation of the behaviour (i.e. the interface) out of the specific class, and keep these in reusable classes whose sole purpose is to represent a behaviour. So we will have a more generic interface called IEnjoyADrink – and then a class EnjoyBeer that implements this – and then finally we would design a class called perhaps Person or FridayNightLoon who would implement a IEnjoyADrink implementation of it’s choice – anyways, we’ll return to this… keep reading!

Finally – don’t ever forget to use the Visual Studio Class Diagram tool – this is your new best friend in the world of OOP, just open a new diagram and drop in the types you want to see:


Gargabe Collection and Finalising and/or Disposing Objects in .NET

This post is based on Chapter 8 of Andrew Troelsen’s “Pro C# 2008 and the .Net Platform” available from Apress.

So, yet another chapter from Mr. Andy Troelsen’s brilliant book – quite possibly the best book on .NET I’ve ever read, stuffed full of goodness and gotchas!

Garbage collection, well round here it happens every Wednesday morning, when I’m rudely awaken by a dirty bin man (he rings my bell… to access my backyard… oh my – I’ve gone gay all of a sudden – good thing my girlfriend wouldn’t read this blog if it was a cold day in hell).
Anyways –  back in the safety of .NET – garbage collection is not quite so predictable – so let’s begin. I think this time, we will try a slight more abbreviated approach (spend my life writing these summaries).

Classes, objects and References (and stack and heap memory)

So, classes are blueprints or definitions, from which objects are created and placed in working memory. The new keyword  returns a reference to an object on the heap, while the reference itself is stored on the stack for further use in your application.

Let’s just pause for air and examine this heap and stack stuff a bit more. Check out an excellent article on this here: http://www.c-sharpcorner.com/UploadFile/rmcochran/csharp_memory01122006130034PM/csharp_memory.aspx?ArticleID=9adb0e3c-b3f6-40b5-98b5-413b6d348b91
Which tells us that (generally speaking) we can:
Think of the Stack as a series of boxes stacked one on top of the next. We keep track of what’s going on in our application by stacking another box on top every time we call a method (called a Frame). We can only use what’s in the top box on the stack. When we’re done with the top box (the method is done executing) we throw it away and proceed to use the stuff in the previous box on the top of the stack. The Heap is similar except that its purpose is to hold information (not keep track of execution most of the time) so anything in our Heap can be accessed at any time. With the Heap, there are no constraints as to what can be accessed like in the stack.

Recall that you get a stack trace in your exceptions – so with the knowledge above this now makes sense as a list of method calls or frames on the stack – each frame can/will then have a number of references pointing into objects lying around in the heap (not unorderly, but freely available). Also this will explain why memory placed on the stack is freed as soon as the current method returns.

So – my learned friends, what happens, when a method (or frame) returns and we have all these objects in the heap that are no longer needed? Well, let’s sit back and let Mr Andy Troelsen explain for us:

The .NET Garbage Collector

Once it’s determined that a heap object is no longer reachable from your application (i.e. no longer used, i.e. no longer referenced from the stack, i.e. no references to local objects, static fields/objects or indeed no method parameters can be found) it becomes available for GC – and will be destroyed (i.e. removed from memory) next time the GC runs – which is whenever the .NET runtime deems it prudent – or, in exceptional cases when your logic instructs it to do so.

What this means is of course that you don’t have to explicitly dispose or null objects – although the latter certainly does no harm, and the first can be a good practice in some cases – but more on that later (below).

Anyways – the GC sounds pretty inefficient, you can’t help but imagine some nasty process that is continually scanning through working memory checking if there is an active reference to any of the in-memory heap objects.
Well – it’s not, because it’s optimised and designed to only run when necessary (low memory being the only certain trigger). Once the GC runs it suspends all threads and then uses “Object Generations” to efficiently scan through memory.
Object Generations is a process whereby objects that survive a GC (i.e. are checked but found to be in use) are promoted to an older generation. when the GC runs it will always first scan the youngest generation, and if this frees sufficient memory, no further GC will occur. However if this is not sufficient, the GC will continue with the next generation, and so forwards down through the generations.
If you keep the stacked methods or boxes on the stack memory in mind this will make sense to you – and the  end result is that long life heap objects that are used throughout the application will not be checked again and again – where as new local objects will be checked first.

The System.GC Class

As a quick aside note that this is a classic example of a static utility class, which it would never make sense to instantiate this in code.
Anyways, moving on:- this static class allows you to manually work with the GC, triggering collections and checking memory and generations etc. I’ve never known or seen this done in any application – but Troelsen tells us that this can be useful if you a) want to make sure GC does not run during a certain procedure (so force a collection before) or b) you know that a (very) large number of objects have gone out of scope.

More interesting is methods like GetTotalMemory() which gives you the bytes currently on the heap, also you can get the generation of a given object, by supplying a reference to it.
Another interesting methods is AddMemoryPressure(long bytesAllocated) – which “Informs the runtime of a large allocation of unmanaged memory that should be taken into account when scheduling garbage collection”  – from MSDN. Remember of course that GC maintains managed code – so if you are for instance calling some COM library, this can be a method to bear in mind.

…which leads us nicely onto

Finalizable and Disposable Objects

So, what do we need these for when we got our lovely little GC?
Well, you need these when you are are working with managed code (i.e. your .NET code) that references unmanaged code!
Makes sense. So, what are they and how do we build them.

Finalizable Objects

The base object class has a protected virtual method which is called whenever the GC collects an object, or the application shuts down. The object base class’ Finalize method does nothing – but you are of course free to override this in any class. However – you do not use the override keyword, in stead you use your class name prefixed with a tilde, with no access modifiers (protected by default) and no parameters, so for example: ~MyClass() { /* finalize here */ }
Kind of like a constructor. Apparently this tilde is more of a C++ syntax – no idea why this is used here.

When objects are placed on the heap the .NET runtime determines if they have overriden the Finalize method – and if so adds them to a queue of objects to be Finalized on removal from the heap.

Disposable Objects

A disposable object implements the IDisposable interface – and unlike Finalizable object, it’s assumed that the object user will manually call Dispose() once finished with the object. At least it should, and btw, the object user, is you!
So to be clear:- the GC has no clue about the IDisposable interface, and to be frank, it just doesn’t want to know. So Dispose should be called by your code, while the object is still alive and well (and referenced) on the heap – of course, how else are you going to call it’s Dispose() method?

So what does one do when implementing the Dispose() method? Simples, you do two things: clean up all unmanaged resources, and then call Dispose on any Disposable managed objects! Note that you can of course use the is keyword to check if an object is IDisposable.

One slightly annoying thing is that things like database connections and file streams have Close() methods, which is in fact an alias to Dispose() – you can call both without causing an error – but really, if it’s IDisposable, call Dispose()  – and then you can get all geeky and clever when some lesser developer comes to you and accuses you of not having “closed” your database connection (tell him it’s not a ruddy garden gate, and that Close is just an alias for Dispose and watch his eyes blink in confusion).

One better and cleaner alternative to the above is the using keyword (which happily also doubles for setting up reference shorthands).
When you use a using block like the below example, the IL code generated is actually a try/catch block, with a call to Dispose on the object used placed in the finally block (however this does of course not mean that any exceptions are handled!):

			//Note you can place >1 object of the same type in a using block
			using(FileStream fileStream = new FileStream(), fileStream2 = new FileStream())
				//Do your thing here
			//Know that both objects have been disposed (aka "closed") here

Whenever possible, always use using blocks – they are good, clean and we like them!

Finally – we have a GC.SuppressFinalize(this); method call – which can be used to build a fool proof object that combines the best of Finalizable and Disposable objects.
The general idea is that the object user might forget to call  Dispose – in which case we want the object to clean up unmanaged resources when the GC collects it and Finalizes it. The methods is simple, put you clean up code in a private method. Call this from both the Dispose and Finalize methods, but in the Dispose, follow this by a call to SuppressFinalize(this); – as you might have guessed, this removes the object from the GC queue of Finalizable objects.


C# .NET Exception Handling

This post is based on Chapter 7 of Andrew Troelsen’s “Pro C# 2008 and the .Net Platform” available from Apress.

So, we’ll assume you know the basics, and just quickly cover a few important gotchas from Mr. Troelsen’s most excellent book.

Some terminology:

  • Bugs: programmer errors (sorry).
  • User errors: users inputting invalid data, and generally dicking around with things.
    Arguably most of these are bugs,  as you should always (and sooner or later will come to) anticipate that your users will dick around with stuff in the most wonderful and fantastic ways possible.
  • Exceptions: Program errors caused by “Exceptional circumstances”. So perhaps your database server blows up, or maybe somone trips over the power cable to the internet.
    Main point is that these are unforeseen force majeure type events, and these are the only true type of exceptions, everything else, unfortunately are bugs – however, quite often the CLR will respond to a bug by raising an exception – thou, if you’re really lucky (and you will be) the bug will result in incorrect data or responses.

The System.Exception Base Class

This implements two interfaces:
System.Runtime.InteropServices._Exception means that unmanaged code bases like COM applications are able to process the Exception.
System.Runtime.Serialization.ISerializable – means you can serialise the exception to a file or similar – more on this later.

Some useful properties of the Exception base class are:

  • Data – this is a IDictionary collection of object key/value pairs that allows you to forward state data to your handling logic (useful for debugging). This is empty by default
  • InnerException – contains info on any exceptions that occurred prior to the current.
    These are forwarded by catching one, and creating a new where you pass the current into the constructor.
    Note that you can loop through these in your handling code using a while != null check (and re-point your reference to the inner, you know what I mean!).
  • Message – this is a short description of the error, you can hand this to the constructor of any exception you choose to throw yourself.
  • Source – this is the assembly that threw the Exception.
  • Stacktrace – this is a trace on the call stack that lead to the exception, note that you read this top down if you want to start with where things went wrong.
  • TargetSite – this is the method that caused the offending operation. Note that this is a System.Reflection.MethodBase object.
  • ToString() – is overridden to give you the Message, Class name and stacktrace – and what’s more it will recurse through the innerexception and call ToString() on each – so you end up with the original exception first, and any subsequent in ascending order.
    Note however that this does miss out a few properties  – so you might not want to rely (solely) on this for any logging.

Note also that you method and class documentation markup allows you to specify the possible exception that should be handled (will show up in intellisense).

Handling and Throwing Exceptions

When should you throw exceptions? I’ve always wondered… and when should you catch and rethrow…?

Well – as a rule of thumb, only throw exceptions when something serious and terminal has gone wrong. If you cannot find a file you need, if you cannot connect to the DB server… or whatever – though most of these will already throw exceptions.
If you can catch and handle a condition, and communicate this to your caller in some sensible way, this is always preferable.

If you do throw exception, note that you should  hand any prior exceptions into the constructor.  You can then set most of the properties mentioned above on your new exception, including a helplink, might come in handy some day, who knows.  Also, any state data that might be useful for debugging can be added to the Data property – like parameter values or a DateTime.Now timestamp. Make sure you null check though!
However – generally you are better of constructing a strongly typed Exception class of your own rather than relying on the Data property.

In fact – never get too clever or complicated in your exception handling – worst thing you can have, is buggy exception handling. Just red ear embarrassing stuff!
Try and keep things simple – the main aim should be to inform the user in a sensible way, and then make sure you log as much as you can.. and make sure you at some point end up with a fail safe catch clause, that if all else fails simply informs the user that x went wrong trying to y. Alwyas avoid (even as a last resort) showing your users the full exception with stacktrace etc, it’s not professional and there are certain security issues (they’re minor, but essentially you could be showing a malicious user part of your code (from the stacktrace) and also inform them of the sorftware platform and version used).

When handling exceptions always try and catch the most specific first (use your intellisense and hover over methods to get possible exceptions).

Note that you can use an empty throw; call to simply rethrow the original exception without any modifications (so the original target will be preserved).

Note that you can use an empty catch{} statement to handle all exceptions (so similar to catching the base System.Exception class – however you catch nothing, but handle everything).

Building Strongly Typed Exceptions

First of all realise that we have system level exception, which inherit from System.SystemException – these are thrown by the .NET runtime, and you should not inherit from this class.

Then we have application level exception, inheriting from System.ApplicationException – to roll your own, inherit from this.

Note that convention is that all exception classes should end in, you guessed it: Exception.

So, just when exactly should you build your own custom exceptions?
Generally, you should do this when the exceptions is tightly coupled to the class you are working with (i.e. none of the existing exception classes makes sense or meet your requirements). A sign of this can be that you find yourself throwing a new ApplicationException – which on the other hand is too general, and not best practise, so – if nothing more specific meets your needs, roll your own!

If you do build your own Exception type (i.e. class) – make sure you use constructor forwarding to avoid code redundancy. Also, if you want to go all the way and follow Microsoft best practises (which of course you do), your custom exception class  should meet the following checklist:

  • Derive from ApplicationException
  • Marked with the Serializable attribute, and define a constructor to handle serialization of your type (more on this later)
  • Define a default constructor, a constructor that sets your Message property and finally a constructor that handles any inner exceptions.

Note that there is a code snippet (ctrl+k+x) in VS2008 for this  – which will give you a class stubs for all the above.

And Finally… the finally block

Had to do that didn’t I?
Only thing to remember here is that this is always executed, exception or no exception. And it’s a great place to tidy up things and close connections – however, do note that you cannot return control from your method (i.e. return…; ) from within a finally block.


Documenting .NET Code

This post is based on Chapter 5 of Andrew Troelsen’s “Pro C# 2008 and the .Net Platform” availble from Apress.

You will no doubt know the general documentation syntax for methods and classes. Here are some tools and tips on how to leverage this into a full blown application documentation:

GhostDoc – is an excellent tool that allows you to define keyboard shortcuts for auto-generating comment blocks. With some practise and good naming practises this will take care of a lot of the work behind documenting your code.

Once you have all your comments ready, you can use the .NET commandline compilers and the /doc argument to generate an XML file from these. Once you have this, you can use tools like NDoc or SandcastleDocs to generate nice browsable documentation.