The Microsoft .NET Framework class library makes extensive use of delegates for many of its types, two examples of which are in Chapter 18: the Find method and the Exists method of the List<T> class. If you recall, these two methods search through a List<T> collection, either returning a matching item or testing for the existence of a matching item. The designers of the List<T> class had absolutely no idea of what should actually constitute a match in your application code when they were implementing this class, so consequently they let you define it instead by providing your own code in the form of a predicate. A predicate is really just a delegate that happens to return a Boolean value.

The following code should help to remind you of how you use the Find method:

struct Person
{
    public int ID { get; set; }
    public string Name { get; set; }
    public int Age { get; set; }
}
...
List<Person> personnel = new List<Person>()
{
    new Person() { ID = 1, Name = "John", Age = 47 },
    new Person() { ID = 2, Name = "Sid", Age = 28 },
    new Person() { ID = 3, Name = "Fred", Age = 34 },
    new Person() { ID = 4, Name = "Paul", Age = 22 },
};
...
// Find the member of the list that has an ID of 3
Person match = personnel.Find(p => p.ID == 3);

Other examples of methods exposed by the List<T> class that use delegates to perform their operations include Average, Max, Min, Count, and Sum. These methods take a Func delegate as the parameter. A Func delegate refers to a method that returns a value (a function). In the following examples, the Average method is used to calculate the average age of items in the personnel collection (the Func<T> delegate simply returns the value in the Age field of each item in the collection), the Max method is used to determine the item with the highest ID, and the Count method calculates how many items have an Age between 30 and 39 inclusive.

double averageAge = personnel.Average(p => p.Age);
Console.WriteLine("Average age is {0}", averageAge);
...
int id = personnel.Max(p => p.ID);
Console.WriteLine("Person with highest ID is {0}", id);
...
int thirties = personnel.Count(p => p.Age >= 30 && p.Age <= 39);
Console.WriteLine("Number of personnel in their thirties is {0}", thirties);

This code generates the following output:

Average age is 32.75
Person with highest ID is 4
Number of personnel in their thirties is 1

You will meet many examples of these and other delegate types used by the .NET Framework class library throughout the remainder of this book. You can also define your own delegates. The best way to fully understand how and when you might want to do this is to see them in action, so next you’ll work through an example.

int thirties = personnel.Count(p => p.Age >= 30 && p.Age <= 39);

Suppose you are writing the control systems for an automated factory. The factory contains a large number of different machines, each performing distinct tasks in the production of the articles manufactured by the factory—shaping and folding metal sheets, welding sheets together, painting sheets, and so on. Each machine was built and installed by a specialist vendor. The machines are all controlled by computer, and each vendor has provided a set of functions that you can use to control its machine. Your task is to integrate the different systems used by the machines into a single control program. One aspect on which you have decided to concentrate is to provide a means of shutting down all the machines—quickly, if needed!

Each machine has its own unique computer-controlled process (and functions) for shutting down safely, as summarized here:

StopFolding();    // Folding and shaping machine
FinishWelding();  // Welding machine
PaintOff();       // Painting machine

A simple approach to implementing the shutdown functionality in the control program is as follows:

class Controller
{
    // Fields representing the different machines
    private FoldingMachine folder;
    private WeldingMachine welder;
    private PaintingMachine painter;
    ...
    public void ShutDown()
    {
        folder.StopFolding();
        welder.FinishWelding();
        painter.PaintOff();
    }
    ...
}

Although this approach works, it is not very extensible or flexible. If the factory buys a new machine, you must modify this code; the Controller class and code for managing the machines is tightly coupled.

Although the names of each method are different, they all have the same “shape”: they take no parameters, and they do not return a value. (You’ll consider what happens if this isn’t the case later, so bear with me.) The general format of each method, therefore, is this:

void methodName();

This is where a delegate can be useful. You can use a delegate that matches this shape to refer to any of the machinery shutdown methods. You declare a delegate like this:

delegate void stopMachineryDelegate();

Note the following points:

After you have declared the delegate, you can create an instance and make it refer to a matching method by using the += compound assignment operator. You can do this in the constructor of the controller class like this:

class Controller
{
    delegate void stopMachineryDelegate();       // the delegate type
    private stopMachineryDelegate stopMachinery; // an instance of the delegate
    ...
    public Controller()
    {
        this.stopMachinery += folder.StopFolding;
    }
    ...
}

It takes a bit to get used to this syntax. You add the method to the delegate; remember that you are not actually calling the method at this point. The + operator is overloaded to have this new meaning when used with delegates. (You will learn more about operator overloading in Chapter 22.) Notice that you simply specify the method name and do not include any parentheses or parameters.

It is safe to use the += operator on an uninitialized delegate. It will be initialized automatically. Alternatively, you can use the new keyword to initialize a delegate explicitly with a single specific method, like this:

this.stopMachinery = new stopMachineryDelegate(folder.StopFolding);

You can call the method by invoking the delegate, like this:

public void ShutDown()
{
    this.stopMachinery();
    ...
}

You use the same syntax to invoke a delegate as you use to make a method call. If the method that the delegate refers to takes any parameters, you should specify them at this time, between the parentheses.

An important advantage of using a delegate is that it can refer to more than one method at the same time. You simply use the += operator to add methods to the delegate, like this:

public Controller()
{
    this.stopMachinery += folder.StopFolding;
    this.stopMachinery += welder.FinishWelding;
    this.stopMachinery += painter.PaintOff;
}

Invoking this.stopMachinery() in the Shutdown method of the Controller class automatically calls each of the methods in turn. The Shutdown method does not need to know how many machines there are or what the method names are.

You can remove a method from a delegate by using the –= compound assignment operator, as demonstrated here:

this.stopMachinery -= folder.StopFolding;

The current scheme adds the machine methods to the delegate in the Controller constructor. To make the Controller class totally independent of the various machines, you need to make stopMachineryDelegate type public and supply a means of enabling classes outside Controller to add methods to the delegate. You have several options:

An object-oriented purist would probably opt for the Add/Remove approach. However, the other approaches are viable alternatives that are frequently used, which is why they are shown here.

Whichever technique you choose, you should remove the code that adds the machine methods to the delegate from the Controller constructor. You can then instantiate a Controller and objects representing the other machines like this (this example uses the Add/Remove approach):

Controller control = new Controller();
FoldingMachine folder = new FoldingMachine();
WeldingMachine welder = new WeldingMachine();
PaintingMachine painter = new PaintingMachine();
...
control.Add(folder.StopFolding);
control.Add(welder.FinishWelding);
control.Add(painter.PaintOff);
...
control.ShutDown();
...

In the following exercises, you will complete an application that forms part of a system for a company called Wide World Importers. Wide World Importers imports and sells building materials and tools, and the application that you will be working on gives customers the ability to browse the items that Wide World Importers currently has in stock and place orders for these items. The application contains a form that displays the goods currently available, together with a pane that lists the items that a customer has selected. When the customer wants to place an order, she can click the Checkout button on the form. The order is then processed, and the pane is cleared.

When the customer places an order, currently several actions occur:

The logic for the auditing and shipping processes is independent from checkout logic, although the order in which these processes occur is immaterial. Furthermore, there is the possibility that either of these elements might be amended in the future, and additional processing might be required by the checkout operation as business circumstances or regulatory requirements change in the future. Therefore, it is desirable to decouple the payment and checkout logic from the auditing and shipping processes to make maintenance and upgrades easier. You will start by examining the application and see how it currently fails to fulfill this objective. You will then modify the structure of the application to remove the dependencies between the checkout logic and the auditing and shipping logic.

One way around this problem is to create another method that calls StopFolding but that takes no parameters itself, like this:

void FinishFolding()
{
    folder.StopFolding(0); // Shut down immediately
}

You can then add the FinishFolding method to the stopMachinery delegate in place of the StopFolding method, using the same syntax as before:

this.stopMachinery += folder.FinishFolding;

When the stopMachinery delegate is invoked, it calls FinishFolding, which in turn calls the StopFolding method, passing in the parameter of 0.

In many cases, adapter methods such as this are small, and it is easy to lose them in a sea of methods, especially in a large class. Furthermore, apart from using the adapter method to adapt the StopFolding method for use by the delegate, it is unlikely to be called elsewhere. C# provides lambda expressions for situations such as this. Lambda expressions are described in Chapter 18, and there are more examples of them earlier in this chapter. In the factory scenario, you can use the following lambda expression:

this.stopMachinery += (() => folder.StopFolding(0));

When you invoke the stopMachinery delegate, it will run the code defined by the lambda expression, which will, in turn, call the StopFolding method with the appropriate parameter.

Lambda expressions can take a number of subtly different forms. Lambda expressions were originally part of a mathematical notation called the lambda calculus, which provides a notation for describing functions. (You can think of a function as a method that returns a value.) Although the C# language has extended the syntax and semantics of the lambda calculus in its implementation of lambda expressions, many of the original principles still apply. Here are some examples showing the different forms of lambda expressions available in C#:

x => x * x // A simple expression that returns the square of its parameter
           // The type of parameter x is inferred from the context.
x => { return x * x ; } // Semantically the same as the preceding
                        // expression, but using a C# statement block as
                        // a body rather than a simple expression
(int x) => x / 2 // A simple expression that returns the value of the
                 // parameter divided by 2
                 // The type of parameter x is stated explicitly.
() => folder.StopFolding(0) // Calling a method
                            // The expression takes no parameters.
                            // The expression might or might not
                            // return a value.
(x, y) => { x++; return x / y; } // Multiple parameters; the compiler
                                 // infers the parameter types.
                                 // The parameter x is passed by value, so
                                 // the effect of the ++ operation is
                                 // local to the expression.
(ref int x, int y) => { x++; return x / y; } // Multiple parameters
                                             // with explicit types
                                             // Parameter x is passed by
                                             // reference, so the effect of
                                             // the ++ operation is permanent.

To summarize, here are some features of lambda expressions of which you should be aware:

this.stopMachinery += delegate { folder.StopFolding(0); };

control.Add(delegate { folder.StopFolding(0); } );

control.Add(delegate(int param1, string param2)
    { /* code that uses param1 and param2 */ ... });

You declare an event in a class intended to act as an event source. An event source is usually a class that monitors its environment and raises an event when something significant happens. In the automated factory, an event source could be a class that monitors the temperature of each machine. The temperature-monitoring class would raise a “machine overheating” event if it detects that a machine has exceeded its thermal radiation boundary (that is, it has become too hot). An event maintains a list of methods to call when it is raised. These methods are sometimes referred to as subscribers. These methods should be prepared to handle the “machine overheating” event and take the necessary corrective action: shut down the machines.

You declare an event similarly to how you declare a field. However, because events are intended to be used with delegates, the type of an event must be a delegate, and you must prefix the declaration with the event keyword. Use the following syntax to declare an event:

event delegateTypeName eventName

As an example, here’s the StopMachineryDelegate delegate from the automated factory. It has been relocated to a new class called TemperatureMonitor, which provides an interface to the various electronic probes monitoring the temperature of the equipment (this is a more logical place for the event than the Controller class):

class TemperatureMonitor
{
    public delegate void StopMachineryDelegate();
    ...
}

You can define the MachineOverheating event, which will invoke the stopMachineryDelegate, like this:

class TemperatureMonitor
{
     public delegate void StopMachineryDelegate();
     public event StopMachineryDelegate MachineOverheating;
     ...
}

The logic (not shown) in the TemperatureMonitor class raises the MachineOverheating event as necessary. You will see how to raise an event in the upcoming section Raising an event. Also, you add methods to an event (a process known as subscribing to the event) rather than adding them to the delegate on which the event is based. You will look at this aspect of events next.

Like delegates, events come ready-made with a += operator. You subscribe to an event by using this += operator. In the automated factory, the software controlling each machine can arrange for the shutdown methods to be called when the MachineOverheating event is raised, like this:

class TemperatureMonitor
{
     public delegate void StopMachineryDelegate();
     public event StopMachineryDelegate MachineOverheating;
     ...
}
...
TemperatureMonitor tempMonitor = new TemperatureMonitor();
...
tempMonitor.MachineOverheating += (() => { folder.StopFolding(0); });
tempMonitor.MachineOverheating += welder.FinishWelding;
tempMonitor.MachineOverheating += painter.PaintOff;

Notice that the syntax is the same as for adding a method to a delegate. You can even subscribe by using a lambda expression. When the tempMonitor.MachineOverheating event runs, it will call all the subscribing methods and shut down the machines.

Knowing that you use the += operator to attach a delegate to an event, you can probably guess that you use the –= operator to detach a delegate from an event. Calling the –= operator removes the method from the event’s internal delegate collection. This action is often referred to as unsubscribing from the event.

You can raise an event, just like a delegate, by calling it like a method. When you raise an event, all the attached delegates are called in sequence. For example, here’s the TemperatureMonitor class with a private Notify method that raises the MachineOverheating event:

class TemperatureMonitor
{
    public delegate void StopMachineryDelegate();
    public event StopMachineryDelegate MachineOverheating;
    ...
    private void Notify()
    {
        if (this.MachineOverheating != null)
        {
            this.MachineOverheating();
        }
    }
    ...
}

This is a common idiom. The null check is necessary because an event field is implicitly null and only becomes non-null when a method subscribes to it by using the += operator. If you try to raise a null event, you will get a NullReferenceException exception. If the delegate defining the event expects any parameters, the appropriate arguments must be provided when you raise the event. You will see some examples of this later.

In the previous exercise, you amended the Wide World Importers application to decouple the auditing and shipping logic from the checkout process. The CheckoutController class that you built invokes the auditing and shipping components by using a delegate and has no knowledge about these components or the methods it is running; this is the responsibility of the application that creates the CheckoutController object and adds the appropriate references to the delegate. However, it might be useful for a component to be able to alert the application when it has completed its processing and enable the application to perform any necessary tidying up.

This might sound a little strange at first—surely when the application invokes the delegate in the CheckoutController object, the methods referenced by this delegate run, and the application only continues with the next statement when these methods have finished? This is not necessarily the case! Chapter 24 demonstrates that methods can run asynchronously, and when you invoke a method, it might not have completed before execution continues with the next statement. This is especially true in Windows Store apps in which long-running operations are performed on background threads to enable the user interface to remain responsive. In the Wide World Importers application, in the CheckoutButtonClicked method, the code that invokes the delegate is followed by a statement that displays a dialog box with a message indicating that the order has been placed. In the Windows 8.1 Windows Store app, the code looks like this:

private void CheckoutButtonClicked(object sender, RoutedEventArgs e)
{
    try
    {
        // Perform the checkout processing
        this.checkoutController.StartCheckoutProcessing(this.order);
        // Display a summary of the order
        MessageDialog dlg = new MessageDialog(...);
        dlg.ShowAsync();
        ...
    }
    ...
}

The code for the WPF version of the application used by Windows 7 and Windows 8 is similar except that WPF uses a different API for displaying messages.

private void CheckoutButtonClicked(object sender, RoutedEventArgs e)
{
    try
    {
        // Perform the checkout processing
        this.checkoutController.StartCheckoutProcessing(this.order);
        // Display a summary of the order
        MessageBox.Show(...);
        ...
    }
    ...
}

In fact, there is no guarantee that the processing performed by the delegated methods has completed by the time the dialog box appears, so the message could actually be misleading. This is where an event is invaluable. The Auditor and Shipper components could both publish an event to which the application subscribes. This event could be raised by the components only when they have completed their processing. When the application receives this event, it can display the message, safe in the knowledge that it is now accurate.

In the following exercise, you will modify the Auditor and Shipper classes to raise an event that occurs when they have completed their processing. The application will subscribe to the event for each component and display an appropriate message when the event occurs.