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

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

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.

Sample screenshot

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|&File"
    Register_Topic="ste://XS/Shell/Menu/File"/>

<UIExtensionSite_Composite
    Parent_Topic="ste://XS/Shell/Menu/File"
    UIElement_Properties="Text|E&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.

Sample screenshot

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|&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.

Sample screenshot

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|&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.

You must Sign In to use this message board.


Per page

Culture problem...
ikharus

12:03 12 Dec '06

First of all, sorry for my english, I'm french, but i'll do my best to be clear enough.

This project is very very nice and usefull. But at the beginning, i was not able to run the solution, I had many "Input string was not in a correct format" (FormatException).

Finally, I realize that my default culture was "fr-CA" (french-Canada). It gives me some headache, like how to manage the "Insert_Priority" in xml mapper file (XSModuleCompMppr.xml). With the culture fr-CA, it should be 5,0 instead of 5.0 for example. I finally tried the following in the Shell, to solve my problem:

[STAThread]
public static void Main() {

  // THE FOLLOWING LINE WAS ADD BY ME
  Thread.CurrentThread.CurrentCulture = new System.Globalization.CultureInfo("en-US", false);
  // END

  instance.Run(); 
}

Now it works for me too. But I would like to use any culture I could need in the future.

So, my question is: Is there a way to make this solution runs without having to set the current culture to en-US?? For my project, it should be "fr-CA". I'm new in .NET, so I'm confused with all that.

Thanks in advance and "Bravo" again Wink

Thanks to babel fish translator too, haha!

Simon

nested workitems
thebts

16:28 5 Dec '06

Any idea how you would cope with nested workitems in this framework?
Sign In·View Thread·PermaLink

User Interface Element Insert Priority Coming Soon!
Tom Polanski

6:08 21 Mar '06

User interface element (UIElement) insert priority is coming soon as an update to the module composite mapper service! Insert priority is set within the XML configuration file specified with a module and provides an end-user control over the ordering of UIElements that are added to the shell through the UI extension site composite mechanism (e.g., menu/toolbar item order independent of module load order). The feature is complete and will be covered in the article (as well as the downloadable source files) ASAP... thanks!

Tom Polanski, Lead Software Engineer
Xtensible Solutions

Re: User Interface Element Insert Priority Now Available!
Tom Polanski

17:04 30 Mar '06

User Interface Element (UIElement) insert priority is now available including article coverage and the downloadable source files. The XSShell application module composite mapper file may be used to try out the insert priority functionality against the core UI menu items (i.e., File, Edit, View, Tools, Window and Help). Tom Polanski, Lead Software Engineer Xtensible Solutions
Sign In·View Thread·PermaLink

MyServerModule Dynamically Loads MyClientModule using Hardcoded Path
Tom Polanski

6:09 20 Mar '06

As mentioned in the article, the MyClientModule is not loaded by default upon executing the XSShell application. The MyServerModule provides a user interface on the shell that dynamically loads the MyClientModule during application run-time. The MyServerModule.MyServerWorkItem.LoadClientModule method uses the following hardcoded path for the module loader service (this logic is not particularly smart with no error handling if the client module cannot be found or is already loaded... though, the Load Client user interface element on the standard tool menu is disabled after its first invocation):

@"C:\XSModuleCompMppr\MyClientModule\bin\Release\XtensibleSolutions.MyClientModule.dll"

One must locate the MyClientModule assembly per the path above in order for it to be dynamically loaded by the MyServerModule (assuming a local C drive, this is the default location on downloading and unzipping the project structure as is from this CodeProject article). Additionally, given that the POC framework shell uses the native CAB reflection-based module loader service against its local startup directory, one may circumvent the dynamic loading mechanism altogether by locating the MyClientModule assembly (XtensibleSolutions.MyClientModule.dll) within the shell executable directory (C:\XSModuleCompMppr\XSShell\bin\Release). Of course, much more robust logic for dynamic loading should be in place for production code.

Tom Polanski, Lead Software Engineer
Xtensible Solutions

Brilliant!
gcadmes

7:33 17 Mar '06

Thank you for sharing your POC extension. I have found this resource to be invaluable! I hope to expand on this and share as well. Greg Cadmes
Sign In·View Thread·PermaLink	5.00/5

AB's seem interesting
Peter Hayward

16:51 27 Feb '06

Yes these application blocks in the Enterprise library sure do look interesting. Your article looks good, hopefully I'll a chance to really look through it in more detail. Peter Hayward
Sign In·View Thread·PermaLink

Excellent
oykica

14:19 27 Feb '06

Thanks for sharing your work. I really enjoy reading articles on how others are extending or using application blocks.
Sign In·View Thread·PermaLink