Using Statement (Visual Basic)
Declares the beginning of a Using block and optionally acquires the system resources that the block controls.
Using { resourcelist | resourceexpression }
[ statements ]
End Using
Parts
resourcelist
Required if you do not supply resourceexpression. List of one or more system resources that this Using block controls.resourceexpression
Required if you do not supply resourcelist. Reference variable or expression referring to a system resource to be controlled by this Using block.statements
Optional. Block of statements that the Using block runs.End Using
Required. Terminates the definition of the Using block and disposes of all the resources that it controls.
Each resource in the resourcelist part has the following syntax and parts:
resourcename As New resourcetype [ ( [ arglist ] ) ]
-or-
resourcename As resourcetype = resourceexpression
resourcelist Parts
resourcename
Required. Reference variable that refers to a system resource that the Using block controls.New
Required if the Using statement acquires the resource. If you have already acquired the resource, use the second syntax alternative.resourcetype
Required. The class of the resource. The class must implement the IDisposable interface.arglist
Optional. List of arguments you are passing to the constructor to create an instance of resourcetype. See Parameter List.resourceexpression
Required. Variable or expression referring to a system resource satisfying the requirements of resourcetype. If you use the second syntax alternative, you must acquire the resource before passing control to the Using statement.
Remarks
Sometimes your code requires an unmanaged resource, such as a file handle, a COM wrapper, or a SQL connection. A Using block guarantees the disposal of one or more such resources when your code is finished with them. This makes them available for other code to use.
Managed resources are disposed of by the .NET Framework garbage collector (GC) without any extra coding on your part. You do not need a Using block for managed resources.
A Using block has three parts: acquisition, usage, and disposal.
Acquisition means creating a variable and initializing it to refer to the system resource. The Using statement can acquire one or more resources, or you can acquire exactly one resource before entering the block and supply it to the Using statement. If you supply resourceexpression, you must acquire the resource before passing control to the Using statement.
Usage means accessing the resources and performing actions with them. The statements between Using and End Using represent the usage of the resources.
Disposal means calling the Dispose method on the object in resourcename. This allows the object to cleanly terminate its unmanaged resource. The End Using statement disposes of the resources under the Using block's control.
Behavior
A Using block behaves like a Try...Finally construction in which the Try block uses the resources and the Finally block disposes of them. Because of this, the Using block guarantees disposal of the resources, no matter how you exit the block. This is true even in the case of an unhandled exception, except for a StackOverflowException.
The scope of every resource variable acquired by the Using statement is limited to the Using block.
If you specify more than one system resource in the Using statement, the effect is the same as if you nested Using blocks one within another.
Structured Exception Handling Within a Using Block
If you need to handle an exception that might occur within the Using block, you can add a complete Try...Finally construction to it. If you need to handle the case where the Using statement is not successful in acquiring a resource, you can test to see if resourcename is Nothing.
Structured Exception Handling Instead of a Using Block
If you need finer control over the acquisition of the resources, or you need additional code in the Finally block, you can rewrite the Using block as a Try...Finally construction. The following example shows skeleton Try and Using constructions that are equivalent in the acquisition and disposal of resource.
Using resource As New resourceType
' Insert code to work with resource.
End Using
' THE FOLLOWING TRY CONSTRUCTION IS EQUIVALENT TO THE USING BLOCK
Dim resource As New resourceType
Try
' Insert code to work with resource.
Catch ex As Exception
' Insert code to process exception.
Finally
' Insert code to do additional processing before disposing of resource.
resource.Dispose()
End Try
Note
The code inside the Using block should not assign the object in resourcename to another variable. When you exit the Using block, the resource is disposed, and the other variable cannot access the resource to which it points.
Example
The following example uses a Using block to acquire a new font. This guarantees that the system calls the Dispose method on the font when your code exits the block.
Public Sub setbigbold(ByVal c As Control)
Using nf As New System.Drawing.Font("Arial", 12.0F, _
System.Drawing.FontStyle.Bold)
c.Font = nf
c.Text = "This is 12-point Arial bold"
End Using
End Sub
See Also
Tasks
How to: Dispose of a System Resource