Daniel Plaisted's Blog

How To Control Who Can Write Extensions For Your MEF Application

dsplaisted — Mon, 01 Nov 2010 23:28:00 GMT

With the MEF DirectoryCatalog, it is easy to load extensions from a given directory for a MEF Application. The DirectoryCatalog will scan any assemblies in that directory and find MEF extensions in those assemblies. This means that adding an extension to a MEF application can be as easy as dropping a DLL in an extensions folder.

However, some people would like to have control over what extensions are allowed in their MEF application. For example, in a commercial application you may want to offer additional optional add-ons for sale, but not allow third party extensibility. In these situations, our recommendation is generally to use strong name signing with your assemblies, and only allow assemblies with the correct public key to be added to the catalog. Doing so is not too complicated, but we haven’t actually provided code showing how to do so… until now.

Below is the code for a MEF catalog which loads extensions from a directory, but ignores any assemblies where the public key doesn’t match one of the keys passed to the constructor. You can also download the project, which also includes some simple tests.

using System;
using System.Collections.Generic;
using System.Linq;
using System.ComponentModel.Composition.Primitives;
using System.IO;
using System.Reflection;

namespace System.ComponentModel.Composition.Hosting
{
    public class StrongNameCatalog : ComposablePartCatalog
    {
        AggregateCatalog _aggregateCatalog = new AggregateCatalog();

        public StrongNameCatalog(string path, params byte[][] trustedKeys)
        {
            foreach (var file in Directory.GetFiles(path))
            {
                AssemblyName assemblyName = null;
                try
                {
                    assemblyName = AssemblyName.GetAssemblyName(file);
                }
                catch (ArgumentException)
                {
                    //  According to MSDN, ArgumentException can be thrown
                    //  if the assembly file is invalid
                }
                catch (BadImageFormatException)
                {
                    //  Not a valid assembly
                }

                if (assemblyName != null)
                {
                    var publicKey = assemblyName.GetPublicKey();
                    if (publicKey != null)
                    {
                        bool trusted = false;
                        foreach (var trustedKey in trustedKeys)
                        {
                            if (assemblyName.GetPublicKey().SequenceEqual(trustedKey))
                            {
                                trusted = true;
                                break;
                            }
                        }

                        if (trusted)
                        {
                            _aggregateCatalog.Catalogs.Add(new AssemblyCatalog(file));
                        }
                    }
                }
            }
        }

        public override IQueryable<ComposablePartDefinition> Parts
        {
            get
            {
                return _aggregateCatalog.Parts;
            }
        }

        public override IEnumerable<Tuple<ComposablePartDefinition, ExportDefinition>>
            GetExports(ImportDefinition definition)
        {
            return _aggregateCatalog.GetExports(definition);
        }
    }
}

A note about “Security”

When people talk about this functionality, they often describe it as a “secure” catalog. I don’t think it’s a good idea to call this a secure catalog, because in most cases it doesn’t increase security. If you are worried about malicious code being loaded from your extension directory, a machine is probably already compromised if an attacker can put an arbitrary file there. And if you want to prevent people from writing their own extensions to your application, the strong name catalog will help deter them, but if they are determined they can modify your application to remove the strong name check.

How to Debug and Diagnose MEF Failures

dsplaisted — Tue, 13 Jul 2010 21:10:00 GMT

The Managed Extensibility Framework (MEF) helps make it easy to write extensible applications. We hope that it is simple to understand the basics and get started. However, MEF brings with it the possibility of new types of failures. Without the proper knowledge, these failures can be difficult to diagnose. This blog post will cover some background information you need to understand when dealing with MEF failures, the common types of MEF failures, and how you can diagnose these issues.

Import Cardinality

MEF imports have one of three cardinalities. A collection import has a cardinality of ZeroOrMore. MEF will supply all of the exports that match the import, whether there are zero, one, ten, or ten thousand. The ImportManyAttribute is used to declare a collection import.

[ImportMany] 
public IEnumerable<IPlugin> Plugins { get; set; }

An import with a cardinality of ExactlyOne only expects one export to satisfy it, and can be called a required import. This can be declared with the ImportAttribute.

[Import] 
public IPlugin Plugin { get; set; }

Finally, you can declare an optional import by setting the AllowDefault property of the ImportAttribute to true. The cardinality of this import is ZeroOrOne.

[Import(AllowDefault=true)] 
public IPlugin Plugin { get; set; }

Rejection

A part with an import with a cardinality of ZeroOrMore or ZeroOrOne does not have any specific requirements as to the number of exports that match the import. The part should work when there are none available, when there is one, and when there are many. On the other hand, an import with a cardinality of ExactlyOne is a declaration of a requirement that the part needs in order to function correctly. If the import cannot be satisfied, MEF assumes the part cannot function correctly and will reject the part, which means it will not be available at all in the container.

A rejection can also be caused when there is more than one matching export. MEF has no way to choose between multiple exports that match an import of cardinality ZeroOrOne or ExactlyOne. So in this case, MEF will not use any of the matching exports. The part will be rejected if the import cardinality was ExactlyOne, and the import will be set to null if the cardinality was ZeroOrOne. If this behavior is not what you want, see these blog posts on Picking an Export and Using Defaults with MEF.

Rejection makes it simpler to write parts, because they can simply assume that their imports with a cardinality of ExactlyOne will be available instead of writing code to handle the case where they aren’t. However, rejection effectively makes parts disappear from the container, so it can be hard to figure out what is wrong if you don’t know to expect it. Furthermore, a problem with one part can cause a chain of rejections. Imagine you have part A which depends (via a required import) on part B, which depends on part C. If part C has an import which can’t be satisfied, then it will be rejected, which will in turn cause part B and part A to be rejected. The symptom of the problem will be that part A doesn’t show up in the container, but the root cause of the problem is with part C. Without understanding rejection, you might look for a problem with part A, see that everything appears to be correct, and be unable to figure out why it isn’t showing up.

Failures Where an Export is not Available

A common type of MEF failure is when an export is not available. The symptoms of this failure can either be that the export is missing from a collection import you expected it to be present in, or that the container throws an exception when you attempt to access it. In the first case, since the export was not required, this is not a composition error as far as MEF is concerned, and your application will often continue to run, albeit without the functionality that the missing export provided. In the second case, MEF is unable to satisfy a request you have made of it. For example, if you call container.GetExport<IFoo>() and there is no IFoo export available, the container will throw a CardinalityMismatchException. Likewise, an exception will be thrown if you call CompositionInitializer.SatisfyImports(), passing in a part that has an import that cannot be satisfied.

There are several possible causes for an export not being available.

There is no export

The export may simply not exist. This can happen if you forget to add an ExportAttribute to your class.

The part providing the export is not in the catalog

If a part is not in the catalog, then its exports will not be available. This can happen if the corresponding assembly was not placed in the correct folder, if it was out of date, or if there was an error loading the assembly (for example, if it references an assembly that is not available). The application may not be set up to include the assembly providing the export in the catalog. It is also possible that the type has a PartNotDiscoverableAttribute on it, preventing it from showing up in the catalog, or that the type is abstract, or that the export is on a base/ancestor type and not the actual type which is in the catalog.

The export does not match the import

The export may be in the catalog and available in the container, but if it doesn’t match an import, then it won’t be used to satisfy that import. An easy way for this to happen is to put an export attribute on a class without specifying the contract. Consider the following two exports

[Export]
public class Plugin1 : IPlugin { }

[Export(typeof(IPlugin))]
public class Plugin2 : IPlugin { }

The contract for the first export is the Plugin1 class, not the IPlugin interface, and so it wouldn’t match an import of IPlugin. The second export specifies that the IPlugin interface is the contract for the export, and would match an IPlugin import.

Here is a list of issues that can prevent an export from matching an import:

Contract name doesn’t match
Export type identity doesn’t match
Metadata doesn’t match
- Metadata key is not present
- Metadata value is not of correct type
Creation policy doesn’t match

Under the hood, a MEF import uses a constraint which takes an ExportDefinition and returns a boolean value indicating whether the export matches the import. This constraint is represented as an expression, and you may see these constraints when debugging MEF or using tools to analyze MEF parts. A typical import constraint looks like this:

exportDefinition => ((exportDefinition.ContractName == "MEFSample.IPlugin")
    AndAlso (exportDefinition.Metadata.ContainsKey("ExportTypeIdentity")
    AndAlso "MEFSample.IPlugin".Equals(exportDefinition.Metadata.get_Item("ExportTypeIdentity"))))

The constraint requires both the contract name and the exported type (which is stored under the metadata key “ExportTypeIdentity”) to match. In many cases, you won’t specify a contract name, and the contract name and the export type identity will be the same. However, if you do specify the contract name, you can still have a type identity mismatch. The following code is an example of this—the export type identity is the Plugin class, but it would need to be the IPlugin interface to match the import.

[Export("SpecialPlugin")]
public class Plugin : IPlugin { }

public class Importer
{
    [Import("SpecialPlugin")]
    public IPlugin SpecialPlugin { get; set; }
}

Using an interface to access MEF metadata values adds additional requirements to the constraint. For each property in the metadata view interface, an export must have a metadata item with a name matching the name of the property, and the value needs to be of the type of the property. To make a piece of metadata optional, you can put a DefaultValueAttribute on the property in the interface. If the following metadata interface is used on an import, then only exports which have metadata with the name “Name” with a value of type string will match the import, but the exports won’t need to have a piece of metadata with the name “Priority”.

public interface IPluginMetadata
{
    string Name { get; }
    [DefaultValue(0)]
    int Priority { get; }
}

Finally, an importer can specify a required creation policy (using the RequiredCreationPolicy properties of the Import and ImportMany attributes). Also, using an ExportFactory (currently only available in the Silverlight version of MEF) will set the required creation policy to NonShared. If the export comes from a part with an incompatible creation policy, it won’t match.

The part providing the export is rejected

If a part is rejected, its exports will not be available. As covered in the rejection section, a part will be rejected if there are no exports available to satisfy any of its required imports, or because there are more than one that could satisfy it. If there aren’t any exports available, this can be for any of the reasons for an export not to be available—there may be no export, the part providing the export might not be in the catalog, the export you think should satisfy the import might not actually match, and the part providing the export could be rejected. There may be a chain of rejections, and at the end of it will be the root cause of the problem which needs to be fixed in order to make the original export available (as well as all of the intermediate ones in the chain).

Recomposition Failures

Another type of failure in MEF is a recomposition failure. MEF supports recomposition, which means that you can change the parts that are available in the container while the application is running, and the container will update the composition graph. This lets you add new extensions at runtime which is especially useful in Silverlight applications for keeping the initial download small and downloading additional functionality after the application starts. However, imports have to opt in to recomposition to allow MEF to add or remove exports after the part has been initialized. If they don’t, or if the recomposition would violate other MEF guarantees (such as import cardinality), MEF will cancel the change by throwing a ChangeRejectedException.

The operations which cause recomposition (and hence can throw a ChangeRejectedException) are:

Modifying an AggregateCatalog by adding or removing a catalog in the Catalogs collection
Calling the DirectoryCatalog.Refresh method
Calling the container’s Compose method, or the ComposeParts or ComposeExportedValue extension methods
Downloading a XAP with a DeploymentCatalog

Recomposition with a DeploymentCatalog is different than the other methods of recomposition in that the ChangeRejectedException won’t be thrown from a method you call. The DeploymentCatalog starts downloading the XAP asynchronously when you call the DownloadAsync method, and when the download completes it triggers recomposition and reports the result by raising the DownloadCompleted event. If the change is rejected, then the Error property of the event args will be set to the ChangeRejectedException.

Assembly Load Issues

In .NET, there are different contexts into which an assembly can be loaded. The default load context is generally the best one to use, but it cannot load assemblies that are not in the application base directory, subdirectories of the application base which are included in the probing path, or the GAC. When using a DirectoryCatalog or passing a path to the AssemblyCatalog constructor, MEF will attempt to load assemblies in the default load context. However, if the assemblies are not in the probing path or the GAC, this will not be possible, and MEF will load them in the load-from context instead.

The load-from context can lead to type identity issues that result in an InvalidCastException, MissingMethodException, or other errors. In order to avoid these issues in a MEF application, you can put any extension directories under the application base directory, and add them to the probing private path in your application configuration file. For other options and more information about assembly loading in .NET, see the Best Practices for Assembly Loading MSDN document.

Methods and Tools for Investigating MEF Failures

Inspecting the catalog in the debugger

A simple way of debugging a MEF application is to inspect the catalog in the Visual Studio debugger while the application is running. You can look at the Parts property to see what parts are in the catalog. This will help you verify that MEF is actually finding the parts you expect it to. You can also drill down and examine the ImportDefinitions and ExportDefinitions properties of each part to see its imports and exports.

Rejection trace messages

MEF uses standard .NET tracing to report parts which are rejected. When a part is rejected, it will trace a message which includes the name of the rejected part, the reason for the rejection, and the import which caused the rejection. An example of a rejection trace message is shown below, with the most important parts in bold.

System.ComponentModel.Composition Warning: 1 : The ComposablePartDefinition 'MEFConsole.PrintCommand' has been rejected. The composition remains unchanged. The changes were rejected because of the following error(s): The composition produced a single composition error. The root cause is provided below. Review the CompositionException.Errors property for more detailed information.

1) No valid exports were found that match the constraint '((exportDefinition.ContractName == "MEFConsole.IPrinterService") AndAlso (exportDefinition.Metadata.ContainsKey("ExportTypeIdentity") AndAlso "MEFConsole.IPrinterService".Equals(exportDefinition.Metadata.get_Item("ExportTypeIdentity"))))', invalid exports may have been rejected.

Resulting in: Cannot set import 'MEFConsole.PrintCommand.PrintService (ContractName="MEFConsole.IPrinterService")' on part 'MEFConsole.PrintCommand'.
Element: MEFConsole.PrintCommand.PrintService (ContractName="MEFConsole.IPrinterService") --> MEFConsole.PrintCommand --> AssemblyCatalog (Assembly="MEFConsole, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null")

When debugging an application in Visual Studio, these trace messages will be shown in the output window. You can enable MEF tracing in an application that is not being debugged by adding a trace listener to the System.ComponentModel.Composition source in your application configuration file. Below is an example of how to log MEF trace information to a log file.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <system.diagnostics>
        <sources>
            <source name="System.ComponentModel.Composition"
                    switchValue="All">
                <listeners>
                    <add name="fileListener"
                         type="System.Diagnostics.TextWriterTraceListener"
                         initializeData="composition.log" />
                </listeners>
            </source>
        </sources>
        <trace autoflush="true" indentsize="4" />
    </system.diagnostics>
</configuration>

MEF doesn’t examine parts to determine if they are rejected until it needs to in order to fulfill a request to the container. This means that the rejection won’t be traced until the point in the program’s execution where an export of the part would be supplied. Also, due to the details of how MEF implements composition, there are a lot of cases where the container doesn’t definitively determine whether a part is rejected, and so it doesn’t send a trace message. In practice, this means that when there is a chain of rejections, only the part at the end of the chain (the opposite end from the root cause) will be traced as rejected, and no rejections at all will be traced when calling the container’s Compose method or the ComposeParts extension method. These limitations mean that tracing can be helpful in detecting that you have a rejection, but will often not give you all the information you need to determine the problem.

Composition Diagnostics with Mefx

The Managed Extensibility Framework Explorer (Mefx) is a command line tool that you can use to diagnose a wide variety of MEF issues. It can display information about MEF parts, determine which parts will be rejected, analyze the root cause for a rejection, and diagnose mismatches between exports and imports.

When using Mefx, you specify what assemblies should be examined for MEF parts with the /file and /dir parameters. Then you use one of the possible action parameters to specify what should be displayed. The /parts parameter lists all of the parts found. The /rejected parameter lists the parts which will be rejected. The /causes command helps find root causes—it lists “primary rejections,” parts that are rejected due to errors not related to the rejection of other parts. Here are some samples of using Mefx, with the output shown in italics:

> mefx /file:MefConsole.exe /parts
MEFConsole.GreetCommand
MEFConsole.PrintCommand
MEFConsole.PrintService
MEFConsole.Program

> mefx /file:MefConsole.exe /rejected
MEFConsole.PrintCommand
MEFConsole.PrintService

> mefx /file:MefConsole.exe /causes
MEFConsole.PrintService

In these samples, the PrintCommand and the PrintService were both rejected, but the PrintService was the root cause of the problem. The /verbose parameter can be used to display detailed information about parts, including a list of their exports and imports. Along with each import the /verbose parameter will show any exports that satisfy the import, any errors with the import, and any “unsuitable” exports—exports that have the same contract name as the import, but don’t match it for some other reason. Using the /verbose parameter to the /causes command will give the following output, which indicates that the reason PrintService was rejected was because it had an import for IPrintSpooler, for which there was no export available:

[Part] MEFConsole.PrintService from: AssemblyCatalog (Assembly="MEFConsole, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null")
[Primary Rejection]
[Export] MEFConsole.PrintService (ContractName="MEFConsole.IPrinterService")
[Import] MEFConsole.PrintService.Spooler (ContractName="MEFConsole.IPrintSpooler")
[Exception] System.ComponentModel.Composition.ImportCardinalityMismatchException: No valid exports were found that match the constraint '((exportDefinition.ContractName == "MEFConsole.IPrintSpooler") AndAlso (exportDefinition.Metadata.ContainsKey("ExportTypeIdentity") AndAlso "MEFConsole.IPrintSpooler".Equals(exportDefinition.Metadata.get_Item("ExportTypeIdentity"))))', invalid exports may have been rejected.

You can also display information about a single part with the /type parameter. To figure out why an export isn’t being supplied to an import, use the /type parameter with the type name for the part that has the import, together with the /verbose parameter. In the below example, this shows that there are two exports with the same contract name as the Commands import, but that the second of them is missing the required metadata for the Name.

> mefx /file:MEFConsole.exe /type:MEFConsole.Program /verbose
[Part] MEFConsole.Program from: AssemblyCatalog (Assembly="MEFConsole, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null")
[Export] MEFConsole.Program (ContractName="MEFConsole.Program")
[Import] MEFConsole.Program.Commands (ContractName="MEFConsole.ICommand")
    [SatisfiedBy] MEFConsole.PrintCommand (ContractName="MEFConsole.ICommand") from: MEFConsole.PrintCommand from: AssemblyCatalog (Assembly="MEFConsole, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null")
    [Unsuitable] MEFConsole.GreetCommand (ContractName="MEFConsole.ICommand") from: MEFConsole.GreetCommand from: AssemblyCatalog (Assembly="MEFConsole, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null")
      [Because] RequiredMetadata, The import requires metadata '[Name, System.String]' but this is not provided by the export.

Running Mefx without any arguments will display the full list of possible parameters. More details about Mefx can be found in this MSDN document.

Visual Mefx

Mefx is a command-line tool which runs on the full desktop .NET framework, and cannot analyze Silverlight applications. Visual Mefx is a GUI-based version of Mefx, which runs under both Silverlight and desktop .NET. It shows a list of parts in the left pane, and the details of the selected part in the right pane. The parts are color-coded according to their rejection status: non-rejected parts use green, primary rejections use red, and non-primary rejections use yellow. Below is a screenshot of Visual Mefx analyzing the same PrintCommand/PrintService rejection issue that we saw earlier.

Mefx Limitations

Mefx analyzes the parts from the files you specify. If your application adds any parts or exports to the container, Mefx won’t know about them and the analysis it performs won’t match what happens in your application. Other customizations to the container, such as using custom export providers or a hierarchy of scoped containers, will also prevent Mefx from accurately analyzing composition issues.

However, you can integrate Mefx’s composition diagnostics functionality into your application to avoid these limitations. Mefx and Visual Mefx both are built on top of a composition diagnostics library. You can reference this library in your application, and use the functionality it provides to perform analysis on the container that your application uses, with any extra parts or customizations that you have made to it.

Mefx Credits and Download

Mefx and the composition diagnostics library was originally written by Nicholas Blumhardt when he was on the MEF team and included in the MEF codeplex releases. Joe McBride ported it to Silverlight and WPF as Visual MEFX. I took his version and made some further improvements. I plan to add Mefx to the community open source MefContrib project, but for now you can download Mefx and Visual Mefx here.

Presentation at TechEd North America 2010

dsplaisted — Thu, 27 May 2010 00:22:49 GMT

TechEd North America 2010 is in a few weeks, and I will be giving a presentation on MEF. Below is the session description:

DEV05-INT | What's Wrong with My .NET Extensible MEF Application?
Thursday, June 10 | 8:00 AM – 9:15 AM | Rm 347

The Managed Extensibility Framework (MEF) is a powerful new technology that will allow users to create extensible applications (applications which can enable third parties to easily modify their behavior). In this session, we discuss what can cause your MEF application to fail, how to go about identifying the source of a failure, and how to subsequently fix it. We discuss the design considerations that impacted why MEF is susceptible to these failures, and how you can keep your code resilient to them.

As you can see, this isn’t another “Introduction to MEF” presentation. There isn’t very much information available on how to diagnose problems that can occur when using MEF. Trying to do so without the right knowledge can be frustrating. So if you are going to be at Tech Ed, I highly recommend coming to this session even if you already know the basics of MEF.

There is also another session on MEF earlier in the week which looks like it will be more of an introduction/overview. The code for that session is DEV304.

Overriding MEF Metadata

dsplaisted — Thu, 01 Apr 2010 04:49:00 GMT

The Managed Extensibility Framework (MEF) is designed to allow open-ended extensibility. It is easy to define a contract and load extensions which satisfy the contract. This is accomplished with a collection import, which can look like this:

[ImportMany]
public IPlugin[] Plugins { get; set; }

Extensions may need to be ordered or prioritized

Often, the importer will need a way to sort or prioritize the imported extensions. If the extensions are displayed in a menu, the importer may want to control what order they appear in. Or there may be multiple extensions which can be used, and the importer needs to choose the “best” one which can handle a given item. For example, if extensions are used to provide UI controls for editing fields, there may be a generic editor which can edit all field types but only uses a simple textbox, and a specialized editor which only works on enums but provides a dropdown box for editing. Both of these extensions could be used to edit an enum, but it is better to use the more specialized one.

Defining MEF metadata on an export

One way to represent the priority of an extension is with MEF metadata. The exporter can add metadata using the ExportMetadataAttribute like this:

[Export(typeof(IPlugin))]
[ExportMetadata("Name", "PluginA")]
[ExportMetadata("Priority", 1)]
public class PluginA : IPlugin { /* ... */ }

A custom export attribute can make this less verbose and add more compile-time checking. With a custom export attribute, the export would look like this:

[ExportPlugin("PluginA", Priority=1)]
public class PluginA : IPlugin

For details on how to create a custom export attribute, see the “Using a Custom Export Attribute” section of this page.

Using MEF metadata on the import side

To get access to MEF metadata, an importer can use an interface with properties corresponding to the metadata keys it wishes to access. To access metadata for the name and priority, the following interface could be used:

public interface IPluginMetadata
{
    string Name { get; }
    [DefaultValue(0)]
    int Priority { get; }
}

To use the interface, an importer can import into a collection of Lazy<T, TMetadata>, like this:

[ImportMany]
public Lazy<IPlugin, IPluginMetadata>[] Plugins { get; set; }

Then plugins could be ordered by priority (highest to lowest) with the following LINQ expression:

Plugins.OrderByDescending(lazy => lazy.Metadata.Priority);

Overriding metadata

Using MEF metadata for the priority puts the responsibility of defining the priority on the extension author. An advantage of this is that when extensions are added to the system, they can “just work” without having to configure the priority. On the other hand, the metadata can’t be modified without recompiling an extension. Extensions from different sources will likely have been developed without any knowledge of each other, so the priority they provide may not be what is desired when they are used together.

So it would be useful to be able to override the metadata that is supplied with an extension. I’ve prototyped a catalog that allows you to do this. You create it as a wrapper around another MEF catalog, and then you tell it what metadata should be overridden before creating your container. The following code creates a catalog and then sets the priority of exports from the PluginA class to 5:

var catalog = new AttributedOverrideCatalog(new TypeCatalog(typeof(PluginA)));
catalog.SetMetadata("Priority", 5, typeof(PluginA));

How it works

The MetadataOverrideCatalog takes the part definitions from the wrapped catalog, and creates wrapper part definitions which return the overridden metadata but delegate all other functionality to the wrapped part definition. For an overview of what part definitions are, see my post on the MEF Primitives.

The MetadataOverrideCatalog is an abstract class with one abstract method: GetExportMetadata, which takes a part and an export as parameters and returns the metadata that should be used for the export (or null if the default metadata should be used). This lets derived catalogs define the specifics of how metadata should be overridden. The AttributedOverrideCatalog provides an implementation which lets you override metadata by passing in the type that the export is defined on.

This is just a sample—in general the hosting code won’t have a reference to the extension type, so you might want to write a catalog which determines what metadata to override based on a configuration file.

Download the source code here.

Podcast with Me on Testing on the MEF Team and at Microsoft

dsplaisted — Wed, 17 Feb 2010 01:52:17 GMT

This week I was on the Herding Code podcast, discussing how we do testing on the MEF team and at Microsoft. You can listen to it here.

This was the first podcast I’ve been on and I enjoyed it quite a bit. Some lessons learned:

When recording a podcast over Skype, make sure you have a good internet connection. I was using a wireless internet service, and my audio quality is really poor. I apologize for this and hope that most of what I say is still understandable.
For a fun game, count the number of times I say “Ummm” and “Uh…” in the podcast!
If, during an interview, you stop and make an aside that you expect to be edited out (such as “Man, you sure are going to have to edit out a lot of Ummms”), that part may not actually get edited out. :-)

Many thanks to Jon Galloway and the rest of the Herding Code crew for having me on their podcast.

Import Cardinality, and Picking Which Export to Use

dsplaisted — Tue, 11 Aug 2009 00:16:03 GMT

In the Managed Extensibility Framework (MEF), an import has a cardinality, which expresses how many exports can be used to satisfy the import. The possible values are ZeroOrOne, ExactlyOne, or ZeroOrMore, and they can be declared in the following ways:

[Import(AllowDefault = true)]
IService ZeroOrOneImport { get; set; }

[Import]
IService ExactlyOneImport { get; set; }

//	Note that the property here is an array.
//	It could also be IEnumerable<IService> or a concrete type that implements ICollection<IService>.
[ImportMany]
IService[] ZeroOrMoreImport { get; set; }

If the cardinality of the import is ExactlyOne, then there must be exactly one matching export available. If there are zero, or if there are two or more, then the import will not be satisfied, and the part will either be rejected or the composition will fail.

A common question we get about MEF is how to modify this behavior, either by specifying a default export to use, or by specifying some logic that will pick the best one according to some criteria. This question recently came up internally at Microsoft, and our architect Blake Stone gave a good explanation and overview of the options. The rest of this post is based on what he said.

In general, we strongly encourage consumer-side policy on picking one of many for what we believe is a good reason. We're trying to encourage not just individual stand-alone extensible systems, but the development of reusable subsystems. If two different teams develop something useful independently then we'd like to be able to drop both of them into a single product and have them work. Designing with a system-wide policy in mind prevents this from working. A natural workaround is to try to isolate the two subsystems from one another using different containers, but this also leads to problems down the road as subsystems tend to overlap in time - and it becomes awkward for one part to participate in more than one subsystem.

So the recommended approaches look like this:

a) Make the importer aware of the selection policy. Change the import to an ImportMany (and the corresponding property to a collection), and have the importer choose which export to use from the list. You can avoid duplicating the code to select the service to use in each importer by writing a custom collection class (which implements ICollection<T>), with an accessor for getting the desired T. Then you can use [ImportMany(typeof(IService))] PolicyBased<IService> (where PolicyBased<T> is the custom collection you wrote) and let the reusable prioritization mechanism do the work for you. Many different schemes along these lines can co-exist.

b) Use two different contracts. In this instance the importer can go ahead and write [Import] IService and pretend things are simple. An exporter, on the other hand would need to [Export("my.namespace.PrioritizedService")] and another part would import all of the prioritized services, pick one, and export it under the IService type-derived contract.

It's worth keeping in mind that in both cases the selection mechanism is required to produce something meaningful, so you'd have to come up with a default IService implementation.

c) If you really must make all of this transparent per your original request, yes that can also be achieved. Just keep in mind that you're opting out of widespread reuse of the functionality you write that depends on it. What you need to do is define your own custom topology of ExportProviders for a container. Implementing a full-fledged ExportProvider can be tricky, but implementing one as a filter over other full-fledged implementations is relatively straightforward. Our own AggregateExportProvider uses a prioritization scheme of its own along these lines (exporters found earlier in its list are preferred over ones found later for the purpose of satisfying imports of exactly one implementation.) For more information on how to do this, see Glenn Block’s blog post on customizing container behavior with defaults.

A Crash Course on the MEF Primitives

dsplaisted — Mon, 08 Jun 2009 22:01:16 GMT

With the Managed Extensibility Framework (MEF), you can use Import and Export attributes to declare what a class consumes and what it offers. For example, below is an example of two different shapes and a toolbox that imports all available shapes.

[Export(typeof(Shape))]
public class Square : Shape
{
    //    Implementation
}

[Export(typeof(Shape))]
public class Circle : Shape
{
    //    Implementation
}

[Export]
public class Toolbox
{
    [ImportMany]
    public Shape[] Shapes { get; set; }

    //    Additional implementation...
}

Generally, to use these components, you will create a catalog which includes them, create a container hooked up to the catalog, and then request a root object from the container, like this:

var catalog = new AssemblyCatalog(typeof(Square).Assembly);
var container = new CompositionContainer(catalog);

Toolbox toolbox = container.GetExportedObject<Toolbox>();

When you request an item from the container, it finds it in the catalog, looks for any imports it has (and the imports of its imports, and so on), creates the objects and wires up the graph as specified by the imports and exports, and returns the object you requested.

The MEF Primitives

Based on the above summary, it may seem like a MEF catalog is simply a collection of types that the container can use. However, catalogs actually provide the available components to the container through an abstraction layer which we call the primitives. The primitives provide APIs for describing, creating, and using components.

An implementation of the primitives specifies how components are defined, and is called a programming model. Different catalogs can provide components that are defined using different programming models. The default programming model for MEF is the attributed programming model which uses the Import and Export attributes. The TypeCatalog, AssemblyCatalog, and DirectoryCatalog that ship with MEF use this programming model.

The ability to use a different programming model provides a lot of flexibility. Instead of using the Import and Export attributes, you could have your imports and exports defined based on a convention or an external configuration file. You could also write a catalog where the components are defined using a dynamic language such as IronPython or IronRuby. And you can use an AggregateCatalog to combine all of these catalogs and use them all together in the same container.

MEF Primitives Definitions

ComposablePartDefinition and ComposablePart are the MEF primitives classes which represent a component. The relationship between a definition and a part is similar to the relationship between a type and an instance. A part represents an instance of a component. A part can be created from a part definition using the CreatePart() method. In contrast to CLR types, however, a ComposablePart does not need to have a corresponding ComposablePartDefinition.

The exports and imports of a part or part definition are represented by ExportDefinitions and ImportDefinitions:

public abstract IEnumerable<ExportDefinition> ExportDefinitions { get; }
public abstract IEnumerable<ImportDefinition> ImportDefinitions { get; }

An export definition has a ContractName property which specifies the contract which is being exported, and a Metadata property (which is a dictionary of string to object) which can store additional information about the export.

An import definition specifies what exports can be used to satisfy the import. It does this using a constraint, which is an expression that can be evaluated on an export definition to determine if a given export can satisfy the import.

public virtual Expression<Func<ExportDefinition, bool>> Constraint { get; }

Nicholas Blumhardt has written a blog post about the import being represented as a constraint which covers this in more depth. The import definition also has properties which specify whether the import supports recomposition and its cardinality. The cardinality specifies how many exports can be used to satisfy the import, and can be ZeroOrMore (for collection imports), ExactlyOne (for required single-valued imports), or ZeroOrOne (for optional single-valued imports).

ComposablePart

In addition to the export and import definitions, a composable part provides functionality for setting the part’s imports and getting its exports.

public abstract void SetImport(ImportDefinition definition, IEnumerable<Export> exports);
public virtual void OnComposed();
public abstract object GetExportedValue(ExportDefinition definition);

SetImport is used to set the imports for a part. The first argument is the import definition of the import to set, and the second argument is a list of exports to satisfy the import. The Export class used here contains the same contract name and metadata information that an export definition would have, but it also has a GetExportedValue() method to return the actual value of the export.

OnComposed will be called after all of the imports have been satisfied. After that, GetExportedValue may be called to get the exported value for an export (specified by the ExportDefinition). If any imports are recomposable, SetImport and then OnComposed will be called again if the available imports change.

Custom Catalogs and Custom ExportProviders

To create a custom programming model, create your own part definition and part classes which derive from ComposablePartDefinition and ComposablePart. You may also need to create your own implementations of ImportDefinition and ExportDefinition. Then create a catalog class which derives from ComposablePartCatalog, and override the Parts property to return a collection of your custom part definitions.

Writing a programming model from scratch can be quite complex. If you want a programming model similar to the default MEF model, but where the imports and exports are defined in different ways (such as through convention or configuration), you may be able to use the methods in the static ReflectionModelServices and AttributedModelServices classes to simplify this.

If you simply want to provide exports to the MEF container, but the exports don’t correspond to parts that have any imports that need to be satisfied by MEF, you can simply implement a custom ExportProvider. This might be useful if you want services from an existing service locater to be available to MEF parts, or if you want to supply configuration values stored in a file.

Further Information

For more information on MEF and the primitives, see the MEF CodePlex site. In particular you may want to read the Architecture Overview and the Hosting the .NET Composition Primitives whitepaper. And of course feel free to ask questions on the MEF Forums.

MEFGrid: A Sample MEF Application

dsplaisted — Thu, 15 Jan 2009 00:48:00 GMT

MEFGrid is a sample MEF application that I presented at Seattle Code Camp and at an Olympia .NET user group meeting. It includes connect 4 and the game of life, but other grid based games could be written and dropped into the extensions directory.

The application demonstrates some of the more advanced features of MEF. The available life patterns, for example, are stored as text files in the LifePatterns directory. A custom catalog makes these available as string-based exports via a custom programming model, and the life game uses a contract adapter to convert the string-based exports to command exports that set the current life pattern.

If I can find the time I will write a series of blog posts explaining how the application works in more detail. For now, feel free to post questions in the comments or on the MEF discussion forums.

Download the MEFGrid sample.

Session on MEF at Seattle Code Camp this Sunday

dsplaisted — Fri, 14 Nov 2008 00:56:59 GMT

I am giving a session on the Managed Extensibility Framework (MEF) this Sunday at Seattle Code Camp. I will be demoing how to build an extensible application using MEF. It will be fun (I hope), heavily code-focused, and will cover most of the core features of MEF.

MEF was featured in the PDC keynote, and for a quick introduction to MEF, you can watch that part of the keynote here.