Event Aggregation QuickStart

The Event Aggregation QuickStart demonstrates how to build a Windows Presentation Foundation 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. This window allows the user to add funds to customers and to see the activity log for each customer.

Figure 1 illustrates the QuickStart main window.

Figure 1
Event Aggregation QuickStart user interface

Building and Running the QuickStart

The QuickStart ships as source code, which means you must compile it before running it. This QuickStart does not have any prerequisites.

To build and run the Event Aggregation QuickStart

1. Run the file Open QS-EventAggregation Quickstart Solution.bat to open the solution in Visual Studio.
2. Right-click the EventAggregation project, and then click Set as StartUp Project.
3. On the Build menu, click Rebuild Solution.
4. Press F5 to run the QuickStart.

Walkthrough

Perform the following steps in the Event Aggregation QuickStart to explore the scenario.

To explore the scenario

1. Run the file Open QS-EventAggregation Quickstart Solution.bat to open the solution in Visual Studio.

2. On the Build menu, click Rebuild Solution.

3. Press F5 to run the application. 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 illustrated in Figure 2.

   

   Figure 2
   QuickStart main window

4. 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 Figure 3.

   

   Figure 3
   Customer and fund selected

5. Click the Add button to add the chosen fund to the selected customer, as shown in Figure 4. Notice that the fund is added to the activity log view corresponding to the selected customer.

   

   Figure 4
   When the Add button is clicked, the selected fund is added to the corresponding activity log view

6. Try adding different combinations of customer and fund pairs, as shown in Figure 5. Notice how the activity log views are updated to reflect the funds added.

   

   Figure 5
   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. The key artifacts of the QuickStart are illustrated in Figure 6 and described in this section.

Figure 6
Event Aggregation QuickStart Conceptual View

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 CompositeWpfEvent<TPayload> class specifying FundOrder as the payload type. You can find this code at EventAggregation.Infrastructure\FundAddedEvent.cs.

public class FundAddedEvent : CompositeWpfEvent<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\FundOrder.cs.

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, supplying the FundOrder instance recently created 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\ModuleB.cs).

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, fundOrder => fundOrder.CustomerId == _customerId);

        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, fundOrder => fundOrder.CustomerId == _customerId);

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

• The FundAddedEventHandler action**.** This event handler will be executed when the Add button is clicked and the filter condition is satisfied.
• The ThreadOption.UIThread option**.** This option specifies the event handler has to run in 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 will be invoked only when the fund is added to the view's corresponding customer.

Acceptance Tests

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

The acceptance tests were developed using the testing framework White. To run these tests, you need to have White installed. For more information about White, including download information, see White on CodePlex.

To run the Event Aggregation QuickStart acceptance tests

1. Place the assemblies required by White in the folder Source\Lib\White. The files are the following:
   • Bricks.dll
   • Bricks.RuntimeFramework.dll
   • Castle.Core.dll
   • Castle.DynamicProxy2.dll
   • Core.dll
   • log4net.config
   • log4net.dll
   • nunit.framework.dll
   • White.NUnit.dll
   • Xstream.Core.dll
2. In Visual Studio, open the solution file QuickStarts\EventAggregation\EventAggregation_AcceptanceTests.sln.
3. Press F5.

Outcome

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