Important Note

Friends, I've noticed that the number of downloads for this article far exceeded the number of votes and bookmarks. So please, if you use this tutorial and like it, vote for it. A bookmark won't hurt either Thanks.

Introduction

Microsoft Prism is a software framework whose purpose is to simplify building WPF and Silverlight applications.

Prism (together with its source code, samples and documentation) can be downloaded from Prism on the CodePlex.

Prism's main advantage lies in the fact that it allows building the WPF or Silverlight software as a set of almost independent modules that can be developed, tested and debugged separately and brought together by Prism framework to become one application.

The importance of developing software as a number of independent modules cannot be overestimated. The smaller the correlation between the modules the easier it is going to be to modify, test and debug one module without affecting the others or without any interference from the others. When it comes to team development, the module independency becomes even more significant, since multiple developers want to work on their modules with as little worry as possible about changes that others make at the same time.

I hope that this tutorial will be set apart from other tutorials due to the following points:

This tutorial is explaining essential Prism functionality based on very simple examples - each example concentrates on no more than a couple of Prism features which are explained in detail. Unfortunately, many Prism samples including the Quick Starts are quite complicated - this makes it more difficult to figure out which features in a Quick Start actually come from Prism and how to use them outside of the Quick Start.

Prism primary goal is to make it possible to develop independent modules and bring them together into an application. One of the most important requirements for that is that different modules should not depend on each other via a project reference. Unfortunately many Quick Starts break this requirement by having its main module (the application) referring to other modules. All of the modules in this tutorial are truly independent of each other and from the application.

All the samples are MEF based: Prism started as a Unity powered project, but now MEF composition framework is apparently ahead of Unity in terms of adoption by Microsoft (based on the fact that the last Unity source code dump was in May 2010, it seems that Unity is dead, even though some bright people do not think so). Currently Prism works with both MEF and Unity, but many Quick Starts and other tutorials were written some time ago and concentrate on Unity rather than on MEF.

All the samples in this tutorial are Silverlight (not WPF) based. There are many other Silverlight based tutorials, but there is a slight edge on the WPF side. Silverlight together with MEF brings another level of complexity, due to the fact that the composition is performed not on the .dll, but on the .xap files. If this tutorial is successful and if I have time I might write another WPF based tutorial in the future.

Overview of the Tutorial

I plan to cover the following parts of Prism in this tutorial (including the future installments).

I left out Prism commanding on purpose, since from my point of view, using MS Expression SDK'sActions/Behaviors achieves the same goal (of sending communication signals from XAML code to the View Model) at much smaller expense.

The purpose of this tutorial is to provide a comprehensive coverage of essential Prism features by using very simple samples that highlight those features one by one, not discuss the design patterns. Since MVVM code is a little more difficult to understand, I try to avoid it here as much as I can, even though I am a great fan of MVVM myself.

I assume that people reading this tutorial have some knowledge of C#, MEF and Silverlight.

Modularity Overview and Samples

As was stated above, Prism's purpose is to bring independently developed modules into one application. We'll call Prism's main module - Prism application (or simply application) throughout the tutorial and the rest of the modules we'll call simply modules or pluggable modules. Prism application loads the modules as they become available or needed and creates a visual application based on them. Different modules within Prism application can communicate between themselves and with the application using different communication methods described later.

Prism application creation and module loading is facilitated by a Bootstrapper class. The bootstrapper can be MEF or Unity based (it will correspondingly derive from MefBootstrapper or UnityBootstrapper classes provided by Prism). Here we will be dealing only with MEF bootstrappers.

Simplest Possible Module Loading Sample

Our first sample is located under SimpleNonVisualModuleSample.sln solution. It is the simplest possible Silverlight project demonstrating loading Prism module into Prism application. It does not even have any visuals (in order to cheat the Silverlight, we set the application's VisualRoot to an empty Grid panel). The only way to prove that the module is loading, is to put a breakpoint within the module's constructor or initializer, run the Silverlight app in the debugger and make sure that the breakpoint is hit.

Let us go over the code involved. The application project: "SimpleNonVisualModuleSample" does not have any view files (since it is a non-visual test application). It only has App.xaml, App.xaml.cs and TheBootstrapper.cs files. App files were created by Visual Studio 2010 when the project was created. App.xaml.cs file had to be slightly modified to run TheBootstrapper within its Application_Startup method instead of assigning the VisualRoot of the application:

To verify that the module is loaded, put a breakpoint at the Initialize() method of Module1Impl class and start the application in the debug mode. The breakpoint hit means that the module is loaded.

Exercise: try recreating the solution from scratch while changing project and class names by going through the following steps:

Follow Appendix A and Appendix B for detailed instructions on how to create Silverlight Prism Application and Module projects.Important Note: Make sure that the directory containing Prism dll files Microsoft.Practices.Prism.dll and Microsoft.Practices.Prism.MefExtensions.dll (which need to be referenced by both Prism Application and Module projects) also contains Microsoft.Practices.ServiceLocation.dll (you can copy them from PrismDll directory of the sample). Microsoft.Practices.ServiceLocation.dll is needed for Prism to work (even though it is not referenced by our projects)Another Important Note: Make sure that the references to Prism files within the Module project have their "Copy Local" property set to false as explained in Appendix B. Otherwise MEF is not going to work.

Once the projects are created, remove MainView.xaml and MainView.xaml.cs files from both of them and remove App.xaml and App.xaml.cs file from the Module project.

Add the bootstrapper class to Application project; add the required code to it and replace the body of Application_Startup method within App.xaml.cs file of the application project to run the bootstrapper.

Add the module implementation class to the Module project and add the required code to it.

Test that the module is loaded by putting a breakpoint in the Module's Initialize method and running an application within a debugger.

If the breakpoint is hit, give yourself a pat, if it is not, try to figure out what is wrong by checking each step carefully and by comparing your code with the sample code.

Visual Prism Application with Module Loading Sample

While the previous sample virtually did not have any visuals, in this example, both the Application and the Module will have them. The application view (called the Shell) figures out where to stick the module view in, based on the region names.

The source code for this sample is located under SimpleVisualModuleLoadingApp.sln solution. Once you run it you'll see the following screen:

The Shell view contains "This is the Shell, Not a Module" text while the module contains "This is Module1" text.

Let us look at the code. The projects were created in exactly the same fashion as those of the previous sample, only we did not remove MainView.xaml and MainView.xaml.cs files. Instead they and their classes were renamed to Shell and Module1View for the application and module views correspondingly.

In this particular example it does not matter but with an eye to future examples, we turn Shell into MEF composable class by adding [Export] attribute to it. It will allow MEF composing it, in case it has some MEF imports. Shell's MEF composition is achieved by overriding ConfigureAggregateCatalog method of MefBootstrapper class within TheBootstrapper class which we do by adding the following line of code:

// Prism's AggregateCatalog is a catalog of all MEF composable parts
// within the application.
// We add the parts corresponding to the current assembly to it
AggregateCatalog.Catalogs.Add(new AssemblyCatalog(this.GetType().Assembly));

This line adds the current application assembly's MEF parts to all MEF composable parts, controlled by Prism's AggregationCatalog.

Shell.xaml file contains "This is the Shell, Not a Module" TextBlock. It also contains the placeholder for a module view:

The module's view is placed over the Application's control based on the region name match.

Notice that TheRegionManager.RegisterViewWithRegion forces a view construction (via MEF or based on a delegate). This method of identifying a view with a region is called View Discovery. Another method allows inserting an already created view into a region and it is called View Injection. View Injection will be described further.

Module1View is made to be a MEF composable class by adding Export attribute to it:

Finally Module1View.xaml file has a very simple content: a "This is Module1" TextBlock.

Exercise: Create a similar sample on your own, changing the project, class and region names. Make sure it runs and displays the module view.Important Note: Make sure that the references to Prism files within the Module project have their "Copy Local" property set to false as explained in Appendix B. Otherwise MEF is not going to work. (And this is really the last time I mention it).

Optional Exercise
One can see that we used ContentControl above to host a model view within the main application (remember Shell.xaml file?) Prism also allows using other controls for this purpose: Selector, ItemsControl and TabControl. Those controls allow plugging in multiple views within the same region. These views will be arranged based on the corresponding control's functionality.

I leave it as an optional exercise to create another view within Module1, register this newly created view with "MyRegion1" within the module, while changing the ContentControl within Shell.xaml file to the following:

As a result the different module views will be arranged according to the StackPanel's layout: one on top of the other and the application will look like this:

public partialclass Shell : UserControl
{
// we need importing constructor (instead of a property)
// since we want to make sure that moduleManager is initialized
// within the constructor, so that we can add an event handler
// to its ModuleDownloadProgressChanged event.
[ImportingConstructor]
public Shell([Import]IModuleManager moduleManager)
{
InitializeComponent();
moduleManager.ModuleDownloadProgressChanged += moduleManager_ModuleDownloadProgressChanged;
}
void moduleManager_ModuleDownloadProgressChanged(object sender, ModuleDownloadProgressChangedEventArgs e)
{
// we only collect download information for Module1Impl module.
if (e.ModuleInfo.ModuleName != "Module1Impl")
return;
TheProgressBar.Value = e.ProgressPercentage;
}
}

We want to handle the ModuleManager's ModuleDownloadProgressChanged event. We also want to add the event handler within the Shell's constructor. To make sure that once we are in the constructor we have an already initialized reference to the ModuleManager, we use MEF's [ImportingConstructor] attribute and add IModuleManager type as an argument of the constructor.

The moduleManager_ModuleDownloadProgressChanged function handles the ModuleDownloadProgressChanged of the ModuleManager. Obviously, the ModuleManager can manage downloads of multiple modules within the application, so if we are interested in downloading progress of a particular module, we only need to collect data related to this module. This is why we have a check for module name:

Unfortunately since the downloading is local and the downloaded module is small, you won't be able to see a gradual change of the progress par - everything will be downloaded at once.

Exercise: build a similar application yourself.

Downloading a Module on Demand Sample

All the samples above have their modules downloaded "when available", i.e. when the module becomes available for download at the server side, which in our samples meant during the application initialization. This was achieved by setting InitializationMode of the corresponding module to InitializationMode.WhenAvailable value within CreateModuleCatalog() method of the bootstrapper:

If we change the initialization mode to InitializationMode.OnDemand the module will not be loaded at the initialization stage. In fact one would have to write code that uses ModuleManager class (introduced in the previous sample) to load the module.

The code for the sample is located under ModuleLoadingOnDemandSample.sln solution. With respect to the previous sample only Shell.xaml and Shell.xaml.cs files are changed.

Shell.xaml now has a button to trigger module download.

Shell.xaml.cs file stores the module manager object obtained within its constructor in _moduleManager class field. Once the "Download Module" button is clicked, LoadModule method of the ModuleManager is called to download the module:

To verify that the sample is working, make sure there is no module view displayed within the Shell at the start. Then click the "Download Module" button, the module view should appear in the middle of the window and the button should get disabled.

Exercise: create a similar demo.

Module Dependency Sample

Prism allows some "On Demand" modules to be loaded automatically if another module is loaded that depends on them. Module dependency can be specified the when module catalog is getting populated within the bootstrapper's CreateModuleCatalog method.

The source code for this sample is located under ModuleDependencySample.sln solution.

There are two modules to be loaded in the application (instead of the usual one): Module0 and Module1. Module1 depends on Module0, as defined in the bootstraper's CreateModuleCatalog function:

This dependency means that Module0 always loads before Module1. To verify this, Shell.xaml region control was changed to an ItemsControl whose ItemsPanel arranges the loaded views in order they are loaded:

The above method, however, always results in a new view being created - if we want to create the view ourselves and then put it into a region, we need to resort to View Injection instead.

The View Injection sample is located under ViewInjectionSample.sln solution.

By looking at Shell.xaml file, you can see that there are two regions: "MyRegion1" and "MyRegion2". "MyRegion1" region simply displays the module view (which is discovered) as before. "MyRegion2", however is used for injecting very simple views (consisting of just one TextBlock).

If we take a look at the module's Module1View.xaml file, we'll see that the module view has an "Inject View" button. Pressing this button will trigger the view injection code in Module1View.xaml.cs file:

Here is how the application is going to look after a few "Inject View" button clicks:

Exercise: Create a similar demo.

Conclusion

This is a detailed overview of Prism Module functionality in small and simple samples. I'd appreciate very much if you could vote for this article and leave a comment. I would love to hear your suggestions for improving and expanding the content of this tutorial.

More tutorials are coming focusing on Prism Navigation and Communication functionality.

History

Feb 14, 2011 - changed the source code to use the newest Prism dlls (from Prism version 52595) - the code changes were very minor - only one project (with module dependency) was affected.

Following are the steps for creating prism's main module (application) project:

Open VS 2010. Go to File menu -> New -> Project

In the opened window choose "Silverlight Application" as the project type, make sure .Net framework 4 is selected, select the name and directory for your project, as shown on the picture below:

Click OK button.

Leave all defaults, unless you want to change the name of your Silverlight hosting web project:

Click OK button.

Add references to Microsoft.Practices.Prism.dll and Microsoft.Practices.Prism.MefExtensions.dll files by right mouse click on References under the Silverlight project and choosing "Add Reference", choosing Browse tab, browsing to the directory containing Prism .dll files and selecting those files:

Then click OK button.Important Note: Make sure that the directory containing these Prism dlls also contains Microsoft.Practices.ServiceLocation.dll (you can copy them from PrismDll directory of the sample). Microsoft.Practices.ServiceLocation.dll is needed for Prism to work (even though it is not referenced by our projects).

Add reference to MEF composition dll (which is part of .NET 4) by going through the similar steps as above, only choosing .NET tab and selecting System.ComponentModel.Composition reference:

Creating a module project is very similar to creating the main module (application) project.

Important Note: The deployment unit in Silverlight is an .xap file, not a .dll library, because of that the modules should be also created as Silverlight Applications, not Silverlight Class Libraries.

Here are the steps for creating a project for a Prism module:

Right click on the solution within VS 2010 Solution Explorer and choose Add->"New Project" to initiate the module project creation.

Just as in case of the application project, choose "Silverlight Application" as the project type, also choose the project name and location

Important Note: Not setting Copy Local to False on Prism references leads to MEF errors. It took me only a day to figure out why my modules do not load within my Prism application.Another Important Note: just like in case of Prism application, make sure that the directory containing these Prism dlls also contains Microsoft.Practices.ServiceLocation.dll (you can copy them from PrismDll directory of the sample). Microsoft.Practices.ServiceLocation.dll is needed for Prism to work (even though it is not referenced by our projects).

Just like you did in case of Prism application, add System.ComponentModel.Composition .NET reference.

Remove the App.xaml and App.xaml.cs files from the Module project by right clicking on them and choosing "Delete" within the Visual Studio Solution Explorer.

Share

About the Author

I have 15 years of experience developing enterprise software, starting from C++ and Java on UNIX and moving towards C# on Windows platforms.
I am fascinated by the new .NET technologies especially WPF, Silverlight and LINQ.
Recently I decided to make a move and start my own contracting consulting and mentoring company AWebPros.
I can be contacted via my web site awebpros.com or through my blog at nickssoftwareblog.com

Hey Nick,
Thanks for your instant reply.
Any Sample from Part1 and Part2 is not running.
It's gets build successfully bt, when I try to run it throws error message as "Unhandled massage code: 4004, Category: ManagedRunTimeError".

Hey Kiran,
the error is very generic, and it is very difficult for me to figure out what went wrong without actually being able to see it. I suggest that you look for statements mark as "Important Note" within the article and make sure you did everything they say
In particular
1. Did you set "Copy Local" to false of prism references within all the non-Main modules?
2. Did you copy Microsoft.Practices.ServiceLocation.dll to the right directory?
3. Did you unblock all the dlls that came with the project?