Introduction

In this article, we will discuss the often confused topic of Implementing the IDisposable interface.
We will try to see when should be need to implement the IDisposable interface 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 IDisposable pattern.

Using the code

Before looking into the details of IDisposable interface 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.

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 using block. Lets do the same thing we did above putting the using block in place.

//2. Let us now look at the other way we should do the same thing (Recommended version)
TextReader tr2 = null;
//lets aquire the resources here
try
{
using (tr2 = new StreamReader(@"Files\test.txt"))
{
//do some operations using resources
string s = tr2.ReadToEnd();
Console.WriteLine(s);
}
}
catch (Exception ex)
{
//Handle the exception here
}

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. using block 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 TextReader class in the above example is implementing IDisposable pattern.

A note on Finalizers

Finalizers are like destructors. they will get called whenever the object goes out of scope. We typically don't need to implement Finalizers but 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 Finalizer
implemented in our class.

class SampleClass
{
~SampleClass()
{
//This is a Finalizer
}
}

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 using statement. Now its time to see why we might need to know more
about implementing the IDisposable pattern 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 atry-finally
block, acquire resources in try block and release them in finally.

Using the object in a using block, 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 IDisposable pattern. Implementing IDisposable pattern will force us to have
a Dispose function.

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 Finalizer that 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 Dispose explicitly in a finally block.

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.

The user will not do anything to relase the resource. We have to take care of releasing resource in finalizer.

The user will use try-finally block. We need to do the clean up and ensure that finalizer will not do it again.

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.

publicvoid Dispose()
{
// If this function is being called the user wants to release the
// resources. lets call the Dispose which will do this for us.
Dispose(true);
// Now since we have done the cleanup already there is nothing left
// for the Finalizer to do. So lets tell the GC not to call it later.
GC.SuppressFinalize(this);
}
protectedvirtualvoid Dispose(bool disposing)
{
if (disposing == true)
{
//someone want the deterministic release of all resources
//Let us release all the managed resources
ReleaseManagedResources();
}
else
{
// Do nothing, no one asked a dispose, the object went out of
// scope and finalized is called so lets next round of GC
// release these resources
}
// Release the unmanaged resource in any case as they will not be
// released by GC
ReleaseUnmangedResources();
}
~MyResources()
{
// The object went out of scope and finalized is called
// Lets call dispose in to release unmanaged resources
// the managed resources will anyways be released when GC
// runs the next time.
Dispose(false);
}

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.

class MyResources : IDisposable
{
//The managed resource handle
TextReader tr = null;
public MyResources(string path)
{
//Lets emulate the managed resource aquisition
Console.WriteLine("Aquiring Managed Resources");
tr = new StreamReader(path);
//Lets emulate the unmabaged resource aquisition
Console.WriteLine("Aquiring Unmanaged Resources");
}
void ReleaseManagedResources()
{
Console.WriteLine("Releasing Managed Resources");
if (tr != null)
{
tr.Dispose();
}
}
void ReleaseUnmangedResources()
{
Console.WriteLine("Releasing Unmanaged Resources");
}
publicvoid ShowData()
{
//Emulate class usage
if (tr != null)
{
Console.WriteLine(tr.ReadToEnd() + " /some unmanaged data ");
}
}
publicvoid Dispose()
{
Console.WriteLine("Dispose called from outside");
// If this function is being called the user wants to release the
// resources. lets call the Dispose which will do this for us.
Dispose(true);
// Now since we have done the cleanup already there is nothing left
// for the Finalizer to do. So lets tell the GC not to call it later.
GC.SuppressFinalize(this);
}
protectedvirtualvoid Dispose(bool disposing)
{
Console.WriteLine("Actual Dispose called with a " + disposing.ToString());
if (disposing == true)
{
//someone want the deterministic release of all resources
//Let us release all the managed resources
ReleaseManagedResources();
}
else
{
// Do nothing, no one asked a dispose, the object went out of
// scope and finalized is called so lets next round of GC
// release these resources
}
// Release the unmanaged resource in any case as they will not be
// released by GC
ReleaseUnmangedResources();
}
~MyResources()
{
Console.WriteLine("Finalizer called");
// The object went out of scope and finalized is called
// Lets call dispose in to release unmanaged resources
// the managed resources will anyways be released when GC
// runs the next time.
Dispose(false);
}
}

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

//5. Lets not do anything and the GC and take care of managed data
// we will let our finalizer to clean the unmanaged data
MyResources r3 = new MyResources(@"Files\test.txt");
r3.ShowData();

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

Aquiring Managed Resources
Aquiring Unmanaged Resources
This is a test data. / Some unmanaged data.
Finalizer called
Actual Dispose called with a False
Releasing Unmanaged Resources

Points of Interest

Implementing IDisposable has 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.

Share

About the Author

I Started my Programming career with C++. Later got a chance to develop Windows Form applications using C#. Currently using C#, ASP.NET & ASP.NET MVC to create Information Systems, e-commerce/e-governance Portals and Data driven websites.

My interests involves Programming, Website development and Learning/Teaching subjects related to Computer Science/Information Systems. IMO, C# is the best programming language and I love working with C# and other Microsoft Technologies.

Comments and Discussions

Let's write a "managed" language and still have coders be responsible for "unmanaged" resources..?? lol....why didn't Microsoft create "Smart Resources".. much like Smart pointers... its silly . The more I learn bout C# the more I hate it... C++ is still way easier to develop applications.. and waaaay more stable

if i read something ignorant like this, i cannot get around to respond that writing something "stable" is an art which someone like you will never achieve in any language... btw. smart-pointers do not necessarily imply that "coders" using them are smart too...

Nice article, but the Microsoft docs for Dispose[^] also specifiy that an exception should not be raised during dispose, which could happen if Dispose is called twice.

This can be done in one of two ways (or both). 1. Setup a instance variable and set it to true the first time Disposed is called. Of course, check it when entering Disposed. 2. Set the "inner" object you just disposed to null so you can't dispose it again.

privatebool _hasDisposed = false;
/*
* other code...
*/void ReleaseManagedResources()
{
Console.WriteLine("Releasing Managed Resources");
if (tr != null)
{
tr.Dispose();
tr = null;
}
}
/*
* other code...
*/protectedvirtualvoid Dispose(bool disposing)
{
if (_hasDisposed == false)
{
Console.WriteLine("Actual Dispose called with a " + disposing.ToString());
if (disposing == true)
{
//someone want the deterministic release of all resources
//Let us release all the managed resources
ReleaseManagedResources();
}
else
{
// Do nothing, no one asked a dispose, the object went out of
// scope and finalized is called so lets next round of GC
// release these resources
}
// Release the unmanaged resource in any case as they will not be
// released by GC
ReleaseUnmangedResources();
_hasDisposed = true;
}
else
{
Console.WriteLine("Already called Dispose.");
}
}

Twenty years from now you will be more disappointed by the things that you didn't do than by the ones you did do. So throw off the bowlines. Sail away from the safe harbor. Catch the trade winds in your sails. Explore, Dream. Discover.

Hi Rahul,Thank you so much for this article. I had a job interview recently and i was actually asked about this interface and the use of using clause. After reading your article and run your code i now have a very good understanding on this implementation. once again thank you so much.Farouk, England

A Finalizer may be called after the object has gone out of scope, but at the convenience of the GC and not deterministically.It is quite different from a C/C++ style destructor in that respect.Furthermore, simply declaring one is an overhead for the GC, and should be done only when necessary.Typically, this is used for limited unmanaged resources.

it is cheaper to seal up the class and skip the finalizer and the virtual Dispose method altogether. hope your post won't get downvoted like mine

another thing is that I can tell from own experience of fixing poorly implemented IDisposibles (namely abstract DisposibleBase, ViewModelBase etc with finalizers and virtual Dispose methods), there is no "beginner stage" in implementing IDisposible. You either do it right or wrong. You can't copy half of an article and slap "A beginners tutorial" on it.

I did not vote your comment, but I suspect it got downvoted for the first sentence (txtspk/streettalk), you posted two URL's without making them into clickable links, and you really could have provided a more constructive comment to justify your vote.