Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

Action Catalog

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.

In smart client applications, you must conditionally execute code (an "action") based on aspects of a program that can change at run time. The logic for the evaluation is not related to the logic of the action that executes if the result of the evaluation is true. You require the ability to add, replace, or remove conditions for the evaluation at run time. You also require the ability to replace the logic that evaluates conditions at run time. Finally, you want certain conditions to be evaluated for all actions and other conditions to apply to only specific actions.

An example is an application that shows a view in a workspace only if the current user is associated with a specific role. The action is the code that shows the view. The condition is the code that determines the user's role and evaluates if the action will execute based on the current user's role. The logic for the condition (determining the role and evaluating if it applies to the action) is not related to the logic for the action (showing the view). A change to the logic that evaluates the user's role has no side-effects on the logic that shows the view.

The solution is to introduce an object (an "action catalog") that evaluates one or more conditions ("condition objects") and executes business logic (an "action") on behalf of other objects. A condition object is responsible for performing the evaluation for a specified action. For example, a condition object can evaluate whether the action to show a view can execute based on the current user's role.

Condition objects can be specific to an action or they can apply to all actions. The action catalog executes an action only if all conditions objects associated with that action return true for their evaluation.

The action catalog object is an instance of the ActionCatalog class. This class contains the following collections:

  • A list of condition objects that apply to all actions
  • A dictionary that maps action names to a list of condition objects specific to that action
  • A dictionary that maps action names to delegates (the action code that is executed if the evaluation returns true)

The class exposes methods to register condition objects for specific actions or all actions. Figure 1 illustrates the fields and methods available in the ActionCatalog class contained in the Bank Branch Client reference implementation.

Ff649051.03-SCSF-PatternsActionCatalog1(en-us,PandP.10).png

Figure 1
Fields and methods of the ActionCatalog class

You can use the CanExecute method to obtain the result of an evaluation for an action. One of the parameters of the CanExecute method is a WorkItem object. This means the condition objects can use the current state of the application in the evaluation. The Execute method calls the CanExecute method, and if the result is true, executes the action.

Developers register an action catalog as a service. This means an application can have more than one action catalog, but each WorkItem can have at most one action catalog. Figure 2 illustrates an application that contains two action catalog instances.

Ff649051.03-SCSF-PatternsActionCatalog2(en-us,PandP.10).png

Figure 2
ActionCatalog services

An action catalog is a service associated with a WorkItem. This means that you must be aware of the WorkItem hierarchy when you use the action catalog.

All actions (the methods identified by an action name) have the same signature, with two arguments. The arguments are the caller object and the target object. The target is an arbitrary object.

The Bank Branch Client reference implementation uses this pattern to provide a user interface that is specific to the current user’s role. For example, only users in the Officer or Manager roles can see the option to purchase a certificate of deposit. You can see this implementation in the following classes and methods.

The Module class in the Infrastructure.Module assembly overrides the AddService method as illustrated in the following code.

public override void AddServices()
{
  base.AddServices();
  _rootWorkItem.Services.AddNew<GenericPrincipalImpersonationService,
     IImpersonationService>();
  IActionCatalog catalog = _rootWorkItem.Services.AddNew<ActionCatalog,
     IActionCatalog>();
  catalog.RegisterGeneralCondition(new
    EnterpriseLibraryAuthorizationActionCondition());
}

This method creates the ActionCatalog service in the root WorkItem and registers a general action condition called EnterpriseLibraryAuthorizationActionCondition. The EnterpriseLibraryAuthorizationActionCondition is a condition object that evaluates actions based on role information. Because it is registered as a general action condition, the condition object is used in the evaluation for all actions.

The BasicAccounts.Module project contains the ModuleActions.cs class that implements two actions: ShowPurchaseCDCommandAction and ShowPurchaseCDViewAction. The ShowPurchaseCDCommandAction method adds the option to purchase a certificate of deposit to the user interface.

[Action(ActionNames.ShowPurchaseCDCommand)]
public void ShowPurchaseCDCommandAction(object caller, object target)
{
  // This is the code to add the “Purchase CD” option to the user interface.
}

The ModuleController class in the same project contains the OnCustomerWorkItemCreated method illustrated in the following code; the application executes this method when it creates a new customer WorkItem.

[EventSubscription(EventTopicNames.CustomerWorkItemCreated,ThreadOption.UserInterface)]
public void OnCustomerWorkItemCreated(object sender, EventArgs<WorkItem> args)
{
   WorkItem customerWorkItem = args.Data
   customerWorkItem.Items.AddNew<ModuleActions>();
   IActionCatalogService catalog =
customerWorkItem.Services.Get<IActionCatalogService>(); 
     catalog.Execute(ActionNames.ShowPurchaseCDCommand, 
       customerWorkItem, this, null);
}

The OnCustomerWorkItemCreated uses the action catalog to conditionally show the option to purchase a certificate of deposit in the user interface. To do this, the OnCustomerWorkItemCreated method performs the following:

  • It obtains the reference to the new customer WorkItem from the event arguments.
  • It creates an instance of the ModuleActions class in the new WorkItem. When it creates the ModuleActions object, ObjectBuilder adds the actions of that class to the action catalog. (In reference implementation, there is one action catalog in the root WorkItem, and an action catalog in each customer WorkItem.)
  • It obtains the instance of the action catalog form the customer WorkItem.
  • It calls the Execute method of that catalog with the ShowPurchaseCDCommands action as the parameter.

Ff649051.note(en-us,PandP.10).gifNote:
The EnterpriseLibraryAuthorizationActionCondition condition object is registered as a general action condition. This means it is used in the evaulation of all actions, including the ShowPurchaseCDCommand action.

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