Export (0) Print
Expand All

FirstChanceExceptionEventArgs Class

Provides data for the notification event that is raised when a managed exception first occurs, before the common language runtime begins searching for event handlers.

System.Object
  System.EventArgs
    System.Runtime.ExceptionServices.FirstChanceExceptionEventArgs

Namespace:  System.Runtime.ExceptionServices
Assembly:  mscorlib (in mscorlib.dll)

'Declaration
Public Class FirstChanceExceptionEventArgs _
	Inherits EventArgs

The FirstChanceExceptionEventArgs type exposes the following members.

  NameDescription
Public methodFirstChanceExceptionEventArgsInitializes a new instance of the FirstChanceExceptionEventArgs class with a specified exception.
Top

  NameDescription
Public propertyExceptionThe managed exception object that corresponds to the exception thrown in managed code.
Top

  NameDescription
Public methodEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Top

This class provides the exception handler for the AppDomain.FirstChanceException event with access to the exception.

The following example creates a series of application domains named Child_0 through Child_3, with a Worker object in each application domain. Each Worker object has a reference to the Worker object in the next application domain, except for the Worker in the last application domain. The FirstChanceException event is handled in all application domains except Child_1.

When the application domains have been created, the default application domain calls the TestException method for the first child application domain. Each Worker object calls the TestException method for the next, until the last Worker throws an exception that is either handled or unhandled. Thus, the current thread passes through all the application domains, and TestException is added to the stack in each application domain.

When the last Worker object handles the exception, the FirstChanceException event is raised only in the last application domain. The other application domains never get a chance to handle the exception, so the event is not raised.

When the last Worker object does not handle the exception, the FirstChanceException event is raised in each application domain that has an event handler. After each event handler has finished, the stack continues to unwind until the exception is caught by the default application domain.

NoteNote

To see how the stack display grows as the event is raised closer and closer to the default application domain, change e.Exception.Message to e.Exception in the FirstChanceHandler event handlers. Notice that when TestException is called across application domain boundaries, it appears twice: once for the proxy and once for the stub.

Imports System.Reflection
Imports System.Runtime.ExceptionServices

Class Example

    Shared Sub Main()

        AddHandler AppDomain.CurrentDomain.FirstChanceException, AddressOf FirstChanceHandler

        ' Create a set of application domains, with a Worker object in each one. 
        ' Each Worker object creates the next application domain. 
        Dim ad As AppDomain = AppDomain.CreateDomain("AD0")
        Dim w As Worker = CType(ad.CreateInstanceAndUnwrap(
                                GetType(Worker).Assembly.FullName, "Worker"),
                                Worker)
        w.Initialize(0, 3)

        Console.WriteLine(vbCrLf & "The last application domain throws an exception and catches it:")
        Console.WriteLine()
        w.TestException(true)

        Try
            Console.WriteLine(vbCrLf & 
                "The last application domain throws an exception and does not catch it:")
            Console.WriteLine()
            w.TestException(false) 

        Catch ex As ArgumentException

            Console.WriteLine("ArgumentException caught in {0}: {1}", 
                AppDomain.CurrentDomain.FriendlyName, ex.Message)
        End Try 
    End Sub 

    Shared Sub FirstChanceHandler(ByVal source As Object, 
                                  ByVal e As FirstChanceExceptionEventArgs)

        Console.WriteLine("FirstChanceException event raised in {0}: {1}",
            AppDomain.CurrentDomain.FriendlyName, e.Exception.Message)
    End Sub 
End Class 

Public Class Worker
    Inherits MarshalByRefObject

    Private ad As AppDomain = Nothing 
    Private w As Worker = Nothing 

    Public Sub Initialize(ByVal count As Integer, ByVal max As Integer)

        ' Handle the FirstChanceException event in all application domains except 
        ' AD1. 
        If count <> 1

            AddHandler AppDomain.CurrentDomain.FirstChanceException, AddressOf FirstChanceHandler

        End If 

        ' Create another application domain, until the maximum is reached. 
        ' Field w remains Nothing in the last application domain, as a signal  
        ' to TestException().  
        If count < max
            Dim nextAD As Integer = count + 1
            ad = AppDomain.CreateDomain("AD" & nextAD)
            w = CType(ad.CreateInstanceAndUnwrap(
                      GetType(Worker).Assembly.FullName, "Worker"),
                      Worker)
            w.Initialize(nextAD, max)
        End If 
    End Sub 

    Public Sub TestException(ByVal handled As Boolean)

        ' As long as there is another application domain, call TestException() on 
        ' its Worker object. When the last application domain is reached, throw a 
        ' handled or unhandled exception. 
        If w IsNot Nothing

            w.TestException(handled)

        Else If handled

            Try 
                Throw New ArgumentException("Thrown in " & AppDomain.CurrentDomain.FriendlyName)

            Catch ex As ArgumentException

                Console.WriteLine("ArgumentException caught in {0}: {1}", 
                    AppDomain.CurrentDomain.FriendlyName, ex.Message)
            End Try 
        Else 

            Throw New ArgumentException("Thrown in " & AppDomain.CurrentDomain.FriendlyName)
        End If 
    End Sub 

    Shared Sub FirstChanceHandler(ByVal source As Object, 
                                  ByVal e As FirstChanceExceptionEventArgs)

        Console.WriteLine("FirstChanceException event raised in {0}: {1}",
            AppDomain.CurrentDomain.FriendlyName, e.Exception.Message)
    End Sub 
End Class 

' This example produces output similar to the following: 

'The last application domain throws an exception and catches it: 

'FirstChanceException event raised in AD3: Thrown in AD3 
'ArgumentException caught in AD3: Thrown in AD3 

'The last application domain throws an exception and does not catch it: 

'FirstChanceException event raised in AD3: Thrown in AD3 
'FirstChanceException event raised in AD2: Thrown in AD3 
'FirstChanceException event raised in AD0: Thrown in AD3 
'FirstChanceException event raised in Example.exe: Thrown in AD3 
'ArgumentException caught in Example.exe: Thrown in AD3

.NET Framework

Supported in: 4.5.2, 4.5.1, 4.5, 4

.NET Framework Client Profile

Supported in: 4

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Show:
© 2014 Microsoft