In my previous post, I classified the different memory resources available in the .NET CLR and I explained the role of the IDisposable interface as well as the use of the Finalize() method.

In this post, I am going to talk more about the implementation details of IDisposable and Finalize().

For reference, I have split this matter into two posts:

• # 1 – What + Why + references
• #2 – A guide about ‘how to implement it’ + samples (this post)

You should know by now when and why you should implement IDisposable and Finalize() method according to the type of resource(s) your class owns. In order to answer the question “How?” we still do need to look at two more aspects: 1) Inheritance (as in Object-Oriented Programming) & 2) Some remaining considerations.

OOP – Inheritance

There is one more aspect to take into consideration in object-oriented programming and that is inheritance. When you define a public base class (or any public class that can be instantiated and is not marked as “sealed”) you should consider that even though you have not any managed or unmanaged resources, you might still need to think about the potential classes that would derived from it. They might require managed or unmanaged resources. In that case, you should make the finalization code (IDisposable + Finalize()) in your base class, so that it is part of the contract and derived-class or client-code could use it correctly (i.e. calling Dispose() whenever it is required).

Obviously, if you are SURE to be  in control of ALL the client code of your class, then you can wait for your derived classes to really require this resource management code (IDisposable + Finalize()) before implementing it.

As for me, as soon as I create a new class, my first step is to make it “sealed” – I found this “habit” very effective, because it closes a lot of questions about inheritance (which method must be declared “virtual”, which method/properties/field should be declared “protected”, …). If later the class must become a base class, then I can review the changes and needs at that time. This is my way, everyone is different 🙂

 Some remaining considerations

Finalizers:

• Be careful, if an exception is thrown in the constructor, the finalizer code will still be executed, so make sure to check whether a field (to a native resource) has been correctly initialized before calling any clean up code on it.

Dispose() method:

• To help to ensure that resources are always cleaned up appropriately, a Dispose() method should be callable multiple times without throwing an exception.
• The object must dispose all of the resources it owns.
• A disposed object cannot be used anymore (i.e. once its Dispose() method has been called), so it must become “garbage” so next time the garbage collector will kick off its managed memory can be reclaimed (or if it has a Finalizer(), it will be place on the “f-reachable” list).
• Once an object has been disposed, all of its public methods must throw the exception of type “ObjectDisposedException”.
• You must make sure that no delegates (from Rooted object) are pointing to it, usually done via “events“. Here, you have two choices:
  1. The instance which is running Dispose() exposes event(s) (aka source of event(s)), then it must reset the list of its subscribers (you might want to define a ‘OnDisposing’ event, so that client code might register and have a chance to be notified when Dispose() is called on the source).
  2.  The instance which is running Dispose() consumes event(s) (aka subscriber of event(s)), then it must unsubscribe itself from the source(s) of events.

Versioning:

• You have to be careful when adding “IDisposable” to your class.
  • If you are in control of all the assemblies using it, then you can add it and review its usage amongst all your code.
  • If you have shipped or distributed your class to customers/partners, you cannot add it like that, because this change the semantics of your class and the client code is not aware of it. In that case, one option to make your existing class “Obsolete” and create a new one with the implementation of IDisposable and let your clients know about the new class.

Native Handle

• Since .NET 2.0, Microsoft has released a new abstract class ‘SafeHandle‘ [Ref-01 & 02] that can help you in disposing native handles. Most of the .NET classes that wrap native handles (File, Pipe, Wait handle, Registry key, …) use internally specialized classes derived from ‘SafeHandle’ (read the doc on .NET v4.0 or above of MSDN about this subject). So you might consider, if needed, to create your own SafeHandle derived class for disposing native handles.

Decision Matrix

So, now we have all the bits of information that should be taken into consideration to find out what really is needed in the code for your class:

• Sealed class or base class?
• What type of resources does your class own?

Once you answered to those questions, then the matrix below provides you with the bits that are required for you case:

Nota:

• Finalize():
  • Must only release unmanaged resources. E.g. native/unsafe handles on file, windows etc.
    No cleaning code on .NET object field(s) should be done inside a Finalizer. (i.e. calling Dispose(), Close() or removing event handlers …).
• Dispose(bool): implement it when the release logic is shared by Dispose() and Finalizer()

Here is a link for downloading a sample solution (VS 2010, C# source code).

The sample code I am providing respect the decision matrix above (and is deliver “AS -IS”, the usual formula for “disclaim”). However, because of refactoring and reuse of code you will find some differences. E.g. for “non-sealed class” instead of defining a “protected virtual Dispose(bool)” method I instead defined a “private” one with the hard-coded “Dispose(bool) logic” in it and defined two virtual methods: one for disposing Managed Resources and one for Unmanaged Resources (I did not update the decision matrix, because it is close to what you can find on current MSDN documentation, so most developers should be familiar with it – the principles are here).

Fx-Cop to the rescue

If you are using Visual Studio 2005 and above and have the “FX-Cop” as part of your edition (also referred as “Code Analysis”) it is a good practice to enable the following checking rules:

This way, every time you add code to your project, FX-Cop can look for you for new usage of Disposable resources and warn you about your usage in your code. This is not bullet proof (I had some cases, long chain of inheritance, where FX-Cop did not detect and did not warn about the not use of IDisposable.Dispose() – but this was more the exception than the rule, so use it).

Conclusion

That is it for me. I hope you have now a better understanding about “how to implement IDisposable”.

References:

• [REF-01] “Safe Handles and Critical Finalization“, MSDN online.
• [REF-02] “SafeHandle Class“, MSDN online.
• “Microsoft.Win32.SafeHandles Namespace“, MSDN online (from Donald’s comment)