NET Event Guidelines

C# allows you to write any type of event that you desire. However, for component compatibility with the .NET Framework, you will need to follow the guidelines that Microsoft has established for this purpose. At the core of these guidelines is the requirement that event handlers have two parameters. The first is a reference to the object that generated the event. The second is a parameter of type EventArgs that contains any other information required by the handler. Thus, .NET-compatible event handlers will have this general form:

 void handler(object source, EventArgs arg) {   // ... }

Typically, the source parameter is passed this by the calling code. The EventArgs parameter contains additional information and can be ignored if it is not needed.

The EventArgs class itself does not contain fields in which you pass additional data to a handler. Instead, EventArgs is used as a base class from which you will derive a class that contains the necessary fields. EventArgs does include one static field called Empty, which obtains an EventArgs object that contains no data.

Here is an example that creates a .NET-compatible event:

 // A .NET-compatible event. using System; // Derive a class from EventArgs. class MyEventArgs : EventArgs {   public int eventnum; } // Declare a delegate for an event. delegate void MyEventHandler(object source, MyEventArgs arg); // Declare an event class. class MyEvent {   static int count = 0;   public event MyEventHandler SomeEvent;      // This fires SomeEvent.   public void OnSomeEvent() {     MyEventArgs arg = new MyEventArgs();     if(SomeEvent != null) {       arg.eventnum = count++;       SomeEvent(this, arg);     }   } } class X {   public void handler(object source, MyEventArgs arg) {     Console.WriteLine("Event " + arg.eventnum +                       " received by an X object.");     Console.WriteLine("Source is " + source);     Console.WriteLine();   } } class Y {   public void handler(object source, MyEventArgs arg) {     Console.WriteLine("Event " + arg.eventnum +                       " received by a Y object.");     Console.WriteLine("Source is " + source);     Console.WriteLine();   } } class EventDemo6 {   public static void Main() {     X ob1 = new X();     Y ob2 = new Y();     MyEvent evt = new MyEvent();     // Add handler() to the event list.     evt.SomeEvent += ob1.handler;     evt.SomeEvent += ob2.handler;     // Fire the event.     evt.OnSomeEvent();     evt.OnSomeEvent();   } }

Here is the output:

 Event 0 received by an X object. Source is MyEvent Event 0 received by a Y object. Source is MyEvent Event 1 received by an X object. Source is MyEvent Event 1 received by a Y object. Source is MyEvent

In this example, MyEventArgs is derived from EventArgs. MyEventArgs adds just one field of its own: eventnum. The event handler delegate MyEventHandler now takes the two parameters required by the .NET Framework. As explained, the first is an object reference to the generator of the event. The second is a reference to EventArgs or a class derived from EventArgs. The event handlers in the X and Y classes, handler( ), also have the same types of parameters.

Inside MyEvent, a MyEventHandler called SomeEvent is declared. In the OnSomeEvent( ) method, SomeEvent is called with the first argument being this, and the second argument being a MyEventArgs instance. Thus, the proper arguments are passed to MyEventHandler to fulfill the requirements for .NET compatibility.

Using EventHandler

For many events, the EventArgs parameter is unused. To help facilitate the creation of code in these situations, the .NET Framework includes a built-in delegate type called EventHandler, which can be used to declare event handlers in which no extra information is needed. Here is an example that uses EventHandler:

 // Use the built-in EventHandler delegate. using System; // Declare an event class. class MyEvent {   public event EventHandler SomeEvent; // uses EventHandler delegate   // This is called to fire SomeEvent.   public void OnSomeEvent() {     if(SomeEvent != null)       SomeEvent(this, EventArgs.Empty);   } } class EventDemo {   static void handler(object source, EventArgs arg) {     Console.WriteLine("Event occurred");     Console.WriteLine("Source is " + source);   }   public static void Main() {     MyEvent evt = new MyEvent();     // Add handler() to the event list.     evt.SomeEvent += handler;     // Fire the event.     evt.OnSomeEvent();   } }

In this case, the EventArgs parameter is unused and is passed the placeholder object EventArgs.Empty. The output is shown here:

 Event occurred Source is MyEvent