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
Term | Definition |
---|---|
resourcelist |
Required if you do not supply resourceexpression . List of one or more system resources that this Using block controls, separated by commas. |
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
Term | Definition |
---|---|
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. |
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. However, you can still use a Using
block to force the disposal of a managed resource instead of waiting for the garbage collector.
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 theUsing
statement. If you supplyresourceexpression
, you must acquire the resource before passing control to theUsing
statement.Usage means accessing the resources and performing actions with them. The statements between
Using
andEnd 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 resources. TheEnd Using
statement disposes of the resources under theUsing
block's control.
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.
If resourcename
is Nothing
, no call to Dispose is made, and no exception is thrown.
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
.
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
' For the acquisition and disposal of resource, the following
' Try construction is equivalent to the Using block.
Dim resource As New resourceType
Try
' Insert code to work with resource.
Finally
If resource IsNot Nothing Then
resource.Dispose()
End If
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.
The following example creates a file that is named log.txt and writes two lines of text to the file. The example also reads that same file and displays the lines of text:
Because the TextWriter and TextReader classes implement the IDisposable interface, the code can use Using
statements to ensure that the file is correctly closed after the write and read operations.
Private Sub WriteFile()
Using writer As System.IO.TextWriter = System.IO.File.CreateText("log.txt")
writer.WriteLine("This is line one.")
writer.WriteLine("This is line two.")
End Using
End Sub
Private Sub ReadFile()
Using reader As System.IO.TextReader = System.IO.File.OpenText("log.txt")
Dim line As String
line = reader.ReadLine()
Do Until line Is Nothing
Console.WriteLine(line)
line = reader.ReadLine()
Loop
End Using
End Sub
.NET feedback
.NET is an open source project. Select a link to provide feedback: