Export (0) Print
Expand All
2 out of 5 rated this helpful - Rate this topic

Publishing and Subscribing to Events

Retired Content

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies.
This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

The Composite UI Application Block includes an event broker system that enables you to publish events that allow communication between components in WorkItems. SmartParts (or other classes) within that WorkItem can then raise the event or subscribe to the published event. This design ensures that SmartParts are loosely coupled and do not need to know about other SmartParts within the application. The event mechanism can also be used for classes that do not have a visual representation, such as controllers, presenters, WorkItems or service agents.

There are two ways of registering publications or subscriptions for an event:

  • Using Attributes. You can use specific attributes as described in the example below to declare .NET events as event publications that will propagate via the event broker system. You then declare methods decorated with the EventSubscription attribute to receive these events in your classes. This is the simplest way of working with events, and provides the same flexibility as the normal programmatic approach—but requires less code. For the attributes to be processed, you must create or add the class instance to the WorkItem.
  • Programatically. You write code to get an instance of the EventTopic you want to publish or subscribe to via the EventTopics collection of a WorkItem instance, and then call its methods to register and unregister publishers and subscribers. This gives flexibility in the placing of event registration and unregistration for publications and subscriptions, but is not required for most common cases. You can also fire topics programmatically in this way, without registering a publisher.

Publishing Events

You can publish events using the EventPublication attribute on an event declaration. This attribute uses two parameters: the event name and the event scope.

The event name is a string that identifies the event, for example, event://UpdatesAvailable. The URI syntax convention is recommended to allow for organized and hierarchical naming. For example, event://UpdatesAvailable/New and event://UpdatesAvailable/Deleted.

Use the PublicationScope enumeration to define the event scope as global, available only to this WorkItem and its descendents, or local to this WorkItem.

To publish an event that is available in all WorkItem instances

  1. Create the event definition as shown in the following code.
    public event SomeEventHandler UpdatesAvailable;
    
    
  2. Add the EventPublication attribute to the definition using the PublicationScope.Global parameter as shown in the following code.
    [EventPublication("event://UpdatesAvailable", PublicationScope.Global)]
    public event SomeEventHandler UpdatesAvailable;
    
    

To publish a event available only to the local and descendant WorkItems

  1. Create the event definition as shown in the following code.
    public event SomeEventHandler UpdatesAvailable;
    
    
  2. Add the EventPublication attribute to the definition using the PublicationScope.Descendants parameter as shown in the following code.
    [EventPublication("event://UpdatesAvailable",
                       PublicationScope.Descendants)]
    public event SomeEventHandler UpdatesAvailable;
    
    

To publish an event that is available only to the local WorkItem

  1. Create the event definition as shown in the following code.
    public event SomeEventHandler UpdatesAvailable;
    
    
  2. Add the EventPublication attribute to the definition using the PublicationScope.WorkItem parameter as shown in the following code.
    [EventPublication("event://UpdatesAvailable", PublicationScope.WorkItem)]
    public event SomeEventHandler UpdatesAvailable;
    
    

Subscribing to Events

Any class within scope (this WorkItem, descendant WorkItems or global, depending on the publication type) can subscribe to an event declared within that scope.

To subscribe to an event

  1. Create the method that should execute when the event is raised.
  2. Add the EventSubscription attribute to the method declaration as shown in the following code.
    [EventSubscription("event://UpdatesAvailable")]
    public void NewUpdates(object sender, SomeEventArgs numUpdates)
    {
      MessageBox.Show(numUpdates.ToString(), "Updates available");
    }
    
    

You can use the arguments within the event to pass information between the publisher and subscriber.

Ff649386.note(en-us,PandP.10).gifNote:
Because the event broker system uses .NET events and delegates in the underlying code, it is possible to change the EventArgs in a subscriber and for other subscribers that are called later to access the modified EventArgs instead of the one sent by the publisher. It is also possible to use the EventArgs to pass data back to a publisher from a subscriber. However, this behavior should be avoided as you cannot guarantee the order in which event subscribers are called.

Running Events on the User Interface Thread

Event subscriptions in Windows Forms applications must execute on the same thread as the user interface if the code in the event handler will interact with controls in the user interface. Subscribers to an event in the Composite UI Application Block can run the subscription on the same thread as the user interface by adding the Thread=ThreadOption.UserInterface parameter to the [EventSubscription] attribute.

To run an event on a the user interface thread

  1. Add a second parameter to the EventSubscription attribute as shown in the following code.
    [EventSubscription("event://UpdatesAvailable", 
                       Thread=ThreadOption.UserInterface)]
    
    

Running Events on a Background Thread

Subscribers to an event can declare the intent to run the subscription in a background thread. When the class containing the declaration is loaded, an additional Thread=ThreadOption.Background parameter notifies the EventTopic that this subscription should run in a background thread.

To run an event on a background thread

  1. Add a second parameter to the EventSubscription attribute as shown in the following code.
    [EventSubscription("event://UpdatesAvailable", 
                       Thread=ThreadOption.Background)]
    
    

Ff649386.note(en-us,PandP.10).gifNote:
Because the subscriber determines the thread on which it executes, the publisher should not dispose the EventArgs or any referenced objects after firing an event. Doing so can result in the arguments being disposed before a subscriber on a background thread is called.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.