Source Schema for the Unity Application Block

Retired Content
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
The latest Enterprise Library information can be found at the Enterprise Library site.

This topic lists the elements and attributes used to configure the Unity Application Block. The configuration file has the following section-handler declaration.

<configSections>
  <section name="unity"
           type="Microsoft.Practices.Unity.Configuration.UnityConfigurationSection,
                 Microsoft.Practices.Unity.Configuration, Version=1.1.0.0,
                 Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
  </configSections>

The section-handler declaration contains the name of the configuration settings section and the name of the section-handler class that processes configuration data in that section. The name of the configuration settings section is unity. The name of the section-handler class is Microsoft.Practices.Unity.Configuration.UnityConfigurationSection.

unity Element

The unity element specifies the configuration of a Unity Application Block. This element is required.

<unity>

  <typeAliases>
    ...
  </typeAliases>

  <containers>
    <container name="containerOne">
      <types>
        ...
      </types>
      <instances>
        ...
      </instances>
      <extensions>
        ...
      </extensions>
      <extensionConfig>
        ...
      </extensionConfig>
    </container>
  </containers>

</unity>

Child Elements

The following sections describe the child elements of the unity element. The unity element has the following child elements:

• typeAliases
• containers

typeAliases Element

The typeAliases element holds a collection of type aliases that allows you to specify more easily the types required in mappings, lifetimes, instances, extensions, and elsewhere in the configuration for Unity containers. The only child element is a collection of typeAlias elements.

<typeAliases>

  <!-- Lifetime manager types -->
  <typeAlias alias="singleton"
       type="Microsoft.Practices.Unity.ContainerControlledLifetimeManager,
             Microsoft.Practices.Unity" />
  <typeAlias alias="external"
       type="Microsoft.Practices.Unity.ExternallyControlledLifetimeManager,
             Microsoft.Practices.Unity" />

  <!-- User-defined type aliases -->
  <typeAlias alias="IMyInterface"
       type="MyApplication.MyTypes.MyInterface, MyApplication.MyTypes" />
  <typeAlias alias="MyRealObject" 
       type="MyApplication.MyTypes.MyRealObject, MyApplication.MyTypes" />
  <typeAlias alias="MyCustomLifetime" 
       type="MyApplication.MyLifetimeManager, MyApplication.MyTypes" />

</typeAliases>

typeAlias Element

The typeAlias element defines a single alias between a specific type and a name that you can use to refer to the type elsewhere in the configuration.

Attributes

The following table lists the attributes for the typeAlias element.

Attribute	Description
alias	The name of the alias and the shorthand name to use elsewhere in the configuration to refer to the specified type. This attribute is required.
type	The full type name of the type for this alias. This attribute is required.

containers Element

The containers element holds a collection of Unity containers. The only child element is a collection of container elements.

container Element

The container element holds details of an individual container.

<container name="containerOne">
  <types>
    ...
  </types>
  <instances>
    ...
  </instances>
  <extensions>
    ...
  </extensions>
  <extensionConfig>
    ...
  </extensionConfig>
</container>

Attributes and Child Elements

The following table lists the attributes for the container element.

Attribute	Description
name	The name of the container. This attribute is optional.

The container element has the following child elements:

• types Element
• instances Element
• extensions Element
• extensionConfig Element

types Element

The types element holds a collection of the registered type mappings for this container. The types element contains a series of type elements that add individual types.

Child Elements

The only child element of the types element is the type element.

type Element

The type element defines a type mapping to insert into the Unity container. 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 you do not specify a lifetime manager, the mapping uses the transient lifetime manager.

<types>

  <!-- Type mapping with no lifetime — defaults to "transient" -->  
  <type type="Custom.MyBaseClass" mapTo="Custom.MyConcreteClass" />

  <!-- Type mapping using aliases -->  
  <type type="IMyInterface" mapTo="MyRealObject" />

  <!-- Lifetime managers specified using the type aliases -->
  <type type="Custom.MyBaseClass" mapTo="Custom.MyConcreteClass">
    <lifetime type="singleton" /> 
  </type>
  <type type="IMyInterface" mapTo="MyRealObject" name="RealObject">
    <lifetime type="external" />
  </type>

  <!-- Lifetime manager specified using the full type name -->
  <!-- Any initialization data specified for the lifetime manager -->
  <!-- will be converted using the default type converter -->
  <type type="Custom.MyBaseClass" mapTo="Custom.MyConcreteClass">
    <lifetime value="sessionKey"
              type="MyApplication.MyTypes.MyLifetimeManager,
                    MyApplication.MyTypes" />
  </type>

  <!-- Lifetime manager initialization using a custom TypeConverter -->
  <type type="IMyInterface" mapTo="MyRealObject" name="CustomSession">
    <lifetime type="MyCustomLifetime" value="ReverseKey"
              typeConverter="MyApplication.MyTypes.MyTypeConverter,
                             MyApplication.MyTypes" />
  </type>

  <!-- type with injection parameters define in configuration -->
  <!-- Type mapping using aliases defined above -->  
  <type type="IMyService" mapTo="MyDataService" name="DataService">
    <typeConfig extensionType="Microsoft.Practices.Unity.Configuration.TypeInjectionElement,
                               Microsoft.Practices.Unity.Configuration">
      <constructor>
        <param name="connectionString" parameterType="string">
          <value value="AdventureWorks"/>
        </param>
        <param name="dataService" parameterType="IMyService">
          <dependency />
        </param>
      </constructor> 
      <property name="MyRealObject" propertyType="IMyInterface" />
      <method name="Initialize">
        <param name="connectionString" parameterType="string">
          <value value="contoso"/>
        </param>
        <param name="dataService" parameterType="IMyService">
          <dependency />
        </param>
      </method>
    </typeConfig>
  </type>

</types>

Attributes and Child Elements

The following table lists the attributes for the type element.

Attribute	Description
name	The name to use when registering this type. This attribute is optional.
type	The source type to configure in the container. The type of the object to map from if this is a mapping registration, or the type of the object if this is a singleton registration. Can be a user-defined alias specified in the typeAliases section of the configuration. This attribute is required.
mapTo	The destination type for type mapping. The type of the object to map to if this is a mapping registration. This attribute is optional.

The type element has the following child elements:

• lifetime Element
• typeConfig Element

lifetime Element

The lifetime element contains details of the lifetime manager to use with the type mapping.

<!-- Standard singleton lifetime manager specified using a type alias -->
<type type="Custom.MyBaseClass" mapTo="Custom.MyConcreteClass">
  <lifetime type="singleton" /> 
</type>

<!-- Custom lifetime manager specified using a type alias -->
<!-- and initialized using a custom TypeConverter  -->
<type type="Custom.MyBaseClass" mapTo="Custom.MyConcreteClass">
  <lifetime type="MyCustomLifetime" value="ReverseKey"
            name="CustomSessionLifetime"
            typeConverter="MyApplication.MyTypes.MyTypeConverter, MyApplication.MyTypes" />
</type>

Attributes

The following table lists the attributes for the lifetime element.

Attribute	Description
name	The name to use when registering this lifetime manager. This attribute is optional.
type	The type of the lifetime manager to use for this mapping. Can be a user-defined alias specified in the typeAliases section of the configuration or one of the default aliases singleton or external. This attribute is required.
value	Any value required to initialize the lifetime manager. This attribute is optional.
typeConverter	The type converter to use to convert the value provided to match the type of the instance. If not specified, the default converter for the specified type is used. This attribute is optional.

typeConfig Element

The typeConfig element specifies an extension class that applies dependency injection requirements you define within the element. You can use this element to configure custom dependency injection settings for the container. Unity includes a configuration section handler named TypeInjectionElement that you can use to specify dependency injection requirements for a type based on the constructor, property, and method injection capabilities that Unity supports, as shown in the following example.

<typeConfig name="" 
            extensionType="Microsoft.Practices.Unity.Configuration.TypeInjectionElement,
                          Microsoft.Practices.Unity.Configuration">

  <constructor>
    <param name="connectionString" parameterType="string">
      <value value="AdventureWorks"/>
    </param>
    <param name="dataService" parameterType="IMyService">
      <dependency />
    </param>
  </constructor> 

  <property name="MyRealObject" propertyType="IMyInterface" />

  <method name="Initialize">
    <param name="connectionString" parameterType="string">
      <value value="contoso"/>
    </param>
    <param name="dataService" parameterType="IMyService">
      <dependency />
    </param>
  </method>

</typeConfig>

Attributes and Child Elements

The following table lists the attributes for the typeConfig element.

Attribute	Description
name	The name to use when registering the configuration of dependency injection requirements for this type. This attribute is optional only when the configuration contains a single typeConfig element. If you include more than one typeConfig element, you must differentiate them with unique values for the name attribute.
extensionType	The type that will interpret the dependency configuration for this object. The default type is TypeInjectionElement. Allows developers to create and specify custom dependency configuration sections for objects. Must be a fully qualified type name. This attribute is required.

When you specify the TypeInjectionElement section handler, the typeConfig element can contain the following optional child elements:

• constructor Element
• property Element
• method Element

constructor Element

The constructor element 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 typeConfig section.

<constructor>
  <param name="connectionString" parameterType="string">
    <value value="AdventureWorks"/>
  </param>
  <param name="dataService" parameterType="IMyService">
    <dependency />
  </param>
</constructor> 

The configuration above corresponds to a constructor that has two parameters, as shown here.

public class MyCustomClass
{
  public MyCustomClass(string connectionString, IMyService dataService)
  { 
    ... 
  }
} 

'Usage
Public Class MyCustomClass
  Public Sub New(connectionString As String, dataService As IMyService)
    ... 
  End Sub
End Class 

The configuration settings specify that the value of the connectionString parameter will be "AdventureWorks", and that the value of the dataService parameter will be the result of any mapping for the IMyService interface stored in the container (effectively a call to the Resolve method for the class IMyService).

Child Elements

The constructor element has one or more child elements named param. These correspond to the parameters of the constructor you want to specify. For details, see param Element.

property Element

The property element contains details of the property (setter) injection requirements for this object type. You can include one or more property elements in each typeConfig section.

<!-- using default dependency injection through container -->
<property name="MyRealObject" propertyType="IMyInterface" />

<!-- using a specific value for the property -->
<property name="MyProjectName" propertyType="String">
  <value value="MyNewProject" />
</property>

<!-- using a specific value and type converter for that value -->
<property name="myObject" parameterType="IMyObject">
  <value type="MyRealObjectInstance" typeConverter="MyTypeConverter" />
</property>

<!-- using a default dependency through the container -->
<property name="dataService" parameterType="IMyService">
  <dependency />
</property>

<!-- using a specific named (non-default) dependency -->
<property name="dataService" parameterType="IMyService">
  <dependency name="MyMappingName" />
</property>

Attributes and Child Elements

The following table lists the attributes for the property element.

Attribute	Description
name	The name of the property to apply dependency injection to. This attribute is required.
propertyType	The data type of this property. Can be a user-defined alias specified in the typeAliases section of the configuration. This attribute is required.

The property element can have either a single value child element or a single dependency child element, but not both. Use a value element to specify the value for the property, or use a dependency element to specify a non-default dependency that Unity should apply when setting the property. If you do not include a child element, Unity will attempt to resolve the value of the property using default dependency injection resolved through the container.

For details of the child elements, see value Element and dependency Element.

method Element

The method element contains details of the method injection requirements for this object type. You can include one or more method elements in each typeConfig section.

<method name="Initialize">
  <param name="connectionString" parameterType="string">
    <value value="contoso"/>
  </param>
  <param name="dataService" parameterType="IMyService">
    <dependency />
  </param>
</method>

The configuration above corresponds to a method named Initialize that takes two parameters, as shown here.

public void Initialize(string connectionString, IMyService dataService)
{ 
  ... 
}

'Usage
Public Sub Initialize(connectionString As String, dataService As IMyService)
  ... 
End Sub

The configuration settings specify that the value of the connectionString parameter will be "AdventureWorks", and that the value of the dataService parameter will be the result of any mapping for the IMyService interface stored in the container (effectively a call to the Resolve method for the class IMyService).

Attributes and Child Elements

The following table lists the attributes for the method element.

Attribute	Description
name	The name of the method to apply dependency injection to. This attribute is required.

The method element has one or more child elements named param. For details, see param Element.

param Element

The param element specifies a parameter for constructor or method injection.

<!-- using a specific value for the parameter -->
<param name="connectionString" parameterType="string">
  <value value="contoso"/>
</param>

<!-- using a specific value and type converter for that value -->
<param name="myObject" parameterType="IMyObject">
  <value type="MyRealObjectInstance" typeConverter="MyTypeConverter" />
</param>

<!-- using a default dependency through the container -->
<param name="dataService" parameterType="IMyService">
  <dependency />
</param>

<!-- using a specific named (non-default) dependency -->
<param name="dataService" parameterType="IMyService">
  <dependency name="MyMappingName" />
</param>

Attributes and Child Elements

The following table lists the attributes for the param element.

Attribute	Description
name	The name of the parameter. This attribute is required.
parameterType	The data type of this parameter. Can be a user-defined alias specified in the typeAliases section of the configuration. This attribute is required.

The param element can contain either a single value element or a single dependency element. Use a value element to specify the value for the parameter, or use a dependency element to specify a non-default dependency that Unity should apply when setting the parameter. If you do not include a child element, Unity will attempt to resolve the value of the parameter using default dependency injection resolved through the container.

For details of the child elements, see value Element and dependency Element.

value Element

The value element specifies a value to apply to a property or parameter. The value can be one of the standard .NET data types such as String or Integer, and Unity will use the corresponding built-in .NET value converter to evaluate the value. Alternatively, you can use a custom object type and provide a reference to a converter for that type.

Attributes

The following table lists the attributes for the value element.

Attribute	Description
type	The type of the value. Can be a user-defined alias specified in the typeAliases section of the configuration, or one of the standard .NET data types. This attribute is optional. If you do not specify a type, the value is assumed to be of type String.
value	The value for this element. This attribute is required.
typeConverter	The type converter to use to convert the value provided to match the type of the instance. If not specified, the default converter for the specified type is used. This attribute is optional.

The value element has no child elements.

dependency Element

The dependency element specifies that Unity should resolve the value for this parameter or property using the types and mappings registered in the container. If you do not specify a type, it uses the type defined for the parameter or property. If you do not specify the name of a mapping or registration, it uses the default (un-named) mapping or registration.

Attributes

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. This attribute is optional.
type	The type to use to resolve a dependency mapping or registration. This attribute is optional. If you do not specify a type, Unity will resolve the type based on the type of the parent parameter or property.

The dependency element has no child elements.

instances Element

The instances element holds a collection of the existing object instances for this container. These are objects (including simple types such as database connection strings) registered with the container using the RegisterInstance method. The instances element contains a series of add elements that add individual instances.

<instances>
  <add name="MyInstance1" type="System.String" value="Some value" />
  <add name="MyInstance2" type="System.DateTime" value="2008-02-05T17:50:00" />
</instances>

Child Elements

The only child element of the instances element is a collection of the add element for instances.

add Element for Instances

The add element for instances defines an instance mapping to insert into the Unity container.

Attributes

The following table lists the attributes for the add element for instances.

Attribute	Description
name	The name to use when registering this instance. This attribute is optional.
type	The type of this instance. This attribute is optional. Can be a user-defined alias specified in the typeAliases section of the configuration. If omitted, the assumed type is System.String.
value	The value to use to initialize the instance. This attribute is required.
typeConverter	The type converter to use to convert the value provided to match the type of the instance. If not specified, the default converter for the specified type is used. This attribute is optional.

extensions Element

The extensions element holds the list of extensions to register with the Unity container. The extensions element contains a series of add elements that add individual extensions.

<extensions>
  <add type="MyApp.MyExtensions.SpecialOne" />
</extensions>

Child Elements

The only child element of the extensions element is a collection of the add element for extensions.

add Element for Extensions

The add element for extensions defines an extension to register with the Unity container.

Attributes

The following table lists the attributes for the add element for extensions.

Attribute	Description
type	The type of extension to add to the container. Can be a user-defined alias specified in the typeAliases section of the configuration. This attribute is required.

extensionConfig Element

The extensionConfig element holds a collection of the extension configuration elements for extensions you add to the container. The extensionConfig element contains a series of add elements that add individual types.

<extensionConfig>
  <add name="MyExtensionConfigHandler"
       type="MyApp.MyExtensions.SpecialOne.ConfigHandler" />
</extensionConfig>

Child Elements

The only child element of the extensionConfig element is a collection of the add element for extension configurations.

add Element for Extension Configurations

The add element for extension configurations contains the name and the type name of a custom class (or the root class of a series of custom classes) that can read the configuration information contained in the add element. For more information about creating custom container extensions and the configuration mechanism, see Creating Container Extensions.

Attributes

The following table lists the attributes for the add element for types.

Attribute	Description
name	The name to use when registering this extension configuration. This attribute is required.
type	The source type of the extension configuration. Must be a fully qualified type name. The extension must contain a class that can read the contents of the extension configuration. This attribute is required.