A delegate dynamically wires up a method caller to its target method. There are two aspects to a delegate: type and instance. A delegate type defines a protocol to which the caller and target will conform, comprising a list of parameter types and a return type. A delegate instance refers to one or more target methods conforming to that protocol.
A delegate instance literally acts as a delegate for the caller: the caller invokes the delegate, and then the delegate calls the target method. This indirection decouples the caller from the target method.
A delegate type declaration is preceded by the keyword delegate, but otherwise it resembles an (abstract) method declaration. For
example:
delegate int Transformer (int x);
To create a delegate instance, you can assign a method to a delegate variable:
class Test
{
static void Main()
{
Transformer t = Square; // Create delegate instance
int result = t(3); // Invoke delegate
Console.Write (result); // 9
}
static int Square (int x) { return x * x; }
}Invoking a delegate is just like invoking a method (as the delegate’s purpose is merely to provide a level of indirection):
t(3);
The statement:
Transformer t = Square;
is shorthand for:
Transformer t = new Transformer(Square);
Note
A delegate is similar to a “callback,” a general term that captures constructs such as C function pointers.
A delegate variable is assigned a method dynamically. This is
useful for writing plug-in methods. In this example, we have a utility method
named Transform, which applies a transform to each
element in an integer array. The Transform method has a
delegate parameter for specifying a plug-in transform.
public delegate int Transformer (int x);
public class Util
{
public static void Transform (int[] values,
Transformer t)
{
for (int i = 0; i < values.Length; i++)
values[i] = t(values[i]);
}
}
class Test
{
static void Main()
{
int[] values = new int[] {1, 2, 3};
Util.Transform(values, Square); // Dynamically
// hook in Square
foreach (int i in values)
Console.Write (i + " "); // 1 4 9
}
static int Square (int x) { return x * x; }
}All delegate instances have multicast capability. This means that a delegate instance can reference not just a single target method, but also a list of target methods. The += operator combines delegate instances. For example:
SomeDelegate d = SomeMethod1; d += SomeMethod2;
Invoking d will now call both SomeMethod1 and SomeMethod2. Delegates are invoked in the order they are added.
The -= method removes the right delegate operand from the left delegate operand. For example:
d -= SomeMethod1;
Invoking d will now cause only SomeMethod2 to be invoked.
Calling += on a delegate variable with a null value
works, and it is equivalent to assigning the variable to a new value:
SomeDelegate d = null; d += SomeMethod1; // Equivalent (when d is // null) to d = SomeMethod1;
Note
All delegate types implicitly inherit System.MulticastDelegate, which inherits from System.Delegate. C# compiles += and -= operations made on a
delegate to the static Combine and Remove methods of the System.Delegate class.
If a multicast delegate has a nonvoid return type, the caller receives the return
value from the last method to be invoked. The preceding methods are still called, but
their return values are discarded. In most scenarios in which multicast delegates are used, they have void return types, so this subtlety does not arise.
When a delegate instance is assigned to an instance method, the delegate instance
maintains a reference not only to the method, but also to the
instance of that method. (The System.Delegate class’s Target property
represents this instance and will be null for a delegate referencing a static
method.)
A delegate type may contain generic type parameters. For example:
public delegate T Transformer<T> (T arg);
Here’s how we could use this delegate type:
static double Square (double x) { return x * x; }
static void Main( )
{
Transformer<double> s = Square;
Console.WriteLine (s (3.3)); // 10.89
}Delegate types are all incompatible with each other, even if their signatures are the same:
delegate void D1( ); delegate void D2( ); ... D1 d1 = Method1; D2 d2 = d1; // compile-time error
Delegate instances are considered equal if they have the same method targets:
delegate void D( ); ... D d1 = Method1; D d2 = Method1; Console.WriteLine (d1 == d2); // true
When you call a method, you can supply arguments that have more specific types than the parameters of that method. This is ordinary polymorphic behavior. For exactly the same reason, a delegate can have more specific parameter types than its method target. This is called contravariance.
Here’s an example:
delegate void SpecificDelegate (SpecificClass s);
class SpecificClass { }
static void Main( )
{
SpecificDelegate specificDelegate = GeneralHandler;
specificDelegate (new SpecificClass( ));
}
static void GeneralHandler (object o)
{
Console.WriteLine (o.GetType( )); // SpecificClass
}If you call a method, you may get back a type that is more specific than what you asked for. This is ordinary polymorphic behavior. For exactly the same reason, the return type of a delegate can be less specific than the return type of its target method. This is called covariance. For example:
delegate Asset DebtCollector( );
class Asset { }
class House : Asset { }
static void Main( )
{
DebtCollector d = new DebtCollector (GetHomeSweetHome);
Asset a = d( );
Console.WriteLine (a.GetType( )); // House
}
static House GetHomeSweetHome( ) { return new House( ); }The DebtCollector expects to get back an Asset—but any Asset will
do: delegate return types are covariant.