Events, delegates and lambdas in .NET C# part 2: delegates in action

Introduction

In the previous installment of this series we looked at the foundations of delegates, events and event handlers. It’s now time to see them in action.

Demo

Open Visual Studio 2012/2013 and create a new Console application with .NET 4.5 as the underlying framework. I haven’t tested the code with .NET4.0 or .NET 3.5 but I think it should work with those frameworks as well.

In Program.cs add the following delegate declaration just above the Main method:

public delegate void WorldSavedHandler(string saviourName, DateTime dateForNextCatastrophy);

So this is a delegate for when some superhero saves the world for the nth time. It is void, it has a name and accepts two parameters: a string and a date. Note that it’s customary but not mandatory to name delegates with the word ‘Handler’ attached.

Add the following methods that match the delegate signature:

static void WorldSaved(string saviour, DateTime nextTime)
{
	Console.WriteLine(string.Concat("World saved by ", saviour, ", get ready again by ", nextTime));
}

static void WorldSavedAgain(string saviour, DateTime nextTime)
{
	Console.WriteLine(string.Concat("World saved this time by ", saviour, ", get ready again by ", nextTime));
}

In Main you can instantiate a delegate and hook up a callback method as follows:

WorldSavedHandler worldSavedHandler = new WorldSavedHandler(WorldSaved);

As you type the declaration in the editor IntelliSense will indicate that the delegate is expecting a void method that accepts a string and a date. If you try to pass in a method that doesn’t match this signature you’ll get a compile error. Add another delegate declaration to Main:

WorldSavedHandler worldSavedAgainHandler = new WorldSavedHandler(WorldSavedAgain);

We have set up two pipelines: worldSavedHandler which sends its data to WorldSaved and worldSavedAgainHandler which sends its data to WorldSavedAgain. We can invoke the delegates the same way as we normally call a method:

worldSavedHandler("Bruce Willis", DateTime.UtcNow.AddYears(2));
worldSavedAgainHandler("Spiderman", DateTime.UtcNow.AddMonths(3));

Console.ReadKey();

I added the call to ReadKey so that the console window doesn’t just close down.

Run the program and you’ll see the appropriate output in the console window.

Why on earth are we bothering with this? Up to now this looks like some funny way of calling methods. Consider the following method which accepts our delegate type:

static void SaveWorld(WorldSavedHandler worldSaved)
{
	worldSaved("Bruce Willis", DateTime.UtcNow.AddMonths(5));
}

In Main comment out the two delegate calls…:

worldSavedHandler("Bruce Willis", DateTime.UtcNow.AddYears(2));
worldSavedAgainHandler("Spiderman", DateTime.UtcNow.AddMonths(3));

…and add the following instead:

SaveWorld(worldSavedHandler);

This is stating that we need to save the world and we have 2 possible delegates to give this work to. We entrust worldSavedHandler with this task so we pass it in. An analogy from the real world is when a boss decides the software development team needs to build the data access layer and appoints a particular team member to do just that. In other words the boss delegates the job to a particular programmer, i.e. a handler.

We know that worldSavedHandler will call WorldSaved. SaveWorld gets the delegate and will invoke whatever was passed to it. SaveWorld does NOT know which handler the delegate will call. From its point of view it could be any method with the correct signature, so it’s quite a dynamic setup. The delegate could have been passed in from whichever external object to the SaveWorld method. SaveWorld passes in Bruce Willis and now + 3 months to some unknown method.

Run the program and you’ll see that WorldSaved was called. Now, without changing SaveWorld directly, you can modify its outcome just by providing a different delegate:

SaveWorld(worldSavedAgainHandler);

Run the program and WorldSavedAgain was called as expected without changing SaveWorld at all.

Let’s look at multicasting quickly. Comment out the call to SaveWorld in Main and instead add a third delegate declaration:

WorldSavedHandler worldSavedOnceMoreHandler = new WorldSavedHandler(WorldSavedOnceMore);

…where WorldSavedOnceMore looks like this:

static void WorldSavedOnceMore(string saviour, DateTime nextTime)
{
	Console.WriteLine(string.Concat("World saved once again by ", saviour, ", get ready again by ", nextTime));
}

There are different way to build an invocation list. The following chains our three delegates together:

worldSavedHandler += worldSavedAgainHandler;
worldSavedHandler += worldSavedOnceMoreHandler;

worldSavedHandler("Superman", DateTime.UtcNow.AddMonths(3));

You’ll see that all three method handlers were called.

The below is equivalent to the above:

worldSavedHandler += worldSavedAgainHandler + worldSavedOnceMoreHandler;
worldSavedHandler("Superman", DateTime.UtcNow.AddMonths(3));

The following will wipe out the first handler:

worldSavedHandler = worldSavedAgainHandler + worldSavedOnceMoreHandler;
worldSavedHandler("Superman", DateTime.UtcNow.AddMonths(3));

This time only WorldSavedAgain and WorldSavedOnceMore are called.

You’ll also see that each handler is called in the order they were added to the invocation list. This way we can invoke multiple handlers by calling just one delegate, in this case worldSavedHandler.

Returning a value from a delegate

Delegates can return values, they don’t need to be void all the time. Add the following delegate to Program.cs:

public delegate string SomeoneJustShoutedHandler(string who, DateTime when);

Add the following handlers:

static string SomeoneShouted(string who, DateTime when)
{
	return string.Concat(who , " has shouted on ", when);
}

static string SomeoneShoutedAgain(string who, DateTime when)
{
	return string.Concat(who, " has shouted on ", when);
}

static string SomeoneShoutedOnceMore(string who, DateTime when)
{
	return string.Concat(who, " has shouted once more on ", when);
}

…and 3 delegate declarations with the delegate chain:

SomeoneJustShoutedHandler someoneShoutedHandler = new SomeoneJustShoutedHandler(SomeoneShouted);
SomeoneJustShoutedHandler someoneShoutedAgainHandler = new SomeoneJustShoutedHandler(SomeoneShoutedAgain);
SomeoneJustShoutedHandler someoneShoutedOnceMoreHandler = new SomeoneJustShoutedHandler(SomeoneShoutedOnceMore);

someoneShoutedHandler += someoneShoutedAgainHandler + someoneShoutedOnceMoreHandler;
string finalShout = someoneShoutedHandler("The neighbour", DateTime.UtcNow);
Console.WriteLine("Final shout: " + finalShout);

Run the code and you’ll see that it’s only the third string that’s returned. It’s logical as we cannot have multiple return values in C#. You can get the individual return values by calling the delegates separately. However, with an invocation list the last delegate in the list will win.

Adding events

We’ve seen that using delegates can work fine without adding events to the code. However, delegates coupled with events help us raise those events and propagate the event arguments to all listeners in the invocation list.

An event is declared using the ‘event’ keyword in C#. It is also declared with the type of the delegate that raises the event as an event by itself cannot do much. Events are the standard way of providing notifications to all listeners. The data will be supplied using the delegate declared in conjunction with the event. In .NET programming you’ll probably rarely see delegates used without events although it’s certainly possible as we’ve seen above. You also give a name to the event. Here’s an example of an event declaration:

public event WorldSavedHandler WorldHasBeenSaved;

Listeners will be able to sign up with the event and receive a notification when the event has fired. It is equivalent to building the invocation list we saw above. So an event is really nothing but a wrapper around a delegate.

There’s also a more complex way of defining an event using the add/remove accessors:

private WorldSavedHandler WorldHasBeenSaved;
public event WorldSavedHandler WorldSaved
{
	[MethodImpl(MethodImplOptions.Synchronized)]
	add
	{
		WorldHasBeenSaved = (WorldSavedHandler)Delegate.Combine(WorldHasBeenSaved, value);
	}
	[MethodImpl(MethodImplOptions.Synchronized)]
	remove
	{
		WorldHasBeenSaved = (WorldSavedHandler)Delegate.Remove(WorldHasBeenSaved, value);
	}
}

This provides more control over how listeners are added to and removed from the invocation list. You’ll probably not see this kind of event declaration too often. However, if you see it somewhere then you’ll now know what it means.

We have a private delegate of type WorldSavedHandler. Then we see the event declaration that conforms to the example provided above. The add accessor defines how a listener is added to the invocation list. The remove accessor does the opposite. The actions are synchronised to make sure that if different threads perform the same action we don’t run into concurrency issues. The ‘value’ keyword indicates the listener that’s going to be added to the invocation list. The Delegate.Combine method takes the delegate we already have and adds in the new one. The remove accessor works with the Delegate.Remove method that removes ‘value’ from the invocation list.

You might use this type of event declaration if you have extra logic on who and when is allowed to be listed on the invocation list. The access may be limited to some special objects that fulfil certain rules.

Now that we know more about events than we ever wanted to we can create some custom events in our code. We’ll actually do that in the next part.

Events, delegates and lambdas in .NET C# part 1: delegate basics

Introduction

I believe that learning the basic features of a popular OO language, such as C# or Java is not too difficult. Obviously you’ll need a positive mindset towards programming in general otherwise you’re bound to fail but that’s true for every discipline. The basic structures found in C#, such as classes, properties, constructors, methods, functions, interfaces and the like are quite straightforward and simple to use even after a couple of months’ worth of training. If you have a Java or C++ background then you can start to be productive with C# after some weeks even.

However, there are some language features that stick out a little as they are slightly more cryptic: events, delegates and lambda expressions. You can certainly come up with others, but my personal experience is that learning these features thoroughly takes more time than the ones listed above.

This series of posts will be dedicated to these language elements of C#.

The building blocks

If you’ve ever done any Windows app development then you must have seen examples of events and event handlers: button click event, list selection changed event, on mouse over event etc. You added an event and an event handler to a button just by double-clicking on it in the visual editor and the following elements were wired together for you in the background:

• Event: notifications originating from objects. These notifications can be used to notify other elements – objects – in the application that may be interested in the event, such as when a new order was placed or a party is about to start. Then the objects listening to those events can perform some work dedicated to them: serve the drinks, order the pizzas, let in the guests etc.
• Event raiser, a.k.a. the Sender: the object that raises the event. They typically don’t know anything about the objects listening to the events raised by themselves
• Event handler: the handler that ‘caught’ the event raised by the button
• Delegate: the glue between the button and the event handler. This is usually hidden in the designer cs file of the Form created by Visual Studio, so you may not even have come across it. Without delegates the event raised would not get to the listening objects and their event handlers
• Event arguments, or EventArgs: the arguments that the Sender is sending to the event handler with the event raised. This can include anything important for the handler, such as the selected item index, the venue for the party, the items that were ordered etc.

Probably the most confusing element in this list is delegates. They are typically described by adjectives such as ‘odd’, ‘strange’ and ‘unusual’. A delegate, also called a function pointer, is a specialised class that derives from the MulticastDelegate base class. As noted above, it connects the event with the event handler. It’s called a function pointer because the event handler will be a function, i.e. a method, and it points at the event handler from the event and wires the event arguments in between.

An event handler will process the data received from a delegate. It is a method with a special signature that must accept a sender of type ‘object’ and an EventArgs parameter or one that’s derived from the EventArgs class. EventArgs objects are normal C# objects with properties. You can easily define your custom event args by deriving from the EventArgs class. You can put in all sorts of properties into your event args that may be interesting for those waiting for the event. A button click event handler may look like this:

public void btnOrderItems_Click(object sender, EventArgs e)
{
      //do something
}

A custom event handler can have the following form:

public void OrderPlaced(object sender, OrderPlacedEventArgs e)
{
      //do something with the order
}

Delegates

You can create delegates with the ‘delegate’ keyword in C#, example:

public delegate void GraphClicked(GraphType graphType, Point clickCoordinate);

It’s void as nothing is returned, data is only sent one way. In this example the delegate’s name is GraphClicked and it accepts two parameters: a graph type and the click coordinates. This declaration is a blueprint for the method, i.e. the handler, that will receive the data from the delegate. The handler method must match this signature otherwise the code will not compile: it must also receive a graph type and the click coordinates. An example of a matching handler:

public void GraphClicked_Handler(GraphType type, Point coords)
{
     //do something
}

Note that the parameter names don’t necessarily match those in the delegate, but the types must match.

The delegate keyword is special in .NET as the compiler does some magic when it sees it declared. It creates another object that inherits from the MulticastDelegate class behind the scenes which in turns derives from the Delegate base class. Multicast delegate means that a single message can be sent to a range of objects through a range of pipelines. Note that you cannot directly derive from the Delegate or the MulticastDelegate classes. You do it indirectly using the delegate keyword and the compiler will do the inheritance trick for you.

The list of pipelines of a multicast delegate is called the Invokation List. The delegates listed here are invoked sequentially.

Now that we have a delegate you can easily instantiate one:

GraphClicked graphClicked = new GraphClicked(GraphClicked_Handler);

So you see a delegate is a class that you can instantiate using the new keyword. Notice that you must specify the handler in the constructor of the delegate. We say that when the graphClicked delegate is invoked then the GraphClicked_Handler method should be called.

You can invoke the graphClicked delegate as follows:

graphClicked(GraphType.Line, new Point(1,1));

So you invoke it like a method and provide the necessary parameters. This adds one delegate item to the invocation list.

There’s nothing stopping you from instantiating several delegates of the same type:

GraphClicked niceGraphClicked = new GraphClicked(NiceGraphClicked_Handler);
GraphClicked uglyGraphClicked = new GraphClicked(UglyGraphClicked_Handler);

These delegates point to two different handlers: NiceGraphClicked_Handler and UglyGraphClicked_Handler. What if you want niceGraphClicked not only invoke NiceGraphClicked_Handler but UglyGraphClicked_Handler as well? In other words you want to extend the invocation list of niceGraphClicked to two items: NiceGraphClicked_Handler but UglyGraphClicked_Handler. It couldn’t be simpler:

niceGraphClicked += uglyGraphClicked;

So now when niceGraphClicked is raised…:

niceGraphClicked(GraphType.Cylinder, new Point(2, 3));

…then both NiceGraphClicked_Handler but UglyGraphClicked_Handler will be called in the same order as they were added to the invocation list.

This post has given you the absolute basics of delegates, events and event handlers. We’ll look at a couple of examples from scratch in the next post.