The top-level element for the configuration section is defined by the name that you specify in the <configSections> tag when adding it to the configuration file. Typically, the element is <unity>, as shown in the following XML example. However, you can choose another name for this section.

The following attribute is the only attribute available for the Unity section:

Attribute

Description

Xmlns

XML namespace for this section. Not required for the configuration file to work, but if you want XML IntelliSense support in Visual Studio, set this to http://schemas.microsoft.com/practices/2010/unity. This element is optional.

The following child elements are available for the <unity> section:

Element

Number

Description

<alias>

Many

Creates a type alias. This element is optional.

<namespace>

Many

Adds a namespace to the namespace search list. This element is optional.

<assembly>

Many

Adds an assembly to the assembly search list. This element is optional.

<sectionExtension>

Many

Adds a section extension, which adds new supported elements to the configuration schema. This element is optional.

<container>

Many

A set of container configurations. This element is optional.

The <container> Element

The <container> element contains a set of configurations for a Unity container instance. Within that element, there can be child elements describing type mapping, injection configuration, instance creation, container extensions, or other options made available through any added section extensions. The following table lists the attribute for the <container> element.

Attribute

Description

name

Name of this container configuration. One container element in the section may omit the name attribute; all others must have unique names. The unnamed <container> element is considered the default, and is the one that will be loaded if a container name is omitted when calling container.LoadConfiguration. This attribute is optional. For more information see Loading Configuration File Information.

The <register> element is the basic building block for any configuration file. It enables you to specify type mappings and injection configuration for a type. If you specify a name, that name is used for the type mapping. If you do not specify a name, it creates a default mapping for the specified types. You can specify a lifetime manager for each mapping. If no explicit lifetime manager is configured for a type, it uses the transient lifetime manager.

The following table lists the attributes for the <register> element.

Attribute

Description

type

The type that is being registered. This is the type that will be requested when calling the Resolve method. This attribute is required.

name

The name of the registration; if omitted the default registration for the type will be created. This attribute is optional.

mapTo

Type which will actually be created and returned when Resolve is called. This sets up a type mapping. It can be a user-defined alias or one of the default aliases. This attribute is optional.

The following example shows the common usage for the <register> element.

// Register a default (un-named) type mapping with a transient lifetime// Specify the registered type as an interface or object type // and the target type you want returned for that type
myContainer.RegisterType<ILogger, EventLogLogger>();

The following table lists the child elements for the <register> element. When using interception configuration extension, Microsoft.Practices.Unity.InterceptionExtension.Configuration.InterceptionConfigurationExtension, additional elements are valid children of a <register> element. For more information see Interception Configuration Schema Elements.

Element

Number

Description

<lifetime>

One

The type that manages instances created by the container. This element is optional.

<constructor>

One

Configures the constructor to be called when creating instances. This element is optional.

<property>

Many

Configures properties that will be set when creating instances. This element is optional.

<method>

Many

Configures methods that will be called when creating instances. This element is optional.

The <lifetime> element specifies which lifetime manager will be used to manage instances created for a type. If omitted, lifetime defaults to the TransientLifetimeManager. See Understanding Lifetime Managers for details about lifetime managers. The following example shows the common usage for the <lifetime> element

The type of the lifetime manager to create. Type must derive from LifetimeManager. Can be a user-defined alias or one of the default aliases. This attribute is required.

typeConverter

The type of type converter to use when creating the lifetime manager. If given, the type converter’s ConvertFrom method will be called to create the lifetime manager, and pass the contents of the value attribute. If not specified, the default converter for the specified type is used. Aliases are allowed. This attribute is optional.

value

Any value required to initialize the lifetime manager. This attribute is optional.

The <constructor>element configuration for the constructor for this type and contains details of the constructor injection requirements for this object type. The constructor element has no attributes. You can include only one <constructor> element in each register section. The example shows the common usage for the <constructor> element.

You can specify a constructor for the injection of a specific named instance. In the following example, InjectionConstructor indicateswhich constructor to use based on its arguments, the string "UI," and causes the TraceSourceLogger constructor with a single string parameter to be invoked.

The <property>element configures a property for injection. It contains details of the property injection requirements for this object type. You can include one or more <property>elements in each <register> element. See Specifying Values for Injection for details on how to specify what value to inject for the property. No explicit value means to inject the default value for the type of the property.

The <method> element configures a method that will be called as part of creating an instance. It contains details of the method injection requirements for this object type. You can include one or more <method> elements for each <register> element.

The <param> element specifies a parameter for constructor or method injection. It is used to determine which constructor or method overload is called, based on the names (and optionally types) of the parameters for the constructor or method.

The type of parameter. This attribute is only required if there are two different overloads with the same parameter name and you need to differentiate between them based on type. Normally, the parameter name alone is sufficient. This attribute is optional.

dependencyName

Name to use to resolve dependencies. This attribute is optional.

dependencyType

The type of dependency to resolve. This attribute is optional.

value

Value to inject for this parameter. This attribute is optional.

The <param> element can take one of the following child elements. Only one child element is allowed.

Element

Number

Description

<dependency>

One

Resolve value for parameter through the container. This element is optional.

<optional>

One

Resolve optional value through the container. This element is optional.

<value>

One

Gives explicit value to use for parameter value. This element is optional.

<array>

One

If parameter is of an array type, specifies what values to put into the resolved array. This element is optional.

For information about the child elements of the <param> element, see the following:

The <dependency> element is used when a value is to be resolved through the container. By default, with no other configuration, this element results in a callback into the container for the default value of the type of the containing parameter or property. Attributes may be used to customize what is resolved. If the value cannot be resolved, then an exception is thrown at resolve time. The following example shows the common usage for the <dependency> element.

The following table lists the attributes for the <dependency> element.

Attribute

Description

name

The name of the named type or mapping registered in the container to use to resolve this dependency. If omitted, the default registration will be resolved. This attribute is optional.

type

Type to resolve from the container. It must be a type compatible with the type of the parameter or property. If omitted, Unity resolves the type based on the type of the parent parameter or property. This attribute is optional.

The <value> element is used to specify a specific value for a parameter or property. This element lets you specify a string that is then passed through a TypeConverter to create the actual object to be injected. If no specific type converter type is given, then the default type converter for the type of parameter or property is used.

The string is converted to an object using the invariant culture; if you wish to use a locale-specific culture you must provide a custom TypeConverter to do so.

The following table lists the attributes for the <value> element.

Attribute

Description

value

The string value to be converted to an object. This attribute is required.

typeConverter

Type of the TypeConverter to use to convert the value to an object. If omitted, the default type converter for the containing parameter or property type will be used. This attribute is optional.

The <optional> element is used when a value should be resolved through the container but its presence is optional. The container will try to resolve this parameter or property using the types and mappings registered in the container, but if the resolution fails, the container returns null instead of throwing an exception.

The following table lists the attributes for the <optional> element.

Attribute

Description

name

The name of the named type or mapping registered in the container to use to resolve this optional dependency. If omitted the default registration will be resolved. This attribute is optional.

type

The type to use to resolve an optional dependency mapping or registration. Must be a type compatible with the type of the parameter or property. If you do not specify a type, Unity will resolve the type of the parameter or property. This attribute is optional.

The <array> element can be used to customize which elements are returned in the array if a parameter or property is of an array type. See Specifying Values for Injection for more details.

The <array> element takes no attributes.

The <array> element has a collection of zero or more child elements. If there are no child elements, an empty, zero-length array for both generic and non-generic types is injected. If there is more than one child, any value element such as <dependency>, <optional>, or <value> may be used, and each one corresponds to an element in the returned array.

If you want to have the default container behavior for arrays, do not specify the <array> element; use the <dependency> element instead.

The following example adds an extension at run time. 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.

The <instance> element is used to specify a value to be placed in the container and to indicate that you do not want that value to be created by the container but that it will be created by using a TypeConverter and then placed in the container by using the RegisterInstance method.

Instances added through configuration tend to be simple because it is hard to represent them with a string value, but they could be arbitrarily complex if there is a type converter that can handle the conversion from a string.

Note:

You cannot use an existing instance with the <instance> element. The <instance> section results in the creation of a new instance, much like something registered with RegisterType would. This is in contrast to the use of RegisterInstance, which requires the user to create the instance manually and then register it.

The following table lists the attributes for the <instance> element.

Attribute

Description

name

The name to use when registering this instance. This attribute is optional.

type

The type of the value. Can be a user-defined alias or one of the default aliases. If omitted, the assumed type is System.String. This attribute is optional.

value

The value to pass to the type converter to create the object. If omitted, null is passed to the type converter. This attribute is optional.

typeConverter

The type converter to use to construct the value. If not specified, the default converter for the type of the value is used. This attribute is optional.

The following example shows how the <instance> element is used in a configuration file.

<container><!-- A named string value --><instancename="NorthwindDb"value="SqlConnectionStringHere"/><!-- A typed value --><instancetype="ConnectionSettings"value="port=1234"typeConverter="ConnectionSettingsTypeConverter"/></container>

The following example shows how you can register instances at run time. The following example creates a default (unnamed) registration for an object of type EmailService that implements the IMyService interface.

The name of the assembly to search. The assembly name must be sufficiently qualified for the common language runtime (CLR) to load it. Assemblies in the GAC, for instance, must have a fully-qualified assembly name. This attribute is required.

The <sectionExtension> element is used to load a schema extension. Unlike the <extension> element, which is used to load a container extension object to modify the run-time behavior of a Unity container instance, this element loads a schema extension, which modifies the allowed elements in the configuration file itself. This is a section-level element; it must occur outside any <container> elements.

The following table describes the attributes for the <sectionExtension> element.

Attribute

Description

type

The type that implements the section extension. This attribute is required.

prefix

Specifies a prefix that will be appended to all the extension elements. This allows you to avoid collisions if two different extensions add an element with the same name. If left out, no prefix will be added. This attribute is optional.