Environment: .NET, C#, Visual Basic .NET, Windows 2000, Windows XP, Windows NT4 SP6a
Microsoft .NET event handling, in common with typical object-oriented frameworks, is implemented using the well-known Observer design pattern. (See the book, Design Patterns, by Gamma et al., Addison-Wesley, 1995, pp 325-330). This article describes how to enhance .NET event handling with the Template Method design pattern. The discussion and code snippets are in C# but the summary sample is implemented in both C# and Visual Basic .NET.
The article elaborates on ideas discussed by Tomas Restrepo in the March 2002 issue of Visual Systems Journal,
which builds on the recommended practice for event handling described by Microsoft in the MSDN Library .NET topic, Design Guidelines for Class Library Developers. (See the sub-topic "Event Usage
Guidelines.")
The simplest strategy for event handling is just to raise an event and not care about who consumes it, or whether different clients need to relate to it in different ways.
Example – Simple Event Handling
Consider a class, Supplier
, that raises an event whenever its name
field is set and a class, Client
, that handles it.
public class Supplier
{
public Supplier() {}public event EventHandler NameChanged;
public string Name
{
get { return name; }
set { name = value; OnNameChanged(); }
}private void OnNameChanged()
{
// If there are registered clients raise event
if (NameChanged != null)
NameChanged(this, new EventArgs());
}private string name;
}public class Client
{
public Client()
{
// Register for supplier event
supplier = new Supplier();
supplier.NameChanged +=
new EventHandler(this.supplier_NameChanged);
}public void TestEvent()
{
// Set the name – which generates an event
supplier.Name = "Kevin McFarlane";
}private void supplier_NameChanged(object sender, EventArgs e)
{
// Handle supplier event
}private Supplier supplier;
}
Clients of an event can be both external and internal.
An "external" client is one that consumes an event but is not related to the class that raises the event. In other words, it is not part of the event class’s inheritance tree. The class, Client
, above is an external client.
An "internal" client can be the event-raising class itself, if it’s handling
its own events, or a subclass of the event-raising class. In such cases, the simple strategy outlined above is inadequate. Clients cannot easily change what happens when the event is raised or what the default behaviour is when handling the event.
To tackle this problem, in the .NET Design Guidelines for Class Library Developers, Microsoft recommends using a protected virtual method for raising each event. This provides a way for subclasses to handle the event using an override. So, in our example, OnNameChanged()
should look like this:
protected virtual void OnNameChanged()
{
// If there are registered clients raise event
if (NameChanged != null)
NameChanged(this, new EventArgs());
}
Microsoft then adds: "The derived class can choose not to call the base class during the processing of OnEventName. Be prepared for this by not including any processing in the OnEventName method that is required for the base class to work correctly."
Therein lies the problem. In general, OnNameChanged()
may do some default
processing before it raises the event. An OnNameChanged()
override may want to do something different. But to ensure that external clients work properly it must
call the base class version. If it doesn’t call the base class version the event will not be raised for external clients. And it may forget to call the base class version. Forgetting to call the base class version, which raises the event, violates the Liskov (polymorphic) substitution principle: methods that use references to base classes must be able to use objects of derived classes without knowing it. Fortunately, there is a way out of this problem.
The Template Method Design Pattern
The purpose of the Template Method design pattern is to define an algorithm as a fixed sequence of steps but have one or more of the steps variable. In our example the algorithm can be considered to consist of raising the event and responding to it. The part that needs to be variable is the response. So the trick is to separate this from the raising of the event. We split OnNameChanged()
into two methods: InternalOnNameChanged()
and OnNameChanged()
.
InternalOnNameChanged()
calls OnNameChanged()
to perform default processing and then raises the event.
private void InternalOnNameChanged()
{
// Derived classes may override default behaviour
OnNameChanged();// If there are registered clients raise event
if (NameChanged != null)
NameChanged(this, new EventArgs());
}protected virtual void OnNameChanged()
{
// Implement default behaviour here
}
The Name
property is now altered to look like this:
get { return name; }
set { name = value; InternalOnNameChanged(); }
The advantages of this technique are:
- An essential step in the base class implementation, in this case raising
the event, cannot be avoided by the derived class’s failing to call the base
class implementation. So external clients can be reliably serviced. - The derived class can safely replace the base class’s default behaviour in
OnNameChanged()
with no worries.
Example – Template Method Design Pattern Event Handling
Below is a complete example implemented in both C# and Visual Basic .NET. It consists of three classes, Supplier
, ExternalClient
and InternalClient
. Supplier
raises an event. The two client classes each consume the event. InternalClient
is a derived class of Supplier
.
ExternalClient
contains an embedded Supplier
reference. However, this is initialised with an InternalClient
reference. Thus when ExternalClient
registers for the Supplier
event, this invokes InternalClient
‘s OnNameChanged()
override. Then the event is handled by InternalClient
‘s NameChanged()
and finally ExternalClient
‘s NameChanged()
handlers.
So the output that is produced is:
InternalClient.OnNameChanged InternalClient.NameChanged ExternalClient.NameChanged
C# Implementation
using System;class Test
{
static void Main(string[] args)
{
ExternalClient client = new ExternalClient();
client.TestSupplier();
}
}// Generates an event when its property is set.
public class Supplier
{
public Supplier() {}public event EventHandler NameChanged;
public string Name
{
get { return name; }
set { name = value; InternalOnNameChanged(); }
}// Internal clients, i.e., derived classes, can override
// default behaviour.
protected virtual void OnNameChanged()
{
// Implement default behaviour here
Console.WriteLine("Supplier.OnNameChanged");
}// If internal clients (derived classes) override the
// default behaviour in OnNameChanged
// then external clients will still receive the event.
private void InternalOnNameChanged()
{
// Derived classes may override default behaviour
OnNameChanged();// If there are registered clients raise event
if (NameChanged != null)
NameChanged(this, new EventArgs());
}private string name;
}// An "internal" client that handles the Supplier.NameChanged
// eventbut first overrides its default behaviour.
public class InternalClient : Supplier
{
public InternalClient()
{
NameChanged += new EventHandler(this.Supplier_NameChanged);
}protected override void OnNameChanged()
{
// Override default behaviour of Supplier.NameChanged
Console.WriteLine("InternalClient.OnNameChanged");
}private void Supplier_NameChanged(object sender, EventArgs e)
{
// Handle Supplier.NameChanged
Console.WriteLine("InternalClient.NameChanged");
}
}// An "external" client that handles the
// Supplier.NameChanged event.
public class ExternalClient
{
public ExternalClient()
{
// Instantiate supplier as a reference to an
// InternalClient instance.
// This should trigger the InternalClient.OnNameChanged
// override when an event is raised.
supplier = new InternalClient();
supplier.NameChanged +=
new EventHandler(this.supplier_NameChanged);
}public void TestSupplier()
{
// This should raise an event and it will be handled by
// the InternalClient and ExternalClient handlers.
supplier.Name = "Kevin McFarlane";
}private void supplier_NameChanged(object sender, EventArgs e)
{
// Handle Supplier.NameChanged
Console.WriteLine("ExternalClient.NameChanged");
}private Supplier supplier;
}
Visual Basic .NET Implementation
Module TestSub Main()
Dim client As ExternalClient = New ExternalClient()
client.TestSupplier()
End SubEnd Module
‘ Generates an event when its property is set.
Public Class Supplier
Sub New()
End SubPublic Event NameChanged As EventHandler
Public Property Name() As String
Get
Return mName
End Get
Set(ByVal Value As String)
mName = Value
InternalOnNameChanged()
End Set
End Property‘ Internal clients, i.e., derived classes, can override
‘ default behaviour.
Protected Overridable Sub OnNameChanged()
‘ Implement default behaviour here
Console.WriteLine("Supplier.OnNameChanged")
End SubPrivate Sub InternalOnNameChanged()
‘ Derived classes may override default behaviour
OnNameChanged()‘ Raise event for clients
RaiseEvent NameChanged(Me, New EventArgs())
End SubPrivate mName As String
End Class‘ An "internal" client that handles the Supplier.NameChanged
‘ event but first overrides its default behaviour.
Public Class InternalClient
Inherits SupplierSub New()
End SubProtected Overrides Sub OnNameChanged()
‘ Override default behaviour of Supplier.NameChanged
Console.WriteLine("InternalClient.OnNameChanged")End Sub
Private Sub Supplier_NameChanged(ByVal sender As Object, _
ByVal e As EventArgs) _
Handles MyBase.NameChanged‘ Handle Supplier.NameChanged
Console.WriteLine("InternalClient.NameChanged")
End Sub
End Class‘ An "external" client that handles the
‘ Supplier.NameChanged event.
Public Class ExternalClient
Sub New()
‘ Instantiate Supplier as a reference to an
‘ InternalClient instance.
‘ This should trigger the InternalClient.OnNameChanged
‘ override when an event is raised.
mSupplier = New InternalClient()‘ Register for Supplier.NameChanged event
AddHandler mSupplier.NameChanged, _
AddressOf mSupplier_NameChanged
End SubPublic Sub TestSupplier()
‘ This should raise an event and it will be handled by
‘ the InternalClient and ExternalClient handlers.
mSupplier.Name = "Kevin McFarlane"End Sub
Private Sub mSupplier_NameChanged(ByVal sender As Object, _
ByVal e As EventArgs)
‘ Handle Supplier.NameChanged
Console.WriteLine("ExternalClient.NameChanged")
End SubPrivate mSupplier As Supplier
End Class