How to: Use the Action Catalog

You can use the action catalog to control whether a business action is executed. The Bank Branch reference implementation includes the action catalog service. It uses this service with the Enterprise Library Security Application Block to implement a role-based user interface.

Prerequisites

The steps in this topic assume that you have an existing smart client application. You can use the Smart Client Software Factory 2010 guidance package to quickly create the starting point for this topic.

To prepare a solution for this topic

1. Install the Smart Client Software Factory 2010.
2. Use the Visual Studio template Smart Client Application to create the initial smart client solution. For information about how to create a solution with this template, see How to: Create Smart Client Solutions.
3. Use the Add Business Module template to add a module to your project. Name the module MyModule. For information about how to create a business module with this template, see How to: Create a Business Module.
4. Use the Add View (with presenter) recipe to create a view in the MyModule project. Enter MyView for the name of the view. For information about how to create a view, see How to: Add a View with a Presenter.

Steps

You will use the action catalog to control the execution of a business action by implementing code that performs the following:

1. Create and register the action condition service.
2. Add the action strategy to ObjectBuilder.
3. Define the action.
4. Relate the action with section of code.
5. Add the action to the action catalog.
6. Conditionally execute the action.

To create and register the action condition service

1. Create a public class named MyActionCondition in the Infrastructure.Module project. Change the class definition to implement the IActionCondition interface. All action condition services implement the IActionCondition interface.

   public class MyActionCondition : rootnamespace.Infrastructure.Interface.Services.IActionCondition
   

2. Add the following using statements to the MyActionCondition class.

   using System.Threading;
   using Microsoft.Practices.CompositeUI;
   

3. Implement the CanExecute method. The action catalog calls this method before executing a business action to determine if the action can be executed. The following code shows a sample implementation.

   public bool CanExecute(string action, WorkItem context, object caller, object target)
   {
     if (action == "ShowMyView" && Thread.CurrentPrincipal.Identity.Name == "Officer")
     {
       return true;
     }
     else
     {
       return false;
     }
   }
   

   Note

   Note: The Bank Branch reference implementation includes an action condition that uses the default authorization provider of Enterprise Library.

4. Add the following using statement to the Module class of the Infrastructure.Module project.

   using rootnamespace.Infrastructure.Interface.Services;
   

5. Create and register the MyActionCondition with the action catalog. Register the action condition as a general condition. This means that this action condition is used for all actions, regardless of the action name. Override the AddServices method to register the action condition using the IActionCatalogService contained in the root WorkItem. To do this, add the following code to the Module class in the Infrastructure.Module project.

   public override void AddServices()
   {
     base.AddServices();
     IActionCatalogService catalog = _rootWorkItem.Services.Get<IActionCatalogService>();
     catalog.RegisterGeneralCondition(new MyActionCondition());
   }
   

To add the action strategy to ObjectBuilder

1. Add the following using statements to the ShellApplication class.

   using rootnamespace.Infrastructure.Library.BuilderStrategies;
   using Microsoft.Practices.ObjectBuilder;
   

2. Override the AddBuilderStrategies method and add the ActionStrategy to ObjectBuilder. Specify the Initialization builder stage for the strategy. This strategy reflects on the methods of objects created by ObjectBuilder and adds entries into the action catalog for methods with an Action attribute.

   protected override void AddBuilderStrategies(Builder builder)
   {
     base.AddBuilderStrategies(builder);
     builder.Strategies.AddNew<ActionStrategy>(BuilderStage.Initialization);
   }
   

To define an action

1. Create a class named ActionNames in the Constants folder of the MyModule project. Add definitions for your action names to this class.

2. In the ActionNames class, add the following string constant. This constant is the name of an action that determines whether the application displays the MyView view.

   public class ActionNames
   {
     public const string ShowMyView = "ShowMyView";        
   }       
   

To relate actions to sections of code

1. Create a class named ModuleActions in the MyModule project. Add the following using statements to this class.

   using Microsoft.Practices.CompositeUI;
   using rootnamespace.Infrastructure.Interface;
   

2. Add the implementation of business actions to the ModuleActions class. Create a method that shows the MyView view. Add the Action attribute to this method. The Action attribute specifies that the method is a business action that is to be registered in the action catalog for conditional execution.

   public class ModuleActions
   {
     private WorkItem _workItem = null;
   
     [ServiceDependency]
     public WorkItem WorkItem
     {
       get { return _workItem; }
       set { _workItem = value; }
     }
   
     [Action(Constants.ActionNames.ShowMyView)]
     public void ShowMyView(object caller, object target)
     {
       IMyView view = WorkItem.Items.AddNew<MyView>();
       WorkItem.Workspaces[Constants.WorkspaceNames.RightWorkspace].Show(view);
     }
   }
   

   Note

   Notes: The method signature must match the following delegate (this delegate is defined in the interface IActionCatalogService):
   public delegate void ActionDelegate(object caller, object target);
   The ObjectBuilder action strategy reflects on the methods of objects within a WorkItem when that WorkItem is constructed. This means if you use the attribute on a method of an object that is not a part of the WorkItem, it will have no effect.

To add an action to the action catalog

1. Open the file ModuleController.cs in the MyModule project. Modify the Run method to call a method that registers actions with the action catalog.

   public override void Run()
   {
   RegisterActions();
   }
   

2. In the RegisterActions method, add a new instance of the ModuleActions class to the Items collection of the WorkItem. ObjectBuilder runs the action strategy when it constructs the ModuleActions object.

   private void RegisterActions()
   {
   WorkItem.Items.AddNew<ModuleActions>();
   } 
   

To conditionally execute an action using the action catalog

1. Add the ExecuteActions method. In this method, use the ActionCatalogService service to conditionally execute the ShowMyView action. Call the Execute (or CanExecute) method of the action catalog service and pass the action name, current WorkItem, a reference to the caller, and an optional fourth argument.

   private void ExecuteActions()
   {
     ActionCatalogService.Execute(Constants.ActionNames.ShowMyView, WorkItem, this, null);
   }
   

2. In the Run method of the ModuleController, call the ExecuteActions method.

   public override void Run()
   {
     RegisterActions();
     ExecuteActions();
   }
   

Outcome

At the conclusion of this topic, you will have the following elements:

• An ActionNames class that contains the definitions of your action names
• A ModuleActions class that contains business actions
• An action condition service, the MyActionCondition class
• An updated ShellApplication class that adds the ObjectBuilder action strategy to ObjectBuilder
• An updated Module class of the Infrastructure.Module project that registers a global action condition
• An updated ModuleController class of the MyModule project that registers and conditionally executes business actions