C# Event Implementation Fundamentals, Best Practices and Conventions

• Download source - 12.5 KB

Introduction

Everything you need to define, implement, and understand custom events using C# is presented in this article. Toward accomplishing these objectives the fundamental building blocks that must or should be utilized are presented, in addition to event implementation best practices and conventions. This article presents both .NET 1.x and 2.0+ alternatives for publishing and subscribing to events.

While support for the implementation of custom events has been available since the 1.0 version of the .NET Framework, additional event-related support and capabilities have been added since then. Some of the new capabilities (e.g., generic System.EventHandler, anonymous methods, delegate inference, etc.) comprise shortcuts intended to make the implementation of events easier. While such techniques do facilitate quicker event implementations, presenting them before or in place of the fundamental building blocks would yield a less explicit presentation. Consequently, this article avoids such shortcuts until after the fundamental building blocks have been introduced.

Contents

1. Assumptions About the Audience
2. Terminology and Definitions
3. Delegates
   • 3.1 Definition and Usage of Delegates
   • 3.2 Why Delegates?
   • 3.3 Delegate Internals
   • 3.4 Delegates Are All The Same (there are no fundamentally differing types of delegates)
4. The Relationship Between Delegates and Events
   • 4.1 Event Handlers (in general)
   • 4.2 The Non Generic System.EventHandler Delegate
   • 4.3 The Generic System.EventHandler<TEventArgs> Delegate
5. Event Arguments (EventArgs)
   • 5.1 The Role of System.EventArgs
   • 5.2 Extending System.EventArgs
   • 5.3 The role of System.ComponentModel.CancelEventArgs
6. Event Declaration Syntax
   • 6.1 Event Declaration Syntax Alternatives
   • 6.2 Considerations For Choosing Between Field-like Syntax and Property-like Syntax
   • 6.3 Publish/Subscribe mechanism Using Delegates Without Events (never do this)
7. Event Raising Code
8. Event Subscriber Registration and Unregistration
   • 8.1 Registering A Subscriber
   • 8.2 Unregistering A Subscriber
9. Event Handling Method
10. .NET 1.x vs. 2.0+ Considerations
    • 10.1 Generics
    • 10.2 Delegate Inference
    • 10.3 Anonymous Methods
    • 10.4 Partial Classes
11. Conventions
    • 11.1 Event Publisher Conventions
    • 11.2 Event Subscriber Conventions
    • 11.3 Naming Conventions
12. Steps to Creating Custom Events
    • 12.1 Prepare the Event Publisher
    • 12.2 Prepare the Event Subscriber
13. Sample Event Implementation
    • 13.1 Sample Event Publisher Code
    • 13.2 Sample Event Subscriber Code
14. Handling Events Raised by .NET Framework Components - Walkthrough and Example
    • 14.1 FileSystemWatcher 'Deleted' Event Implementation
    • 14.2 Handling the FileSystemWatcher.Deleted Event
15. Windows Forms Events
    • 15.1 NET 1.x and 2.0+ Difference - Partial Classes
    • 15.2 Partial Classes and Windows Forms Designer Considerations For Events
    • 15.3 Walkthrough - Handling a Windows Forms Event
    • 15.4 Windows Forms and Threading Considerations
16. Cancellable Events
17. ASP.NET Web Forms Events
18. Sources
19. History

1. Assumptions About the Audience

This article assumes a working knowledge of .NET programming with C#, in addition to an understanding of Generics, which were introduced in the 2.0 version of the .NET Framework. If you do not understand Generics, this article can still be helpful as there are ways to implement events that do not rely on Generics. Both generic and non-generic event implementation techniques are presented in this article.

2. Terminology and Definitions

The literature presenting events and related concepts frequently makes use of multiple words or expressions to describe any given concept. The following list catalogs much of this terminology with brief explanations of the concepts behind the expressions.

event, pre-event, post-event, and state, change of state, and expected change of state

The term, event, typically means that a change in state of an object has occurred or is about to occur. The term is also used in reference to some activity taking place within an object or application — activity like the processing of a gesture from an end user (e.g., button clicked), or the reporting of progress during a long-running task.

The term, "state," refers to the current set of values of one or more variables in an object or application. A change in state means the value of one or more variables within an object has changed. In the event notification process, changes in state, or expected changes in state, are primary motivations for raising events. So, we have two ways to define an event relative to a change in state: immediately prior to a change in state, or immediately after a change in state. While the former are referred to as pre-events, the latter are referred to as post-events.

Post-events announce that the change in state has already occurred, and pre-events announce the fact that a change in state is about to occur. Pre-events can be implemented as cancellable — meaning that the subscriber may cancel the event before the change in state occurs, thereby preventing the change in state from occurring, or preventing the further processing of a long-running task.

event publisher, event source, subject

These are the classes or objects of which their state is of interest to other classes or objects. Event publishers maintain their internal state, and notify other classes (subscribers) through the raising of events or similar notification mechanisms.

event subscriber, sink, listener, observer

These are the classes or objects that are interested in changes in state (or expected changes in state) of the event publishers. These terms refer to the classes or objects that typically perform some action in response to the occurrence of an event.

raise, fire, or trigger an event; notification, or event notification

Event notifications (frequently expressed as, "fire an event" or "raise an event" or "trigger an event") are generally in the form of the event publisher calling a method in one or more subscribers. Consequently, the raising of an event ultimately means that code in the event publisher causes code in one or more subscribers to run.

In cases where no subscribers [to an event] have registered with the publisher, the event would not be raised.

Please note that in this article, events are described as "raised" (not "fired" or "triggered"). This convention comes from the team of developers who authored much of the .NET Framework (Cwalina and Abrams, 2006). They prefer the term, "raise," because it doesn't have the negative connotations of the expressions, "fire" or "trigger."

event data, event-related data, and event arguments ("event args")

When an event is raised, the publisher will frequently include data that gets sent to the subscribers through the event notification process. This data is presumably relevant to the particular event that was raised, and would be of interest to the event subscribers.

For example, an event can be raised when a file gets renamed. Data relevant to that particular "file renamed" event could include (1) the name of the file before the name was changed, and (2) the name of the file after the name was changed. Those file names could comprise the event data that are sent to the subscribers during the raising of the "file renamed" event.

Delegate Type, Delegates

A clear understanding of the .NET Delegates type is crucial to the understanding of events as implemented in the .NET Framework. Consequently, much of this article is dedicated to explaining the relationship between delegates and events.

Two Meanings of "Event Handler"

The literature outside of this article frequently uses the term, "event handler," in reference to either (1) the delegate upon which an event is defined (in the publisher), or (2) any method registered with the event (in the subscriber). Furthermore, Intellisense in Visual Studio refers to an event handling method (in the subscriber) as simply, "handler." For purposes of clarity, this article uses the expression, "event handler," in reference to the delegate, while using the expression,"event handling method," in reference to any method registered with an event.

To summarize; an "event handler" is the delegate upon which an event is based, while an "event handling method" is a method called in the subscriber when an event is raised.

Event handlers are delegates, although delegates are not necessarily event handlers (there are many uses of delegates beyond supporting events). Delegates are presented in more detail later in this article, but only to the extent that they are relevant to events.

.NET events and the GoF Observer pattern

Events, as implemented in the .NET Framework and as described in this article, constitute a .NET optimized implementation of the Observer Pattern that was documented by the "Gang of Four" or "GoF" (Gamma et al.1995). The .NET mechanisms used to implement events (delegates in particular) substantially reduce the amount of work required to implement the Observer pattern in .NET applications.

3. Delegates

In order to understand events, as implemented in .NET applications, one must have a clear understanding of the .NET delegate type and the role it plays in the implementation of events.

3.1 Definition and Usage of Delegates

Delegates can be understood as intelligent containers that hold references to methods, as opposed to containers that hold references to objects. Delegates can contain references to zero, one, or many methods. In order for a method to be called by a particular delegate instance, that method must be registered with the delegate instance. When registered, the method is added to the delegate's internal collection of method references (the delegate's "invocation list"). Delegates can hold references to static methods or instance methods in any class visible to the delegate instance. Delegate instances can call their referenced methods either synchronously, or asynchronously. When called asynchronously, the methods execute on a separate thread pool thread. When a delegate instance is invoked ("called"), then all methods referenced by the delegate are called automatically by the delegate.

Delegates cannot contain references to just any method. Delegates can hold references only to methods defined with a method signature that exactly matches the signature of the delegate.

Consider the following delegate declaration:

public delegate void MyDelegate(string myString);

Notice that the delegate declaration looks like a method declaration, but with no method body.

The signature of the delegate determines the signature of methods that can be referenced by the delegate. So, the sample delegate above (MyDelegate) can hold references only to methods that return void while accepting a single string argument. Consequently, the following method can be registered with an instance of MyDelegate:

private void MyMethod(string someString) 
{
   // method body here. 

}

The following methods, however, cannot be referenced by a MyDelegate instance because their signatures do not match that of MyDelegate.

private string MyOtherMethod(string someString) 
{
   // method body here. 

}

private void YetAnotherMethod(string someString, int someInt) 
{
   // method body here. 

}

After a new delegate type is declared, an instance of that delegate must be created so that methods can be registered with, and ultimately invoked by, the delegate instance.

// instantiate the delegate and register a method with the new instance. 

MyDelegate del = new MyDelegate(MyMethod);

After a delegate is instantiated, additional methods can be registered with the delegate instance, like this:

del += new MyDelegate(MyOtherMethod);

At this point, the delegate can be invoked, like this:

del("my string value");

And, because both MyMethod and MyOtherMethod are registered with the MyDelegate instance (named del), that instance will invoke both MyMethod and MyOtherMethod when the above line executes, passing each the string value, "my string value."

Delegates and Overloaded Methods

In the case of an overloaded method, only the particular overload having a signature that exactly matches the signature of the delegate can be referenced by (or registered with) the delegate. When you write code that registers an overloaded method with a delegate instance, the C# compiler will automatically select and register the particular overload with a matching signature.

So, for example, if your application declared the following delegate type...

public delegate int MyOtherDelegate(); // returns int, no parameters

... and you registered an overloaded method named MyOverloadedMethod with an instance of MyOtherDelegate, like this...

anotherDel += new MyOtherDelegate(MyOverloadedMethod);

... the C# compiler will register only the particular overload with a matching signature. Of the following two overloads, only the first would be registered with the anotherDel instance of the MyOtherDelegate type:

// requires no parameters - so can be registered with a MyOtherDelegate 

// instance. 

private int MyOverloadedMethod()
{
   // method body here.  

}
// requires a string parameter - so cannot be registered with a MyOtherDelegate instance. 

private int MyOverloadedMethod(string someString) 
{
   // method body here.  

}

A single delegate cannot selectively register or call both (multiple) overloads. If you need to call both (multiple) overloads, then you would need additional delegate types — one delegate type per signature. Your application-specific logic would then determine which delegate to invoke, and therefore which overload is called (by the delegate with the corresponding signature).

3.2 Why Delegates?

If this is your first introduction to delegates, you may be wondering, "Why bother? It's just simpler to call the method directly — so what is the benefit of going through a delegate?"

Necessary Indirection

A brief answer (to the "why bother?" question above) is that the code we write or components we use cannot always "know" which specific method to call at a particular point in time. So, one important perspective of delegates is that they provide a way for .NET components to call your code — without the .NET component having to know anything about your code beyond the method signature (as mandated by the delegate type). For example, .NET Framework components, like the Timer component, frequently need to execute code that you write. Because the Timer component cannot possibly know which specific method to call, it specifies a delegate type (and therefore signature of a method) to be invoked. Then you connect your method — with the requisite signature — to the Timer component by registering your method with a delegate instance of the delegate type expected by the Timer component. The Timer component can then run your code by invoking the delegate which, in turn, calls your method. Note that the Timer component still knows nothing about your specific method. All the Timer component knows about is the delegate. The delegate, in turn, knows about your method because you registered your method with that delegate. The end result is that the Timer component causes your method to run, but without knowing anything about your specific method.

Just like the Timer component example above, we can make use of delegates in a way that enables us to write our code without our code having to "know" the specific method that will ultimately be called at a specific point. Rather than calling a method at that point, our code can invoke a delegate instance — which, in turn, calls any methods that are registered with the delegate instance. The end result is that a compatible method is called even though the specific method to be called was not written directly into our code.

Synchronous and Asynchronous Method Invocation

All delegates inherently provide for both synchronous and asynchronous method invocation. So, another common reason to call methods via delegate instances is to invoke methods asynchronously — in which case the called method runs on a separate thread pool thread.

Event Foundation

As you'll see later in this article, delegates play an integral role in the implementation of events in the .NET Framework. In brief, delegates provide a necessary layer of indirection between event publishers and their subscribers. This indirection is necessary in order to maintain a clean separation between the publisher and subscriber(s) — meaning that subscribers can be added and removed without the publisher needing to be modified in any way. In the case of event publication, the use of a delegate makes it possible for an event publisher to know nothing about any of its subscribers while still broadcasting events and associated event data to any/all subscribers.

Other Uses

Delegates serve important roles in .NET applications beyond those already listed. Those other roles will not be further presented here because the intent of this article is to focus only on the foundational role that delegates serve in the implementation of events in .NET applications.

3.3 Delegate Internals

Declaring a Delegate Results in A New Class Being Created

A delegate declaration that you write is sufficient to define an entire and new delegate class. The C# compiler takes your delegate declaration and inserts a new delegate class in the output assembly. The name of that new class is the name of the delegate type you supply in your delegate declaration. The signature you specify in your delegate declaration becomes the signature of the methods in the new class used to call any/all of the delegate's referenced methods (specifically the Invoke and BeginInvoke methods). This new class extends (inherits) System.MulticastDelegate. So most of the methods and properties available in your new delegate class come from System.MulticastDelegate. The Invoke, BeginInvoke, and EndInvoke methods are inserted by the C# compiler when it creates the new class in the output assembly (these are the methods you can call to cause the delegate to invoke any/all referenced methods — Invoke for synchronous invocation, and BeginInvoke and EndInvoke used in asynchronous invocations).

The new class created from your delegate declaration can be understood as being a completed and full-blown MulticastDelegate implementation that has the type name you supplied in your delegate declaration, and is capable of calling methods with the specific signature that you also supplied in your delegate declaration.

As an example, when the C# compiler encounters the following delegate declaration...

public delegate string MyFabulousDelegate(int myIntParm);

... the compiler inserts a new class named MyFabulousDelegate into the output assembly. The Invoke, BeginInvoke, and EndInvoke methods of the MyFabulousDelegate class include the int parameter and returned string value in their respective method signatures.

It should be noted that MulticastDelegate is a special class in that compilers can derive from it, but you cannot derive from it explicitly. Your use of the C# delegate keyword and associated syntax is how you instruct the C# compiler to extend MulticastDelegate for your purposes.

Meaning of Multicast

The meaning of "multicast" in System.MulticastDelegate is that the delegate is capable of holding references to multiple methods — not just one method. In the case of delegate instances that hold references to multiple methods, all referenced methods are called when the delegate instance is invoked.

Delegates are Immutable

Delegate instances are immutable — meaning that once a delegate instance is created, it cannot be modified. So, when you register a method with a delegate, what is happening is that a new delegate instance is created that includes the additional method in its invocation list. If you unregister a method from a delegate instance, a new delegate instance is returned that has the unregistered method omitted from its invocation list. If you were to create a new object variable of a particular delegate type, then set it equal to an existing delegate instance (of that particular type), you would get a complete and separate copy of the delegate. Modifications to the copy (e.g., registering an additional method) would affect only the copy. The invocation list of the original instance would remain unchanged.

Delegates are not Function Pointers

Finally, C and C++ programmers will recognize that delegates are similar to C-style function pointers. An important difference, though, is that a delegate is not simply a pointer to a raw memory address. Instead, delegate instances are type-safe objects that are managed by the .NET CLR and that specifically reference one or more "methods" (as opposed to memory addresses).

3.4 Delegates Are All The Same (there are no fundamentally differing types of delegates)

These statements are all true:
"If you've seen one delegate, you've seen them all."
or
"All delegates are created equal."
or
"A delegate is a delegate is a delegate."

When you read about different "types" of delegates, you should understand that, internally, all delegates are the same. This is true for delegates provided by the .NET Framework and for delegates you create for your own purposes. To say "they are all the same" specifically means that all delegates (1) inherit from System.MulticastDelegate, which in turn inherits from System.Delegate; and (2) provide the same set of members, including the Invoke, BeginInvoke, and EndInvoke() methods, etc.

What differentiates delegate types is nothing more than:

1. The type name of the delegate.
2. The signature of the delegate — including return type and number and types of parameters.
3. Intended usage or role of the delegate.

Take, for example, the generic Predicate delegate (System.Predicate<T>). Here is what makes it a "Predicate delegate":

1. The type name: Predicate
2. The signature: returns bool, accepts a single object typed parameter for which the type, being generic, can be specified at design time.
3. Intended usage or role: this delegate will reference a method that defines a set of criteria and determines whether the specified object meets those criteria.

Beyond the type name, signature, and intended usage, the Predicate<T> delegate has the same set of members that any other delegate has, including Invoke, BeginInvoke, etc. Consequently, this is what is meant by the statement, "delegates are all the same."

To be clear, it is not the case that the Predicate<T> delegate has any additional methods or properties that help it to fulfill its intended role. If some delegates had properties or methods that other delegates do not have, then those delegates would have different or unique capabilities and we therefore would not be able to say they are all the same.

Regarding the intended usage perspective; you are free to use any delegate for purposes not intended by the delegate's creators — as delegates are not tied to any particular usage. You could, for example, use a Predicate<T> delegate to call any method that returns bool and accepts a single object typed parameter — even if those methods do not determine whether the specified object meets any criteria (which is the intended usage of the Predicate<T> delegate). Granted, you should not use delegates for purposes other than those which they are intended to serve, as much of the value in the .NET Framework providing pre-built delegates (like Predicate<T>) is that we can understand the role they play without having to dig through a bunch of code to find out what they are actually doing.

The name of a delegate type communicates its intended role in your code. So be sure to use the appropriate delegate type, or create your own with an informative type name, even if another delegate with the requisite signature — but a potentially misleading name given your particular usage — is available.

4. The Relationship Between Delegates and Events

Events in .NET programming are based on delegates. Specifically, an event can be understood as providing a conceptual wrapper around a particular delegate. The event then controls access to that underlying delegate. When a client subscribes to an event, the event ultimately registers the subscribing method with the underlying delegate. Then, when the event is raised, the underlying delegate invokes each method that is registered with it (the delegate). In the context of events, then, delegates act as intermediaries between the code that raises events and the code that executes in response — thereby decoupling event publishers from their subscribers.

Events do not, by themselves, maintain a list of subscribers. Instead, events control access to some underlying list of subscribers — and that list is typically implemented as a delegate (although other list-type objects or collections can serve in place of a delegate).

4.1 Event Handlers (in general)

A delegate that exists in support of an event is referred to as an "event handler". To be clear, an "event handler" is a delegate, although delegates are frequently not event handlers.

Unfortunately, many authors writing about events use the term, "event handler", in reference to both (1) the delegate upon which an event is based, and (2) a method called by the delegate when the event is raised. In order to avoid confusion resulting from this state of affairs, this article uses the expression, "event handler," only in reference to the delegate, while using the expression, "event handling method," in reference to any method registered with the delegate.

Custom Event Handlers

You can define your own event handlers (delegates), or you can use one of the event handlers provided by the .NET Framework (i.e., System.EventHandler, or the generic System.EventHandler<TEventArgs>). The following sample event declaration make use of a custom event handler rather than using a Framework-provided event handler.

Consider the following:

Line 1: public delegate void MyDelegate(string whatHappened);
Line 2: public event MyDelegate MyEvent;

Line 1 declares a delegate type for which any method can be assigned — provided that the method returns void and accepts a single string argument:

• public — scope specifying that objects outside of our class can reference the delegate. If the delegate type is declared within the event publishing class, then it will need to be publicly scoped so that event subscribers can see it and declare instances of it with which to register their event handling methods (more on this later).
• delegate — keyword used to declare custom delegates in the .NET Framework.
• void — return type. This is part of the delegate signature, and therefore the return type that registering methods must specify.
• MyDelegate — type name of the delegate.
• (string whatHappened) — the rest of the signature. Any method that registers with the event must accept a single string argument (in addition to returning void).

Line 2 declares an event in terms of the delegate type. Notice that the event (which is named MyEvent) is declared very much like a method declaration — but with its data type specified as the delegate type:

• public — scope specifying that objects outside of our class can subscribe to the event.
• event — keyword used to define the event.
• MyDelegate — data type of the event (this is the custom delegate type defined in Line 1.)
• MyEvent — name of the event.

The delegate declared in Line 1 is just an ordinary delegate (as are all delegates), and can be used for any purpose delegates can fulfill. Line 2 (i.e., the usage of the delegate type) is what turns that delegate into an event handler. In order to communicate that a particular delegate type is being used as an event handler, a naming convention has emerged whereby the delegate type name ends with "Handler" (more on this later).

Standardized Event Handlers

While you can create your own event handlers (and sometimes you might need to), you should use one of the EventHandler delegates provided by the .NET Framework in cases where one of the Framework's event handlers would work with your particular event implementation. Many events make use of event handlers that can have common or identical signatures. So, rather than clutter your source code with many delegates that differ only by type name, you can/should make use of the built-in event handlers, as doing so reduces the amount of code you would need to write and maintain, and makes your code more easily understood. If someone reading your code sees you are basing an event on the System.EventHandler delegate, for example, then they automatically know a lot about your event implementation without having to look further.

4.2 The Non Generic System.EventHandler Delegate

Available in version 1.x of the .NET Framework, the non generic System.EventHandler delegate enforces the convention (described in greater detail below) of event handlers returning no value while accepting two parameters, the first being an object-typed parameter (to hold a reference to the class raising the event) and a second parameter of type System.EventArgs or a subclass thereof (to hold any event data). System.EventArgs is presented later.

This is how the .NET Framework declares the System.EventHandler delegate.

public delegate void EventHandler(object sender, EventArgs e);

4.3 The Generic System.EventHandler<TEventArgs> Delegate

Available since the 2.0 version of the .NET Framework, the generic System.EventHandler delegate enforces the same signature convention as enforced by the non generic version — but accepts a generic type parameter for the second, System.EventArgs, parameter.

The declaration of this built-in delegate enforces the constraint that the type, TEventArgs, be of type System.EventArgs (including, of course, subclasses thereof):

public delegate void EventHandler<TEventArgs>(object sender, TEventArgs e) 
where TEventArgs : EventArgs;

Now suppose you want to strongly type the sender, rather than having it typed as object. You can leverage generics to create your own generic event handler:

public delegate void MyGenericEventHandler<T, U>(T sender, 
    U u) where U : EventArgs;

You can then use this custom generic event handler to additionally specify a type-safe sender parameter (i.e., thereby limiting the type of object that can be communicated as having raised the event):

public event MyGenericEventHandler<MyPublisher, MyEventArgs> MyEvent;

The intent here would be that this event will only be raised by objects of type MyPublisher. Subscribers to the event would therefore be able to subscribe only to events published by the MyPublisher class.

5. Event Arguments (EventArgs)

Event arguments — sometimes referred to as "event args" — constitute the data sent by the publisher of an event to the subscribers during the raising of the event. Presumably this data is relevant to the occurrence of the event. For example, when a "file was just deleted" event is raised, the event arguments would likely include the name of the file before the name change, as well as the name of the file after the name was changed. The event handling methods can read the event arguments (referred to as "event data") to learn more about the event occurrence.

5.1 The Role of System.EventArgs

You have two basic alternatives for including event arguments with your events.

1. You can encapsulate all event arguments as properties of a class that derives from System.EventArgs. At runtime, an instance of that class is then sent to the event subscribers when the event is raised. The event subscribers read the event arguments as properties of that class.
2. You can avoid the use of System.EventArgs and, instead, declare individual event arguments — much as you would include arguments in a method declaration. This approach is discouraged for reasons described in section 5.2.

The first alternative listed above is strongly encouraged, and support for it is built into the .NET Framework through the System.EventArgs class. Events implemented in .NET Framework components, by convention, provide their event arguments as instances System.EventArgs, or as event-specific subclasses of System.EventArgs.

Some events carry no data. In these cases, System.EventArgs is used as a placeholder, primarily for purposes of keeping one consistent event handler signature across all events regardless of whether the events carry data or carry no data. In cases of events with no data, the event publisher sends the value, System.EventArgs.Empty, during the raising of the event.

5.2 Extending System.EventArgs

The existence of System.EventArgs and its recommended uses are in support of the event implementation conventions. It is certainly possible for a publisher of an event to specify event data without making use of System.EventArgs or any subclass thereof. In such cases, the delegate signature could specify each parameter type and name. The problem with this approach, however, is that such a signature ties the event publisher with all subscribers. If you want to modify the parameters in the future, then all subscribers would have to be modified as well. It is therefore recommended to encapsulate all event data in a subclass of System.EventArgs, as doing so reduces the amount of work required to subsequently change the number and types of values sent to event subscribers.

To illustrate the tradeoffs involved in sending a System.EventArgs subclass instance vs. sending individual event arguments, consider a scenario in which you want to add a single string value to the event data. If you were to specify your event data as individual parameters in the delegate signature (rather than subclassing System.EventArgs), then all subscribers to your event would have to be modified to accept the additional string parameter. Even subscribers that do not care about this additional string value would have to be modified to accept it, as the custom event handler signature would be changed. If you had, instead, subclassed System.EventArgs, then all you would have to do is add a new string property to your class. The event signature would not change, and therefore neither would the event handler signature used in any of the existing subscribers. Subscribers that do not care about the new string property would not have to be touched because the event handler signature would not be changed — and they could simply ignore the additional string property. Subscribers that do care about the new string value would be able to read it as a property of the EventArgs subclass.

Here is an example of an EventArgs subclass that encapsulates a single string value:

public class FileDeletedEventArgs : System.EventArgs 
{
   // Field

   string m_FileName = string.empty; 

   // Constructor

   FileDeletedEventArgs(string fileName) 
   {
      m_FileName = fileName; 
   }

   // Property

   public string FileName 
   {
      get { return m_FileName; }
   }
}

5.3 The Role of System.ComponentModel.CancelEventArgs

System.ComponentModel.CancelEventArgs is derived from System.EventArgs, and exists in support of cancellable events. Beyond the members provided by EventArgs, CancelEventArgs provides the Boolean Cancel property that, when set to true by an event subscriber, is used by the event publisher to cancel the event.

Section 16 of this article presents cancellable events in greater detail (click here to go there now).

6. Event Declaration Syntax

6.1 Event Declaration Syntax Alternatives

The event keyword is used to formally declare an event. There are two valid event declaration syntax alternatives. Regardless of the syntax you write, the C# compiler will translate both property declarations into the following three components in the output assembly.

1. Privately scoped event handler (or a functionally equivalent data structure). The delegate is privately scoped in order to prevent external code from invoking the event, and thereby preserving encapsulation.
2. publicly scoped Add method; used to add subscribers to the private event handler.
3. publicly scoped Remove method used to remove subscribers from the private event handler.

1. Field-like syntax

public event TheEventHandler MyEvent;

The field-like syntax declares the event in one or two lines of code (one line for the event, another for the associated event handler — if/when not using a built-in EventHandler delegate).

2. Property-like syntax

public event TheEventHandler MyEvent
{
   add
   {
      // code here adds the incoming delegate instance to underlying list of 

      // event handlers

   }
   remove
   {
      // code here removes the delegate instance from the underlying list of 

      // event handlers

   }
}

The property-like syntax appears very similar to a typical property declaration, but with explicit add and remove blocks in place of "getter" and "setter" blocks. Instead of retrieving or setting the value of a private member variable, they add and remove incoming delegate instances to/from the underlying event handler or other data structure that servers a similar role.

Threading Considerations

The field-like syntax is automatically thread safe:

public event FileDeletedHandler FileDeleted;

The property-like syntax will be as thread safe as you make it. The following is a thread safe version:

private readonly object padLock = new object();

public event System.EventHandler<filedeletedeventargs />FileDeleted
{
   add
   {
      lock (padLock) 
      {
         FileDeleted += value; 
      }
   }
   remove
   {
      lock (padLock) 
      {
         FileDeleted -= value; 
      }
   }
}

You can omit the lock{} blocks and padLock variable declaration if thread safety is of no concern.

6. 2 Considerations For Choosing Between Field-like Syntax and Property-like Syntax

When choosing amongst the syntax alternatives, consider that the property-like syntax gives you more control over your event implementation than is available with the field-like syntax. While the field-like syntax will be compiled into IL that very much resembles the IL generated for the property-like syntax, the field-like syntax does not afford you the same opportunities to explicitly control the event implementation.

Using the property-like syntax enables you to more carefully control the registration and unregistration of subscribers with the event handler (delegate). It also enables you to more easily and explicitly implement the specific locking mechanisms of your choice to address thread safety concerns. The property-like syntax additionally enables you to implement a custom event handler mechanism other than a delegate. You might want to do this in scenarios where you want to support many possible events, only a few of which would have any subscribers at any given point in time. In such a scenario, your event implementation would use a hash table or similar data structure, rather than an individual delegate, to maintain a list of all possible events and any associated listeners.

6.3 Publish/Subscribe Mechanism Using Delegates Without Events (never do this)

It should be clearly understood that events are not delegates — even though events are very much dependent upon delegates, and in some ways can be seen as a form of a delegate implementation. Events are also not delegate instances, even if they can be used in very similar ways.

While you can omit the event keyword (and therefore the formal declaration of the event) and simply use a public delegate to provide a publish-and-subscribe notification mechanism, you should never do so. The problem with public delegates (as compared to event declaration), is that methods outside of the publishing class can cause publicly scoped delegates to invoke their referenced methods. This violates basic encapsulation principles and can be the source of major problems (race conditions, etc) that may be difficult to debug. Consequently you should implement events only through the use of the event keyword. When delegates are implemented in support of events, the delegate — even if declared as a public member of the defining class — can only be invoked from within the defining class (via the raising of the event), and other classes can only subscribe to and unsubscribe from the underlying delegate via the event.

7. Event Raising Code

For each event, the publisher should include a protected virtual method that is responsible for raising the event. This will allow subclasses to [more] easily access base class events. Of course the recommendation to make this method protected and virtual applies only to non static events in unsealed classes.

protected virtual void OnMailArrived(MailArrivedEventArgs) 
{
   // Raise event here

}

Once an event and any associated delegate and publishing method have been defined, the publisher will need to raise the event. Raising the event should generally be a two step process. The first step would be to check to see if there are any subscribers. The second step is to raise the event, but only if there are any subscribers.

If there are no subscribers, then the delegate will test to null. The following logic raises the event, but only if the event has any subscribers.

if (MyEvent != null) 
{
   MyEvent(this, EventArgs.Empty); 
}

There is a possibility that the event could be cleared (by code executing in another thread) between the test for null and the line that actually raises the event. This scenario constitutes a race condition. So it is recommended to create, test, and raise a copy of the event's event handler (delegate), like this:

MyEventHandler handler = MyEvent;
 
if (handler != null) 
{
   handler (this, EventArgs.Empty) 
}

Any unhandled exceptions raised in the event handling methods in subscribers will be propagated to the event publisher. The raising of the event should therefore be attempted only within a try/catch block:

public void RaiseTheEvent(MyEventArgs eventArgs) 
{
   try
   {
      MyEventHandler handler = MyEvent; 
      if (handler != null) 
      {
         handler (this, eventArgs) 
      }
   }
   catch
   {
      // Handle exceptions here

   }
}

Events can have multiple subscribers — each of which is called, in turn, by the event handler (delegate) when the event handler is invoked by the [handler (this, eventArgs)] line. The event handler used in the above block of code would stop iterating over it's invocation list (of subscribed event handling methods) when the first unhandled exception is raised by a subscriber. So, if there were 3 subscribers, for example, and the 2nd one threw an unhandled exception when invoked by the delegate, then the 3rd subscriber would never receive the event notification. If you want for every subscriber to receive the event notification even if other subscribers throw unhandled exceptions, then you could use the following logic which explicitly loops through the event handler's invocation list:

public void RaiseTheEvent(MyEventArgs eventArgs) 
{
   MyEventHandler handler = MyEvent; 
   if (handler != null) 
   {
      Delegate[] eventHandlers = handler.GetInvocationList();
      foreach (Delegate currentHandler in eventHandlers)
      {
         MyEventHandler currentSubscriber = (MyEventHandler)currentHandler;
         try
         {
            currentSubscriber(this, eventArgs);
         }
         catch (Exception ex)
         {
            // Handle exception here.

         } 
      }
   }
}

8. Event Subscriber Registration and Unregistration

By design, the publisher of an event has absolutely no knowledge of any of the subscribers. Consequently, it is the job of subscribers to register or unregister themselves with the publisher of an event.

8.1 Registering A Subscriber

In order to subscribe to an event, the subscriber needs three things:

1. a reference to the object publishing the event of interest
2. an instance of the delegate upon which the event is defined
3. a method that will be called by the publisher when it raises the event

The subscriber then registers its event handler (delegate) instance with the publisher, like this:

thePublisher.EventName += new 
MyEventHandlerDelegate(EventHandlingMethodName);

In the above line...

• thePublisher is the reference to the object that will raise the event of interest. Notice how the event, EventName, is accessed as if it were a public property of thePublisher.
• The += operator is used to add the delegate instance to the invocation list of the event handler in the publisher. Remember, multiple subscribers may register with the event. Use the += operator to append the current subscriber to the underlying delegate's invocation list.
• MyEventHandlerDelegate is a reference the particular event hander delegate to be used (if not one of the built-in EventHandler delegates).
• Finally EventHandlingMethodName supplies the name of the method in the subscribing class that is to be called upon the raising of the event.

WARNING: Do not use the = operator when registering an event subscriber with a publisher. Doing so would replace any/all currently registered event subscribers with the current subscriber. Instead, be sure to use the += operator to cause the current subscriber to be appended to the event handler's invocation list.

8.2 Unregistering A Subscriber

A subscriber can unregister from the publisher, like this:

thePublisher.EventName -= 
EventHandlerDelegate(EventHandlingMethodName);

The -= operator is used to remove the delegate instance from the invocation list in the publisher.

Subscribers are automatically unregistered when an object is disposed — if the subscriber was not already explicitly unregistered from the event.

9. Event Handling Method

An event handling method is the method in an event subscriber that is executed by the event publisher upon the raising of an event. Be aware that some literature describing events in .NET refers to these methods as "event handlers" even though, to be technically precise, an "event handler" is a delegate upon which an event is based — and not any method referenced by a such a delegate.

The important requirement of the event handling method is that its signature must match the signature of the event handler (delegate) upon which the event is defined.

You should also carefully consider the consequences of any exceptions that may be thrown or caught in the event handling method. Exceptions not caught in the event handling method will propagate to the event publisher.

10. .NET 1.x vs. 2.0+ Considerations

The concepts and features presented in this section were introduced in the 2.0 version of the .NET Framework. These newer features amount to shortcuts and, possibly, the simplification of your code when used smartly.

There is a risk, however, that the improper use of some of these features could make your event implementation code more difficult to understand. For example, if you made use of an "anonymous method" (presented below) that was comprised of 30+ lines of code, your event implementation would likely be far more difficult to read than an equivalent implementation that, instead, places those 30+ lines in a named method.

It is important to understand that these 2.0+ concepts and features do not present any fundamental change to the way events are implemented in .NET Framework applications. Instead, they are mostly intended to simplify the way we go about implementing events.

10.1 Generics

In addition to the Generic-specific features presented elsewhere in this article (e.g., System.EventHandler<T>), it should be noted that any event implementation techniques that rely in any way on Generics will not be available in .NET 1.x applications, as Generics were first introduced in the 2.0 version of the .NET Framework.

10.2 Delegate Inference

The C# 2.0 (and newer) compiler is smart enough to determine the type of delegate with which a particular event is implemented. This "delegate inference" capability enables you to omit the declaration of the requisite delegate in the code that registers an event handling method with an event.

Consider the following 1.x code that registers an event handling method with an event. This code explicitly instantiates the event handler (delegate) in order to register the associated method with the event.

thePublisher.EventName += new MyEventHandlerDelegate(EventHandlingMethodName);

The following 2.0+ code uses delegate inference to register the same method with the event. Notice the following code appears to register the event handling method directly with the event.

thePublisher.EventName += EventHandlingMethodName;

When you assign the method name directly to the event like that, the C# compiler ensures that the method signature matches the signature of the event handler upon which the event is based. The C# compiler then inserts the requisite delegate registration code (i.e., ... += new MyEventHandlerDelegate(EventHandlingMethodName);) in the output assembly.

This simplified syntax is made possible by the C# compiler, and not by any change to the fundamental ways that events are implemented in the .NET Framework. To be clear, it is not the case that events in C# 2.0 (and newer) can directly reference methods. What the compiler is doing for us is supplying the [still] requisite delegate syntax in the output assembly — as if we had explicitly instantiated the delegate.

10.3 Anonymous Methods

An anonymous method is a block of code that you pass to a delegate (rather than passing the name of a method to be referenced by the delegate). When the C# compiler encounters an anonymous method, it creates a complete method in the output assembly that contains the code block you supplied. The compiler supplies a name for the method, then references that [new] method from the associated delegate instance (all this happens in the output assembly). The method is said to be "anonymous" because you are making use of it without knowing its name (it has no name in your source code).

Anonymous methods present an opportunity for you to write simpler code. Consider the following code that registers a short event handling method with an event:

static void EventHandlingMethod(object sender, EventArgs e)
{
   Console.WriteLine("Handled by a named method");
}

thePublisher.EventName += new MyEventHandlerDelegate(EventHandlingMethod);

The above logic can be rewritten with an anonymous method, like this:

thePublisher.EventName += delegate {
   Console.WriteLine("Handled by anonymous method");
};

Anonymous methods are intended to simplify our code. This simplification can happen when the code block is relatively short. In the above example, the version of the logic that uses the anonymous method syntax is easy to read because we don't have to locate any separate event handling method in order to understand how the subscriber will respond when the event is raised. The anonymous method syntax can, however, be more cumbersome to read (more so than logic that references a named method) in cases where the code block is comprised of many lines of code. Some authors suggest that code blocks containing more than three or four lines of code should not be implemented as anonymous methods. These more lengthy code blocks should, instead, go into named methods in order to improve readability.

To summarize the alternatives presented so far, the following code demonstrates three options for registering an event handling method with an event. The first demonstrates the explicit approach that works with all versions of the .NET Framework. The second demonstrates delegate inference. The third demonstrates the use of an anonymous method:

// Option 1 - explicit delegate creation with a named method

thePublisher.EventName += new MyEventHandlerDelegate(EventHandlingMethod);

// Option 2 - delegate inference

thePublisher.EventName += EventHandlingMethod;

// Option 3 - anonymous method

thePublisher.EventName += delegate(object sender, EventArgs e) {
   Console.WriteLine("handled by anonymous method");
   // You can access the sender and e parameters here if necessary

};

// Event handling method used in options 1 and 2

static void EventHandlingMethod(object sender, EventArgs e)
{
   Console.WriteLine("Handled by a named method");
}

10.4 Partial Classes

Partial classes are relevant to the implementation of events in that Visual Studio will place event registration code and event handling method stubs in the partial class files associated with a given Windows Form class. Click here to go to section 15.1 which presents the implementation of events in partial classes in greater detail.

11. Conventions

The following conventions were gleaned from a number of resources, including the authors of the .NET Framework and other well-known industry experts (see reference list at the end of this article for the complete list).

11.1 Event Publisher Conventions

Event Name

• Choose a name that clearly communicates the state change the event represents.
• Events can be categorized as (1) events raised before a state change occurs; and (2) events raised after a state change occurs. Consequently, the event name should be chosen to reflect the before or after [state change] aspect of the event.

Examples — for events raised before state change:

• FileDownloading
• TemperatureChanging
• MailArriving

Examples — for events raised after state change:

• FileDownloadCompleted
• TemperatureChanged
• MailArrived

System.EventArgs Subclass (where applicable)

• In the case of events that must or may [someday] carry custom event data, you should create a new class that (1) extends System.EventArgs, and (2) implements the members (e.g., properties) required to contain and expose your custom event data
• The only time you should not subclass EventArgs is when you are certain that your event will never carry event data
• The name of your EventArgs subclass should be the name of the event, with 'EventArgs' appended

Example EventArgs subclass names:

• DownloadCompletedEventArgs
• TemperatureChangedEventArgs
• MailArrivedEventArgs

For events that contain no data, and never will, it is recommended to pass System.EventArgs.Empty. This recommended practice serves to maintain the event implementation conventions even for events that have no event data. If there is a possibility that your event may someday carry event data, even if not at initial implementation, then you should create a subclass of System.EventArgs, and use that in your events. The primary benefit of this recommendation is that you will someday be able to add data (properties) to your subclass without breaking compatibility with existing subscribers.

Event Handler (delegate) Name

• If you are using .NET Framework 1.x, then you should use the built-in System.EventHandler delegate
• If you are using .NET Framework 2.0 or newer (for 'both' publishers and subscribers), then you can make use of the generic System.EventHandler<TEventArgs> delegate
• If you create your own delegate, then the delegate name should be comprised of the event name, with the word, 'Handler' appended

Example custom event handler (delegate) names:

• DownloadCompletedHandler
• TemperatureChangedHandler
• MailArrivedHandler

Event Handler (delegate) Signature

As stated above, under "Delegate Name," you should use one of the System.EventHandler delegates provided by the .NET Framework. In these cases, the delegate signature is, of course, determined for you and automatically conforms to the recommended conventions.

The following recommendations are implemented in the System.EventHandler delegates provided by the .NET Framework. If you create your own event handlers, then you should follow these recommendations in order to remain consistent with the .NET Framework's implementation.

• The delegate should always return void.

  In the case of event handlers, it simply makes no sense to return a value to the event publisher. Remember, event publishers, by design, have no knowledge of their subscribers. In fact the delegate, by design, acts as an intermediary between the event publisher and its subscribers. Consequently, publishers aren't supposed to know anything about their subscribers — including the possibility of receiving returned values. It is the delegate that is calling each subscriber, so any return value would make it only as far as the delegate and would never get to the publisher anyway. This rationale holds true for avoiding output parameters that use either the out or ref parameter modifiers. The output parameters of the subscribers would never propagate to the publisher.

• The first parameter should be of the object type and should be named sender.

  This first parameter is to hold a reference to the object that raises the event. Passing a reference to the event publisher enables the event subscriber to distinguish amongst multiple possible publishers of a given event. Without a reference to the publisher, the event handling method would have no way to identify or act on the specific publisher that raised a particular event.

  The data type for sender is object because practically any class can raise events. Avoiding a strongly-typed sender parameter allows for one consistent event handler signature to be employed across all events. Where necessary, the event handling method can cast the sender parameter to the specific event publisher type.

  Static events should pass null as the value of sender, rather than omitting the sender parameter.

• The second parameter should be named 'e' and should be of the System.EventArgs type or your custom subclass of System.EventArgs (e.g., MailArrivedEventArgs).

  In the case of cancellable events, the second parameter is either of the System.ComponentModel.CancelEventArgs type or your custom subclass thereof. In the case of events that carry no event data, you should specify System.EventArgs as the second parameter type. In such cases System.EventArgs.Empty is specified as the value of this parameter when the event is raised. This practice is recommended to maintain conformance to the convention — so that all event handler signatures include an EventArgs parameter — even for events that do not have EventArgs. Apparently, according to the convention, having one consistent signature is more important than having multiple event handler signatures — even in cases where one of the parameters will never be used.

Examples (with no custom data sent with the event):

delegate void DownloadCompletedHandler(object sender, EventArgs e);
delegate void TemperatureChangedHandler (object sender, EventArgs e);
delegate void MailArrivedHandler (object sender, EventArgs e);

Examples (with custom data sent with the event):

delegate void DownloadCompletedHandler(object sender, 
    DownloadCompletedEventArgs e);
delegate void TemperatureChangedHandler (object sender, 
    TemperatureChangedEventArgs e);
delegate void MailArrivedHandler (object sender, 
    MailArrivedEventArgs e);

Event Declaration

• Assuming the event is to be made available to code outside of the publishing class, the event would be declared with the public keyword (to make it accessible to code outside of the publishing class).
• The event handler upon which the event is based is specified as the type of the event — in a similar fashion with which a data type is specified in a typical property or method declaration.

Example (uses built-in generic System.EventHandler<TEventArgs> delegate):

public event System.EventHandler<mailarrivedeventargs> MailArrived;

Example (makes use of a custom event handler):

public delegate void MailArrivedHandler (object sender, 
    MailArrivedEventArgs e); 

public event MailArrivedHandler<mailarrivedeventargs> MailArrived;

Method That Raises the Event

• Rather than raising an event inline throughout your code, it is recommended to create a separate method that is responsible for raising the event. You then call that method throughout your code as necessary.
• The name of this method should be the word On with the event name appended.
• If your event makes use of a custom EventArgs subclass, then the method that raises the event should accept at least one parameter that is of the particular EventArgs subclass defined for the custom event data.
• For non-static classes that are not sealed, the method should be implemented as virtual with accessibility specified as protected so that derived classes can easily notify clients registered with the base class.
• For sealed classes the accessibility of the method should of course be set to private, as the raising of events should not be initiated from outside of the class.

Examples (each takes a custom EventArgs subclass type as an argument):

OnDownloadCompleted(DownloadCompletedEventArgs) 
{
   // Raise event here

}

private OnTemperatureChanged(TemperatureChangedEventArgs) 
{
   // Raise event here

}

virtual OnMailArrived(MailArrivedEventArgs) 
{
   // Raise event here

}

11.2 Event Subscriber Conventions

Event Handling Method Name

• The convention implemented by Visual Studio, when it automatically creates an event handling method stub, is to name the method as (1) the name of the object raising the event; followed by (2) an underscore character; with (3) the event name appended.

Examples:

• downloader_DownloadCompleted
• weatherStation_TemperatureChanged
• mailManager_OnMailArrived

• Another convention for determining the name of the event handling method is the same as that described above for specifying name of the method that raises the event in the publisher. Specifically, the name of the method should be the word On with the event name appended.

Examples:

• OnDownloadCompleted
• OnTemperatureChanged
• OnMailArrived

Event Handling Method Signature

• The signature of the event handling method must exactly match the delegate signature. According to the event handling conventions, as well as the EventHandler delegates provided by the .NET Framework, the event handling method must return void, while accepting exactly two parameters: an object-typed variable named sender, and an EventArgs (or derived class) instance named 'e'.

Examples:

void DownloadManager_DownloadCompleted(object sender, 
    DownloadCompletedEventArgs e) 
{
   // event handling code goes here

}

void WeatherStation_TemperatureChanged(object sender, 
   TemperatureChangedEventArgs e) 
{
   // event handling code goes here

}

void MailMonitor_MailArrived(object sender, MailArrivedEventArgs e) 
{
   // event handling code goes here

}

Subscribing to the Event (code that registers the Event Handling Method with the Event)

• To register a method with an event, use the += syntax, according to this pattern:

  EventPublisherObject.EventName += new EventHandlerDelegateName(NameOfMethodToCall);

Example:

m_MailMonitor.MailArrived += new EventHandler(
    this.MailMonitor_MailArrived);

WARNING: Do not use the = operator when registering an event subscriber with a publisher. Doing so would replace any/all currently registered event subscribers with the current subscriber. Instead, be sure to use the += operator to cause the current subscriber to be appended to the event handler's invocation list.

Unsubscribing from the Event (Code that Unregisters the Event Handling Method from the Event)

• To unregister a method with an event, use the -= syntax, according to this pattern:

  EventPublisherObject.EventName -= new EventHandlerDelegateName(NameOfMethodToCall);

Example:

m_MailMonitor.MailArrived -= new EventHandler(
    this.MailMonitor_MailArrived);

11.3 Naming Conventions

Camel Casing

Camel casing is a naming convention whereby the first letter is lower case, with each subsequent "word part" starting with an upper case letter. By convention, variables names are camel cased.

Camel cased examples: someStringToWrite, ovenTemperature, latitude

Pascal Casing

Pascal casing is naming convention whereby every "word part" of a name starts with an upper case letter, with other letters lower case, and no underscores. By convention, names of classes, events, delegates, methods, and properties are to be Pascal cased.

Pascal cased examples: MailArrivedEventHandler, AppClosing, MyClassName

12. Steps to Creating Custom Events

In order to keep the following steps as brief as possible, little or no explanation of any given step is provided. Explanations, examples, and conventions for each step are presented elsewhere throughout this article.

12.1 Prepare the Event Publisher

Step 1: EventArgs - Decide how your event will account for EventArgs.

• Including EventArgs with custom events is required to conform to the event publishing standards. EventArgs, however, are not a technical requirement — you can create, raise, and handle custom events that do not make any use of EventArgs.
• If your event will never communicate custom event data, then you can satisfy this step by deciding to use the built-in System.EventArgs class. You would later specify the value, EventArgs.Empty, when raising the event.
• If your event is not cancellable and includes custom event data, then you should create a class that extends System.EventArgs. Your custom EventArgs subclass would include any additional properties that contain the event data.
• If your event is cancellable then you can use System.ComponentModel.CancelEventArgs — which includes the Boolean Cancel property that clients can set to true to cancel the event. You can create a subclass of CancelEventArgs that has properties for any additional event-specific data.

Step 2: Event Handler - Decide which event handler your event will use.

• You have two basic alternatives — create your own event handler (delegate) or use one of the EventHandler delegates provided by the .NET Framework. If you use one of the built-in event handlers, then you will have less code to maintain and your event handler signature will automatically conform to the convention of returning void, while accepting the parameters, object sender, and EventArgs e
• If using .NET 1.x, consider using the built-in System.EventHandler delegate.
• If using .NET 2.0, consider using the built-in generic System.EventHandler<TEventArgs> delegate.

Step 3: Declare the Event — Decide which syntax to use: field-like syntax or property-like syntax.

• The field-like syntax will suffice for many custom event implementations.
• Consider going with the property-like syntax when your class exposes a large number of events, only a few of which are expected to be subscribed to at any given time.

Step 4: Event-Raising Method — Decide whether you will raise the event from a method, or raise it inline.

• It is generally recommended to raise events from a method that is dedicated to that task, rather than raising events inline and throughout your code.

Step 5: Raise the event.

• Either raise the event inline, or call the method that raises the event.
• Prior to raising the event you will need to have an instance of your EventArgs subclass populated with event-specific data. If not making use of any EventArgs subclass, then you should include System.EventArgs.Empty in place of a custom EventArgs class when you raise the method.

12.2 Prepare the Event Subscriber

Because this article presents the event pattern (object sender, EventArgs e) implemented throughout the .NET Framework classes, the following steps will help you wire up event handling methods that work with practically all .NET Framework events, in addition to custom events you create according to the same pattern.

Step 1: Write the Event Handling Method.

• Define an event handling method with a signature that exactly matches the delegate upon which the method is defined.
• When using either the built-in non generic System.EventArgs, or the generic System.EventHandler<TEventArgs> delegate in the event declaration, the resulting signature automatically matches the convention of returning void and accepting the parameters (object sender, EventArgs e).

Step 2: Instantiate the Event Publisher.

• Declare class-level member variable that references the class or object that publishes the event of interest.

Step 3: Instantiate the event handler (if necessary).

• If the event of interest is based on a custom event handler, then create an instance of that event handler, passing in the name of the event handling method.
• This step may be combined with Step 4 (next) by using the new keyword to instantiate the delegate in the same line in which the delegate is registered with the event

Step 4: Register the subscriber (event handling method) with the event.

• Any .NET version: Use the += syntax to register the event handler with the event.
• .NET 2.0+: Alternatively, through delegate inference, you can simply assign the method name directly to the event.
• .NET 2.0+: Alternatively, if the event handling method is very brief (3 or so lines of code), your implementation may be easier to read if you register the event handling logic via an "anonymous method."

Step 5: Unregister the subscriber (event handling method) from the event.

• When the subscriber should no longer receive event notifications from the publisher, then you can unregister the subscriber from the event.
• This step can be considered as optional, given that subscribers are automatically unregistered from publishers when the subscriber is disposed.

13. Sample Event Implementation

This example makes use of a custom event handler, carries event data in a custom EventArgs subclass, declares an event with field-like syntax, and otherwise conforms to recommended event implementation standards and guidelines. None of the .NET 2.0+ features (anonymous methods, etc) are used in order to keep the presentation as explicit as possible.

This sample event is raised when a file is moved by a "file mover" utility (in the sample project). The event data includes (1) the name of the file moved, (2) the source folder path, and (3) the destination file path.

13.1 Sample Event Publisher Code

Step 1: Subclass EventArgs

Here we derive a new class, MoveFileEventArgs, from EventArgs in order encapsulate the event data sent to the subscriber.

public class MoveFileEventArgs : EventArgs
{
   // Fields

   private string m_FileName = string.Empty;
   private string m_SourceFolder = string.Empty;
   private string m_DestinationFolder = string.Empty;

   // Constructor

   public MoveFileEventArgs(string fileName, string sourceFolder, 
      string destinationFolder)
   {
      m_FileName = fileName;
      m_SourceFolder = sourceFolder;
      m_DestinationFolder = destinationFolder;
   }
   // Properties (read-only)

   public string FileName
   {
      get { return m_FileName; }
   }

   public string SourceFolder
   {
      get { return m_SourceFolder; }
   }

   public string DestinationFolder
   {
      get { return m_DestinationFolder; }
   }
}

Step 2: Event Handler (delegate)

Here we declare a new delegate that conforms to the event conventions, returns void and accepts two parameters; an object named 'sender' and EventArgs named 'e'.

public delegate void MoveFileEventHandler(object sender, 
    MoveFileEventArgs e);

Step 3: Declare the Event

Here we declare the event using the field-like syntax.

public event MoveFileEventHandler MoveFile;

Step 4: Event-Raising Method

Here we declare the method that raises the event.

private void OnMoveFile()
{
   if (MoveFile != null) // will be null if no subscribers

   {
      MoveFile(this, new MoveFileEventArgs("SomeFileName.txt", 
          @"C:\TempSource", @"C:\TempDestination"));
   }
}

Step 5: Raise the Event

Here we have a method that would do the work of interest (move the file). Once the work is completed, the method that raises the event is called.

public void UserInitiatesFileMove()
{
   // code here moves the file.


   // Then we call the method that raises the MoveFile event

   OnMoveFile();
}

13.2 Sample Event Subscriber Code

Step 1: Write the Event Handling Method

This method is called when the fileMover instance raises the MoveFile event. It's signature exactly matches the event handler's signature.

void fileMover_MoveFile(object sender, MoveFileEventArgs e) 
{
   MessageBox.Show(sender.ToString() + " moved the file, " + 
      e.FileName + ", from " + 
      e.SourceFolder + " to " +  e.DestinationFolder); 
}

Step 2: Instantiate the Event Publisher

FileMover fileMover = new FileMover();

Step 3: Instantiate the event handler as we register the subscriber (event handling method) with the event

This approach combines steps 3 and 4 from the steps listed in the section 14.2.