Understanding and Implementing IDisposable Interface – A Beginner’s Tutorial

In this article, we will discuss the often confused topic of Implementing the IDisposableinterface. We will try to see when should be need to implement the IDisposableinterface and what is the right way of implementing it.

Background

Often in our application development we need to aquire some resources. These resources coould be files that we want to use from a clustered storage drive, database connections etc. The important thing to remember while using these resources is to release these resources once we are done with it.

C++ programmers are very well aware of the the concept of Resource Acquisition is Initialization(RAII). This programing idiom states that of an object want to use some resources then it is his responsibility to acquire the resource and release it. It should do so in normal conditions and in exceptional/error conditions too. This idiom is implemented very beautifully using constructors, destructors and exception handling mechanism.

Let us not digress and see how we can have a similar idiom in C# using IDisposablepattern.

Using the code

Before looking into the details of IDisposableinterface let us see how we typically use the resources, or what are the best practices to use the resources. We should always acquire the resources assuming two things. One we could get the resource and use it successfully. secondly there could be some error/exception while acquiring the resource. So the resource acquisition and usage should always happen inside a try block. The resource release should always be in the finally block. As this finally block will be executed always. Let us see a small code snippet to understand a little better.

Using Try-finally to manage resources

Putting ‘using’ in place to manage resources

The other way to do the same thing us to use using, this way we only have to think about the resource acquisition and the exception handling. the resource release will be done automatically because the resource acquisition is wrapped inside the usingblock. Lets do the same thing we did above putting the usingblock in place.

Both the above approaches are essentially the same but the only difference is that in the first approach we have to release the resource explicitly where as in the second approach the resource release was done automatically. usingblock is the recommended way of doing such things as it will do the clean up even if the programmers forget to do it.

The use of ‘ using’ block is possible because the TextReaderclass in the above example is implementing IDisposablepattern.

A note on Finalizers

Finalizersare like destructors. they will get called whenever the object goes out of scope. We typically don’t need to implement Finalizersbut if we are planning to implement IDisposable pattern and at the same time we want the resource cleanup to happen when the local object goes out of scope then we will have to have a Finalizerimplemented in our class.

When and why we need to Implement IDisposable

Now we know how the resource acquisition and release should be done ideally. we also know that the recommended way of doing this is usingstatement. Now its time to see why we might need to know more about implementing the IDisposablepattern ourselves.

Lets assume that we are writing a class which will be reused all across the project. This class will acquire some resources. To acquire these resources our class will be needing some managed objects(like in above example) and some unmanaged stuff too(like using a COM component or having some unsafe code with pointers).

Now since our class is acquiring resources, the responsibility of releasing these resources also lies with the class. Let us have the class with all the resource aquisition and release logic in place.

We have the class ready with the resource allocation and deallocation code. We also have the functions to use the class. Now we want to use this class following the guidelines earlier in this article. i.e.

  • Using the object in a try-finally block, acquire resources in try block and release them in finally.
  • Using the object in a usingblock, the resource release will be done automatically.
  • The object when goes out of scope it should get disposed automatically as it was a local variable.

Implementing IDisposable

Now if we need to perform the clean up using while using our object and facilitate all the above mentioned functionalities we need to implement the IDisposablepattern. Implementing IDisposable pattern will force us to have a Disposefunction.

Secondly if the user want to use the try-finally approach then also he can call this Dispose function and the object should release all the resources.

Lastly and most importantly, lets have a Finalizerthat will release the unmanaged resources when the object goes out of scope. The important thing here is to do this finalize only if the programmer is not using the ‘ using’ block and not calling the Disposeexplicitly in a finally block.

For now lets create the stubs for these functions.

So to understand the possible scenario how this class might need disposal let us look at the following possible use cases for our class. we will also see what should be done in each possible scenario.

  1. The user will not do anything to relase the resource. We have to take care of releasing resource in finalizer.
  2. The user will use try-finally block. We need to do the clean up and ensure that finalizer will not do it again.
  3. The user will put a using ‘block’. We need to do the clean up and ensure that finalizer will not do it again.

So here is the standard way of doing this Dispose business. It is also known as dispose pattern. Lets see how this should be done to achieve all we wanted.

So now the complete definition of our class looks like this. This time I have added some print messages to the methods so that we can see how things work when we use different approaches.

Let us use this class first with a try-finally block

The sequence of operations can be understood by these ouptut messages.

Let us use this class putting a usingblock in place

The sequence of operations can be understood by these ouptut messages.

Let us use this and leave the resource release to GC. the unmanaged resources should still be cleaned up when the finalizer gets called.

The sequence of operations can be understood by these ouptut messages.

Points of Interest

Implementing IDisposablehas always been a little confusing for the beginners. I have tried to jot down my understanding of when to implement this interface and what is the right way if implementing it. Although this article is written from a beginner’s perspective, I hope this article has been informative and helpful to someone.

Download sample code for this article: IDisposableTestApplication