NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Delegate Class

Represents a delegate, which is a data structure that refers to a static method or to an object instance and an instance method of that object.

Object
   Delegate

[Visual Basic]
MustInherit Public Class Delegate
   Implements ICloneable, ISerializable
[C#]
public abstract class Delegate : ICloneable, ISerializable
[C++]
public __gc __abstract class Delegate : public ICloneable,
   ISerializable
[JScript]
public abstract class Delegate implements ICloneable, ISerializable

Remarks

The Delegate class is the base class for delegates.

The closest equivalent of a delegate in C or C++ is a function pointer. However, a function pointer can only reference static functions, whereas a delegate can reference both static and instance methods. When the delegate references instance methods, the delegate stores not only a reference to the method's entry point, but also a reference to the object instance for which to invoke the method. Unlike function pointers, delegates are object-oriented, type-safe, and secure.

An invocation list is a linked list of delegates that are to be invoked when the Invoke method is called.

A delegate that inherits directly from the Delegate class has an invocation list with only one element-- itself. A delegate that inherits from the MulticastDelegate class may have an invocation list with more than one element. The Combine and Remove methods are used to create new invocation lists.

Subclasses of Delegate and MulticastDelegate are declared with special syntax.

For example, the following declarations are for a delegate which encapsulates a method that takes a single parameter of type String and has no return value:

// Managed C++ delegate declaration
__delegate void mySingleCast(String *value);

[Visual Basic]

' VB delegate declaration 
Public Delegate Sub mySingleCast(value As String)

When these declarations are compiled, a class by the name of mySingleCast is generated. This class has two members, a constructor and an Invoke method. The compiler generates metadata for these members and sets a bit indicating that no implementation is provided. The EE provides the implementation. Although the class declarations that follow are not 100% accurate, they offer a glimpse of what the declaration for mySingleCast would look like if the compiler did not generate the class from the simplified delegate declaration syntax given above.

// Managed C++ pseudo code for mySingleCast 
class mySingleCast { 
  public: 
    mySingleCast(Object *obj, int ptr); 
  public: 
    void Invoke(String *value); 
};

[Visual Basic]

' VB pseudo code for mySingleCast 
Class mySingleCast 
  Public Sub New(obj As Object, ptr As Long) 
  Public Sub Invoke(value As String) 
End Class

Observe that the mySingleCast class contains two members (this is true for every subclass of Delegate and MulticastDelegate). The first member is a constructor with the metadata signature .ctor (System/Object, I4), where .ctor indicates that the member is a constructor, System/Object indicates the first parameter is an Object, and I4 indicates that the second parameter is a 4-byte integer. The first parameter is the target of the delegate and the second parameter is the address of the method body. The second member of a mySingleCast is a method with the metadata signature Void Invoke(System/String). The parameter list, which consists a single String parameter, indicates that the mySingleCast delegate encapsulates methods that take a single String parameter. Note that the Invoke method is used for early bound invocation of the method encapsulated by this delegate (late bound invocation is accomplished via Delegate.DynamicInvoke).

Compilers are free to access the constructor in any way they choose; this constructor requires special handling. For example, observe the difference in how the mySingleCast constructor is invoked in Managed C++ and VB:

// Managed C++ delegate instantiation 
class myEcho { 
  public: 
    void shout(String *value) {Console::WriteLine(value);}; 
}; 

void main() { 
  myEcho *obj = new myEcho(); 
  mySingleCast *dlgt = new mySingleCast(obj, &myEcho::shout); 
  // alternative : mySingleCast *dlgt = new mySingleCast(obj->shout); 
  dlgt->Invoke("Argh!"); 
};

[Visual Basic]

' VB pseudo code for mySingleCast 
Class myEcho 
  Public Sub Shout(value As String) 
    Console.WriteLine(value) 
  End Sub 
End Class 

Sub main 
  Dim obj As myEcho 
  Set obj = New myEcho() 
  Dim dlgt As mySingleCast 
  Set dlgt = New mySingleCast(AddressOf obj.shout) 
  dlgt.Invoke("Argh!") 
End Sub

Observe that VB invokes the mySingleCast constructor with an expression as the parameter (AddressOf obj.shout). This is due to the fact that VB does not allow the address of a method to be determined in any other way. The IL that is emitted by the VB compiler actually calls the constructor discussed above, passing an Object reference and the address of the method body. On the other hand, Managed C++ allows the mySingleCast constructor to be invoked directly--new mySingleCast(obj, &myEcho::shout). Alternatively, the following syntax may be used: new mySingleCast(obj->shout). (Note that even if the method to be encapsulated is static, Managed C++ does not allow the constructor of a delegate to be invoked with only the address of a member of a managed class. Managed C++ may choose to do this in the future, since the constructor for every subclass of Delegate or MulticastDelegate allows the target object to be a null reference if the method is static.)

Requirements

Namespace: System

Assembly: mscorlib.dll

See Also

Delegate Members | System Namespace | MulticastDelegate