A delegate wires up a method caller to its target method at runtime. 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 is an object that 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 (since 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);
And t(3)
is shorthand for:
t.Invoke (3);
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 at runtime. This is
useful for writing plug-in methods. In this example, we have a utility
method named Transform
that 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);
class Test
{
static void Main()
{
int[] values = { 1, 2, 3 };
Transform (values, Square);
foreach (int i in values)
Console.Write (i + " "); // 1 4 9
}
static void Transform (int[] values, Transformer t
)
{
for (int i = 0; i < values.Length; i++)
values[i] = t (values[i]);
}
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 +
and +=
operators combine delegate instances. For example:
SomeDelegate d = SomeMethod1; d += SomeMethod2;
The last line is functionally the same as:
d = d + SomeMethod2;
Invoking d
will now call both
SomeMethod1
and SomeMethod2
. Delegates are invoked in the
order they are added.
The -
and -=
operators remove the right delegate operand
from the left delegate operand. For example:
d -= SomeMethod1;
Invoking d
will now cause only
SomeMethod2
to be invoked.
Calling +
or +=
on a delegate variable with a null
value is legal, as is calling -=
on a delegate variable with a single target
(which will result in the delegate instance being null
).
Delegates are immutable, so when you call
+=
or -=
, you’re in fact creating a
new delegate instance and assigning it to the existing
variable.
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.
All delegate types implicitly derive from 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.
When an instance method is assigned to a
delegate object, the latter must maintain a reference not only to the
method, but also to the instance to which the
method belongs. 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
}
With generic delegates, it becomes possible to write a small
set of delegate types that are so general they can work for methods of
any return type and any (reasonable) number of arguments. These
delegates are the Func
and Action
delegates, defined in the System
namespace (the in
and out
annotations indicate variance, which we will cover
shortly):
delegate TResult Func <out TResult> (); delegate TResult Func <in T, out TResult> (T arg); delegate TResult Func <in T1, in T2, out TResult> (T1 arg1, T2 arg2);... and so on, up to T16
delegate void Action (); delegate void Action <in T> (T arg); delegate void Action <in T1, in T2> (T1 arg1, T2 arg2);... and so on, up to T16
These delegates are extremely general. The Transformer
delegate in our previous example
can be replaced with a Func
delegate that takes a single argument of
type T
and returns a same-typed
value:
public static void Transform<T> (
T[] values, Func<T,T> transformer
)
{
for (int i = 0; i < values.Length; i++)
values[i] = transformer (values[i]);
}
The only practical scenarios not covered by these delegates are
ref
/out
and pointer parameters.
Delegate types are all incompatible with one another, even if their signatures are the same:
delegate void D1(); delegate void D2(); ... D1 d1 = Method1; D2 d2 = d1; // Compile-time error
The following, however, is permitted:
D2 d2 = new
D2 (d1);
Delegate instances are considered equal if they have the same type and method target(s). For multicast delegates, the order of the method targets is significant.
When you call a method, you may get back a type that is more specific than what you asked for. This is ordinary polymorphic behavior. In keeping with this, a delegate target method may return a more specific type than described by the delegate. This is covariance, and has been supported since C# 2.0:
delegate object ObjectRetriever(); ... static void Main() { ObjectRetriever o = new ObjectRetriever (GetString); object result = o(); Console.WriteLine (result); // hello } static string GetString() { return "hello"; }
The ObjectRetriever
expects
to get back an object
, but an
object
subclass will also do because delegate return
types are covariant.
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. In keeping with this, a delegate target method may have less specific parameter types than described by the delegate. This is called contravariance:
delegate void StringAction (string s); ... static void Main() { StringAction sa = new StringAction (ActOnObject); sa ("hello"); } static void ActOnObject (object o) { Console.WriteLine (o); // hello }
We saw in Generics how type parameters can be covariant and contravariant for generic interfaces. The same capability also exists for generic delegates from C# 4.0. If you’re defining a generic delegate type, it’s a good practice to:
Mark a type parameter used only on the return value as
covariant (out
).
Mark any type parameters used only on parameters as
contravariant (in
).
Doing so allows conversions to work naturally by respecting
inheritance relationships between types. The following delegate
(defined in the System
namespace)
is covariant for TResult
:
delegate TResult Func<out
TResult>();
allowing:
Func<string> x = ...; Func<object> y = x;
The following delegate (defined in the System
namespace) is contravariant for
T
:
delegate void Action<in
T> (T arg);
Action<object> x = ...; Action<string> y = x;