Publishing Events

You can publish events by 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;
   

   'Usage
   Public Event UpdatesAvailable As SomeEventHandler
   

2. Add the EventPublication attribute to the definition by using the PublicationScope.Global parameter, as shown in the following code.

   [EventPublication("event://UpdatesAvailable", PublicationScope.Global)]
   public event SomeEventHandler UpdatesAvailable;
   

   'Usage
   <EventPublication("event://UpdatesAvailable", PublicationScope.Global)> _
   Public Event UpdatesAvailable As SomeEventHandler
   

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;
   

   'Usage
   Public Event UpdatesAvailable As SomeEventHandler
   

2. Add the EventPublication attribute to the definition by using the PublicationScope.Descendants parameter, as shown in the following code.

   [EventPublication("event://UpdatesAvailable",
                      PublicationScope.Descendants)]
   public event SomeEventHandler UpdatesAvailable;
   

   'Usage
   <EventPublication("event://UpdatesAvailable", _
                      PublicationScope.Descendants)> _
   Public Event UpdatesAvailable As SomeEventHandler
   

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;
   

   'Usage
   Public Event UpdatesAvailable As SomeEventHandler
   

2. Add the EventPublication attribute to the definition by using the PublicationScope.WorkItem parameter, as shown in the following code.

   [EventPublication("event://UpdatesAvailable", PublicationScope.WorkItem)]
   public event SomeEventHandler UpdatesAvailable;
   

   'Usage
   <EventPublication("event://UpdatesAvailable", PublicationScope.WorkItem)> _
   Public Event UpdatesAvailable As SomeEventHandler
   

Subscribing to Events

Any class within the 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");
   }
   

   'Usage
   <EventSubscription("event://UpdatesAvailable")> _
   Public Sub NewUpdates(sender As Object, numUpdates As SomeEventArgs)
     MessageBox.Show(numUpdates.ToString(), "Updates available")
   End Sub
   

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

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

• Add a second parameter to the EventSubscription attribute, as shown in the following code.

  [EventSubscription("event://UpdatesAvailable", 
                     Thread=ThreadOption.UserInterface)]
  

  'Usage
  <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

• Add a second parameter to the EventSubscription attribute, as shown in the following code.

  [EventSubscription("event://UpdatesAvailable", 
                     Thread=ThreadOption.Background)]
  

  'Usage
  <EventSubscription("event://UpdatesAvailable", _ 
                     Thread:=ThreadOption.Background)>