.NET 1.1+

C# Events

The fifteenth part of the C# Object-Oriented Programming tutorial explains the use of events. Events can be added to a class to allow it to indicate when a specific action has occurred or is about to occur. Subscribers may then react to the event.

What is an Event?

In the first fourteen parts of the C# Object-Oriented Programming tutorial we have described the creation of classes with methods, properties and other structures. Each of these is similar because it allows a direct command to be given to a class or object within the flow of a program. This is similar to the early programming languages, which simply processed a sequence of commands and loops until complete.

The sequential or procedural method of programming is limited to this type of processing. However, C#'s object-oriented approach is also event-driven. This means that as activities occur, a class may raise events to indicate the action that happened and to pass related information to other classes that have subscribed to the event. These may be used for various purposes including indicating the progress of a long-running process.

A key advantage of using events is that a class that publishes an event does not need to know the details of the subscribers at design-time. As events are based upon delegates, the subscribers are only added when the program is running.

Creating an Event

There are three parts to creating an event handler within a class. Firstly a delegate is required. The delegate is used to hold the details of the subscribers to the event. Secondly, a public event is created. This event is visible externally to the class and used for creating the event subscriptions. It is also the member that is visible using Visual Studio's Intellisense feature. Finally, a method is created within the class. The method contains the code that fires the event. Each of these three elements is described in the following sections.

To provide an example of the use of events, we will create a new program containing a class that represents a car. When the car's speed exceeds a safety limit, an event will be fired. To begin, create a new console application named "EventDemo". Add a class file named "Car" to the project and add the following code to the class to create a read-only Speed property and an Accelerate method. The _safetySpeed variable holds the maximum speed permitted and will be used later.

class Car
{
    private int _speed = 0;
    private int _safetySpeed = 70;

    public int Speed
    {
        get
        {
            return _speed;
        }
    }

    public void Accelerate(int mph)
    {
        _speed += mph;
    }
}

Creating the Delegate

The delegate for an event is declared using the standard syntax for any delegate. However, it should be declared with a data type of void as events are multicasting. This means that multiple subscribers can be attached to a single event with each being notified of the event in turn.

The delegate's signature is important as this is the signature that subscribers will see. To comply with the expected standards, the signature should contain two parameters. The first parameter should be an object named 'source'. This will contain a reference to the object that raised an event. The second parameter should be of the type EventArgs and should be named 'e'. EventArgs is a special class that can be derived from to create custom classes for passing information when an event fires. This is described later in this article.

In this example we will add an event to the Car class that is raised when the car exceeds the safety limit speed. To create the delegate for this event, add the following code to the namespace (outside of the class definition).