On this page:	Download:
Business Scenario | Building and Running the QuickStart | Walkthrough | Implementation Details | The FundAddedEvent Event | Event Publishing | Event Subscription | Unit and Acceptance Tests | Unit Tests for WPF Version - Outcome | Unit Tests for Silverlight Version - Outcome | Acceptance Tests - Outcome | More Information

The Event Aggregation QuickStart demonstrates how to build a composite application that uses the Event Aggregator service. This service enables you to establish loosely coupled communications between components in your application.

Business Scenario

The main window of the Event Aggregation QuickStart represents a subset of a fictitious financial system. In this window, users can add funds to customers and see the activity log for each customer. The following illustration shows the QuickStart main window.

Building and Running the QuickStart

This QuickStart requires Visual Studio 2010 to run. The Silverlight version of this QuickStart also requires Silverlight 4 and the Silverlight 4 Tools for Visual Studio 2010.

To build and run the Event Aggregation QuickStart

1. In Visual Studio, open the solution file Quickstarts\EventAggregation\EventAggregation.sln.
2. Make sure the desired version of the QuickStart is set as the startup project. If it is not, right-click the desired project in Solution Explorer, and then click Set as Startup Project:
   • To build and run the Windows Presentation Foundation (WPF) version of the QuickStart, the startup project should be the EventAggregation.Desktop project in the Desktop solution folder.
   • To build and run the Silverlight version of the QuickStart, the startup project should be the EventAggregation.Silverlight project in the Silverlight solution folder.
3. On the Build menu, click Rebuild Solution.
4. Press F5 to run the QuickStart.

Walkthrough

To explore the scenario, perform the steps to build and run the QuickStart:

1. The main window is composed of two views: one view for adding funds to a customer and one view that shows the activity log for each customer account. The main window is shown in the following illustration.
   QuickStart main window – WPF version

   

2. In the Customer drop-down list box, click a customer, and then click a fund in the Fund drop-down list box, as shown in the following illustration.
   Customer and fund selected

   

3. Click the Add button to add the chosen fund to the selected customer, as shown in the following illustration. Notice that the fund is added to the activity log view corresponding to the selected customer.
   Selected fund listed in the corresponding activity log view

   

4. Try adding different combinations of customer and fund pairs, as shown in the following illustration. Notice how the activity log views are updated to reflect the added funds.
   The activity log view for each customer reflects the funds added

   

Implementation Details

The QuickStart highlights the key elements that interact when using the Event Aggregator service. This section describes the key artifacts of the QuickStart, which are shown in the following illustration.

The FundAddedEvent Event

The FundAddedEvent event is raised when the user adds a fund for a customer. This event is used by the modules ModuleA and ModuleB to communicate in a loosely coupled way. The following code shows the event class signature; the class extends the CompositePresentationEvent<TPayload> class, specifying FundOrder as the payload type. This code is located at EventAggregation.Infrastructure.{Technology}\FundAddedEvent.cs, where {Technology} can be Desktop or Silverlight.

public class FundAddedEvent : CompositePresentationEvent<FundOrder>
{
}

The following code is the class definition for the FundOrder class; this class represents a fund order and specifies the ticker symbol and the customer's identifier. This code is located at EventAggregation.Infrastructure.{Technology}\FundOrder.cs, where {Technology} can be Desktop or Silverlight.

public class FundOrder
{
    public string CustomerId { get; set; }
    public string TickerSymbol { get; set; }
}

Event Publishing

When the user adds a fund for a customer, the event FundAddedEvent is published by the AddFundPresenter class (located at ModuleA\AddFundPresenter.cs). The following code shows how the FundAddedEvent is published.

void AddFund(object sender, EventArgs e)
{
    FundOrder fundOrder = new FundOrder();
    fundOrder.CustomerId = View.Customer;
    fundOrder.TickerSymbol = View.Fund;

    if (!string.IsNullOrEmpty(fundOrder.CustomerID) && !string.IsNullOrEmpty(fundOrder.TickerSymbol))
        eventAggregator.Get<FundAddedEvent>().Publish(fundOrder);
}

In the preceding code, first a FundOrder instance is created and set up. Then, the FundAddedEvent is retrieved from the Event Aggregator service and the Publish method is invoked on it; this supplies the recently created FundOrder instance as the FundAddedEvent event's parameter.

Event Subscription

The ModuleB module contains a view named ActivityView. An instance of this view shows the activity log for a single customer. The ModuleB initializer class creates two instances of this view, one for Customer1 and one for Customer2, as shown in the following code (this code is located at ModuleB.{Technology}\ModuleB.cs), where {Technology} can be Desktop or Silverlight.

public void Initialize()
{
    ActivityView activityView1 = Container.Resolve<ActivityView>();
    ActivityView activityView2 = Container.Resolve<ActivityView>();

    activityView1.CustomerId = "Customer1";
    activityView2.CustomerId = "Customer2";

    IRegion rightRegion = RegionManager.Regions["RightRegion"];
    rightRegion.Add(activityView1);
    rightRegion.Add(activityView2);
}

When an instance of the ActivityView view is created, its presenter subscribes an event handler to the FundAddedEvent event using a filter expression. This filter expression defines a condition that the event's argument must meet for the event handler to be invoked. In this case, the condition is satisfied if the fund order corresponds to the customer associated to the view. The event handler contains code to display the new fund added to the customer in the user interface.

The following code shows the CustomerId property of the ActivityPresenter class. In the property setter, an event handler for the FundAddedEvent event is subscribed using the Event Aggregator service.

public string CustomerId
{
    get { return _customerId; }
    set
    {
        _customerId = value;

        FundAddedEvent fundAddedEvent = eventAggregator.Get<FundAddedEvent>();

        if (subscriptionToken != null)
        {
            fundAddedEvent.Unsubscribe(subscriptionToken);
        }

        subscriptionToken = fundAddedEvent.Subscribe(FundAddedEventHandler, ThreadOption.UIThread, false, FundOrderFilter);

        View.Title = string.Format(CultureInfo.CurrentCulture, Resources.ActivityTitle, CustomerId);
    }
}

The following line, extracted from the preceding code, shows how the event handler is subscribed to the FundAddedEvent event.

subscriptionToken = fundAddedEvent.Subscribe(FundAddedEventHandler, ThreadOption.UIThread, false, FundOrderFilter);

In the preceding line, the following parameters are passed to configure the subscription:

• The FundAddedEventHandler action. This event handler is executed when the Add button is clicked and the filter condition is satisfied.
• The ThreadOption.UIThread option. This option specifies that the event handler will run on the user interface thread.
• The KeepSubscriberReferenceAlive flag. This flag is false and indicates that the lifetime of the subscriber's reference is not managed by the event. This is set to false because the lifetime of the subscriber, the presenter class, is managed by its view, which contains a reference to it.
• The filter predicate. This filter is a condition that specifies that the event handler is invoked only when the fund is added to the view's corresponding customer.

Note:
Silverlight does not support weak references to lambda expressions or anonymous delegates. Therefore, the filter parameter must be a separate method if you are targeting Silverlight.

The Event Aggregation QuickStarts multi-targets both WPF and Silverlight, so the filter parameter FundOrderFilter is not a delegate; instead, it is a separate method, as shown in the following code.

public bool FundOrderFilter(FundOrder fundOrder)
{
    return fundOrder.CustomerId == _customerId;
}
...

FundAddedEvent fundAddedEvent = eventAggregator.GetEvent<FundAddedEvent>();

subscriptionToken = fundAddedEvent.Subscribe(FundAddedEventHandler, ThreadOption.UIThread, false, FundOrderFilter);

Unit and Acceptance Tests

The Event Aggregator QuickStart includes unit tests within the solution. Unit tests verify if individual units of source code work as expected.

Unit Tests for WPF Version

To run the Event Aggregator QuickStart unit tests for the WPF version

• On the Test menu of Visual Studio, point to Run, and then click All Tests in Solution.

Outcome

You should see the Test Results pane in Visual Studio indicating that all the unit tests passed.

Unit Tests for Silverlight Version

To run the Event Aggregator QuickStart unit tests for the Silverlight version

1. In Solution Explorer, expand the UnitTests solution folder in the Silverlight solution folder.
2. Right-click either the ModuleA.Tests.Silverlight or ModuleB.Tests.Silverlight unit test project, and then click Set as StartUp Project.
3. Press F5
4. Optionally, repeat steps 2 and 3, choosing the other unit test project.

Outcome

You should see a web browser window with the test results indicating that all the unit tests passed.

Acceptance Tests

The Event Aggregator QuickStart includes a separate solution that includes acceptance tests. The acceptance tests describe how the application should perform when you follow a series of steps; you can use the acceptance tests to explore the functional behavior of the application in a variety of scenarios.

To run the Event Aggregator QuickStart acceptance tests

1. In Visual Studio, open the solution file QuickStarts\EventAggregation\EventAggregation.Tests.AcceptanceTest\EventAggregation.Tests.AcceptanceTest.sln.
2. Right-click EventAggregation.Tests.AcceptanceTest, and then click Set as StartUp Project.
3. Press F5.

Outcome

You should see the QuickStart window and the tests automatically interact with the application. At the end of the test run, you should see that all tests have passed.

More Information

For more information about event aggregation, see Chapter 9, "Communicating Between Loosely Coupled Components."

To learn about other QuickStarts included with Prism, see the following topics:

• Modularity QuickStarts for WPF
• Modularity QuickStarts for Silverlight
• Basic MVVM QuickStart
• MVVM QuickStart
• Commanding QuickStart
• UI Composition QuickStart
• State-Based Navigation QuickStart
• View-Switching Navigation QuickStart
• Multi-Targeting QuickStart

Last built: August 28, 2012