Export (0) Print
Expand All

How to: Receive First-Chance Exception Notifications

The FirstChanceException event of the AppDomain class lets you receive a notification that an exception has been thrown, before the common language runtime has begun searching for exception handlers.

The event is raised at the application domain level. A thread of execution can pass through multiple application domains, so an exception that is unhandled in one application domain could be handled in another application domain. The notification occurs in each application domain that has added a handler for the event, until an application domain handles the exception.

The procedures and examples in this article show how to receive first-chance exception notifications in a simple program that has one application domain, and in an application domain that you create.

For a more complex example that spans several application domains, see the example for the FirstChanceException event.

In the following procedure, the entry point for the application, the Main() method, runs in the default application domain.

To demonstrate first-chance exception notifications in the default application domain

  1. Define an event handler for the FirstChanceException event, using a lambda function, and attach it to the event. In this example, the event handler prints the name of the application domain where the event was handled and the exception's Message property.

    using System;
    using System.Runtime.ExceptionServices;
    
    class Example
    {
        static void Main()
        {
            AppDomain.CurrentDomain.FirstChanceException += 
                (object source, FirstChanceExceptionEventArgs e) =>
                {
                    Console.WriteLine("FirstChanceException event raised in {0}: {1}",
                        AppDomain.CurrentDomain.FriendlyName, e.Exception.Message);
                };
    
  2. Throw an exception and catch it. Before the runtime locates the exception handler, the FirstChanceException event is raised and displays a message. This message is followed by the message that is displayed by the exception handler.

    try
    {
        throw new ArgumentException("Thrown in " + AppDomain.CurrentDomain.FriendlyName);
    }
    catch (ArgumentException ex)
    {
        Console.WriteLine("ArgumentException caught in {0}: {1}", 
            AppDomain.CurrentDomain.FriendlyName, ex.Message);
    }
    
  3. Throw an exception, but do not catch it. Before the runtime looks for an exception handler, the FirstChanceException event is raised and displays a message. There is no exception handler, so the application terminates.

            throw new ArgumentException("Thrown in " + AppDomain.CurrentDomain.FriendlyName);
        }
    }
    

    The code that is shown in the first three steps of this procedure forms a complete console application. The output from the application varies, depending on the name of the .exe file, because the name of the default application domain consists of the name and extension of the .exe file. See the following for sample output.

    /* This example produces output similar to the following:
    
    FirstChanceException event raised in Example.exe: Thrown in Example.exe
    ArgumentException caught in Example.exe: Thrown in Example.exe
    FirstChanceException event raised in Example.exe: Thrown in Example.exe
    
    Unhandled Exception: System.ArgumentException: Thrown in Example.exe
       at Example.Main()
     */
    

If your program contains more than one application domain, you can choose which application domains receive notifications.

To receive first-chance exception notifications in an application domain that you create

  1. Define an event handler for the FirstChanceException event. This example uses a static method (Shared method in Visual Basic) that prints the name of the application domain where the event was handled and the exception's Message property.

    static void FirstChanceHandler(object source, FirstChanceExceptionEventArgs e)
    {
        Console.WriteLine("FirstChanceException event raised in {0}: {1}",
            AppDomain.CurrentDomain.FriendlyName, e.Exception.Message);
    }
    
  2. Create an application domain and add the event handler to the FirstChanceException event for that application domain. In this example, the application domain is named AD1.

    AppDomain ad = AppDomain.CreateDomain("AD1");
    ad.FirstChanceException += FirstChanceHandler;
    

    You can handle this event in the default application domain in the same way. Use the static (Shared in Visual Basic) AppDomain.CurrentDomain property in Main() to get a reference to the default application domain.

To demonstrate first-chance exception notifications in the application domain

  1. Create a Worker object in the application domain that you created in the previous procedure. The Worker class must be public, and must derive from MarshalByRefObject, as shown in the complete example at the end of this article.

    Worker w = (Worker) ad.CreateInstanceAndUnwrap(
                            Assembly.GetExecutingAssembly().FullName, "Worker");
    
  2. Call a method of the Worker object that throws an exception. In this example, the Thrower method is called twice. The first time, the method argument is true, which causes the method to catch its own exception. The second time, the argument is false, and the Main() method catches the exception in the default application domain.

    // The worker throws an exception and catches it.
    w.Thrower(true);
    
    try
    {
        // The worker throws an exception and doesn't catch it.
        w.Thrower(false);
    }
    catch (ArgumentException ex)
    {
        Console.WriteLine("ArgumentException caught in {0}: {1}", 
            AppDomain.CurrentDomain.FriendlyName, ex.Message);
    }
    
  3. Place code in the Thrower method to control whether the method handles its own exception.

    if (catchException)
    {
        try
        {
            throw new ArgumentException("Thrown in " + AppDomain.CurrentDomain.FriendlyName);
        }
        catch (ArgumentException ex)
        {
            Console.WriteLine("ArgumentException caught in {0}: {1}", 
                AppDomain.CurrentDomain.FriendlyName, ex.Message);
        }
    }
    else
    {
        throw new ArgumentException("Thrown in " + AppDomain.CurrentDomain.FriendlyName);
    }
    

The following example creates an application domain named AD1 and adds an event handler to the application domain's FirstChanceException event. The example creates an instance of the Worker class in the application domain, and calls a method named Thrower that throws an ArgumentException. Depending on the value of its argument, the method either catches the exception or fails to handle it.

Each time the Thrower method throws an exception in AD1, the FirstChanceException event is raised in AD1, and the event handler displays a message. The runtime then looks for an exception handler. In the first case, the exception handler is found in AD1. In the second case, the exception is unhandled in AD1, and instead is caught in the default application domain.

Note Note

The name of the default application domain is the same as the name of the executable.

If you add a handler for the FirstChanceException event to the default application domain, the event is raised and handled before the default application domain handles the exception. To see this, add the C# code AppDomain.CurrentDomain.FirstChanceException += FirstChanceException; (in Visual Basic, AddHandler AppDomain.CurrentDomain.FirstChanceException, FirstChanceException) at the beginning of Main().

using System;
using System.Reflection;
using System.Runtime.ExceptionServices;

class Example
{
    static void Main()
    {
        // To receive first chance notifications of exceptions in  
        // an application domain, handle the FirstChanceException 
        // event in that application domain.
        AppDomain ad = AppDomain.CreateDomain("AD1");
        ad.FirstChanceException += FirstChanceHandler;

        // Create a worker object in the application domain.
        Worker w = (Worker) ad.CreateInstanceAndUnwrap(
                                Assembly.GetExecutingAssembly().FullName, "Worker");

        // The worker throws an exception and catches it.
        w.Thrower(true);

        try
        {
            // The worker throws an exception and doesn't catch it.
            w.Thrower(false);
        }
        catch (ArgumentException ex)
        {
            Console.WriteLine("ArgumentException caught in {0}: {1}", 
                AppDomain.CurrentDomain.FriendlyName, ex.Message);
        }
    }

    static void FirstChanceHandler(object source, FirstChanceExceptionEventArgs e)
    {
        Console.WriteLine("FirstChanceException event raised in {0}: {1}",
            AppDomain.CurrentDomain.FriendlyName, e.Exception.Message);
    }
}

public class Worker : MarshalByRefObject
{
    public void Thrower(bool catchException)
    {
        if (catchException)
        {
            try
            {
                throw new ArgumentException("Thrown in " + AppDomain.CurrentDomain.FriendlyName);
            }
            catch (ArgumentException ex)
            {
                Console.WriteLine("ArgumentException caught in {0}: {1}", 
                    AppDomain.CurrentDomain.FriendlyName, ex.Message);
            }
        }
        else
        {
            throw new ArgumentException("Thrown in " + AppDomain.CurrentDomain.FriendlyName);
        }
    }
}

/* This example produces output similar to the following:

FirstChanceException event raised in AD1: Thrown in AD1
ArgumentException caught in AD1: Thrown in AD1
FirstChanceException event raised in AD1: Thrown in AD1
ArgumentException caught in Example.exe: Thrown in AD1
 */

  • This example is a command-line application. To compile and run this code in Visual Studio 2010, add the C# code Console.ReadLine(); (in Visual Basic, Console.ReadLine()) at the end of Main(), to prevent the command window from closing before you can read the output.

Show:
© 2015 Microsoft