How to: Create a Solution Using the Composite Application Library for WPF


This topic requires you to have the following Composite Application Library and Unity Application Block assemblies:

  • Microsoft.Practices.Composite.dll
  • Microsoft.Practices.Composite.Presentation.dll
  • Microsoft.Practices.Composite.UnityExtensions.dll
  • Microsoft.Practices.Unity.dll
  • Microsoft.Practices.ObjectBuilder2.dll
  • Microsoft.Practices.ServiceLocation.dll

The Composite Application Library ships as source code—this means you must compile it to get the Composite Application Library assemblies (Microsoft.Practices.Composite.dll, Microsoft.Practices.Composite.Presentation.dll, and Microsoft.Practices.Composite.UnityExtensions. dll).

To compile the solution

  1. In Windows Explorer, double-click one of the following batch files to open the Composite Application Library solution in Visual Studio:
    • Desktop only - Open Composite Application Library.bat
    • Desktop & Silverlight - Open Composite Application Library.bat
  2. Build the solution. The Composite Application Library assemblies will be placed at the CAL\Desktop\Composite.UnityExtensions\bin\Debug folder.


To create a solution that uses the Composite Application Library, the following tasks must be performed:

  • Create a solution with a Shell project.
  • Define the Shell window layout.
  • Set up the application's bootstrapper.
  • (Optional) Create an infrastructure project.

The following procedure describes how to create a solution with a Shell project.

To create a solution with a Shell project

  1. In Visual Studio, create a new Windows Presentation Foundation (WPF) application. To do this, point to New on the File menu, and then click Project. In the Project types list, click Windows in the Visual C# node. In the Templates box, click WPF Application. Finally, set the project's name, such as CALApplication1, specify a valid location, and then click OK.

    This project will be the Shell project of your application.

  2. (Optional) Using Windows Explorer, create a folder named Library inside your solution's folder, and then copy the following assemblies, located in the folder CAL\Desktop\Composite.UnityExtensions\bin\Debug, into the previously created folder:

    • Microsoft.Practices.Composite.dll. This assembly contains the implementation of the Composite Application Library for WPF core components, such as modularity, logging, and communication services, and several core interfaces' definitions. This assembly does not contain user interface (UI)—specific elements.
    • Microsoft.Practices.Composite.Presentation.dll. This assembly contains the implementation of Composite Application Library for WPF components that target WPF applications, including commands, regions, and events.
    • Microsoft.Practices.Composite.UnityExtensions.dll. This assembly contains base and utility classes you can reuse in applications based on the Composite Application Library for WPF that consume the Unity Application Block. For example, it contains a bootstrapper base class, the UnityBootstrapper class, that creates and configures a Unity container with default services when the application starts.
    • Microsoft.Practices.Unity.dll and Microsoft.Practices.ObjectBuilder2.dll. These assemblies enable you to use the Unity Application Block in your application. By default, applications built with the Composite Application Library for WPF use the Unity Application Block. However, developers who prefer to use different container implementations can build adapters for them using the provided extensibility points in the Composite Application Library.
    • Microsoft.Practices.ServiceLocation.dll. This assembly contains the Common Service Locator interface used by the Composite Application Library for WPF to provide an abstraction over Inversion of Control containers and service locators; therefore, the user can easily change the container implementation.
  3. In the Shell project, add references to the assemblies mentioned in the previous step.


For IntelliSense to be available for the Composite Application Library, the XML documentation files for each of these assemblies must be placed in the same directory as the referenced assemblies.

The Shell window is a place to host different UI components that exposes a way for itself to be dynamically populated by others. The following procedure explains how to define the Shell window layout.

To define the Shell window layout

  1. In Solution Explorer, rename the file Window1.xaml to Shell.xaml.

  2. Open the code behind file Shell.xaml.cs, and then rename the Window1 class to Shell using the Visual Studio refactoring tools. To do this, right-click Window1 in the class signature, point to Refactor, and then click Rename, as illustrated in Figure 1. In the Rename dialog box, type Shell in the New Name box, and then click OK. If the Preview Changes — Rename dialog box appears, click Apply.


    Figure 1

    Renaming Window1 using Visual Studio refactoring tools

  3. Open the Shell.xaml file in XAML view and set the following attribute values to the Window root element:

    • x:Class = "CALApplication1.Shell" (The Class attribute has to match the code behind class's name)
    • Title = "Shell"

    Your code should look like the following.

    <Window x:Class="CALApplication1.Shell"
        Title="Shell" Height="300" Width="300">
  4. Open the App.xaml file, and then change the StartupUri attribute of the Application node from Window1.xaml to Shell.xaml, as shown in the following code.

    <Application x:Class="CALApplication1.App"

    The following steps describe how to add an ItemsControl control to the Shell window and associate a region to it.

  5. Add the following namespace definition to the root Window element. You need this namespace to use an attached property for regions; this property is defined in the Composite Application Library.

  6. Replace the Grid control in the Shell window with an ItemsControl control named MainRegion, as shown in the following code.

    <Window x:Class="CALApplication1.Shell"
        Title="Shell" Height="300" Width="300">
        <ItemsControl Name="MainRegion" />
  7. In the ItemsControl control definition, set the attached property cal:RegionManager.RegionName to "MainRegion", as shown in the following code. This attached property indicates that a region named MainRegion is associated with the control

    <ItemsControl Name="MainRegion" cal:RegionManager.RegionName="MainRegion" />

A Bootstrapper class is a class that is in charge of initializing the application. Typically, the bootstrapper initializes the container used for dependency injection, registers services and region adapters, creates and shows the Shell window, and loads modules. The following procedure explains how to set up the application's bootstrapper.

To set up the application's bootstrapper

  1. Add a new class file to the Shell project named Bootstrapper.cs.

  2. To the top of the file, add the following using statements.

    using Microsoft.Practices.Composite.UnityExtensions;
    using System.Windows;using Microsoft.Practices.Composite.Modularity;
  3. Update the signature of the Bootstrapper class to inherit from the UnityBootstrapper class.

    public class Bootstrapper : UnityBootstrapper
  4. Override the CreateShell method in the Bootstrapper class. The CreateShell method should obtain an instance of the Shell window and display it to the user. The following code illustrates a possible implementation of the CreateShell method.

    protected override DependencyObject CreateShell()
        Shell shell = Container.Resolve<Shell>();
        return shell;


    You can return the Shell object or null. If you return the Shell object, the UnityBootstrapper base class will attach the default region manager to it.

  5. Override the GetModuleCatalog method in the Bootstrapper class. In this template method, you typically create an instance of the module catalog, populate it with modules, and return it. The module catalog interface is Microsoft.Practices.Composite.Modularity.IModuleCatalog, and it is responsible for storing the metadata of all the modules in the application. The Composite Application Library includes different methods of populating the module catalog in WPF:

    • Populating the module catalog from code. This is the most straightforward method of populating the module catalog. In this approach, the module information is added to the module catalog in code. If you directly reference the modules, you can use the module type to add the module. However, directly referencing modules results in a less decoupled design. If you do not directly reference modules from the shell, you must provide the fully qualified type name, and the location of the assembly.

      Another advantage of this approach is that you can easily add conditional logic to determine which modules should be loaded.

    • Populating the catalog from a XAML file. Another approach is to declaratively specify the kind of module catalog to create and which modules to add to it, by creating a ModuleCatalog.xaml file. Typically, the XAML file is added as a resource to your shell; from a technical perspective, this approach is very similar to defining the module catalog from code.

    • Populating the catalog from a configuration file. In WPF, you can specify the module information in the App.config file. The advantage of this approach is that because this configuration file is not compiled with the application, new modules can be easily added without recompiling the shell.

    • Populating the catalog from a directory. In WPF, you can also declare the modules in a directory and use the DirectoryModuleCatalog to look for modules in that designated folder.

      This approach requires you to configure modules using attributes in code, and is the easiest way to add and remove modules from your application.

    The following code illustrates how the Modularity (Directory Lookup) QuickStart for WPF implements the GetModuleCatalog method by populating the catalog from a directory.


    The code below will throw a directory not found error if a Modules directory does not exist in the CalApplication1...\bin\Debug path.

    protected override IModuleCatalog GetModuleCatalog()
        return new DirectoryModuleCatalog() {ModulePath = @".\Modules"};
  6. Open the file App.xaml.cs, and then paste the following code inside the body of the App class to initialize the bootstrapper in the handler for the Startup event of the application.

    protected override void OnStartup(StartupEventArgs e)
        Bootstrapper bootstrapper = new Bootstrapper();
  7. Open the file App.xaml, and then remove the attribute StartupUri. This attribute is not required because you are manually instantiating the Shell window.


    Additional customization can be made to the Bootstrapper class by overriding methods of its base class. For more information, see How to: Register and Use Services.

Additionally, you can create an infrastructure project to store elements shared by multiple modules in the application. The following procedure describes how to create an infrastructure project.

To create an infrastructure project

  1. In your solution, add a new class library project named Infrastructure.
  2. Add references to the project to the following Composite Application Library assemblies:
    • Microsoft.Practices.Composite.dll
    • Microsoft.Practices.Composite.Presentation.dll
  3. Add references to the project to the following WPF assemblies:
    • PresentationCore.dll
    • PresentationFramework.dll
    • WindowsBase.dll
  4. To the Shell project, add a reference to the Infrastructure project.


You will have a Composite Application Library solution that you can use as the base to build a composite application. This solution is the base required for multiple procedures in this guidance. Figure 2 illustrates the resulting solution in Solution Explorer.


Figure 2

Resulting solution in Solution Explorer

Next Steps

The following are typical tasks that you perform after you create a solution using the Composite Application Library:

  • Modify the Shell layout. For example, you can add or remove regions, or you can change the overall appearance. For information about how to add a region, see How to: Add a Region.
  • Create modules. A module encapsulates a set of related concerns. Modules are independently developed and deployed, and they interact with each other to create the application. For information about how to create a module, see How to: Create a Module.

More Information

For a complete list of How-to topics included with the Composite Application Guidance, see Development Activities.

Home page on MSDN | Community site