How to implement the Dispose method in a derived class in Visual Basic .NET or in Visual Basic 2005 (315528)



The information in this article applies to:

  • Microsoft Visual Basic 2005
  • Microsoft Visual Basic .NET (2003)
  • Microsoft Visual Basic .NET (2002)

This article was previously published under Q315528

SUMMARY

When you author a class that extends a base class, you need to somehow handle the release of allocated resources. To do this, the Dispose method from the base class should be overridden in the derived classes. This article discusses common problems encountered in this scenario, how to properly override the Dispose method, and is meant to clarify some of the subtleties in the following Visual Basic .NET help article: Refer to this Help document for detailed information about error handling and for general examples of the Dispose method.

MORE INFORMATION

A base class needs to contain an overloaded set of Dispose methods. The first instance of the sample code that follows is a version without parameters, and the second instance accepts a Boolean parameter:
'Method that is called by Public to ensure TRUE is passed to Dispose
Public Overloads Notoverridable Sub Dispose()
    Dispose( TRUE )
    ' Take yourself off of the finalization queue.
    GC.SuppressFinalize(Me)
End Sub

'Method that does the actual disposal of resources
Protected Overloads Overridable Sub Dispose(ByVal disposing As Boolean)
    'Clean Up Resources
End Sub
				

Dispose() is the method that is called when an object is disposed of in the code in which the object was created. This is a Public method, and therefore it can be used when an instance of the class exists. The Dispose() method then calls the Dispose(Boolean) method and passes a value of TRUE. The Dispose(Boolean) method is responsible for cleaning up the resources of the class.
When a class is derived from a base class, only the Dispose(Boolean) method needs to be overridden. All resource-cleanup for the derived class will be performed in this overridden method, and then the Dispose(Boolean) method for the base class is called. The following is a primitive example of the function overriding the base class:
Protected Overloads Overrides Sub Dispose(disposing As Boolean)
   'Clean Up Resources
   MyBase.Dispose( disposing )
End Sub
				
The derived class does not need a Dispose() method, because that method is inherited from the base class. When Dispose() is called on an instance of the derived class, Dispose() uses the Dispose(Boolean) of the derived class rather than the one in the base class. It is then important that the Dispose(Boolean) method of the derived class calls the Dispose(Boolean) method of the base class. This is done by means of the MyBase.Dispose(disposing) method. The Dispose(Boolean) method for the base class must be called to ensure that the resources of the base class are also disposed of.
Dispose() is meant as an entry point for public access to the disposal of an object and to ensure that TRUE is passed to the Dispose(Boolean) method. FALSE should be passed only when the Dispose(Boolean) method is called by the runtime or Finalize method. When FALSE is passed, only the unmanaged resources will be disposed. When TRUE is passed, both the managed and unmanaged resources are disposed.
The Visual Studio Development Environment inserts the code to override the Dispose() method into a class that inherits a system object (for example, Inherits System.Windows.Forms.TextBox). This is performed from the menus (at the top of the code window, by default) by selecting Overrides and then clicking Dispose(). The code that is inserted looks something like the following:
Public Overloads Overrides Sub Dispose()
   'Clean Up Resources
End Sub
				
If this is done, no compile errors are raised. However, when the derived class is loaded at runtime, you receive a runtime error message similar to the following:
An unhandled exception of type 'System.TypeLoadException' occurred in system.windows.forms.dll.

Additional information: Declaration referenced in a method implementation can not be a final method. Type: ClassLibrary1.UserControl1. Assembly: Dispose.
NOTE: The Type value will be different from that in the preceding example. That is merely the name of the class that attempted to use an improperly overridden Dispose() method.
To correct this issue, just overload the Dispose(Boolean) method instead of Dispose(), and make sure that a call is made to the Dispose(Boolean) method of the base class and that TRUE is passed to it.

NOTE: In Visual Basic .NET or in Visual Basic 2005, the Overridable keyword is used like the Virtual keyword in C# and C++. Methods are, by default, NotOverridable.

Modification Type:MinorLast Reviewed:10/3/2006
Keywords:kbvs2005swept kbvs2005applies kberrmsg kbinfo KB315528 kbAudDeveloper