Close and Dispose - which to call?

I want to clarify this situation.

According to Microsoft guidelines, it's a good practice to provide Close method where suitable. Here is a citation from Framework design guidelines

Consider providing method Close(), in addition to the Dispose(), if close is standard terminology in the area. When doing so, it is important that you make the Close implementation identical to Dispose ...

In most of cases Close and Dispose methods are equivalent. The main difference between Close and Dispose in the case of SqlConnectionObject is:

An application can call Close more than one time. No exception is generated.

If you called Dispose method SqlConnection object state will be reset. If you try to call any method on disposed SqlConnection object, you will receive exception.

That said:

• If you use connection object one time, use Dispose. A using block will ensure this is called even in the event of an exception.
• If connection object must be reused, use Close method.

As usual the answer is: it depends. Different classes implement IDisposable in different ways, and it's up to you to do the necessary research.

As far as SqlClient goes, the recommended practice is to do the following:

using (SqlConnection conn = /* Create new instance using your favorite method */)
{
    conn.Open();
    using (SqlCommand command = /* Create new instance using your favorite method */)
    {
        // Do work
    }
    conn.Close(); // Optional
}

You should be calling Dispose (or Close*) on the connection! Do not wait for the garbage collector to clean up your connection, this will tie up connections in the pool until the next GC cycle (at least). If you call Dispose, it is not necessary to call Close, and since the using construct makes it so easy to handle Dispose correctly, there is really no reason to call Close.

Connections are automatically pooled, and calling Dispose/Close on the connection does not physically close the connection (under normal circumstances). Do not attempt to implement your own pooling. SqlClient performs cleanup on the connection when it's retrieved from the pool (like restoring the database context and connection options).

*if you are calling Close, make sure to do it in an exception-safe way (i.e. in a catch or finally block).

For SqlConnection, from the perspective of the connection itself, they are equivalent. According to Reflector, Dispose() calls Close() as well as doing a few additional memory-freeing operations -- mostly by setting members equal to null.

For Stream, they actually are equivalent. Stream.Dispose() simply calls Close().

You DO need to call Dispose()!

Dispose() is for the developer to call, the Garbage Collector calls Finalize(). If you don't call Dispose() on your objects any unmanaged resources that they used won't be disposed until the garbage collector comes around and calls finalize on them (and who knows when that will happen).

This scenario is called Non Deterministic Finalization and is a common trap for .net developers. If you're working with objects that implement IDisposable then call Dispose() on them!

http://www.ondotnet.com/pub/a/oreilly/dotnet/news/programmingCsharp_0801.html?page=last

While there may be many instances (like on SqlConnection) where you call Disponse() on some object and it simply calls Close() on it's connection or closes a file handle, it's almost always your best bet to call Dispose()! unless you plan on reusing the object in the very near future.

This would-be quick advice became a long answer. Sorry.

As tyler pointed out in his nice answer, calling Dispose() is a great programming practice. This is because this method is supposed to "rally together" all the resource-freeing needed so there are no unneeded open resources. If you wrote some text to a file, for example, and failed to close the file (free the resource), it will remain open and no one else will be able to write to it until the GC comes around and does what you should have done.

Now, in some cases there will be "finalizing" methods more specific to the class you're dealing with, like StreamWriter.Close(), which overrides TextWriter.Close(). Indeed they are usually more suited to the situation: a StreamWriter's Close(), for example, flushes the stream and the underlying encoder before Dispose()ing of the object! Cool!

However, browsing MSDN you'll find that even Microsoft is sometimes confused by the multitude of closers and disposers. In this webpage, for instance, in some examples Close() is called before the implicit Dispose() (see using statement if you don't understand why it's implicit), and in one in particular they don't bother to. Why would that be? I too was perplexed.

The reason I figured (and, I stress, this is original research and I surely might lose reputation if I'm wrong) is that Close() might fail, yielding an exception whilst leaving resources open, while Dispose() would surely free them. Which is why a Dispose() should always safeguard a Close() call (sorry for the pun).

MyResource r = new MyResource();

try {
  r.Write(new Whatever());

  r.Close()
finally {
  r.Dispose();
}

And yes, I guess Microsoft slipped on that one example. Perhaps that timestamp would never get flushed to the file.

I'm fixing my old code tomorrow.

Edit: sorry Brannon, I can't comment on your answer, but are you sure it's a good idea to call Close() on a finally block? I guess an exception from that might ruin the rest of the block, which likely would contain important cleanup code.

Reply to Brannon's: great, just don't forget to call Close() when it is really needed (e.g. when dealing with streams - don't know much about SQL connections in .NET).