Routed Events (part 2)

Referring back to Routed Events (to part 1), let’s have a closer look at this part of the example source code:

// bubbling
private void MyMouseUp(object sender, MouseButtonEventArgs e) {
  FrameworkElement lElement = sender as FrameworkElement;
  string lAppend = Environment.NewLine;
  if (sender is Window) lAppend += Environment.NewLine;
  Results.Text += e.RoutedEvent.RoutingStrategy.ToString() + ": " + lElement.ToString() + lAppend;
  e.Handled = false;
  Results.ScrollToEnd();
} //

 

Suppressing Events

e.Handled allows you to halt the event routing process. Set this boolean to true and the event stops traveling any further. A small change demonstrates the altered behavior:

// bubbling
private void MyMouseUp(object sender, MouseButtonEventArgs e) {
  FrameworkElement lElement = sender as FrameworkElement;
  string lAppend = Environment.NewLine;
  if (sender is Window) lAppend += Environment.NewLine;
  Results.Text += e.RoutedEvent.RoutingStrategy.ToString() + ": " + lElement.ToString() + lAppend;
  e.Handled = (e.ChangedButton == MouseButton.Right);
  Results.ScrollToEnd();
} //

If you use the right MouseButton now, the bubbling routing event process stops. The same applies to the tunneling process when you change the MyPreviewMouseUp() method accordingly.

 

Raising Suppressed Events

You can avoid the suppression of Routed Events. This cannot be done through XAML. Use the AddHandler() method instead. An overload accepts a boolean for its third parameter. Set this one to true and you will receive events even if the e.Handled flag was set to true.

Let’s slightly change our example source code to:

<Window x:Class="DemoApp.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:app="clr-namespace:DemoApp"
        Title="MainWindow" Height="500" Width="630"
        Name="MyWindow" PreviewMouseUp="MyPreviewMouseUp">
    ...

...
public MainWindow() {
 InitializeComponent();
 
 List<Data> lItems = new List<Data>() {
    new Data() {Name = "Otto", LastName = "Waalkes"},
    new Data() {Name = "Heinz", LastName = "Rühmann"},
    new Data() {Name = "Michael", LastName = "Herbig"},
    new Data() {Name = "Sky", LastName = "du Mont"},
    new Data() {Name = "Dieter", LastName = "Hallervorden"},
    new Data() {Name = "Diether", LastName = "Krebs"},
    new Data() {Name = "Helga", LastName = "Feddersen"},
    new Data() {Name = "Herbert", LastName = "Grönemeyer"},
  };
    
  MyListView.ItemsSource = lItems;
  MyWindow.AddHandler(UIElement.MouseUpEvent, new MouseButtonEventHandler(MyMouseUp), true);      
} //
...

Et voilà! The Routed Event gets executed despite the set e.Handled flag.

 
Attached Events

The Click event is defined in the ButtonBase class. It is a kind of combination of a Button press and release. But how can you use the bubbling behavior on a higher level like eg. a Grid that does not derive from the ButtonBase class? Attached events enable you to add event handlers to arbitrary elements, which do not define or inherit these.
Let’s add a Click event to the window level by adding Button.Click=”MyClick”:

<Window x:Class="DemoApp.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:app="clr-namespace:DemoApp"
        Title="MainWindow" Height="500" Width="630"
        Name="MyWindow" PreviewMouseUp="MyPreviewMouseUp"
        Button.Click="MyClick" >
    ...

private void MyClick(object sender, RoutedEventArgs e) {
  MessageBox.Show("Click received!");
} //

The program does not raise any Click events. We did even override the Click event of our TripleClickButton class. You won’t see a lot. But have a look at the two scroll bars. The scroll bar background (not the scroll bar itself) raises click events. As we are on the window level, we now receive these unexpected events. Indeed, this is a good example. A click of the scroll bar background bubbles through the hierarchy and finally raises the attached Click event on the window level.
Don’t forget to analyse the e.Source of your event parameter. You need to filter out the right Click event.

 

Style EventSetter

While Property setters are most common in Styles, EventSetters are rarely seen. They can be used for more complex problems. The simple ones should be solved by using Style.Triggers. Let’s say you want to change the color of a TextBlock when entering or leaving the area with the mouse cursor.

...
<Window.Resources>
    <Style x:Key="ChangeBackgroundColor" TargetType="TextBlock">
        <EventSetter Event="TextBlock.MouseEnter" Handler="ChangeBackgroundColorOnMouseEnter" /> // direct event
        <EventSetter Event="TextBlock.MouseLeave" Handler="ChangeBackgroundColorOnMouseLeave" /> // direct event
    </Style>
</Window.Resources>
...
<TextBlock Text="LastName:  " Grid.Column="2"  VerticalAlignment="Center" FontSize="16" Style="{StaticResource ChangeBackgroundColor}"/>
...

    private void ChangeBackgroundColorOnMouseEnter(object sender, MouseEventArgs e) { ((TextBlock)sender).Background = Brushes.Red; }
    private void ChangeBackgroundColorOnMouseLeave(object sender, MouseEventArgs e) { ((TextBlock)sender).Background = null; }

 

This example could be simplified. No C# code required:

...
<Window.Resources>
    <Style x:Key="ChangeBackgroundColor" TargetType="TextBlock">
        <Style.Triggers>
            <Trigger Property="TextBlock.IsMouseOver" Value="True">
                <Setter Property="TextBlock.Background" Value="Red" />
            </Trigger>
        </Style.Triggers>                       
    </Style>
</Window.Resources>
...
<TextBlock Text="LastName:  " Grid.Column="2"  VerticalAlignment="Center" FontSize="16" Style="{StaticResource ChangeBackgroundColor}"/>
...

 

I see the need for further explanations on Trigger types. I have just added a reminder on my To-Do-List.
But for now a simple list must suffice:

• Trigger: Simplest trigger form. Reacts on DependencyProperty changes and then uses setters to change styles.
• MultiTrigger: Combines multiple Triggers. All conditions must be met.
• DataTrigger: Reacts on changes in bound data.
• MultiDataTrigger: Combines multiple DataTriggers. All conditions must be met.
• EventTrigger: Reacts on events. Used for animations.

In a nutshell: There are three trigger types. They use dependency properties, routed events or data binding.

Routed Events (part 1)

Events notify your code that something has happened. You subscribe to events like you subscribe eg. to a monthly magazine. Let’s say a new magazine comes out. The postal worker delivers it to your mail box. You don’t need to ask for the new magazine to be sent to you each time.
Something similar takes place in WPF. A button is pressed and the program delivers that information to your mail box, which is a callback method.

Links:
Events Part1
Events Part2
Events Part3
 

The classical event has a standard pattern:

public delegate void dMyDelegate();
public event dMyDelegate MyEvent;

public void addEvent() { MyEvent += Callback; }
public void removeEvent() { MyEvent -= Callback; }

public void CallEvent() {
  dMyDelegate d = MyEvent;
  if (d == null) return;
  d();
} //

void Callback() { Console.WriteLine("Event raised"); }

Or this:

private EventHandler _Handler;
public event EventHandler MyEvent {
  add { _Handler += value; }
  remove { _Handler -= value; }
} //

...

 
 

But what exactly is a “Routed Event”?

Routed Events are used in connection with WPF. They are required for a certain routing concept. In WinForms the callback is sent by the corresponding component (eg. the button). But in WPF event routing allows an event to take place in one element, but be raised by another one. That way you can handle events in the most convenient place.
A Button could be part of a template, which in turn is a part of a ListView. The Button could have an image, an ornated border, a grid and many extras. It does make sense to receive events on the group level sometimes.

We know direct events from WinForms. A mouse click raises an event. But in WPF there are two more types:

1. Bubbling Events: They travel up the hierarchy of the visual tree. The click raises an event on the button, then on the grid, then on the window. It also raises events on all objects on the way.
2. Tunneling Events: These events travel to the opposite direction. A keyboard entry would start at the window level, then travel through the grid towards the button.

 

Let’s just delve into a practical example. Run the code and observe what is happening.

 

<Window x:Class="DemoApp.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        Title="MainWindow" Height="500" Width="630"
        MouseUp="MyMouseUp" PreviewMouseUp="MyPreviewMouseUp">
    <Grid MouseUp="MyMouseUp" PreviewMouseUp="MyPreviewMouseUp">
        <Grid.RowDefinitions>
            <RowDefinition Height="300" />
            <RowDefinition Height="*" />
        </Grid.RowDefinitions>
        <ListView Name="MyListView" Margin="0,0,0,0" Grid.IsSharedSizeScope="True" ScrollViewer.VerticalScrollBarVisibility="Auto" ScrollViewer.CanContentScroll="True" MouseUp="MyMouseUp"  PreviewMouseUp="MyPreviewMouseUp" Grid.Row="0">
            <ListView.ItemTemplate>
                <DataTemplate>
                    <GroupBox Header="Item" FontSize="10">
                        <Grid PreviewMouseUp="MyPreviewMouseUp" MouseUp="MyMouseUp">
                            <Grid.ColumnDefinitions>
                                <ColumnDefinition />
                                <ColumnDefinition SharedSizeGroup="A" />
                                <ColumnDefinition />
                                <ColumnDefinition SharedSizeGroup="A" />
                                <ColumnDefinition />
                            </Grid.ColumnDefinitions>
                            <TextBlock Text="Name:  " Grid.Column="0" VerticalAlignment="Center"  FontSize="16" PreviewMouseUp="MyPreviewMouseUp"/>
                            <TextBlock Text="{Binding Name}" FontWeight="Bold" Grid.Column="1"  VerticalAlignment="Center" FontSize="16"/>
                            <TextBlock Text="LastName:  " Grid.Column="2"  VerticalAlignment="Center" FontSize="16"/>
                            <TextBlock Text="{Binding LastName}" FontWeight="Bold" Grid.Column="3" VerticalAlignment="Center" FontSize="16"/>
                            <TextBlock Text="Click me" Grid.Column="4" FontSize="16" MouseUp="MyMouseUp" Background="AliceBlue"/>
                        </Grid>
                    </GroupBox>
                </DataTemplate>
            </ListView.ItemTemplate>
        </ListView>
        <TextBox Name="Results" IsReadOnly="True" FontSize="14" ScrollViewer.VerticalScrollBarVisibility="Auto" Height="Auto" Grid.Row="1" />
    </Grid>
</Window>

using System;
using System.Collections.Generic;
using System.Windows;
using System.Windows.Documents;
using System.Windows.Input;

namespace DemoApp {
  public partial class MainWindow : Window {

    public class Data {
      public string Name { get; set; }
      public string LastName { get; set; }
    } //

    public MainWindow() {
      InitializeComponent();

      List<Data> lItems = new List<Data>() {
        new Data() {Name = "Otto", LastName = "Waalkes"},
        new Data() {Name = "Heinz", LastName = "Rühmann"},
        new Data() {Name = "Michael", LastName = "Herbig"},
        new Data() {Name = "Sky", LastName = "du Mont"},
        new Data() {Name = "Dieter", LastName = "Hallervorden"},
        new Data() {Name = "Diether", LastName = "Krebs"},
        new Data() {Name = "Helga", LastName = "Feddersen"},
        new Data() {Name = "Herbert", LastName = "Grönemeyer"},
      };
      MyListView.ItemsSource = lItems;
    } //

    // bubbling
    private void MyMouseUp(object sender, MouseButtonEventArgs e) {
      FrameworkElement lElement = sender as FrameworkElement;
      string lAppend = Environment.NewLine;
      if (sender is Window) lAppend += Environment.NewLine;
      Results.Text += e.RoutedEvent.RoutingStrategy.ToString() + ": " + lElement.ToString() + lAppend;
      e.Handled = false;
      Results.ScrollToEnd();
    } //

    // tunneling
    private void MyPreviewMouseUp(object sender, MouseButtonEventArgs e) {
      FrameworkElement lElement = sender as FrameworkElement;
      string lAppend = Environment.NewLine;
      if (sender.Equals(e.OriginalSource)) lAppend += Environment.NewLine;
      Results.Text += e.RoutedEvent.RoutingStrategy.ToString() + ": " + lElement.ToString() + lAppend;
      e.Handled = false;
      Results.ScrollToEnd();
    } //

  } // class
} // namespace

 
Tunneling Events are raised before Bubbling Events. The convention for Tunneling Events in .Net is that names have to start with the prefix “Preview”. Therefore The “MouseUp” event is a Bubbling Event and “PreviewMouseUp” is a Tunneling Event.
Today’s XAML source code subscribes to bubbling/tunneling events at several places. Compare the output with the code. In theory you could deal with all events on the window level. Use the e.OriginalSource field of the event argument MouseButtonEventArgs e to distinguish between the many possible events. You will also receive events that you did not explicitly subscribe to. Click into the lower textbox or on a scroll bar; this will raise events on the Grid, (ListView) and Window.

Now, let’s add a tunneling event to the “Click me” TextBlock.

<TextBlock Text="Click me" Grid.Column="4" FontSize="16" MouseUp="MyMouseUp" PreviewMouseUp="MyPreviewMouseUp" Background="AliceBlue"/>

 
This activates the code that was redundant so far:

if (sender.Equals(e.OriginalSource)) lAppend += Environment.NewLine;

 
 
Custom Routed Events

How can we add a custom routed event? Just follow this pattern:

• Inherit an element from another class.
• Define a public static readonly RoutedEvent.
• Register that Event by using the EventManager.
• Add an “old school” C# event that forwards “old school” subscriptions to your WPF routed event.

 
And here we go. Let’s add a button with a triple click event.

using System;
using System.Collections.Generic;
using System.Windows;
using System.Windows.Controls;

namespace DemoApp {
  public class TripleClickButton : Button {

    /*
     * The methods AddHandler, RemoveHandler and RaiseEvent are inherited from UIElement
     */

    // public static readonly !
    public static readonly RoutedEvent TripleClickEvent = EventManager.RegisterRoutedEvent("TripleClick", RoutingStrategy.Bubble, typeof(RoutedEventHandler), typeof(TripleClickButton));

    // Link classical approach to the above WPF RoutedEvent.
    // Do not add any complex code here!
    public event RoutedEventHandler TripleClick {
      add { AddHandler(TripleClickEvent, value); }
      remove { RemoveHandler(TripleClickEvent, value); }
    } //

    // How to trigger our Routed Event. 
    void RaiseTripleClickEvent() {
      RoutedEventArgs lRoutedEventArgs = new RoutedEventArgs(TripleClickButton.TripleClickEvent);
      RaiseEvent(lRoutedEventArgs);
    } //

    private List<DateTime> _Clicks = new List<DateTime>();
    protected override void OnClick() {
      lock (_Clicks) { // In theory we do not need a lock, because the event is always raised on the Dispatcher thread.
        DateTime lNow = DateTime.Now;
        _Clicks.Add(lNow);
        if (_Clicks.Count < 3) return;
        if (lNow.Subtract(_Clicks[0]).TotalMilliseconds < 1000) {
          _Clicks.Clear();
          RaiseTripleClickEvent();
          return;
        }
        _Clicks.RemoveAt(0);
      }      
    } //

  } // class
} // namespace

 
Declare the new class in the XAML window namespace and replace the rightmost TextBlock by our new custom button.

<Window x:Class="DemoApp.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:app="clr-namespace:DemoApp"
        ...
       <TextBlock Text="{Binding LastName}" FontWeight="Bold" Grid.Column="3" VerticalAlignment="Center" FontSize="16"/>
       <app:TripleClickButton Content="TripleClick me" Grid.Column="4" FontSize="16" Background="Salmon" TripleClick="TripleClickButton_TripleClick" Tag="{Binding Name}" />
     </Grid>
     ...

 

Define the event itself in the main window. Here is the full code:

using System;
using System.Collections.Generic;
using System.Windows;
using System.Windows.Controls;
using System.Windows.Documents;
using System.Windows.Input;

namespace DemoApp {
  public partial class MainWindow : Window {

    public class Data {
      public string Name { get; set; }
      public string LastName { get; set; }
    } //

    public MainWindow() {
      InitializeComponent();

      List<Data> lItems = new List<Data>() {
        new Data() {Name = "Otto", LastName = "Waalkes"},
        new Data() {Name = "Heinz", LastName = "Rühmann"},
        new Data() {Name = "Michael", LastName = "Herbig"},
        new Data() {Name = "Sky", LastName = "du Mont"},
        new Data() {Name = "Dieter", LastName = "Hallervorden"},
        new Data() {Name = "Diether", LastName = "Krebs"},
        new Data() {Name = "Helga", LastName = "Feddersen"},
        new Data() {Name = "Herbert", LastName = "Grönemeyer"},
      };
      MyListView.ItemsSource = lItems;

      
    } //

    // bubbling
    private void MyMouseUp(object sender, MouseButtonEventArgs e) {
      FrameworkElement lElement = sender as FrameworkElement;
      string lAppend = Environment.NewLine;
      if (sender is Window) lAppend += Environment.NewLine;
      Results.Text += e.RoutedEvent.RoutingStrategy.ToString() + ": " + lElement.ToString() + lAppend;
      e.Handled = false;
      Results.ScrollToEnd();
    } //

    // tunneling
    private void MyPreviewMouseUp(object sender, MouseButtonEventArgs e) {
      FrameworkElement lElement = sender as FrameworkElement;
      string lAppend = Environment.NewLine;
      if (sender.Equals(e.OriginalSource)) lAppend += Environment.NewLine;
      Results.Text += e.RoutedEvent.RoutingStrategy.ToString() + ": " + lElement.ToString() + lAppend;
      e.Handled = false;
      Results.ScrollToEnd();
    }

    // custom event
    private void TripleClickButton_TripleClick(object sender, RoutedEventArgs e) {
      Button lButton = e.OriginalSource as Button;
      if (lButton == null) return;
      
      Results.Text = "TripleClick received from " + lButton.Tag;
    } //

  } // class
} // namespace

 

And the full XAML:

<Window x:Class="DemoApp.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:app="clr-namespace:DemoApp"
        Title="MainWindow" Height="500" Width="630"
        MouseUp="MyMouseUp" PreviewMouseUp="MyPreviewMouseUp">
    <Grid MouseUp="MyMouseUp" PreviewMouseUp="MyPreviewMouseUp">
        <Grid.RowDefinitions>
            <RowDefinition Height="300" />
            <RowDefinition Height="*" />
        </Grid.RowDefinitions>
        <ListView Name="MyListView" Margin="0,0,0,0" Grid.IsSharedSizeScope="True" ScrollViewer.VerticalScrollBarVisibility="Auto" ScrollViewer.CanContentScroll="True" MouseUp="MyMouseUp"  PreviewMouseUp="MyPreviewMouseUp" Grid.Row="0">
            <ListView.ItemTemplate>
                <DataTemplate>
                    <GroupBox Header="Item" FontSize="10">
                        <Grid PreviewMouseUp="MyPreviewMouseUp" MouseUp="MyMouseUp">
                            <Grid.ColumnDefinitions>
                                <ColumnDefinition />
                                <ColumnDefinition SharedSizeGroup="A" />
                                <ColumnDefinition />
                                <ColumnDefinition SharedSizeGroup="A" />
                                <ColumnDefinition />
                            </Grid.ColumnDefinitions>
                            <TextBlock Text="Name:  " Grid.Column="0" VerticalAlignment="Center"  FontSize="16" PreviewMouseUp="MyPreviewMouseUp"/>
                            <TextBlock Text="{Binding Name}" FontWeight="Bold" Grid.Column="1"  VerticalAlignment="Center" FontSize="16"/>
                            <TextBlock Text="LastName:  " Grid.Column="2"  VerticalAlignment="Center" FontSize="16"/>
                            <TextBlock Text="{Binding LastName}" FontWeight="Bold" Grid.Column="3" VerticalAlignment="Center" FontSize="16"/>
                            <app:TripleClickButton Content="TripleClick me" Grid.Column="4" FontSize="16" Background="Salmon" TripleClick="TripleClickButton_TripleClick" Tag="{Binding Name}" />
                        </Grid>
                    </GroupBox>
                </DataTemplate>
            </ListView.ItemTemplate>
        </ListView>
        <TextBox Name="Results" IsReadOnly="True" FontSize="14" ScrollViewer.VerticalScrollBarVisibility="Auto" Height="Auto" Grid.Row="1" />
    </Grid>
</Window>

 

 

The next post will be about:

• Marking Routed Events as handled to avoid further processing.
• Suppressing the suppression of the Handled flag.
• Attached Events
• Style EventSetters

Stay tuned 😉

Events (part 3, advanced)

Events: Let’s go multithreading! We want the crème de la crème. Well, multitasking is also fine.

The code does not need to run in a specific sequence. The required independence is given. Again, there are many ways to use multithreading. An easy approach is to start a task in each method that is called by the event.

C# does support BeginInvoke() for delegates. This method is not supported by the .NET Compact Framework though. We don’t care, because our hardcore programs are for serious applications, definitely not for mobile phone apps. Let’s see how good BeginInvoke() works. Maybe we don’t have to reinvent the wheel.

BeginInvoke() initiates asynchronous calls, it returns immediately and provides the IAsyncResult, which can be used to monitor the progress of the asynchronous call.
EndInvoke() retrieves the results. It blocks until the thread has completed.

You have the following options after calling BeginInvoke():
1) Call EndInvoke() to block the current thread until the call completes.
2) Obtain the WaitHandle from IAsyncResult.AsyncWaitHandle, use its WaitOne() and then call EndInvoke().
3) Poll the IAsyncResult to check the current state, after it has completed call EndInvoke().
4) Pass a callback to BeginInvoke(). The callback will use the ThreadPool to notify you. In the callback you have to call EndInvoke().

public event EventHandler OnChange;

public void DoSomeWork(object sender, object e) {
    Thread.Sleep(2100);
    Console.WriteLine("Thread " + Thread.CurrentThread.ManagedThreadId + " mission accomplished!");
} //

public void RunMyExample() {
    OnChange += new EventHandler(DoSomeWork);
    //OnChange += new EventHandler(DoSomeWork);
    //OnChange += new EventHandler(DoSomeWork);

    IAsyncResult lAsyncResult;

    Console.WriteLine("Choice 1");
    lAsyncResult = OnChange.BeginInvoke(this, EventArgs.Empty, null, null);
    OnChange.EndInvoke(lAsyncResult);

    Console.WriteLine("Choice 2");
    lAsyncResult = OnChange.BeginInvoke(this, EventArgs.Empty, null, null);
    lAsyncResult.AsyncWaitHandle.WaitOne();

    Console.WriteLine("Choice 3");
    lAsyncResult = OnChange.BeginInvoke(this, EventArgs.Empty, null, null);
    while (!lAsyncResult.IsCompleted) {
        Thread.Sleep(500);
        Console.WriteLine("work still not completed :(");
    }

    Console.WriteLine("Choice 4"); 
    OnChange.BeginInvoke(this, EventArgs.Empty, (xAsyncResult) => {
            Console.WriteLine("callback running");
            OnChange.EndInvoke(xAsyncResult);
        }, null);

    Console.WriteLine("press return to exit the program");
    Console.ReadLine();
}//    

example output:
Choice 1
Thread 6 mission accomplished!
Choice 2
Thread 6 mission accomplished!
work still not completed 😦
work still not completed 😦
work still not completed 😦
work still not completed 😦
Thread 10 mission accomplished!
work still not completed 😦
press return to exit the program
Thread 6 mission accomplished!
callback running

After having lived such a nice life, we have to face a major issue with BeginInvoke(). Uncomment “//OnChange += new EventHandler(DoSomeWork);”, don’t get annoyed now!
You will get an error message saying

“The delegate must have only one target”.

Although the delegate class can deal with multiple targets, asynchronous calls accept just one target.

So let’s try something else.

    public event EventHandler OnChange;

    public void DoSomeWork(object sender, object e) {
        Thread.Sleep(2100);
        Console.WriteLine("Thread " + Thread.CurrentThread.ManagedThreadId + " mission accomplished!");
    } //

    public void RunMyExample() {
        OnChange += new EventHandler(DoSomeWork);
        OnChange += new EventHandler((sender, e) => { throw new Exception("something went wrong"); });
        OnChange += new EventHandler(DoSomeWork);

        EventHandler lOnChange = OnChange;
        if (lOnChange == null) return;   // just to demonstrate the proper way to call events, not needed in this example                
        foreach (EventHandler d in lOnChange.GetInvocationList()) {
            Task lTask = Task.Factory.StartNew(() => d(this, EventArgs.Empty));
            lTask.ContinueWith((i) => { Console.WriteLine("Task canceled"); }, TaskContinuationOptions.OnlyOnCanceled);
            lTask.ContinueWith((i) => { Console.WriteLine("Task faulted"); }, TaskContinuationOptions.OnlyOnFaulted);
            lTask.ContinueWith((i) => { Console.WriteLine("Task completion"); }, TaskContinuationOptions.OnlyOnRanToCompletion);
        }

        Console.WriteLine("press return to exit the program");
        Console.ReadLine();
    }//    

It seems that Microsoft has a serious bug here.This code does not execute properly each time. I guess it has to do with the asynchronous behaviour of StartNew(). It sometimes calls the wrong method DoSomeWork() three times and does not raise the exception.
It seems foreach overrides variable “d” before it is inserted in StartNew(). With a little tweak we can avoid this bug. We simply assign “d” to a new local variable. That way we have unique copies of “d”. Weird stuff, but that is the life of a coder sometimes.

public event EventHandler OnChange;

public void DoSomeWork(object sender, object e) {
    Thread.Sleep(2100);
    Console.WriteLine("Thread " + Thread.CurrentThread.ManagedThreadId + " mission accomplished!");
} //

public void RunMyExample() {
    OnChange += new EventHandler(DoSomeWork);
    OnChange += new EventHandler((sender, e) => { throw new Exception("something went wrong"); });
    OnChange += new EventHandler(DoSomeWork);

    EventHandler lOnChange = OnChange;
    if (lOnChange == null) return;   // just to demonstrate the proper way to call events, not needed in this example                
    foreach (EventHandler d in lOnChange.GetInvocationList()) {
        EventHandler e = d;
        Task lTask = Task.Factory.StartNew(() => e(this, EventArgs.Empty));
        lTask.ContinueWith((i) => { Console.WriteLine("Task canceled"); }, TaskContinuationOptions.OnlyOnCanceled);
        lTask.ContinueWith((i) => { Console.WriteLine("Task faulted"); }, TaskContinuationOptions.OnlyOnFaulted);
        lTask.ContinueWith((i) => { Console.WriteLine("Task completion"); }, TaskContinuationOptions.OnlyOnRanToCompletion);
    }

    Console.WriteLine("press return to exit the program");
    Console.ReadLine();
}//    

Example output:
press return to exit the program
Thread 11 mission accomplished!
Thread 10 mission accomplished!
Task completion
Task faulted
Task completion

This tiny tweak worked. You just have to know the compiler bugs. I hope this little notice saves you at least 3 hours of work.
You probably remember that we faced a similar issue in my post “Exiting Tasks (advanced)” https://csharphardcoreprogramming.wordpress.com/2013/12/11/exiting-tasks/ . I would suggest to only use Task.Factory.StartNew() with caution. Maybe it only happens in conjunction with lambda expressions.
The following code is also running very well. The variable “d” is not used directly in Task.Factory.StartNew().

...
 foreach (EventHandler d in lOnChange.GetInvocationList()) {
            Action a = () => d(this, EventArgs.Empty);
            Task lTask = Task.Factory.StartNew(a);
            lTask.ContinueWith((i) => { Console.WriteLine("Task canceled"); }, TaskContinuationOptions.OnlyOnCanceled);
            lTask.ContinueWith((i) => { Console.WriteLine("Task faulted"); }, TaskContinuationOptions.OnlyOnFaulted);
            lTask.ContinueWith((i) => { Console.WriteLine("Task completion"); }, TaskContinuationOptions.OnlyOnRanToCompletion);
        }
...

Events (part 2, advanced)

We are going to construct our custom event accessor now. It deals with additions and removals of subscriptions. Accessors do pretty much look like property definitions. But instead of set and get you have to use add and remove.

public class MyActionEvent4 {
    private object _Lock = new object();            // a new object simply to avoid lock conflicts
    private event EventHandler<MyArgs> _OnChange;
    private event EventHandler<MyArgs> OnChange {
        add {
            lock (_Lock) { _OnChange += value; }
        }
        remove {
            lock (_Lock) { _OnChange -= value; }
        }
    } //

    public void RaiseEvent() {
        lock (_Lock) {
            EventHandler<MyArgs> lHandler = _OnChange;
            if (lHandler == null) return;
            lHandler(this, new MyArgs(0));   
        }        
    }//
} // class

Now we have one big problem here. The RaiseEvent() method has to obtain a lock each time, which causes a serious impact on time sensitive programs. Luckily you do not need to care about changing subscriptions during the invocation. Delegate references are thread-safe, because they are immutable like strings. Let’s simply take the lock out of the RaiseEvent() method, et voilà!

public class MyActionEvent5 {
    private object _Lock = new object();
    private event EventHandler<MyArgs> _OnChange;
    private event EventHandler<MyArgs> OnChange {
        add {
            lock (_Lock) { _OnChange += value; }
        }
        remove {
            lock (_Lock) { _OnChange -= value; }
        }
    } //

    public void RaiseEvent() {
        EventHandler<MyArgs> lHandler = _OnChange;
        if (lHandler == null) return;
        lHandler(this, new MyArgs(0));   
    }//
} // class

It is clear that events are not delegates. They restrict access rights from outside of the event class. To describe events you could most likely say that they are wrappers around delegates.

Whenever an exception is thrown during an event call then all following calls will not be executed. And it is tricky to determine which calls were not executed, because the order of event calls is not guaranteed to be in sequence. In fact it does execute in sequence, but there is no guarantee.

static void EventExceptions1() {
    MyActionEvent3 lEvent = new MyActionEvent3();
    lEvent.OnChange += (sender, e) => Console.WriteLine("Executed subscription 1");
    lEvent.OnChange += (sender, e) => { throw new Exception("OMG!"); };
    lEvent.OnChange += (sender, e) => Console.WriteLine("Executed subscription 3");
    lEvent.RaiseEvent();
} //

So you have to deal with exceptions manually if you want to satisfy/execute as many event subscriptions as possible. You could add a try/catch block for each subscription. Or you could invoke the InvocationList yourself by calling the GetInvocationList() method [System.Delegate] and execute each item manually in a try/catch block. Let’s have a look at the following practical solution:

public class MyActionEvent6 {
    public event EventHandler OnChange = delegate { };

    public void RaiseEvent() {
        List<Exception> lExceptions = new List<Exception>();

        foreach (Delegate lHandler in OnChange.GetInvocationList()) {
            try { lHandler.DynamicInvoke(this, EventArgs.Empty); }
            catch (Exception ex) { lExceptions.Add(ex); }
        }

        if (lExceptions.Count > 0) throw new AggregateException(lExceptions);
    }//
} // class

static void EventExceptions6() {
    MyActionEvent6 lEvent = new MyActionEvent6();
    lEvent.OnChange += (sender, e) => Console.WriteLine("Executed subscription 1");
    lEvent.OnChange += (sender, e) => { throw new Exception("OMG!"); };
    lEvent.OnChange += (sender, e) => Console.WriteLine("Executed subscription 3");

    try { lEvent.RaiseEvent(); }
    catch (AggregateException ex) {
        foreach (Exception lException in ex.InnerExceptions) {
            Console.WriteLine(lException.InnerException.Message);
        }
    }
} //

Events (part 1, advanced)

Events link code dynamically together via subscriptions. There are many ways to achieve this. To better understand events, we will start with the old school approach. It is pretty much Java style. You would not do such in C#.

public interface IListener {
    void OnEvent(int xDummy);
} // interface

public class AnyClass {
    private List<Ilistener> _Listeners = new List<Ilistener>();

    public void AddListener(IListener xListener) {
        lock (_Listeners) { _Listeners.Add(xListener); }
    } //

    public void RemoveListener(IListener xListener) {
        lock (_Listeners) { _Listeners.Remove(xListener); }
    } //

    protected void RaiseEvent() {
        lock (_Listeners) {
            foreach (IListener lListener in _Listeners) lListener.OnEvent(0);
        }
    }//

    public void DoSomeCalc() {
        Console.WriteLine("calculating something");
        Console.WriteLine("done");
        Console.WriteLine("going to tell others");
        RaiseEvent();
    } //
} // class

public class MyLittleProgram : IListener {
    public void StartDemo() {
        AnyClass c = new AnyClass();
        c.AddListener(this);
        c.DoSomeCalc();
        c.RemoveListener(this);
    } //

    public void OnEvent(int xDummy) {
        Console.WriteLine("Hey, cool! I got a notification");
    } //
} // class

static void Main(string[] args) {    
    MyLittleProgram p = new MyLittleProgram();
    p.StartDemo();

    Console.ReadLine();
} //

Above example program uses a List that stores classes. An event is raised by iterating through that list and calling the desired method. This is a lot of code for something really simple.
In the post “Delegates (basics)” https://csharphardcoreprogramming.wordpress.com/2013/12/16/delegates-basics/ we have learned to use delegates. And let’s emphasize it again: We are talking about MulticastDelegates. In the post “Lambda expressions (advanced)” https://csharphardcoreprogramming.wordpress.com/2013/12/17/lambda-expressions-advanced/ we then came across Func and Action. The next step would be to make use of Action.

public class MyActionEvent {
    public Action OnChange { get; set; }

    public void RaiseEvent() {
        Action lAction = OnChange;
        if (lAction == null) return;
        lAction();
    }//
} // class

static void Main(string[] args) {
    MyActionEvent lEventClass = new MyActionEvent();
    lEventClass.OnChange += () => Console.WriteLine("I got a notification.");
    lEventClass.OnChange += () => Console.WriteLine("Me too.");
    lEventClass.RaiseEvent();

    Console.ReadLine();
} //

Notice that we used a local delegate variable (Action lAction = OnChange;) and did not call OnEvent directly. This is important in a multithreaded environment. Allthough it is unlikely, the event could still turn null before it gets raised.

Above code is much more legible now. But it is really bad practice. The event is accessible from outside. The class MyActionEvent loses control over the event. The Action OnChange is accessible and can be raised from outside the class. This is why C# implemented the “event” keyword. Code no longer uses public properties but public event fields, which are properly protected.
An event can only be assigned by using “+=”, whereas an Action can also be entirely overridden with “=”. It makes programming a little bit safer, you don’t run the risk of removing all previous subscriptions by mistake. Also events can only be raised by code within the same class. There is no way events could be raised from outside.

To make your life easier you can assign an empty delegate during the initialization process. By using “= delegate { };” there is no further need to check for the null condition, especially that no outside code can assign null to the event. Only code inside the class can assign null. Therefore the class is in full control of the event.

public class MyActionEvent2 {
    public event Action OnChange = delegate { };

    public void RaiseEvent() {
        OnChange();
        Console.WriteLine("number of event handlers: " + OnChange.GetInvocationList().Length);
    }//
} // class

Personally I do not like the approach with empty delegates. The number of delegates is artificially increased by one. A null check is pretty much using no time at all, so why should someone prefer to call an empty method each time an event is raised?

The next step is to replace the dirty Action by a proper delegate definition, which is EventHandler<>. By default its parameters are the sender object and some event arguments. This is a C# convention and should be followed. Surely you are familiar with such event calls from the Winforms/WPF environment.

public class MyArgs : EventArgs {
    public MyArgs(int xValue) {
        Value = xValue;
    } // constructor

    public int Value { get; set; }
} // class

public class MyActionEvent3 {
    public event EventHandler<myargs> OnChange;

    public void RaiseEvent() {
        EventHandler<myargs> lHandler = OnChange;
        if (lHandler == null) return;
        lHandler(this, new MyArgs(0));                
    }//
} // class

static void Main(string[] args) {
    MyActionEvent3 lEventClass = new MyActionEvent3();
    lEventClass.OnChange += (sender, e) => Console.WriteLine("Event raised, field value is: " + e.Value);            
    lEventClass.RaiseEvent();
    
    Console.ReadLine();
} //

Delegates (basics)

A delegate is like an enhanced classical pointer. It is type-safe and needs a specific method signature. Delegates can invoke methods, thus they can be used for events.
To declare a delegate simply add the word “delegate” in front of a method definition.

// methods
private double Multiply(double a, double b) { return a * b; }
private double Add(double a, double b) { return a + b; }

// a delegate for any of the above methods
private delegate double dCalc(double a, double b);

Assign a method to a delegate and then use the delegate to call the method.

void Delegates1() {
    dCalc calc = Add; // creates a new delegate
    Console.WriteLine("Sum " + calc(6.0, 3.0));

    calc = Multiply; // creates a new delegate
    Console.WriteLine("Product " + calc(6.0, 3.0));

    Console.ReadLine();
} //

example output:
Sum 9
Product 18

You can use operators to add or remove delegates. The next example shows that a delegate can point to multiple methods. This can be done, because delegates inherit from the System.MulticastDelegate class, which in turn inherits from System.Delegate.

private delegate void dPrint();

private void PrintA() { Console.WriteLine("Print A"); }
private void PrintB() { Console.WriteLine("Print B"); }

void Delegates2() {
    Console.WriteLine("--------------------------------");
    dPrint print = PrintA;
    print += PrintB;
    Console.WriteLine("added A and B");
    print();

    Console.WriteLine("--------------------------------");
    print -= PrintA;
    Console.WriteLine("removed A");
    print();

    Console.ReadLine();
} //

example output:
——————————–
added A and B
Print A
Print B
——————————–
removed A
Print B

Delegates do have iterators. You can loop through and/or count them. By now you should easily understand that delegates have nothing to do with pointers (as eg. used in C++). They do not just point somewhere. A delegate is a complex class. And we are dealing with multicast delegates on top of that.

private delegate void dPrint();

private void PrintA() { Console.WriteLine("Print A"); }
private void PrintB() { Console.WriteLine("Print B"); }

void Delegates3() {
    dPrint print = PrintA;
    print += PrintB;
    print += PrintB;
    print();
    Console.WriteLine("number of invokes: " + print.GetInvocationList().GetLength(0));
    foreach (Delegate d in print.GetInvocationList()) {
        Console.WriteLine(d.Method.Name + "()");
    }

    Console.ReadLine();
} //

example output:
Print A
Print B
Print B
number of invokes: 3
PrintA()
PrintB()
PrintB()

There are some words to learn here:

Covariance describes a return value that is more derived than defined in the delegate.
Contravariance describes a method with parameters that are less derived than those defined in the delegate.
Invariant describes a generic type parameter that is neither marked covariant nor contravariant.
Variance Covariance and Contravariance are collectively called variance.

Covariance looks like standard polymorphism, whereas Contravariance seems counterintuitive. What is important to remember is that a covariant type parameter can be used as the return type of a delegate, and contravariant type parameters can be used as parameter types.

Contravariance was introduced in C# 4. Source code that did not compile in C# 3.5 is now compiling and running very well under C# 4. Contravariance is meaningful for write-only methods. So the input does not produce an output of the same hierarchy.

Covariance example:

class A { public int dummyA = 0; }
class B : A { public double dummyB = 0.0; }

delegate A dCovariance();

B Test() { return new B(); }

void Delegates4() {
    dCovariance covariance = Test;  // test returns class B, not class A as defined in the delegate

    foreach (Delegate d in covariance.GetInvocationList()) {
        Console.WriteLine(d.Method.Name + "()");
    }

    Console.ReadLine();
} //

example output:
Test()

Contravariance example:

class A { public int dummyA = 0; }
class B : A { public double dummyB = 0.0; }

void Test2(A xParameter) { return; }

delegate void dContravariance(B xClassB);

void Delegates5() {
    // The parameter in Test2() is of type class "A", but the
    // delegate was defined with a class "B" parameter.
    dContravariance contravariance = Test2;

    foreach (Delegate d in contravariance.GetInvocationList()) {
        Console.WriteLine(d.Method.Name + "()");
    }

    contravariance(new B());  // <= important !!!!

    Console.ReadLine();
} //

example output:
Test2()

When calling contravariance(…) we have to pass any class B instance as parameter. And the method Test2() has obviously no problems with this. Class B is more derived. It does make sense now that Test2() can be less derived, doesn’t it?

Contravariance will be discussed in more detail when looking at generic interfaces with the “in T” annotation. One commonly used contravariant interface is IComparer. Lean back for the moment and just have a quick look at a custom interface using the “in T” annotation. That should be enough for today.

interface IPerson<in T> {
    string Name { get; set; }
    int Age { get; set; }
}