EventBroker QuickStart

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. To create client business applications using current Microsoft technologies, see patterns & practices' Prism.

The EventBroker QuickStart demonstrates the publish-and-subscribe event mechanism in the Composite UI Application Block, which includes threading options and event scoping.

To run the EventBroker QuickStart

1. Open the EventBroker QuickStart solution in Visual Studio 2010.
2. On the Build menu, click Rebuild Solution.
3. Click the Start Debugging button on the standard toolbar, or click Start Debugging on the Debug menu.

Overview

This example contains two forms that allow you to enter and then process fictitious customers (see Figure 1). The LaunchPadForm allows you to enter customers and add them to a global list. The CustomerListView form allows you to add customers either to the global list, or to a list that is local to this form. You can also use to the controls in the CustomerListView form to move (process) customers local to this form instance into the global list.

Figure 1

The EventBroker QuickStart in action

As you interact with the CustomerListView form by adding global customers or moving local customers to the global list, it raises an event that causes the LaunchPadForm to update its list of global customers. It does this by publishing and subscribing to events. You will see details of the events appear in the text box when you enable tracing using the check box above it. Look at the code in TraceTextBox.cs to see how it works.

The ProcessLocal button in the CustomerListView form runs its code on a background thread, and then displays another form containing a progress bar that shows the status of the process that is taking place (see Figure 2). The CustomerListView form and ProgressView also communicate by using the publish-and-subscribe event model, and the events appear in the trace text box on the LaunchPadForm.

Figure 2

Processing local customers in the CustomerListView form

What You Need to Know

To understand this example, you should be familiar with the following:

• The publish-and-subscribe model for events
• The basic principles of the design of the Composite UI Application Block framework
• The terms listed in the Glossary of Terms section

Design of the EventBroker QuickStart

The following steps describe the startup sequence of the example:

1. The Main method in BrokerApplication.cs creates instances of BrokerApplication shell and calls the Run method. The BrokerApplication class declaration specifies that the base class FormShellApplication should run the default WorkItem class and show the LaunchPadForm form.
2. Code in BrokerApplication.cs overrides the BeforeShellCreated method to load the State for the application (an empty list of customers).
3. The LaunchPadForm creates a new LaunchPadController instance and obtains a reference to the list of customers in the State.
4. The OnLoad event handler in the LaunchPadForm subscribes to the StateChanged event, and the LaunchPadForm provides an event handler for this event that refreshes the list of global customers shown on this form.

You can interact with the application in several ways:

• Enter a customer ID in the LaunchPadForm and click Add Customer to enter a customer in the global customer list box.
• Click Show List in the LaunchPadForm to open the CustomerListView form, which displays both local and global customers.
• Enter a customer ID in the CustomerListView and add it to the global customer list or the local customer list.
• Click Process Local in the CustomerListView to move customers from the local customer list to the global customer list. During this process, a separate form shows the progress of this processing.
• Click Cancel to stop the asynchronous processing of local customers.

The following steps describe what happens when you enter a CustomerID in the LaunchPadForm and click the Add Customer button:

1. Clicking the Add Customer button executes the btnFireCustomerChange_Click event handler in the LaunchPadForm.cs file. Providing that a value exists in the text box, the event handler calls the AddCustomer method of the LaunchPadController, passing in the value from the text box.
2. The AddCustomer method of the LaunchPadController adds the customer to the stored customer list and raises the StateChanged event.
3. The StateChanged event handler in the LaunchPadForm.cs file clears and repopulates the list box in the LaunchPadForm that displays the list of customers.

The following steps describe what happens when you click the Show List button in the LaunchPadForm:

1. Clicking the Show List button executes the btnNewCustomerList_Click event handler in the LaunchPadForm.cs file. This event handler calls the ShowCustomerList method of the LaunchPadController.
2. The ShowCustomerList method creates a new child WorkItem, and creates a new empty local list of customers as the State within this WorkItem. Then it creates a new instance of the CustomerListView form and calls its Show method.
3. The constructor of the CustomerListView form uses the dependency injection feature of the Composite UI Application Block to inject a new CustomerListController instance though the [CreateNew] attribute, and gets a reference to the State in the child WorkItem by using the [State] attribute.
4. The OnLoad event handler in the CustomerListView form subscribes to the StateChanged events of both the parent WorkItem and controller's State class, and then populates its list of global customers (customers in all the WorkItems).

The following steps describe what happens when you enter a CustomerID in the CustomerListView form and click the Add Local button:

1. Clicking the AddLocal button executes the btnAddLocalCustomer_Click event handler in the CustomerListView form. Providing that you entered a value in the text box, this routine calls the AddLocalCustomer method of the CustomerListController, passing in the customer ID, and then clears the text from the text box and sets the input focus back to it.
2. The AddLocalCustomer method of the CustomerListController adds the customer ID to the local customer list, and then raises the StateChanged event of the State class.
3. The CustomerListView form, which subscribes to the StateChanged event of the State class, clears and repopulates its local list of customers.

The following steps describe what happens when you enter a CustomerID in the CustomerListView form and click the Add Global button:

1. Clicking the AddGlobal button executes the btnAddGlobalCustomer_Click event handler in the CustomerListView form. Providing that you entered a value in the text box, this routine calls the AddGlobalCustomer method of the CustomerListController, passing in the customer ID, and then clears the text from the text box and sets the input focus back to it.
2. The AddGlobalCustomer method of the CustomerListController raises the GlobalCustomerAdded event (which is decorated with the [EventPublication] attribute with the URI identifier "topic://EventBrokerQuickStart/CustomerAdded"), passing the customer ID in the event arguments.
3. The LaunchPadController subscribes to the event ‘topic://EventBrokerQuickStart/CustomerAdded’ EventTopic using the [EventSubscription] attribute. This invokes its AddCustomer method, which adds the customer to the stored customer list and raises the StateChanged event.
4. The StateChanged event handler in the LaunchPadForm.cs file clears and repopulates the list box in the LaunchPadForm that displays the list of customers.
5. The CustomerListView, which also subscribes to the StateChanged events, clears and repopulates its global list of customers.

The following steps describe what happens when you click the Process Local button in the CustomerListView form:

1. Clicking the ProcessLocal button executes the btnProcessLocal_Click event handler in the CustomerListView form. This routine calls the ProcessLocalCustomers method of the CustomerListController.
2. The ProcessLocalCustomers method creates a list of customers for processing, fires the StartProcess event as a global event, and clears the local customer list. Then it raises the StateChanged event so that the CustomerListView updates its list of customers. Finally, it creates and shows the ProgressView form.
3. The CustomerListController subscribes to the StartProcess event through the StartProcessHandler routine. This is decorated with the [EventSubscription] attribute, which includes Thread = Background so that the event handler runs on a separate thread. The CustomerListView form also subscribes to this event to enable the Cancel button.
4. The StartProcessHandler routine iterates through the list of customers in the event argument calling a separate routine named OnProgressChanged, which raises the ProgressChanged event, for each one. A Thread.Sleep statement introduces an artificial delay into the process so that you can cancel it if you wish.
5. The ProgressView form subscribes to the ProgressChanged event, and uses this to update a ProgressBar control to indicate processing taking place.
6. The CustomerListController also subscribes to the ProgressChanged event it raised, and calls the AddGlobalCustomer routine to add each customer to the global list. This raises the StateChanged event, which causes the LaunchPadForm and CustomerListView to update their lists of customers.
7. After processing of all the customers completes, the StartProcessHandler routine in the CustomerListController calls a separate routine named OnProgressComplete, which raises the ProcessCompleted event.
8. The ProgressView form subscribes to this event, and calls the Close method to close itself. The CustomerListView form also subscribes to this event to disable the Cancel button.
9. The CustomerListController also subscribes to the ProcessCompleted event it raised, and sets the value of two flag variable, cancelled and processing, to false.

The following steps describe what happens when you click the Cancel button in the CustomerListView form:

1. Clicking the Cancel button executes the btnCancelProcess_Click event handler in the CustomerListView form. This routine calls the CancelProcess method of the CustomerListController.
2. The CancelProcess method checks if the processing flag variable is set to true and, if so, sets the cancelled variable to true. This causes the StartProcessHandler routine to stop processing customers.

Reviewing the EventBroker QuickStart

The following procedure describes how to review the execution of the EventBroker QuickStart.

 To review the EventBroker QuickStart

1. Open the EventBroker QuickStart solution from the extracted source code.
2. On the Build menu, click Rebuild Solution.
3. Insert breakpoints on the following lines of code:

1. On the Debug menu, click Start Debugging.
2. When the debugger enters break mode, step through the code until you reach the Run method of the file CabApplication.cs. As you step through this method, pay particular attention to the initialization sequence of the application, and the services added during initialization.
3. When the main form is loaded, enter a customer ID and click Add Customer. Notice that the customer number is displayed in the list of global customers.
4. Click Show List. Notice that a child WorkItem is created with its own set of services and its own State. This WorkItem displays the CustomerListView. You will see that when the view loads, an EventTopic is created for each EventPublication and EventSubscription in CustomerListController.cs.
5. Enter a customer ID, and then click Add Global. Notice that the call to GlobalCustomerAdded raises the event://EventBrokerQuickStart/CustomerAdded EventTopic, which the OnCustomerAdded method of the LaunchPadController can subscribe to because the EventTopic has global scope (the default). This adds the customer to the state for the WorkItem.
6. Enter a customer ID, and then click Add Local. Notice that this process adds the customer to the state for the child WorkItem.
7. Enter another customer ID, and then click Add Local.
8. Click Process Local. Notice that the call to StartProcess raises the event://EventBrokerQuickStart/StartProcess EventTopic that is subscribed to by the StartProcessHandler method of the CustomerListController. This subscription is declared using the Thread = ThreadOption.Background parameter, meaning that the method is invoked on a background thread.
9. Enter eight local customer IDs, and then click AddLocal. Do not step through the code; instead, immediately click Cancel. Step through the cancel process and notice how it cancels the routine on background by setting the cancelled property to true. Depending how quickly you click Cancel, you should see that not all the local entries move to the root WorkItem global customer list.