Registering Container Extensions

Microsoft Enterprise Library 5.0

DropDown image DropDownHover image Collapse image Expand image CollapseAll image ExpandAll image Copy image CopyHover image

This topic explains how to register information that instructs Unity to load and use container extensions that add additional functionality to the container, and how you can register configuration information for these extensions.

This topic contains the following sections that explain container extensions:

Adding and Removing Extensions

You can add a custom or third-party extension to the Unity container at run time using the AddExtension and AddNewExtension methods, and you can remove extensions using the RemoveAllExtensions method.

To add an extension, use the AddNewExtension or AddExtension method of the container. For example, this code creates a new instance of an extension class named MyCustomExtension that you have previously created, and which resides in this or a referenced project, and adds it to the container.

C# Copy Code
IUnityContainer container = new UnityContainer();
container.AddNewExtension<MyCustomExtension>();
Visual Basic Copy Code
Dim container As IUnityContainer = New UnityContainer()
container.AddNewExtension(Of MyCustomExtension)()

If you already have an existing extension instance, you add it to the container using the AddExtension method. For example, this code adds an extension instance referenced by the variable named myExistingExtension to the container.

C# Copy Code
IUnityContainer container = new UnityContainer();
container.AddExtension(myExistingExtension);
Visual Basic Copy Code
Dim container As IUnityContainer = New UnityContainer()
container.AddExtension(myExistingExtension)

The AddNewExtension method creates the actual extension object by resolving it from the container. The previous example using AddNewExtension is equivalent to the following example.

C# Copy Code
IUnityContainer container = new UnityContainer();
container.AddExtension(container.Resolve<MyCustomExtension>());
Visual Basic Copy Code
Dim container As IUnityContainer = New UnityContainer()
container.AddExtension(container.Resolve(Of MyCustomExtension)())

You cannot remove individual extensions from the container. However, you can remove all currently registered extensions and then add back any you want to use. To remove all existing extensions, use the RemoveAllExtensions method of the container. For example, this code removes all extensions from an existing container referenced in the variable named container.

C# Copy Code
container.RemoveAllExtensions();
Visual Basic Copy Code
container.RemoveAllExtensions()

Important parts of the container's core functionality are implemented using the extension mechanism. You will be unable to successfully resolve objects after you call RemoveAllExtensions unless you explicitly add those core parts back to the container.

Accessing Configuration Information for Extensions

Container extensions will usually add strategies and policies to the container. However, extensions can expose configuration interfaces that allow them to read and expose configuration information. The extension must provide its own features to read and manage configuration information.

To access the configuration information for an extension, use the Configure method. This method of the UnityContainer class walks the list of extensions added to the container and returns the first one that implements the type you specify in the parameter of the Configure method. The method returns the required configuration interface, or it returns null (Nothing in Visual Basic) if the configuration type is not found.

There are two overrides of the Configure method. You can specify the extension type in the generic overload as a configurator (a class that implements the IUnityContainerExtensionConfigurator interface), or you can use the non-generic overload that accepts and returns an Object type. The following code shows both overrides of the Configure method used to retrieve the configuration as a type named MyConfigInterface.

C# Copy Code
// using a "configurator" where MyConfigInterface implements 
// the IUnityContainerExtensionConfigurator interface
MyConfigInterface configurator = container.Configure<MyConfigInterface>();

// using an Object type
Object config = container.Configure(typeof(MyConfigInterface));
Visual Basic Copy Code
' using a "configurator" where MyConfigInterface implements 
' the IUnityContainerExtensionConfigurator interface
Dim configurator As MyConfigInterface = container.Configure(Of MyConfigInterface)()

' using the configuration interface type
Dim config As Object = container.Configure(GetType(MyConfigInterface))

For more information about configuration for container extensions, see Creating and Using Container Extensions.

Methods for Registering and Configuring Container Extensions

The following table summarizes the method overloads you can use to register and configure container extensions at run time.

Method

Description

AddExtension(UnityContainerExtension extension)

Adds the specified extension object, which must be of type UnityContainerExtension, to the container. Returns a reference to the container, equivalent to this in C# or Me in Visual Basic.

AddNewExtension<TExtension>( )

Creates a new extension object of type TExtension and adds it to the container. Returns a reference to the container, equivalent to this in C# or Me in Visual Basic.

Configure<TConfigurator>( )

Returns the configuration of the specified extension interface as an object of type TConfigurator or null if the specified extension interface is not found. Extensions can expose configuration interfaces in addition to adding strategies and policies to the container. This method walks the list of extensions and returns the first one that implements the specified type.

Configure(Type configurationInterface)

Returns the configuration of the specified extension interface as an object of type configurationInterface or null if the specified extension interface is not found. Extensions can expose configuration interfaces in addition to adding strategies and policies to the container. This method walks the list of extensions and returns the first one that implements the specified type.

RemoveAllExtensions( )

Removes all installed extensions from the container, including all extensions that implement the default behavior, but it does not remove registered instances and singletons already set up in the container. To use the container again after executing this method, you must add either the default extensions or your own custom extensions. Returns a reference to the container, equivalent to this in C# or Me in Visual Basic.

More Information