Try...Catch...Finally Statement (Visual Basic)

Provides a way to handle some or all possible errors that may occur in a given block of code, while still running code.

Try
    [ tryStatements ]
    [ Exit Try ]
[ Catch [ exception [ As type ] ] [ When expression ]
    [ catchStatements ]
    [ Exit Try ] ]
[ Catch ... ]
[ Finally
    [ finallyStatements ] ]
End Try

Parts

Term	Definition
tryStatements	Optional. Statement(s) where an error can occur. Can be a compound statement.
Catch	Optional. Multiple Catch blocks permitted. If an exception occurs when processing the Try block, each Catch statement is examined in textual order to determine whether it handles the exception, with exception representing the exception that has been thrown.
exception	Optional. Any variable name. The initial value of exception is the value of the thrown error. Used with Catch to specify the error caught. If omitted, the Catch statement catches any exception.
type	Optional. Specifies the type of class filter. If the value of exception is of the type specified by type or of a derived type, the identifier becomes bound to the exception object.
When	Optional. A Catch statement with a When clause catches exceptions only when expression evaluates to True. A When clause is applied only after checking the type of the exception, and expression may refer to the identifier representing the exception.
expression	Optional. Must be implicitly convertible to Boolean. Any expression that describes a generic filter. Typically used to filter by error number. Used with When keyword to specify circumstances under which the error is caught.
catchStatements	Optional. Statement(s) to handle errors that occur in the associated Try block. Can be a compound statement.
Exit Try	Optional. Keyword that breaks out of the Try...Catch...Finally structure. Execution resumes with the code immediately following the End Try statement. The Finally statement will still be executed. Not allowed in Finally blocks.
Finally	Optional. A Finally block is always executed when execution leaves any part of the Try...Catch statement.
finallyStatements	Optional. Statement(s) that are executed after all other error processing has occurred.
End Try	Terminates the Try...Catch...Finally structure.

Remarks

If you expect that a particular exception might occur during a particular section of code, put the code in a Try block and use a Catch block to retain control and handle the exception if it occurs.

A Try…Catch statement consists of a Try block followed by one or more Catch clauses, which specify handlers for various exceptions. When an exception is thrown in a Try block, Visual Basic looks for the Catch statement that handles the exception. If a matching Catch statement is not found, Visual Basic examines the method that called the current method, and so on up the call stack. If no Catch block is found, Visual Basic displays an unhandled exception message to the user and stops execution of the program.

You can use more than one Catch statement in a Try…Catch statement. If you do this, the order of the Catch clauses is significant because they are examined in order. Catch the more specific exceptions before the less specific ones.

The following Catch statement conditions are the least specific, and will catch all exceptions that derive from the Exception class. You should ordinarily use one of these variations as the last Catch block in the Try...Catch...Finally structure, after catching all the specific exceptions you expect. Control flow can never reach a Catch block that follows either of these variations.

• The type is Exception, for example: Catch ex As Exception

• The statement has no exception variable, for example: Catch

When a Try…Catch…Finally statement is nested in another Try block, Visual Basic first examines each Catch statement in the innermost Try block. If no matching Catch statement is found, the search proceeds to the Catch statements of the outer Try…Catch…Finally block.

Local variables from a Try block are not available in a Catch block because they are separate blocks. If you want to use a variable in more than one block, declare the variable outside the Try...Catch...Finally structure.

Tip

The Try…Catch…Finally statement is available as an IntelliSense code snippet. In the Code Snippets Manager, expand Code Patterns - If, For Each, Try Catch, Property, etc, and then Error Handling (Exceptions). For more information, see How to: Insert IntelliSense Code Snippets.

Finally Block

If you have one or more statements that must run before you exit the Try structure, use a Finally block. Control passes to the Finally block just before it passes out of the Try…Catch structure. This is true even if an exception occurs anywhere inside the Try structure.

A Finally block is useful for running any code that must execute even if there is an exception. Control is passed to the Finally block regardless of how the Try...Catch block exits.

The code in a Finally block runs even if your code encounters a Return statement in a Try or Catch block. Control does not pass from a Try or Catch block to the corresponding Finally block in the following cases:

• An End Statement is encountered in the Try or Catch block.

• A StackOverflowException is thrown in the Try or Catch block.

It is not valid to explicitly transfer execution into a Finally block. It is not valid to transfer execution out of a Finally block except through an exception.

If a Try statement does not contain at least one Catch block, it must contain a Finally block.

Tip

If you do not have to catch specific exceptions, the Using statement behaves like a Try…Finally block, and guarantees disposal of the resources, regardless of how you exit the block. This is true even with an unhandled exception. For more information, see Using Statement (Visual Basic).

Exception Argument

The Catch block exception argument is an instance of the Exception class or a class that derives from the Exception class. The Exception class instance corresponds to the error that occurred in the Try block.

The properties of the Exception object help to identify the cause and location of an exception. For example, the StackTrace property lists the called methods that led to the exception, helping you find where the error occurred in the code. Message returns a message that describes the exception. HelpLink returns a link to an associated Help file. InnerException returns the Exception object that caused the current exception, or it returns Nothing if there is no original Exception.

Considerations When Using a Try…Catch Statement

Use a Try…Catch statement only to signal the occurrence of unusual or unanticipated program events. Reasons for this include the following:

• Catching exceptions at runtime creates additional overhead, and is likely to be slower than pre-checking to avoid exceptions.

• If a Catch block is not handled correctly, the exception might not be reported correctly to users.

• Exception handling makes a program more complex.

You do not always need a Try…Catch statement to check for a condition that is likely to occur. The following example checks whether a file exists before trying to open it. This reduces the need for catching an exception thrown by the OpenText method.

Private Sub TextFileExample(ByVal filePath As String)

    ' Verify that the file exists.
    If System.IO.File.Exists(filePath) = False Then
        Console.Write("File Not Found: " & filePath)
    Else
        ' Open the text file and display its contents.
        Dim sr As System.IO.StreamReader =
            System.IO.File.OpenText(filePath)

        Console.Write(sr.ReadToEnd)

        sr.Close()
    End If
End Sub

Ensure that code in Catch blocks can properly report exceptions to users, whether through thread-safe logging or appropriate messages. Otherwise, exceptions might remain unknown.

Partial-Trust Situations

In partial-trust situations, such as an application hosted on a network share, Try...Catch...Finally does not catch security exceptions that occur before the method that contains the call is invoked. The following example, when you put it on a server share and run from there, produces the error "System.Security.SecurityException: Request Failed." For more information about security exceptions, see the SecurityException class.

Try
    Process.Start("https://www.microsoft.com")
Catch ex As Exception
    MsgBox("Can't load Web page" & vbCrLf & ex.Message)
End Try

In such a partial-trust situation, you have to put the Process.Start statement in a separate Sub. The initial call to the Sub will fail. This enables Try...Catch to catch it before the Sub that contains Process.Start is started and the security exception produced.

Example

The following example illustrates the structure of the Try...Catch...Finally statement.

Public Sub TryExample()
    ' Declare variables.
    Dim x As Integer = 5
    Dim y As Integer = 0

    ' Set up structured error handling.
    Try
        ' Cause a "Divide by Zero" exception.
        x = x \ y

        ' This statement does not execute because program
        ' control passes to the Catch block when the
        ' exception occurs.
        MessageBox.Show("end of Try block")
    Catch ex As Exception
        ' Show the exception's message.
        MessageBox.Show(ex.Message)

        ' Show the stack trace, which is a list of methods
        ' that are currently executing.
        MessageBox.Show("Stack Trace: " & vbCrLf & ex.StackTrace)
    Finally
        ' This line executes whether or not the exception occurs.
        MessageBox.Show("in Finally block")
    End Try
End Sub

In the following example, the CreateException method throws a NullReferenceException. The code that generates the exception is not in a Try block. Therefore, the CreateException method does not handle the exception. The RunSample method does handle the exception because the call to the CreateException method is in a Try block.

The example includes Catch statements for several types of exceptions, ordered from the most specific to the most general.

Public Sub RunSample()
    Try
        CreateException()
    Catch ex As System.IO.IOException
        ' Code that reacts to IOException.
    Catch ex As NullReferenceException
        MessageBox.Show("NullReferenceException: " & ex.Message)
        MessageBox.Show("Stack Trace: " & vbCrLf & ex.StackTrace)
    Catch ex As Exception
        ' Code that reacts to any other exception.
    End Try
End Sub

Private Sub CreateException()
    ' This code throws a NullReferenceException.
    Dim obj = Nothing
    Dim prop = obj.Name

    ' This code also throws a NullReferenceException.
    'Throw New NullReferenceException("Something happened.")
End Sub

The following example shows how to use a Catch When statement to filter on a conditional expression. If the conditional expression evaluates to True, the code in the Catch block runs.

Private Sub WhenExample()
    Dim i As Integer = 5

    Try
        Throw New ArgumentException()
    Catch e As OverflowException When i = 5
        Console.WriteLine("First handler")
    Catch e As ArgumentException When i = 4
        Console.WriteLine("Second handler")
    Catch When i = 5
        Console.WriteLine("Third handler")
    End Try
End Sub
' Output: Third handler

The following example has a Try…Catch statement that is contained in a Try block. The inner Catch block throws an exception that has its InnerException property set to the original exception. The outer Catch block reports its own exception and the inner exception.

Private Sub InnerExceptionExample()
    Try
        Try
            ' Set a reference to a StringBuilder.
            ' The exception below does not occur if the commented
            ' statement is used instead.
            Dim sb As System.Text.StringBuilder
            'Dim sb As New System.Text.StringBuilder

            ' Cause a NullReferenceException.
            sb.Append("text")
        Catch ex As Exception
            ' Throw a new exception that has the inner exception
            ' set to the original exception.
            Throw New ApplicationException("Something happened :(", ex)
        End Try
    Catch ex2 As Exception
        ' Show the exception.
        Console.WriteLine("Exception: " & ex2.Message)
        Console.WriteLine(ex2.StackTrace)

        ' Show the inner exception, if one is present.
        If ex2.InnerException IsNot Nothing Then
            Console.WriteLine("Inner Exception: " & ex2.InnerException.Message)
            Console.WriteLine(ex2.StackTrace)
        End If
    End Try
End Sub

See Also

Reference

Err

Exit Statement (Visual Basic)

On Error Statement (Visual Basic)

Exception

Throw Statement (Visual Basic)

Concepts

Best Practices for Using IntelliSense Code Snippets

Exception Handling (Task Parallel Library)

Other Resources

Structured Exception Handling in Visual Basic

Change History

Date	History	Reason
April 2011	Reorganized and added to remarks, and added examples.	Information enhancement.