Microsoft patterns & practices Composite UI Application Block (CAB) based Module Composite Mapper Service: An XML Configurable Builder for Workspaces, UIElements, Commands, and Event Publications/Subscriptions

• Download source files - 997 Kb

Introduction

A Microsoft patterns & practices Composite UI Application Block (CAB) based module composite mapper service is provided including C# source code that builds Workspaces, UIElements, Commands and Event Publications/Subscriptions using an XML configuration file specified with a module. The module composite mapper service is based and executes on the CAB using a Model-View-Presenter (MVP) pattern within a proof-of-concept (POC) framework. This article and its included source code provide POC framework classes, module composite mapper service classes, module composite mapper XML configuration file syntax and examples, module composite mapper topic format guidelines, and example/template modules.

In addition to POC framework and module composite mapper service items described in further detail, the following CAB items are referenced throughout the context of this article and are defined in the CAB documentation similar to the following:

• Module: distinct deployment unit of a CAB application; modules provide for separation of concerns such as a module that houses all (or logically grouped) infrastructure services for a specific application type or a module that houses the components that realize a specific (or logically grouped) use cases including work items, commands, events, SmartParts, services and other components
• Shell: represents the main window of the application and provides core UI items such as a menu, toolbar, statusbar and workspaces; controls hosted in the shell (i.e., module-specified UIElements as built by the module composite mapper) are shared across the application, such as a menu item, toolbar button, or status panel (core menu items such as File-Exit and Help-About are handled by the shell itself); modules use the workspaces to display their role-specific user interface
• Service: provides infrastructure functionality to an application (e.g., the CAB-specific module loader service and the POC framework module composite mapper service)

Proof-of-Concept Framework

The module composite mapper service is based and executes on the CAB using a Model-View-Presenter (MVP) pattern within a proof-of-concept (POC) framework. While the POC framework can be modified (or removed altogether) based on your needs, the following describes the POC framework base classes in further detail. Note that the POC framework shell uses the native CAB reflection-based module loader service against a local startup directory.

• Module Initialization Class (e.g., MyModuleInit): in the POC framework, effectively only a bootstrap mechanism for the module work item (contained in the root namespace for any module)
  
  
• Work Item Interface and Class (IXSWorkItem and XSWorkItem): the model bridge (i.e., communicates state to underlying business objects) and/or model implementation (i.e., communicates state to a persistence layer) in the MVP pattern that contains the views (i.e., SmartParts), presenters, and other components (i.e., UI elements, commands, events, services and more) that collaborate at runtime to realize a specific use case (contained in the root namespace for any module); in the POC framework, work item-based composite mappings are applied on work item build up (i.e., OnBuiltUp) ensuring that event publication/subscription is consistent with the native CAB application initialization sequence (as well as shell workspace, UI element and command initialization prior to module catalog enumeration that may rely on shell hosted items):
  
  this.RootWorkItem.Services.Get<IXSModuleCompMpprService>().ApplyModuleMappings(this);
  
  
  
  In the POC framework, note that base work item and presenter classes provide generic events for programming efficiency and infrastructure performance optimization by alleviating the need for repetively specifying such application-wide events using the module composite mapper service (i.e., the native CAB declarative model for event publication is used).
  
  
• Presenter Interface and Class (IXSPresenter and XSPresenter): the presenter in the MVP pattern that manages end-user displayed view(s) based on events broadcast/received or method calls made from/to the participating work item (i.e., model) (contained in the SmartParts namespace for any module); in the POC framework, presenter-based composite mappings are applied on presenter construction (which occurs on the owning XSWorkItem.Run) ensuring that views are not accessed by composite mapper classes (e.g., XSWorkspaceCompMppr) until they are actually shown:
  
  this.workItem.RootWorkItem.Services.Get<IXSModuleCompMpprService>().ApplyModuleMappings(this);
  
  
  
  As noted previously, the POC framework base work item and presenter classes provide generic events for programming efficiency and infrastructure performance optimization by alleviating the need for repetively specifying such application-wide events using the module composite mapper service (i.e., the native CAB declarative model for event publication is used).
  
  
• View Interface and Class (IXSView and XSView): the view in the MVP pattern that provides end-user display only based on method calls made from/to the participating presenter (contained in the SmartParts namespace for any module)
  
  
  
  

Module Composite Mapper Service

The module composite mapper service allows a module developer to specify the following composite types using a module composite mapper XML configuration file (syntax is described in further detail). Note that composite is used as a generic term to describe any one of the following items:

• Workspace: encapsulates a particular layout of controls and SmartParts, such as within tabbed pages; in the POC framework, mainly applicable to the shell presenter that provides interfaces with which to easily display module views in desired workspaces
• UI Extension Site: identified by an extension site topic, provides a UI element adapter that serves as an extension point for any registered UI element (i.e., for adding and removing child UI elements); in the POC framework, allows a module to specify user interface element extensions within the shell (e.g., menu, toolbar and statusbar items) including end-user control over the ordering of UI elements that are added using an insert priority
• Command: associates a command handler method that is defined on the module presenter with any command topic
• Event Publication: specifies a method that is defined on the module work item or presenter as a publication handler for event broadcast
• Event Subscription: specifies a method that is defined on the module work item or presenter as a subscription method for event receive

A module developer minimally interacts with the module composite mapper service through the following items only (contained in the Services.XSModuleCompMppr namespace for any module):

• Module composite mapper XML configuration file specification
• Workspace topic access for view display (from the workspace composite mapper for the shell... an XSWorkspaceCompMppr class static property)
• User interface element access for view management (from the presenter-specific UI extension site composite mapper... an XSPresenter base class property)

Module Composite Mapper Service Classes

• Module Composite Mapper Service Interface and Class (IXSModuleCompMpprService and XSModuleCompMpprService): a singleton service class that manages module composite mapper creation and delegates the application of module composite mappings (at the work item or presenter level) to the contained module composite mapper
  
  
  
  The module composite mapper service is instantiated and registered in the shell application AddServices method per the following:
  
  

  XSModuleCompMpprService service = XSModuleCompMpprService.CreateInstance();
  this.RootWorkItem.Services.Add<IXSModuleCompMpprService>(service);

• Module Composite Mapper Class (XSModuleCompMppr): builds the module composite mapper object hierarchy using the XML configuration file specified with a module (and a private XMLReader-based loader class, XSModuleCompMpprLoader) and delegates the application of composite mappings (at the work item or presenter level) to the contained composite mappers; note that the module composite mapper class applies event publication and event subscription composite mappings to both work items and presenters (as specified in the configuration file) whereas workspace, UI extension site, and command composite mappings are applied to presenters only given the interpretation of the MVP pattern as realized in the POC framework implementation
  
  
  
  
• Composite Mapper Classes: the workhorses of the service, composite mapper classes apply composite mappings (at the work item or presenter level with the overloaded ApplyCompositeMappings method) based on the contained composites (if any) built from the module composite mapper XML configuration file
  
  
  
  Several unique interfaces are provided on the composite mapper classes including:
  
  XSWorkspaceCompMppr.ShellWorkspaceCompMppr: workspace composite mapper for the shell that allows for...
  XSWorkspaceCompMppr.GetWorkspaceTopic: workspace topic access for view display by pre-defined workspace types
  
  The base XSPresenter.ShowView method displays its current view in the requested workspace as follows:
  
  protected void ShowView(XSWorkspaceType thisWorkspaceType)
  {
      this.workItem.RootWorkItem.Workspaces[
          XSWorkspaceCompMppr.ShellWorkspaceCompMppr.GetWorkspaceTopic(
              thisWorkspaceType)].Show(this.View);
  }
  
  
  
  XSUIExtSiteCompMppr.GetUIElements: user interface element access for view management by the presenter (e.g., setting a menu item and toolbar item Checked property on command invocation); currently all UI elements are returned that match the topic parameter including either the UI element command, registration or parent topic property (obviously, this can be modified or extended to meet your needs)
  
  
  
  
• Composite Classes: composites are essentially persisted by (read-only) and built directly from the module composite mapper XML configuration file; static object creation methods (i.e., CreateInstance) are provided by each of the composite classes including some validation of XML configuration file input parameters passed from the XSModuleCompMpprLoader loader class
  
  
  

Module Composite Mapper XML Configuration File Syntax and Examples (XSModuleCompMppr.xml)

The syntax of the module composite mapper XML configuration file is provided in detail below including example composite specifications. The module composite mapper service currently requires the following of the configuration file in order to function properly:

• The configuration file and any associated image files must be set to compile as embedded resources in the container module project
• The configuration file must be located and named per the following namespace hierarchy, i.e., folders and file name (assuming a project name of MyComponentModule)
  
  MyComponentModule.Services.XSModuleCompMppr.XSModuleCompMppr.xml
  
  The XSModuleCompMppr.CreateInstance method uses the following code in order to get a manifest resource stream using the IXSWorkItem parameter type (as it is expected to be in the assembly default namespace), standard module composite mapper service assembly extended namespace and filename (reference XSModuleCompMppr.AssyXSModuleCompMpprNS):
  
  mpprStream = thisWorkItem.GetType().Assembly.GetManifestResourceStream(
      thisWorkItem.GetType(),
      XSModuleCompMppr.AssyXSModuleCompMpprNS);

XSModuleCompMppr.xml Syntax

<XtensibleSolutions version="2.0" language="XSModuleCompMppr">
    <!--Module composite mapper contains composite mappers: 
         * Workspace (optional; applies to shell presenter only)
         * UI extension site (optional)
         * Command (optional)
         * Event (optional) 
            NOTE: ALL WorkItems/Presenters publish generic events.-->
    <Module_Composite_Mapper>
      <!--Workspace composite mapper contains workspace composites:
            * Workspace type descriptor (optional; for readability only) and... 
            * Workspace type enumeration value (required)
            * Workspace topic (required)-->
      <Workspace_Composite_Mapper>
          <Workspace_Composite
              XSWorkspaceType_Descriptor="Foo"
              XSWorkspaceType_Enum="0"
              Workspace_Topic="wks://XS/Shell/Foo"/>
      <!--UI extension site composite mapper contains UI extension site composites: 
           * Parent topic (required)
           * Insert priority (optional - defaults to 0.0; used to indicate an 
              insertion priority for positioning the UI element in relation to its sibling 
              items); if not populated, the null priority is assigned (0.0) and the default 
              CAB behavior is used for the requested insertion (appended as the last item); 
              if populated (with a float value), the indicated priority is assigned and 
              used for positioning the requested insertion where: 
              - the smaller the indicated magnitude, the higher its priority and the closer 
                the item will be to the top of the list if not the first (i.e., 1.0 is 
                considered "priority one", though the actual algorithm has no practical limit 
                on the lower bounds while also considering the special value of 0.0)
              - the higher the indicated magnitude, the lower its priority and the closer 
                the item will be to the bottom of the list if not the last (e.g., 99.0 is 
                lower priority than 1.0)
              - equivalent priorities result in the existing item taking precedence (i.e., the
                new item is inserted immediately after that which it is equal to in priority)
              - an assigned priority always takes precedence over those not assigned 
                that are appended as the last items (e.g., 99.0 is higher priority 
                than 0.0)
           * UI element Type (optional - defaults to "ToolStripMenuItem")
           * UI element properties (optional; a generic attribute with 
              property|value|property|value|... pairs used to configure 
              virtually any property on the created UI element); currently 
              supported property types include strings, booleans, and images...

              Examples: 

              "Text|&amp;File": sets the Text property on the UI element to "File" 
              with the "F" specified as the UI element mnemonic

              "Checked|true": sets the Checked property on the UI element to True

              "Image|MyImageFile.ico": sets the Image property on the UI element 
              from the image file as specified (e.g., toolbar icons); images must 
              be named per the property specification (e.g., MyImageFile.ico), 
              co-located alongside the composite mapper file in the XSModuleCompMppr 
              folder, and compiled as an embedded resource

           * Register topic (optional) and...
           * Register property (optional - defaults to "DropDownItems"; used to 
              indicate which property on the created UI element is registered as 
              an extension point)
           * Command topic (optional) and...
           * Command event name (optional - defaults to "Click")-->
      <UIExtensionSite_Composite_Mapper>
          <UIExtensionSite_Composite 
              Parent_Topic="ste://XS/Shell/Menu"
              Insert_Priority="1.0"
              UIElement_Type="ToolStripMenuItem" 
              UIElement_Properties="Text|&amp;File"
              Register_Topic="ste://XS/Shell/Menu/File"
              Register_Property="DropDownItems"
              Command_Topic="cmd://XS/Shell/File_Click"
              Command_EventName="Click"/>
      </UIExtensionSite_Composite_Mapper>
      <!--Command composite mapper contains command composites: 
           * Command topic (required)
           * Command handler method name (required)-->
      <Command_Composite_Mapper>
          <Command_Composite 
              Command_Topic="cmd://XS/Shell/FileExit_Click"
              Command_HandlerName="OnFileExit_Click"/>
      </Command_Composite_Mapper>
      <!--NOTE: ALL WorkItems/Presenters publish generic events.-->
      <!--Event publication composite mapper contains event publication composites: 
           * Event topic (required)
           * Publication scope descriptor (optional; for readability only) and... 
           * Publication scope enumeration value (optional - defaults to 
             Global {0}); values include (see the CAB help for more info): 
                 - Global {0}
                 - WorkItem {1}
                 - Descendants {2} 
         * Publisher type descriptor (optional; for readability only) and... 
         * Publisher type enumeration value (optional - defaults to WorkItem {0}); 
            values include: 
                - WorkItem {0}
                - Presenter {1} 
         * Publication handler method name (required)-->
      <EventPublication_Composite_Mapper>
          <EventPublication_Composite 
              Event_Topic="evt://XS/MyModule/MyEvent"
              PublicationScope_Descriptor="Global"
              PublicationScope_Enum="0"
              XSEventPubSubType_Descriptor="WorkItem"
              XSEventPubSubType_Enum="0" 
              Publication_HandlerName="BroadcastMyEvent"/>
      </EventPublication_Composite_Mapper>
      <!--Event subscription composite mapper contains event subscription composites: 
           * Event topic (required)
           * Subscriber type descriptor (optional; for readability only) and... 
           * Subscriber type enumeration value (optional - defaults to WorkItem {0}); 
              values include: 
                  - WorkItem {0}
                  - Presenter {1} 
           * Subscription method name (required)-->
      <EventSubscription_Composite_Mapper>
          <EventSubscription_Composite 
              Event_Topic="evt://XS/MyModule/MyEvent"
              XSEventPubSubType_Descriptor="WorkItem"
              XSEventPubSubType_Enum="0" 
              Subscription_MethodName="OnReceiveMyEvent"/>
      </EventSubscription_Composite_Mapper>
    </Module_Composite_Mapper>
</XtensibleSolutions>

Module Composite Mapper Topic Formats

The following sub-sections provide guidance on standard module composite topic formats including examples. The examples use parameter strings and method attributes for context and clarity whereas the module composite mapper service actually alleviates the need for these decorations through use of the single-point of configuration module composite mapper file.

Workspace Topic Format

wks (workspace)
XS (Xtensible Solutions, Inc. or end-user company)
ModuleName (or Generic if application-wide)
Descriptor00/Descriptor01/...

(client-defined; workspace topic descriptor should use the relevant XSWorkspaceType name followed by a brief indication of the specific instance, such as WorkspaceTypeFooMain)

Examples

this.RootWorkItem.Workspaces.Add(
    this.Shell.GetWorkspace(XSWorkspaceType.WorkspaceTypeFoo),
    "wks://XS/Shell/WorkspaceTypeFooMain");

this.RootWorkItem.Workspaces["wks://XS/Shell/WorkspaceTypeFooMain"].Show(this.view);

UIExtensionSite Topic Format

ste (UIExtensionSite)
XS (Xtensible Solutions, Inc. or end-user company)
ModuleName (or Generic if application-wide)
Descriptor00/Descriptor01/...

(client-defined; site topic descriptors should use the path to the UIElement of interest)

Examples

this.RootWorkItem.UIExtensionSites.RegisterSite(
    "ste://XS/Shell/Menu", this.Shell.MainMenuStrip);

this.RootWorkItem.UIExtensionSites.RegisterSite(
    "ste://XS/Shell/Menu/File", fileMenuItem);

Command Topic Format

cmd (command)
XS (Xtensible Solutions, Inc. or end-user company)
ModuleName (or Generic if application-wide)
Descriptor_Event

(client-defined; command topic descriptor should use a brief indication of the event followed by the actual event being handled, such as "FileExit_Click")

Command Invoker: Descriptor_Event (e.g., FileExit_Click)
Command Handler Method: OnDescriptor_Event (e.g., OnFileExit_Click)

Examples

Command Invoker

workItem.Commands["cmd://XS/Shell/FileExit_Click"].AddInvoker(fileExitMenuItem, "Click");

Command Handler

[CommandHandler("cmd://XS/Shell/FileExit_Click")]
public void OnFileExit_Click(object sender, EventArgs e) { myObject.MyMethod(); }

Event Topic Format

evt (event)
XS (Xtensible Solutions, Inc. or end-user company)
ModuleName (or Generic if application-wide)
Descriptor

(client-defined; event topic descriptor should use a brief indication of the event to be broadcast)

Event Publication Handler: BroadcastDescriptor (e.g., BroadcastFoo)
Event Subscription Method: OnReceiveDescriptor (e.g., OnReceiveFoo)

Examples

Event Publication

The publication handler itself...

[EventPublication("evt://XS/Generic/Foo")]
public event EventHandler<DataEventArgs<string>> BroadcastFoo;

Public method for invoking the publication handler from referring classes. While not required for events that should not be invoked except by the publishing class itself, if appropriate, provides an interface for referring classes that may also require invocation of the event, such as a view that may invoke an event defined on its owning presenter...

public void DoBroadcastFoo(object sender, string thisMessage)
{
    this.BroadcastFoo(sender, new DataEventArgs<string>(thisMessage));
}

Event Subscription

[EventSubscription("evt://XS/Generic/Foo")]
[EventSubscription("evt://XS/Generic/Bar")]
public void OnReceiveGeneric(object sender, DataEventArgs<string> e)
{
    myObject.MyMethod(e.Data);
}

Example Modules

XSShell

The XSShell application module provides core UI items such as a menu, toolbar and workspaces.

• Module Composite Mapper File (XSModuleCompMppr.xml)
  
  Specifies a workspace topic for the Foo workspace type
  
  <Workspace_Composite 
      XSWorkspaceType_Descriptor="Foo"
      XSWorkspaceType_Enum="0"
      Workspace_Topic="wks://XS/Shell/Foo"/>
  
  Specifies a user interface element on the standard file menu
  
  <UIExtensionSite_Composite
      Parent_Topic="ste://XS/Shell/Menu"
      Insert_Priority="1.0"
      UIElement_Properties="Text|&amp;File"
      Register_Topic="ste://XS/Shell/Menu/File"/>
  
  <UIExtensionSite_Composite
      Parent_Topic="ste://XS/Shell/Menu/File"
      UIElement_Properties="Text|E&amp;xit"
      Command_Topic="cmd://XS/Shell/FileExit_Click"/>
  
  Specifies a command handler for the UI element on the presenter
  
  <Command_Composite
      Command_Topic="cmd://XS/Shell/FileExit_Click"
      Command_HandlerName="OnFileExit_Click"/>

In the POC framework, the XSShellApplication class overrides the AfterShellCreated method to register core UIExtensionSites in support of the module composite mapper service:

this.RootWorkItem.UIExtensionSites.RegisterSite(
  "ste://XS/Shell/Menu",
  XSToolStripUIAdapterFactory.GetAdapter(this.Shell.MainMenuStrip));
this.RootWorkItem.UIExtensionSites.RegisterSite(
  "ste://XS/Shell/Toolbar",
  XSToolStripUIAdapterFactory.GetAdapter(this.Shell.MainToolStrip));

MyServerModule

The MyServerModule provides a user interface on the shell that dynamically loads another module (MyClientModule) during application run-time.

• Module Composite Mapper File (XSModuleCompMppr.xml)
  
  Specifies a user interface element on the standard tool menu
  
  <UIExtensionSite_Composite
      Parent_Topic="ste://XS/Shell/Menu/Tools"
      Insert_Priority="1.0"
      UIElement_Properties="Text|&amp;Load Client"
      Command_Topic="cmd://XS/MyServerModule/ToolsLoadClientModule_Click"/>
  
  Specifies a command handler for the UI element on the presenter
  
  <Command_Composite
      Command_Topic="cmd://XS/MyServerModule/ToolsLoadClientModule_Click"
      Command_HandlerName="OnToolsLoadClientModule_Click"/>
  
  Specifies an event subscription to the MyClientModule ClientEvent
  
  <EventSubscription_Composite
      Event_Topic="evt://XS/MyClientModule/ClientEvent"
      Subscription_MethodName="OnReceiveClientEvent"/>
  
  
• Presenter Class (MyServerPresenter): defines a command handler (OnToolsLoadClientModule_Click) that...
  
  Disables the user interface element on the standard tool menu
  Calls LoadClientModule on the work item
  
  
  
  
• View Class (XSView): no module-specific view class is defined (the base view implementation is instantiated on the presenter)
• Work Item Class (MyServerWorkItem):
  
  Defines a method (LoadClientModule) that loads another module using the module loader service (MyClientModule with a hard-coded path)
  Defines a subscription method (OnReceiveClientEvent) that displays a message box on receiving the MyClientModule ClientEvent
  
  

MyClientModule

The MyClientModule provides a user interface on the shell that allows the end-user to broadcast a module-defined event across the application, as well as show or hide its view.

• Module Composite Mapper File (XSModuleCompMppr.xml)
  
  Specifies user interface elements on the standard view menu and toolbar (note the Checked and Image property settings)
  
  <UIExtensionSite_Composite
      Parent_Topic="ste://XS/Shell/Menu/View"
      Insert_Priority="1.0"
      UIElement_Properties="Text|&amp;Client|Checked|true"
      Command_Topic="cmd://XS/MyClientModule/ViewMyClient_Click"/>
  
  <UIExtensionSite_Composite
      Parent_Topic="ste://XS/Shell/Toolbar"
      Insert_Priority="1.0"
      UIElement_Type="ToolStripButton"
      UIElement_Properties="Image|LoadClientModule.ico|Checked|true"
      Command_Topic="cmd://XS/MyClientModule/ViewMyClient_Click"/>
  
  Specifies a command handler for the UI elements on the presenter
  
  <Command_Composite
      Command_Topic="cmd://XS/MyClientModule/ViewMyClient_Click"
      Command_HandlerName="OnViewMyClient_Click"/>
  
  Publishes a module-defined event with its publication handler on the presenter
  
  <EventPublication_Composite
      Event_Topic="evt://XS/MyClientModule/ClientEvent"
      XSEventPubSubType_Enum="1"
      Publication_HandlerName="BroadcastClientEvent"/>
  
  
• Presenter Class (MyClientPresenter):
  
  On construction displays the view on the Bar (versus Foo) workspace
  Defines a publication handler (BroadcastClientEvent) that broadcasts the module-defined event
  Defines a command handler (OnViewMyClient_Click) that shows/hides its view
  
  
  
  The OnViewMyClient_Click command handler sets the view visibility and uses the presenter UIExtSiteCompMppr.GetUIElements method to set the menu item and toolbar item Checked property on command invocation:
  
  bool visible = (!(view.Visible));
  foreach (ToolStripItem uiElement in
          this.UIExtSiteCompMppr.GetUIElements(((Command)sender).Name))
      uiElement.GetType().GetProperty("Checked").SetValue(uiElement, visible, null);
  view.Visible = visible;
  
  
• View Class (MyClientView): defines a local user interface event (uiButtonBroadcastClientEvent_Click) that...
  
  Invokes the publication handler on the presenter (DoBroadcastClientEvent)
  
  

Conclusion

The module composite mapper service provides a consistent, XML configurable, and single per-module persistence paradigm for dynamically building workspaces, UIElements, commands, and event publications/subscriptions within a CAB based application. Regardless of any up and coming composite builder architecture implemented by the Microsoft patterns & practices CAB team, the module composite mapper service provides a clear, concise and well-segregated framework for moving from the current (relatively undefined) approach into any production-oriented module composite development process. In fact, given the XML configuration oriented composite builder snippets available to date, albeit generally limited in scope compared to the module composite mapper service, one should be able to migrate relatively seamless from (or integrate across) the module composite mapper service and any successor approach.