Discovery by context

You can gain finer-grained control over the discovery process by using type and metadata filters with a composition context.

The CompositionContext

You may have noticed a CompositionContext argument can be passed into the EntityManager constructor, and the probe messages in your log all mention it too:

Just what is this, and why does it keep showing up everywhere? In the discovery topic we discussed how DevForce uses MEF to discover the extensible components of your application, but what we didn't mention is that this discovery is contextual. The default context is just that, a default, and always used when you haven't specified a context. The CompositionContext.Default  provides no special type or metadata filtering.

When and why to use a CompositionContext?

The CompositionContext is used in DevForce's built-in support for faking, but it's also useful for creating mocks during testing, and in any situation in which you might want several different custom implementations of an interface or base class. For example, you might have a requirement that in most cases you'll use an EntityServerQueryInterceptor in a certain way, but in particular situations you'd like different interceptor logic.  With a custom CompositionContext you can easily define that "particular situation", and define a custom EntityServerQueryInterceptor to be used only for it.  

Most, but not all, of the DevForce extensible components support a custom context.  Those that do not are ones needed during application initialization and not as part of EntityManager activities. For example, custom loggers and components controlling service or proxy configuration cannot be discovered or composed contextually.

You can define and use any number of CompositionContexts within your application.  As we'll see below it's generally the EntityManager, via its constructor, which determines the context in use.

Creating a custom CompositionContext

You can implement the ICompositionContextResolver  interface or extend the BaseCompositionContextResolver  to define and resolve your custom CompositionContexts.   The BaseCompositionContextResolver will automatically register any statically defined composition contexts found within the sub-class, but you can also override its GetCompositionContext method to programmatically define new contexts.

Here's a sample resolver defining two custom contexts, "MockQuery" and "Admin":

We also see above that these custom contexts are defined from existing built-in contexts.  Once created a CompositionContext is immutable, but you can easily create new contexts based on an existing context and supply different composition criteria.  Above we see a new context based on the Fake context but using its own custom EntityServerQueryInterceptor, and another context based on the Default context but using custom query and save interceptors.  The sample above is also defining the extensible types specific to the context (although we didn't show the code for them).  

In defining a custom composition context you must both register the context and define the extensible components it will use.  There are two mechanisms used to accomplish this: one allows you to specify the types to be used when you create the context, while the other allows you to define metadata filters to be applied during discovery.  

Discovery with types specified

This approach is the one you'll see most often in discovery examples, and was also used in the sample above.  Here you specify the generators or the types to be used by the custom context.  Remember to do two things:  

1. Use the WithGenerator method to register types to the context.
2. Mark these types with the System.ComponentModel.Composition.PartNotDiscoverable attribute.  This is required to hide the types from standard MEF discovery, since here DevForce is preempting that discovery.

Here's a sample resolver defining the composition contexts.  Instead of defining static fields we're overriding the GetCompositionContext method to define the contexts at run time.  

Remember that your resolver may need to be defined on both client and server, depending on the type generators it defines and where they will be used.  For example, an IEntityLoginManager is used only on the server.

Be sure to decorate the types used by your custom contexts with the MEF PartNotDiscoverable attribute.  This tells both MEF and DevForce to ignore the types during standard discovery.

Below are a few very simple samples of custom types for the contexts defined above.

Discovery with metadata filters

Instead of defining the types to be used with the custom context when you create the context you can instead define metadata filtering rules.  Here you'll do the following:

1. Build one or more metadata filters with BuildExportFilter.
2. Registers the filters with the context using WithFilter and WithTypeFilter methods.
3. Mark your types with the System.ComponentModel.Composition.ExportMetadata and System.ComponentModel.Composition.InheritedExport attributes.

Here's a sample resolver defining the composition contexts.  As above we overrode the GetCompositionContext method to define the contexts at run time.  The BuildExportFilter method is used to build a filter for the metadata attributes to be used.  Here we'll be using only a single metadata attribute named "Env".  We're also using the WithFilter method to indicate that any types meeting the metadata criteria will be used.  We could also use the WithTypeFilter to indicate specific metadata by type.

We must decorate our types to add the metadata wanted.  This requires both the ExportMetadata attribute, to add metadata to the type, and the InheritedExport attribute, which is required by MEF to ensure that the custom metadata is found.  

Here are the same simple classes as defined above, but this time using metadata.

Using a CompositionContext

The CompositionContext is usually specified by name during the construction of an EntityManager:

We saw earlier that every custom CompositionContext was also given a unique name, via the WithName method.  It's this name which is provided in the EntityManager constructor.  The name defines the context to be used for all composition performed during the login, query, save, and other operations performed by the EntityManager, and the EntityServer it's connected to.  In a few types, such as the VerifierEngine,  the CompositionContext may also be set explicitly. This is because these classes may be instantiated and used independently of any EntityManager.

If the CompositionContext name isn't provided to an EntityManager the CompositionContext.Default will be used.

Changing the Default CompositionContext

You can use type or metadata filtering with the Default context too.  This is particularly useful when you're also using custom contexts but also need to ensure the behavior of the Default context.  

To modify the Default context you'll create a new CompositionContext based on CompositionContext.Default, and assign it the same name as the Default.  Note this is a bit of a trick:  the CompositionContext.Default will remain untouched, but by taking its name you will effectively preempt use of the prior one.

For example, here we add a custom EntityServerQueryInterceptor to the Default context.  Note the WithName clause:  it ensures the Default name is retained.

Here's the same thing using a metadata filter:

Custom fakes and mocks

Custom composition contexts are particularly useful in creating custom fakes and mocks for testing. The built-in support for faking is discussed separately in more detail, but here we show how to create custom contexts to aid in testing.

Let's assume we want to test how well our client code copes with a query exception thrown on the server. You generally don't want to force a query exception by modifying your production code, but you can test this easily with a mock.

Here we've written a FailingEntityServerQueryInterceptor that always throws an exception no matter what the query. Note the PartNotDiscoverable attribute on the custom class. This tells MEF to skip this class when discovering EntityServerQueryInterceptors. We don't want this one popping up in our production application!

Now that we've created a custom context that incorporates our interceptor, let's see how it affects a client-side query.