In the previous example the configuration resources are assumed to be located in the bin\Debug directory. You can use Spring's IResource abstraction to load resources from other locations.

The following example shows how to create an IoC container referring to resources located in the root directory of the filesystem an as an embedded assembly resource.

IApplicationContext context = new XmlApplicationContext(
                 "file:///services.xml",
                 "assembly://MyAssembly/MyDataAccess/data-access.xml");

The above example uses Spring.NET's IResource abstraction. The IResource interface provides a simple and uniform interface to a wide array of IO resources that can represent themselves as System.IO.Stream.

	Note
	After you learn about Spring's IoC container, you may want to know more about Spring's IResource abstraction to load meta data from other locations as desribed below and alsoin the chapter Chapter 7, Resources

These resources are most frequently files or URLs but can also be resources that have been embedded inside a .NET assembly. A simple URI syntax is used to describe the location of the resource, which follows the standard conventions for files, i.e. file:///services.xml and other well known protocols such as http.

The following snippet shows the use of the URI syntax for referring to a resource that has been embedded inside a .NET assembly, assembly://<AssemblyName>/<NameSpace>/<ResourceName>. The IResource abstraction is explained further in Section 7.1, “Introduction”.

Note

To create an embedded resource using Visual Studio you must set the Build Action of the .xml configuration file to Embedded Resource in the file property editor. Also, you will need to explicitly rebuild the project containing the configuration file if it is the only change you make between successive builds. If using NAnt to build, add a <resources> section to the csc task. For example usage, look at the Spring.Core.Tests.build file included the distribution.

You can also create a container by using a custom configuration section in the standard .NET application configuration file (one of App.config or Web.config). A custom configuration section that creates the same IApplicationContext as the previous example is

<spring>
  <context>
    <resource uri="file://services.xml"/>
    <resource uri="assembly://MyAssembly/MyDataAccess/data-access.xml"/>
  </context>
</spring> 

The context type (specified as the value of the type attribute of the context element) is optional. In a standalone application the context type defaults to the Spring.Context.Support.XmlApplicationContext class and in a Web application defaults to WebApplicationContext. An example of explicitly configuring the context type The following example shows explicit use of the context type attribute:

<spring>
  <context type="Spring.Context.Support.XmlApplicationContext, Spring.Core">
    <resource uri="file:///services.xml"/>
    <resource uri="assembly://MyAssembly/MyDataAccess/data-access.xml"/>
  </context>
</spring>

To acquire a reference to an IApplicationContext using a custom configuration section, one simply uses the following code;

IApplicationContext ctx = ContextRegistry.GetContext();

The ContextRegistry is used to both instantiate the application context and to perform service locator style access to other objects. (See Section 5.15, “Service Locator access” for more information). The glue that makes this possible is an implementation of the Base Class Library (BCL) provided IConfigurationSectionHandler interface, namely the Spring.Context.Support.ContextHandler class. The handler class needs to be registered in the configSections section of the .NET configuration file as shown below.

<configSections>
  <sectionGroup name="spring">
    <section name="context" type="Spring.Context.Support.ContextHandler, Spring.Core"/>
  </sectionGroup>
</configSections> 

This declaration now enables the use of a custom context section starting at the spring root element.

In some usage scenarios, user code will not have to explicitly instantiate an appropriate implementation IApplicationContext interface, since Spring.NET code will do it for you. For example, the ASP.NET web layer provides support code to load a Spring.NET WebApplicationContext automatically as part of the normal startup process of an ASP.NET web application. As such, once the container has been created for you, it is often the case that you will never need to explicitly interact with it again in your code, for example when configuring ASP.NET pages.

Spring.NET comes with an XSD schema to make the validation of the XML object definitions a whole lot easier. The XSD document is thoroughly documented so feel free to take a peek inside (see Appendix D, Spring.NET's spring-objects.xsd). The XSD is currently used in the implementation code to validate the XML document. The XSD schema serves a dual purpose in that it also facilitates the editing of XML object definitions inside an XSD aware editor (typically Visual Studio) by providing validation (and Intellisense support in the case of Visual Studio). You may wish to refer to Chapter 40, Visual Studio.NET Integration for more information regarding such integration.

Your XML object definitions can also be defined within the standard .NET application configuration file by registering the Spring.Context.Support.DefaultSectionHandler class as the configuration section handler for inline object definitions. This allows you to completely configure one or more IApplicationContext instances within a single standard .NET application configuration file as shown in the following example.

<configuration>

  <configSections>
    <sectionGroup name="spring">
      <section name="context" type="Spring.Context.Support.ContextHandler, Spring.Core"/>
      <section name="objects" type="Spring.Context.Support.DefaultSectionHandler, Spring.Core" />
    </sectionGroup>
  </configSections>

  <spring>

    <context>
      <resource uri="config://spring/objects"/>
    </context>
       
    <objects xmlns="http://www.springframework.net">
        ...
    </objects>

  </spring>

</configuration>

Other options available to structure the configuration files are described in Section 5.12.1, “Context Hierarchies” and Section 5.2.2.3, “Composing XML-based configuration meta data”.

The IApplicationContext can be configured to register other resource handlers, custom parsers to integrate user-contributed XML schema into the object definitions section, type converters, and define type aliases. These features are discussed in section Section 5.11, “Configuration of IApplicationContext”

It can be useful to have object definitions span multiple XML files. Often each individual XML configuration file represents a logical layer or module in your architecture.

You can use the IApplicationContext constructor to load object definitions from all these XML fragments. This constructor takes multiple IResource locations, as was shown in the previous section. Alternatively, use one or more occurrences of the <import/> element to load object definitions from another file (or files). For example:

<objects xmlns="http://www.springframework.net">

  <import resource="services.xml"/>
  <import resource="resources/messageSource.xml"/>
  <import resource="/resources/themeSource.xml"/>

  <object id="object1" type="..."/>
  <object id="object2" type="..."/>

</objects>

In the preceeding example, external object definitions are being loaded from three files, services.xml, messageSource.xml, and themeSource.xml. All location paths are relative to the definition file doing the importing, so services.xml must be in the same directory as the file doing the importing, while messageSource.xml and themeSource.xml must be in a resources location below the location of the importing file. As you can see, a leading slash is ignored, but given that these paths are relative, it is better form not to use the slash at all. The contents of the files being imported, including the top level <objects/> element, must be valid XML object definitions according to the Spring Schema.

Every object has one or more identifiers. These identifiers must be unique within the container that hosts the objects. An object usually has only one identifier, but if it requires more than one, the extra ones can be considered aliases.

When using XML-based configuration meta data, you use the 'id' and/or 'name'attributes to specify the object identifier(s). The 'id' attribute allows you to specify exactly one id, and because it is a real XML element ID attribute, the XML parser is able to do some extra validation when other elements reference the id. As such, it is the preferred way to specify an object id. However, the XML specification does limit the characters which are legal in XML IDs. This is usually not a constraint, but if you have a need to use one of these special XML characters, or want to introduce other aliases to the object, you can specify them in the 'name' attribute , separated by a comma (,), semicolon (;), or whitespace.

Note

You are not required to supply a name or id for a object. If no name or id is supplied explicitly, the container will generate a unique name for that object. However, if you want to refer to that object by name, through the use of the ref element or Service Location style lookup, you must provide a name. The motivations for not supplying a name for a object are to use autowiring and inline-objects which will be discussed later.

 <alias name="fromName" alias="toName"/>

<alias name="SubsystemA-DbProvider" alias="SubsystemB-DbProvider"/>
<alias name="SubsystemA-DbProvider" alias="MyApp-DbProvider"/>

When you create an object using the constructor approach, all normal classes are usable by and compatible with Spring. That is, the class being developed does not need to implement any specific interfaces or to be coded in a specific fashion. Simply specifying the object type should be sufficient. However, depending on what type of IoC you are going to use for that specific object, you may need to create a default constructor.

With XML-based configuration meta data you can specify your object class as follows:

<object id="exampleObject" type="Examples.ExampleObject, ExamplesLibrary"/>

For details about the mechanism for supplying arguments to the constructor (if required), and setting object instance properties after the object is constructed, see Section 5.3.1, “Dependency injection”.

This XML fragment describes an object definition that will be identified by the exampleObject name, instances of which will be of the Examples.ExampleObject type that has been compiled into the ExamplesLibrary assembly. Take special note of the structure of the type attribute's value... the namespace-qualified name of the class is specified, followed by a comma, followed by (at a bare minimum) the name of the assembly that contains the class. In the preceding example, the ExampleObject class is defined in the Examples namespace, and it has been compiled into the ExamplesLibrary assembly.

The name of the assembly that contains the type must be specified in the type attribute. Furthermore, it is recommended that you specify the fully qualified assembly name ^[2] in order to guarantee that the type that Spring.NET uses to instantiate your object (s) is indeed the one that you expect. Usually this is only an issue if you are using classes from (strongly named) assemblies that have been installed into the Global Assembly Cache (GAC).

If you have defined nested classes use the addition symbol, +, to reference the nested class. For example, if the class Examples.ExampleObject had a nested class Person the XML declaration would be

<object id="exampleObject" type="Examples.ExampleObject+Person, ExamplesLibrary"/>

If you are defining classes that have been compiled into assemblies that are available to your application (such as the bin directory in the case of ASP.NET applications) via the standard assembly probing mechanisms, then you can specify simply the name of the assembly (e.g. ExamplesLibrary.Data)... this way, when (or if) the assemblies used by your application are updated, you won't have to change the value of every <object/> definition's type attribute to reflect the new version number (if the version number has changed)... Spring.NET will automatically locate and use the newer versions of your assemblies (and their attendant classes) from that point forward.

When defining an object which is to be created using a static factory method, you use the type attribute to specify the type containing the static factory method and an attribute named factory-method to specify the name of the factory method itself. You should be able to call this method (with an optional list of arguments as described later) and return a live object, which subsequently is treated as if it had been created through a constructor. One use for such an object definition is to call static factories in legacy code.

The following object definition specifies that the object will be created by calling a factory-method. The definition does not specify the type of the returned object, only the type containing the factory method. In this example, CreateInstance must be a static method.

<object id="exampleObject"
      type="Examples.ExampleObjectFactory, ExamplesLibrary"
      factory-method="CreateInstance"/>

For details about the mechanism for supplying (optional) arguments to the factory method and setting object instance properties after it has been returned from the factory, see Section 5.3.2, “Dependencies and configuration in detail”

Similar to instantiation through a static factory method, instantiation with an instance factory method invokes a a non-static method on an existing object from the container to create a new object. To use this mechanism, leave the type attribute empty, and in the factory-object attribute specify the name of an object in the current (or parent/ancestor) container that contains the instance method that is to be invoked to create the object. Set the name of the factory method itself with the factory-method attribute.

<!-- the factory object, which contains an instance method called 'CreateInstance' -->
<object id="exampleFactory" type="...">
  <!-- inject any dependencies required by this object -->
</object>

<!-- the object that is to be created by the factory object -->
<object id="exampleObject"
      factory-method="CreateInstance"
      factory-object="exampleFactory"/>

This approach shows that the factory object itself can be managed and configured through dependency injection (DI). See Dependencies and configuraiton in detail.

	Note
	In Spring documentation, 'factory object', refers to an object that is configured in the Spring container that will create objects via an instance or static factory method. By contrast, IFactoryObject (notice the capitalization) refers to a Spring-specific IFactoryObject .

The following examples shows the definition of simple generic types and how they can be created in Spring's XML based configuration file.

namespace GenericsPlay
{
    public class FilterableList<T>
    {
        private List<T> list;
        
        private String name;

        public List<T> Contents
        {
            get { return list; }
            set { list = value; }
        }

        public String Name
        {
            get { return name; }
            set { name = value; }
        }
        
        public List<T> ApplyFilter(string filterExpression)
        {
            /// should really apply filter to list ;)
            return new List<T>();
        }

    }
}

The XML configuration to create and configure this object is shown below

<object id="myFilteredIntList" type="GenericsPlay.FilterableList&lt;int>, GenericsPlay">
  <property name="Name" value="My Integer List"/>
</object>

There are a few items to note in terms how to specify a generic type. First, the left bracket that specifies the generic type, i.e. <, is replaced with the string < due to XML escape syntax for the less than symbol. Yes, we all realize this is less than ideal from the readability point of view. Second, the generic type arguments can not be fully assembly qualified as the comma is used to separate generic type arguments. Alternative characters used to overcome the two quirks can be implemented in the future but so far, all proposals don't seem to help clarify the text. The suggested solution to improve readability is to use type aliases as shown below

<typeAliases>
 <alias name="GenericDictionary" type=" System.Collections.Generic.Dictionary&lt;,>" />
 <alias name="myDictionary" type="System.Collections.Generic.Dictionary&lt;int,string>" />
</typeAliases>

So that instead of something like this

<object id="myGenericObject" 
        type="GenericsPlay.ExampleGenericObject&lt;System.Collections.Generic.Dictionary&lt;int , string>>, GenericsPlay" />

It can be shortened to

<object id="myOtherGenericObject" 
        type="GenericsPlay.ExampleGenericObject&lt;GenericDictionary&lt;int , string>>, GenericsPlay" />

or even shorter

<object id="myOtherOtherGenericObject" 
        type="GenericsPlay.ExampleGenericObject&lt;MyIntStringDictionary>, GenericsPlay" />

Refer to Section 5.11, “Configuration of IApplicationContext” for additional information on using type aliases.

The following classes are used to demonstrate the ability to create instances of generic types that themselves are created via a static generic factory method.

public class TestGenericObject<T, U>
{
    public TestGenericObject()
    {
    }

    private IList<T> someGenericList = new List<T>();
    
    private IDictionary<string, U> someStringKeyedDictionary =
        new Dictionary<string, U>();

    public IList<T> SomeGenericList
    {
        get { return someGenericList; }
        set { someGenericList = value; }
    }

    public IDictionary<string, U> SomeStringKeyedDictionary
    {
        get { return someStringKeyedDictionary; }
        set { someStringKeyedDictionary = value; }
    }

}

The accompanying factory class is

public class TestGenericObjectFactory
{
    public static TestGenericObject<V, W> StaticCreateInstance<V, W>()
    {
        return new TestGenericObject<V, W>();
    }

    public TestGenericObject<V, W> CreateInstance<V, W>()
    {
        return new TestGenericObject<V, W>();
    }
}

The XML snippet to create an instance of TestGenericObject where V is a List of integers and W is an integer is shown below

<object id="myTestGenericObject"
        type="GenericsPlay.TestGenericObjectFactory, GenericsPlay"
        factory-method="StaticCreateInstance&lt;System.Collections.Generic.List&lt;int>,int>"
/>

The StaticCreateInstance method is responsible for instantiating the object that will be associated with the id 'myTestGenericObject'.

Using the class from the previous example the XML snippet to create an instance of a generic type via an instance factory method is shown below

<object id="exampleFactory" type="GenericsPlay.TestGenericObject&lt;int,string>, GenericsPlay"/>

<object id="anotherTestGenericObject"
        factory-object="exampleFactory" 
        factory-method="CreateInstance&lt;System.Collections.Generic.List&lt;int>,int>"/>

This creates an instance of TestGenericObject<List<int>,int>

Constructor-based DI is accomplished by the container invoking a constructor with a number of arguments, each representing a dependency. Calling a static factory method with specific arguments to construct the object is nearly equivalent, and this discussion treats arguments to a constructor and to a static factory method similarly. The following example shows a class that can only be dependency-injected with constructor injection. Notice that there is nothing special about this class (no container specific interfaces, base classes or attributes)

public class SimpleMovieLister
{
  // the SimpleMovieLister has a dependency on a MovieFinder
  private IMovieFinder movieFinder;

  // a constructor so that the Spring container can 'inject' a MovieFinder
  public MovieLister(IMovieFinder movieFinder)
  {
    this.movieFinder = movieFinder;
  }

  // business logic that actually 'uses' the injected IMovieFinder is omitted...

}

namespace X.Y
{
    public class Foo
    {
        public Foo(Bar bar, Baz baz)
        {
           // ...
        }
    }
}

<object id="foo" type="X.Y.Foo, Example">
  <constructor-arg ref="bar"/>
  <constructor-arg ref="baz"/>
</object>   

<object id="bar" type="X.Y.Bar, Example"/>
<object id="baz" type="X.Y.Baz, Example"/>

using System;

namespace SimpleApp
{
  public class ExampleObject
  {
    private int years;              //No. of years to the calculate the Ultimate Answer

    private string ultimateAnswer;  //The Answer to Life, the Universe, and Everything

    public ExampleObject(int years, string ultimateAnswer)
    {
       this.years = years;
       this.ultimateAnswer = ultimateAnswer;
    }

}

<object name="exampleObject" type="SimpleApp.ExampleObject, SimpleApp">
  <constructor-arg type="int" value="7500000"/>
  <constructor-arg type="string" value="42"/>
</object>

<object name="exampleObject" type="SimpleApp.ExampleObject, SimpleApp">
  <constructor-arg index="0" value="7500000"/>
  <constructor-arg index="1" value="42"/>
</object>

<object name="exampleObject" type="SimpleApp.ExampleObject, SimpleApp">
  <constructor-arg name="years" value="7500000"/>
  <constructor-arg name="ultimateAnswer" value="42"/>
</object>

Setter-based DI is accomplished by the container invoking setter properties on your objects after invoking a no-argument constructor or no-argument static factory method to instantiate your object.

The following eample shows a class that can only be dependency injected using pure setter injection.

public class MovieLister
{
  private IMovieFinder movieFinder;

  public IMovieFinder MovieFinder
  {
      set
      {
          movieFinder = value;
      }
  }

  // business logic that actually 'uses' the injected IMovieFinder is omitted...
}

The IAppliationContext supports constructor- and setter-based DI for the objects it manages. It also supports setter-based DI after some dependencies have already been supplied via the constructor approach..

The configuration for the dependencies comes in the form of the IObjectDefinition class, which is used together with TypeConverters to know how to convert properties from one format to another. However, most users of Spring.NET will not be dealing with these classes directly (that is programatically), but rather with an XML definition file which will be converted internally into instances of these classes, and used to load an entire Spring IoC container instance. Refer to Section 6.3, “Type conversion” for more information regarding type conversion, and how you can design your classes to be convertible by Spring.NET.

The container resolves object dependeices as:

The Spring container validates the configuration of each object as the container is created, including the validation of whether object reference properties refer to valid object. However, the object properties themselves are not set until the object is actually created. Objects that are defined as singletons and set to be pre-instantiated, are created when the container is created. Otherwise, the object is created only when it is requested. Creation of an object potentially causes a graph of objects to be created as the objects dependencies and its dependencies' dependencies (and so on) are created and assigned.

You can generally trust Spring.NET to do the right thing. It detects configuration problems, such as references to non-existent object definitions and circular dependencies, at container load-time. Spring sets properties and resolves dependencies as late as possible, which is when the object is actually created. This means that a Spring container which has loaded correctly can later generate an exception when you request an object if there is a problem creating that object or one of its dependencies. For example, the object throws an exception as a result of a missing or invalid property. This potentially delayed visibility of some configuration issues is why IApplicationContext by default pre-instantiate singleton objects. At the cost of some upfront time and memory to create these objects before they are actually needed, you discover configuration issues when the IApplicationContext is created, not later. If you wish, you can still override this default behavior and set any of these singleton objects will lazy-initialize, rather than be pre-instantiated.

If no circular dependencies exist, when one or more collaborating objects are being injected into a dependent object, each collaborating object is totally configured prior to being passed into the dependent object. This means that if object A has a dependency on object B, the Spring IoC container completely configures object B prior to invoking the setter method on object A. In other words, the object is instantiated (if not a pre-instantiated singleton), its dependencies are set, and the relevant lifecycle methods (such as a configured init method or the IIntializingObject callback method) will all be invoked.

First, an example of using XML-based configuration meta data for setter-based DI. A small part of a Spring XML configuration file specifying some object definitions:

<object id="exampleObject" type="Examples.ExampleObject, ExamplesLibrary">

    <!-- setter injection using the ref attribute -->
    <property name="objectOne" ref="anotherExampleObject"/>    
    <property name="objectTwo" ref="yetAnotherObject"/>
    <property name="IntegerProperty" value="1"/>
</object>

<object id="anotherExampleObject" type="Examples.AnotherObject, ExamplesLibrary"/>
<object id="yetAnotherObject" type="Examples.YetAnotherObject, ExamplesLibrary"/>

[C#]
public class ExampleObject
{
  private AnotherObject objectOne;
  private YetAnotherObject objectTwo;
  private int i;
  
  public AnotherObject ObjectOne
  {
    set { this.objectOne = value; }
  }
  
  public YetAnotherObject ObjectTwo
  {
    set { this.objectTwo = value; }
  }
  
  public int IntegerProperty
  {
    set { this.i = value; }
  }  
}

In the preceding example, setters have been declared to match against the properties specified in the XML file. Find below an example of using constructor-based DI.

<object id="exampleObject" type="Examples.ExampleObject, ExamplesLibrary">
    <constructor-arg name="objectOne" ref="anotherExampleObject"/>
    <constructor-arg name="objectTwo" ref="yetAnotherObject"/>
    <constructor-arg name="IntegerProperty" value="1"/>
</object>

<object id="anotherExampleObject" type="Examples.AnotherObject, ExamplesLibrary"/>
<object id="yetAnotherObject" type="Examples.YetAnotherObject, ExamplesLibrary"/>

[Visual Basic.NET]
Public Class ExampleObject

    Private myObjectOne As AnotherObject
    Private myObjectTwo As YetAnotherObject
    Private i As Integer
    
    Public Sub New (
        anotherObject as AnotherObject,
        yetAnotherObject as YetAnotherObject,
        i as Integer)
        
        myObjectOne = anotherObject
        myObjectTwo = yetAnotherObject
        Me.i = i
    End Sub
End Class

The constructor arguments specified in the object definition will be used to pass in as arguments to the constructor of the ExampleObject.

Now consider a variant of this where instead of using a constructor, Spring is told to call a static factory method to return an instance of the object

<object id="exampleObject" type="Examples.ExampleFactoryMethodObject, ExamplesLibrary"
     factory-method="CreateInstance">
    <constructor-arg name="objectOne" ref="anotherExampleObject"/>
    <constructor-arg name="objectTwo" ref="yetAnotherObject"/>
    <constructor-arg name="intProp" value="1"/>
</object>

<object id="anotherExampleObject" type="Examples.AnotherObject, ExamplesLibrary"/>
<object id="yetAnotherObject" type="Examples.YetAnotherObject, ExamplesLibrary"/>

[C#]
public class ExampleFactoryMethodObject
{
  private AnotherObject objectOne;
  private YetAnotherObject objectTwo;
  private int i;
  
  // a private constructor
  private ExampleFactoryMethodObject()
  {
  }

  public static ExampleFactoryMethodObject CreateInstance(AnotherObject objectOne,
                               YetAnotherObject objectTwo,
                               int intProp)
  {
    ExampleFactoryMethodObject fmo = new ExampleFactoryMethodObject();
    fmo.AnotherObject = objectOne;
    fmo.YetAnotherObject = objectTwo;
    fmo.IntegerProperty = intProp;
    return fmo;
  }

  // Property definitions

}

Arguments to the static factory method are supplied via <constructor-arg/> elements, exactly the same as if a constructor had actually been used. The type of the class being returned by the factory method does not have to be of the same type as the class which contains the static factory method, although in this example it is. An instance (non-static) factory method would be used in an essentially identical fashion (aside from the use of the factory-object attribute instead of the type attribute), so will not be detailed here.

Note that Setter Injection and Constructor Injectionare not mutually exclusive. It is perfectly reasonable to use both for a single object definition, as can be seen in the following example:

<object id="exampleObject" type="Examples.MixedIocObject, ExamplesLibrary">
    <constructor-arg name="objectOne" ref="anotherExampleObject"/>
    <property name="objectTwo" ref="yetAnotherObject"/>
    <property name="IntegerProperty" value="1"/>
</object>

<object id="anotherExampleObject" type="Examples.AnotherObject, ExamplesLibrary"/>
<object id="yetAnotherObject" type="Examples.YetAnotherObject, ExamplesLibrary"/>

[C#]
public class MixedIocObject
{
  private AnotherObject objectOne;
  private YetAnotherObject objectTwo;
  private int i;
  
  public MixedIocObject (AnotherObject obj)
  {
    this.objectOne = obj;
  }
  
  public YetAnotherObject ObjectTwo
  {
    set { this.objectTwo = value; }
  }
  
  public int IntegerProperty
  {
    set { this.i = value; }
  }  
}

The value attribute of the <property/> element specifies a property or constructor argument as a human-readable string representation. As mentioned previously, TypeConverter instances are used to convert these string values from a System.String to the actual property or argument type.

In the following example, we use a SqlConnection from the System.Data.SqlClient namespace. This class (like many other existing classes) can easily configured by Spring as it offers a convenient public property for configuration of its ConnectionString property.

<objects xmlns="http://www.springframework.net">
  <object id="myConnection" type="System.Data.SqlClient.SqlConnection">
      <!-- results in a call to the setter of the ConnectionString property -->
      <property
          name="ConnectionString"
          value="Integrated Security=SSPI;database=northwind;server=mySQLServer"/>
  </object>
</objects>

<object id="theTargetObject" type="..."> 
   . . .
</object>

<object id="theClientObject" type="...">
  <property name="targetName"> 
    <idref object="theTargetObject"/> 
  </property>
</object>

<object id="theTargetObject" type="..."> 
  . . .
</object>

<object id="theClientObject" type="...">
  <property name="targetName" value="theTargetObject"/> 
</object>

<property name="targetName">
  <idref local="theTargetObject"/> 
</property>

<property name="myProp">
  <value xml:space="preserve"> &#x000a;&#x000d;&#x0009;</value>
</property>

The ref element is the final element allowed inside a <constructor-arg/> or <property/> definition element. Here you set the value of the specified property to be a reference to another object (a collaborator) managed by the container. The referenced object is a dependency of the object whose property will be set, and it is initialized on demand as needed before the property is set. (If the collaborator is a singleton object it may be initialized already by the container.) All references are ultimately just a reference to another object. Scoping and validation depend on whether you specify the id/name of the object through the object, local, or parent attributes.

Specifying the target object through the object attribute of the ref tag is the most general form, and allows creation of a reference to any object in the same container or parent container, regardless of whether it is in the same XML file. The value of the object attribute may be the same as the id attribute of the target object, or as one of the values in the name attribute of the target object.

<ref object="someObject"/>

Specifying the target object by using the local attribute leverages the ability of the XML parser to validate XML id references within the same file. The value of the local attribute must be the same as the id attribute of the target object. The XML parser will issue an error if no matching element is found in the same file. As such, using the local variant is the best choice (in order to know about errors are early as possible) if the target object is in the same XML file.

<ref local="someObject"/>

Specifying the target object through the parent attribute creates a reference to an object that is in a parent container of the current container. The value of the 'parent' attribute may be the same as either the 'id' attribute of the target object, or one of the values in the 'name' attribute of the target object, and the target object must be in a parent container to the current one. You use this object reference variant mainly when you have a hierarchy of containers and you want to wrap an existing object in a parent container with some sort of proxy which will have the same name as the parent object.

<!-- in the parent context -->
<object id="AccountService" type="MyApp.SimpleAccountService, MyApp">
  <!-- insert dependencies as required as here -->
</object>

<!-- in the child (descendant) context -->
<object id="AccountService" <-- notice that the name of this object is the same as the name of the 'parent' object
        type="Spring.Aop.Framework.ProxyFactoryObject, Spring.Aop">
  <property name="target">
    <ref parent="AccountService"/> <-- notice how we refer to the parent object -->
  </property>
  <!-- insert other configuration and dependencies as required as here -->
</object>

An <object/> element inside the <constructor-arg/> or <property/> element defines so called inner object.

<object id="outer" type="...">

  <!-- Instead of using a reference to target, just use an inner object --> 

  <property name="target"> 
    <object type="ExampleApp.Person, ExampleApp"> 
      <property name="name" value="Tony"/> 
      <property name="age" value="51"/> 
    </object>
  </property>
</object>

An inner object definition does not require a defined id or name; the container ignores these values. It also ignores the scope flag. Inner object are always anonymous and they are always scoped as prototypes. It is not possible to inject inner objects into collaborating objects other than into the enclosing object.

The list, set, name-values and dictionary elements allow properties and arguments of the type IList, ISet, NameValueCollection and IDictionary, respectively, to be defined and set.

<objects xmlns="http://www.springframework.net">
  <object id="moreComplexObject" type="Example.ComplexObject">
      <!--
      results in a call to the setter of the SomeList (System.Collections.IList) property
      -->
      <property name="SomeList">
          <list>
              <value>a list element followed by a reference</value>
              <ref object="myConnection"/>
          </list>
      </property>
      <!--
      results in a call to the setter of the SomeDictionary (System.Collections.IDictionary) property
      -->
      <property name="SomeDictionary">
          <dictionary>
              <entry key="a string => string entry" value="just some string"/>
              <entry key-ref="myKeyObject" value-ref="myConnection"/>
          </dictionary>
      </property>
      <!--
      results in a call to the setter of the SomeNameValue (System.Collections.NameValueCollection) property
      -->
      <property name="SomeNameValue">
          <name-values>
              <add key="HarryPotter" value="The magic property"/>
              <add key="JerrySeinfeld" value="The funny (to Americans) property"/>
          </name-values>
      </property>
      <!-- 
      results in a call to the setter of the SomeSet (Spring.Collections.ISet) property 
      -->
      <property name="someSet">
          <set>
              <value>just some string</value>
              <ref object="myConnection"/>
          </set>
      </property>
  </object>
</objects>

Many classes in the BCL expose only read-only properties for collection classes. When Spring.NET encounters a read-only collection, it will configure the collection by using the getter property to obtain a reference to the collection class and then proceed to add the additional elements to the existing collection. This results in an additive behaviour for collection properties that are exposed in this manner.

The value of a Dictionary entry, or a set value, can also again be any of the following elements:

(object | ref | idref | expression | list | set | dictionary |
      name-values | value | null)

The shortcut forms for value and references are useful to reduce XML verbosity when setting collection properties. See Section 5.3.2.9, “Value and ref shortcut forms” for more information.

Spring supports setting values for classes that expose properties based on the generic collection interfaces IList<T> and IDictionary<TKey, TValue>. The type parameter for these collections is specified by using the XML attribute element-type for IList<T> and the XML attributes key-type and value-type for IDictionary<TKey, TValue>. The values of the collection are automatically converted from a string to the appropriate type. If you are using your own user-defined type as a generic type parameter you will likely need to register a custom type converter. Refer to Section 5.5, “Type conversion” for more information. The implementations of IList<T> and IDictionary<TKey, TValue> that is created are System.Collections.Generic.List and System.Collections.Generic.Dictionary.

The following class represents a lottery ticket and demonstrates how to set the values of a generic IList.

public class LotteryTicket { 

  List<int> list;

  DateTime date; 

  public List<int> Numbers { 
    set { list = value; }
    get { return list; } 
  }

  public DateTime Date { 
    get { return date; } 
    set { date = value; } 
  } 
}

The XML fragment that can be used to configure this class is shown below

<object id="MyLotteryTicket" type="GenericsPlay.Lottery.LotteryTicket, GenericsPlay">
  <property name="Numbers"> 
    <list element-type="int"> 
      <value>11</value>
      <value>21</value> 
      <value>23</value>
      <value>34</value> 
      <value>36</value>
      <value>38</value> 
    </list> 
  </property>
  <property name="Date" value="4/16/2006"/>
</object>

The following shows the definition of a more complex class that demonstrates the use of generics using the Spring.Expressions.IExpression interface as the generic type parameter for the IList element-type and the value-type for IDictionary. Spring.Expressions.IExpression has an associated type converter, Spring.Objects.TypeConverters.ExpressionConverter that is already pre-registered with Spring.

    public class GenericExpressionHolder
    {
        private System.Collections.Generic.IList<IExpression> expressionsList;

        private System.Collections.Generic.IDictionary<string,IExpression> expressionsDictionary;

        public System.Collections.Generic.IList<IExpression> ExpressionsList
        {
            set { this.expressionsList = value; }
        }

        public System.Collections.Generic.IDictionary<string, IExpression> ExpressionsDictionary
        {
            set { this.expressionsDictionary = value; }
        }

        public IExpression this[int index]
        {
            get
            {
                return this.expressionsList[index];
            }
        }

        public IExpression this[string key]
        {
            get { return this.expressionsDictionary[key]; }
        }
    }

An example XML configuration of this class is shown below

<object id="genericExpressionHolder"
    type="Spring.Objects.Factory.Xml.GenericExpressionHolder,
    Spring.Core.Tests">
    <property name="ExpressionsList">
        <list element-type="Spring.Expressions.IExpression, Spring.Core">
            <value>1 + 1</value>
            <value>date('1856-7-9').Month</value>
            <value>'Nikola Tesla'.ToUpper()</value>
            <value>DateTime.Today > date('1856-7-9')</value>
        </list>
    </property>
    <property name="ExpressionsDictionary">
        <dictionary key-type="string" value-type="Spring.Expressions.IExpression, Spring.Core">
            <entry key="zero">
                <value>1 + 1</value>
            </entry>
            <entry key="one">
                <value>date('1856-7-9').Month</value>
            </entry>
            <entry key="two">
                <value>'Nikola Tesla'.ToUpper()</value>
            </entry>
            <entry key="three">
                <value>DateTime.Today > date('1856-7-9')</value>
            </entry>
        </dictionary>
    </property>
</object>

As of Spring 1.3, the container supports the merging of collections. An application developer can define a parent-style <list/>, <dictionary/>, <set/> or <name-value/> element, and have child-style <list/>, <dictionary/>, <set/> or <name-value/> elements inherit and override values from the parent collection. That is, the child collection's values are the result of merging the elements of the parent and child collections, with the child's collection elements overriding values specified in the parent collection.

This section on merging discusses the parent-child object mechanism. Readers unfamiliar with parent and child object definitions may wish to read the relevant section before continuing.

The following example demonstrates collection merging:

<object id="parent" abstract="true" type="Example.ComplexObject, Examples">
  <property name="AdminEmails">
    <name-values>
      <add key="administrator" value="administrator@example.com"/>
      <add key="support" value="support@example.com"/>
    </name-values>
  </property>
</object>

<object id="child" parent="parent" >
  <property name="AdminEmails">
    <!-- the merge is specified on the *child* collection definition -->
    <name-values merge="true">
      <add key="sales" value="sales@example.com"/>
      <add key="support" value="support@example.co.uk"/>                
    </name-values>
  </property>
</object>

Notice the use of the merge=true attribute on the <name-values/> element of the AdminEmails property of the child object definition. When the child object is resolved and instantiated by the container, the resulting instance has an AdminEmails Properties collection that contains the result of the merging of the child's AdminEmails collection with the parent's AdminEmails collection:

administrator=administrator@example.com  // from parent
sales=sales@example.com                  // from child
support=support@example.co.uk            // overridden by child

The child Properties collection's value set inherits all property elements from the parent <name-values/>, and the child's value for the support value overrides the value in the parent collection. This merging behaviour applies similarly to the <list/>, <dictionary/>, and <set/> collection types. In the specific case of the <list/> element, the semantics associated with the IList collection type, that is, the notion of an ordered collection of values, is maintained; the parent's values precede all of the child list's values. In the case of the IDictionary, ISet, and NameValue collection types, no ordering exists. Hence no ordering semantics are in effect for the collection types that underlie the associated IDictionary, ISet, and NameValueCollection implementation types that the container uses internally.

Spring treats empty arguments for properties and the like as empty Strings. The following XML-based configuration meta data snippet sets the email property to the empty String value ("")

<object type="Examples.ExampleObject, ExamplesLibrary"> 
  <property name="email" value=""/> 
</object>

This results in the email property being set to the empty string value (""), in much the same way as can be seen in the following snippet of C# code

exampleObject.Email = "";

The <null> element is used to handle null values. For example:

<object type="Examples.ExampleObject, ExamplesLibrary"> 
  <property name="email"><null/></property>
</object>

This results in the email property being set to null, again in much the same way as can be seen in the following snippet of C# code:

exampleObject.Email = null;

An indexer lets you set and get values from a collection using a familiar bracket [] notation. Spring's XML configuration supports the setting of indexer properties. Overloaded indexers as well as multi-parameter indexers are also supported. The property expression parser described in Chapter 11, Expression Evaluation is used to perform the type conversion of the indexer name argument from a string in the XML file to a matching target type. As an example consider the following class

public class Person
{
    private IList favoriteNames = new ArrayList();

    private IDictionary properties = new Hashtable();

    public Person()
    {
        favoriteNames.Add("p1");
        favoriteNames.Add("p2");
    }

    public string this[int index]
    {
        get { return (string) favoriteNames[index]; }
        set { favoriteNames[index] = value; }
    }

    public string this[string keyName]
    {
        get { return (string) properties[keyName]; }
        set { properties.Add(keyName, value); }
    }
}

The XML configuration snippet to populate this object with data is shown below

<object id="person" type="Test.Objects.Person, Test.Objects">
    <property name="[0]" value="Master Shake"/>
    <property name="['one']" value="uno"/>
</object>

Note

The use of the property expression parser in Release 1.0.2 changed how you configure indexer properties. The following section describes this usage. The older style configuration uses the following syntax <object id="objectWithIndexer" type="Spring.Objects.TestObject, Spring.Core.Tests"> <property name="Item[0]" value="my string value"/> </object> You can also change the name used to identify the indexer by adorning your indexer method declaration with the attribute [IndexerName("MyItemName")]. You would then use the string MyItemName[0] to configure the first element of that indexer. There are some limitations to be aware in the older indexer configuration. The indexer can only be of a single parameter that is convertible from a string to the indexer parameter type. Also, multiple indexers are not supported. You can get around that last limitation currently if you use the IndexerName attribute.

Spring XML used to be even more verbose. What is now popular usage is actually the shortcut from of the original way to specify values and references.

There are also some shortcut forms that are less verbose than using the full value and ref elements. The property, constructor-arg, and entry elements all support a value attribute which may be used instead of embedding a full value element. Therefore, the following:

<property name="myProperty">
      <value>hello</value>
</property>

<constructor-arg> 
  <value>hello</value>
</constructor-arg> 

<entry key="myKey">
  <value>hello</value>
</entry>

are equivalent to:

<property name="myProperty" value="hello"/>

<constructor-arg value="hello"/> 

<entry key="myKey" value="hello"/>

In general, when typing definitions by hand, you will probably prefer to use the less verbose shortcut form.

The property and constructor-arg elements support a similar shortcut ref attribute which may be used instead of a full nested ref element. Therefore, the following...

<property name="myProperty"> 
  <ref object="anotherObject"/>
</property>

<constructor-arg index="0"> 
  <ref object="anotherObject"/> 
</constructor-arg>

is equivalent to...

<property name="myProperty" ref="anotherObject"/>

<constructor-arg index="0" ref="anotherObject"/>

	Note
	The shortcut form is equivalent to a <ref object="xxx"> element; there is no shortcut for either the <ref local="xxx"> or <ref parent="xxx"> elements. For a local or parent ref, you must still use the long form.

Finally, the entry element allows a shortcut form the specify the key and/or value of a dictionary, in the form of key/key-ref and value/value-ref attributes. Therefore, the following

<entry> 
  <key>
     <ref object="MyKeyObject"/>
  </key> 
  <ref object="MyValueObject"/> 
</entry>

Is equivalent to:

<entry key-ref="MyKeyObject" value-ref="MyValueObject"/>

As mentioned previously, the equivalence is to <ref object="xxx"> and not the local or parent forms of object references.

You can use compound or nested property names when you set object properties. Property names are interpreted using the Spring Expression Language (SpEL) and therefore can leverage its many features to set property names. For example, in this object definition a simple nested property name is configured

<object id="foo" type="Spring.Foo, Spring.Foo"> 
  <property name="bar.baz.name" value="Bingo"/> 
</object>

As an example of some alternative ways to declare the property name, you can use SpEL's support for indexers to configure a Dictionary key value pair as an alternative to the nested <dictionary> element. More importantly, you can use the 'expression' element to refer to a Spring expression as the value of the property. Simple examples of this are shown below

<property name=“minValue” expression=“int.MinValue” />

<property name=“weekFromToday” expression="DateTime.Today + 7"/>

Using SpEL's support for method evaluation, you can easily call static method on various helper classes in your XML configuraiton.

Rather than having to specifically declare in your code that you are adding a method to be invoked on an event, using the <listener> element you can register a plain object's methods with the corresponding event declaratively in your application configuration.

Using the listener element you can:

The same event registration in the example above can be achieved using configuration using the <listener> element.

<object id="eventListener1" type="SpringdotNETEventsExample.TestEventHandler, SpringdotNETEventsExample">
   <!-- wired up to an event exposed on an instance -->
   <listener event="Click" method="HandleEvent">
      <ref object="source"/>
   </listener>
</object>

<object id="eventListener2" type="SpringdotNETEventsExample.TestEventHandler, SpringdotNETEventsExample">
   <!-- wired up to an event exposed on an instance -->
   <listener event="Click" method="HandleEvent">
      <ref object="source"/>
   </listener>
</object>

In this case the two different objects will have their HandleEvent method invoked, as indicated explicitly using the method attribute, when a Click event, as specified by the event attribute, is triggered on the object referred to by the ref element.

Regular expressions can be employed to wire up more than one handler method to an object that contains one or more events.

<object id="eventListener" type="SpringdotNETEventsExample.TestEventHandler, SpringdotNETEventsExample">
   <listener method="Handle.+">
      <ref object="source"/>
   </listener>
</object>

Here all the eventListener's handler methods that begin with 'Handle', and that have the corresponding two parameters of a System.Object and a System.EventArgs, will be registered against all events exposed by the source object.

You can also use the name of the event in regular expression to filter your handler methods based on the type of event triggered.

<object id="eventListener" type="SpringdotNETEventsExample.TestEventHandler, SpringdotNETEventsExample">
   <!-- For the Click event, the HandleClick handler method will be invoked. -->
   <listener method="Handle${event}">
      <ref object="source"/>
   </listener>
</object>

Finally, you can register an object's handler methods against a selection of events, filtering based on their name using a regular expression.

<object id="eventListener" type="SpringdotNETEventsExample.TestEventHandler, SpringdotNETEventsExample">
   <listener method="HandleEvent" event="Cl.+">
      <ref object="source"/>
   </listener>
</object>

In this example the eventListener's HandleEvent handler method will be invoked for any event that begins with 'Cl'.

On a per-object basis, you can exclude an object from auto wiring. In Spring's XML format, set the autowire-candidate attribute of the <object/> element to false; the container makes that specific object definition unavailable to the auto wiring infrastructure (including attribute style configurations such as [Autowired]).

You can also limit auto wire candidates based on pattern-matching against object names. The top-level <objects/> element accepts one or more patterns within its default-autowire-candidates attribute. For example, to limit auto wire candidate status to any object whose name ends with Repository, provide a value of *Repository. To provide multiple patterns, define them in a comma-separated list. An explicit value of true or false for a object definitions autowire-candidate attribute always takes precedence, and for such objects, the pattern matching rules do not apply.

These techniques are useful for objects that you never want to be injected into other objects by auto wiring. It does not mean that an excluded object cannot itself be configured using auto wiring. Rather, the object itself is not a candidate for auto wiring other objects.

The [Autowire] attribute in the Spring.Objects.Factory.Attributes namespace can be used to mark a variable, property or method for automatically wiring by injection. It works similar to the auto wire configuration described in the paragraph above with a byType setting, except that you can define variables, properties or methods specifically that you want to autowire. In a latter paragraph you will see how you can even further define the object or value to inject.

To get the [Autowire] attribute working you need to add the auto wire post processor into your spring configuration file.

<object type="Spring.Objects.Factory.Attributes.RequiredAttributeObjectPostProcessor, Spring.Core"/>

To use the auto wire attribute on a variable, it can be private or public. The following code shows how to use the attribute. The post processor will try to find a registered object that is from the requested type. If more than one registered objects are found from that type you will get an ObjectCreationException. To prevent or control this situation you can use the primary attribute in the <object> definition, later you will see an example for this situation.

public class SomeObject 
{
    ...

    [Autowired]
    private IFoo hello;

    [Autowired]
    public IFoo Hello { get; set; }

    ...
} 

You can also use the auto wire attribute to inject into methods. In this case all parameters are looked up and found objects of the requested type injected into the method parameters. You are not restricted to a single method parameter.

public class SomeObject
{
    public IFoo hello; 

    [Autowired] 
    private void Prepare(IFoo hello)
    {
       this.hello = hello; 
    }
} 

If you have several objects defined from the same type you can make the following change to the <object> definition and define one of the objects as primary. In case the container will find several objects from a requested type but will check if there is a primary object and if true will use this object instead. The container will not throw a ObjectCreationException. If the container finds more than one objects for the requested type as primary, the container will throw a ObjectCreationException.

<object id="HelloFoo" type="Spring.Objects.Factory.Attributes.ByType.HelloFoo, Spring.Core.Tests" 
        primary="true"/>

You can also use the auto wire attribute for injection in to a List<T>, ISet<T> or Dictionary<string, T> type. In this case the container looks up for the requested type defined in the generic part of the definition and will create a List<T>, HashedSet<T> or Dictionary<string, T> with all found objects injected. For the dictionary type the key is the registered name of the object.

public class AutowireLists
{
    [Autowired]
    public IList<IFoo> foosList;

    [Autowired]
    public Spring.Collections.Generic.ISet<IFoo> foosSet;

    [Autowired]
    public IDictionary<string, IFoo> foosDictionary; 
} 

By default all found autowired objects are treated as required. This means if the container can't find an registered object of the requested type it will throw on ObjectCreationException. For this situation you can use the Required property of the [Autowire] attribute to mark an object as not required and therefore will not throw an ObjectCreationException.

public class AutowirePropertyNotRequired
{
   [Autowired(Required = false)]
   public IFoo Hello { get; set; } 
} 

The [Autowire] attribute is also processed in the case of an inheritent class that has variables, properties or methods annotated with the [Autowire] attribute. The order of the processing is that all inheritent classes are processed before the actual class is processed.

The [Autowire] attribute is wiring byType and therefore not fine-grained enough for some situations. You can also not inject values from loaded PropertyPlaceHolder files. For these cases you can use the [Value] attribute instead and this allows the following situations:

Inject an object by their Id:

public class AutowireViaValue
{
   [Value("@(CiaoFoo)")]
   public IFoo ciao;
}

This works on private variables and also on properties.

You can also use this scenario for auto wiring with a method:

public class AutowireMethodWithValue
{
    public IFoo ciao; 

    [Autowired]
    private void Prepare([Value("@(CiaoFoo)")] IFoo ciao)
    {
       this.ciao = ciao; 
    }
}

You can also use the [Value] attribute to access properties from a PropertyPlaceHolder configuration:

public class AutowirePropertyPlaceHolder
{ 
    [Value("${greeting}")]
    public string greeting;
}

Basically you can use the full Spring Expression Language, here we only showed these two examples of how you could use the [Value] attribute.

The [Qualifier] attribute allows you to define a qualification property on top of giving the object a name. This can be used for defining several objects from the same type and inject different values, later via auto wiring you can refer to this definition property. Here an example. First we create our basic object.

public interface IFoo 
{ 
   string Say(); 
}

public class SayFoo : IFoo 
{ 
   private string _message;

   public string Say() 
   {
      return "hello"; 
   }
}

Now we define our objects within our spring configuration file. We create tow object that use the same base object type but we inject different values. If we you use the [Autowire] we would get an ObjectCreationException because we two objects of the same type and most likely we would not got the object we wanted.

<object id="HelloFoo" type="Spring.Objects.Factory.Attributes.ByType.SayFoo, Spring.Core.Tests">
   <qualifier value="hello" />
   <property name="_message" value="Hello" />
</object>

<object id="CiaoFoo" type="Spring.Objects.Factory.Attributes.ByType.SayFoo, Spring.Core.Tests">
   <qualifier value="ciao" />
   <property name="_message" value="Hello" />
</object> 

With the <qualifier> element in our object definition we provided further information that we can use during the auto wire process. See the code below and how to use the [Qualifier] attribute to inject the object we want without getting a ObjectCreationException.

public class AutowireQithQualifier
{
   [Autowired] 
   [Qualifier("ciao")] 
   public IFoo Ciao { get; set; } 
} 

The inherited QualifierAttribute class allows you to define an object by more properties than a single qualifier value. You can define objects by fine grained, own defined, properties within a attribute. The first thing you need to do is to create a new attribute derived from QualifierAttribute and define your properties.

public class DialectAttribute : QualifierAttribute
{
   private string _language = "";
   public string Language { get { return _language; } set { _language = value; } } 
} 

The next step is to define your objects and the meta information attached to them. The attributes you define within the <qualifier> element are the same as your peroperties in your created attribute.

<object id="HelloFoo" type="Spring.Objects.Factory.Attributes.ByType.SayFoo, Spring.Core.Tests">
   <qualifier type="Spring.Objects.Factory.Attributes.ByQualifierAttribute.DialectAttribute">
      <attribute key="Language" value="English" /> 
   </qualifier>
   <property name="_message" value="Hello" />
</object>

<object id="CiaoFoo" type="Spring.Objects.Factory.Attributes.ByType.SayFoo, Spring.Core.Tests">
   <qualifier type="Spring.Objects.Factory.Attributrf4res.ByQualifierAttribute.DialectAttribute">
      <attribute key="Language" value="Italian" />
   </qualifier>
   <property name="_message" value="Ciao" />
</object>

Now you have defined your objects with new meta information. To use this meta information within the auto wiring process you need to add your created attribute as additional attribute to the [Autowire] attributes in your code. The properties you use within the added attribute will be matched with all registered objects. If they properties are matching the object is used for injection. If more then one object is found in the matching process and no object is defined as primary a ObjectCreationException is thrown.

public class AutowireByMetaInformation
{
    [Autowired]
    [Dialect(Language = "Italian")]
    public IFoo ciao;
} 

Lookup method injection is the ability of the container to override methods on container managed objects, to return the result of looking up another named object in the container. The lookup typically involves a prototype object as in the scenario described in the preceding section. The Spring framework implements this method injection by a dynamically generating a subclass overriding the method using the classes in the System.Reflection.Emit namespace.

	Note
	You can read more about the motivation for Method Injection in this blog entry.

Looking at the CommandManager class in the previous code snippit, you see that the Spring container will dynamically override the implementation of the CreateCommand() method. Your CommandManager class will not have any Spring dependencies, as can be seen in this reworked example below:

using System.Collections;

namespace Fiona.Apple
{
    public abstract class CommandManager
    {

        public object Process(IDictionary commandState)
        {
            Command command = CreateCommand();
            command.State = commandState;
            return command.Execute();
        }

        // okay... but where is the implementation of this method?
        protected abstract Command CreateCommand();
    }
}

In the client class containing the method to be injected (the CommandManager in this case) the method to be injected requires a signature of the following form:

<public|protected> [abstract] <return-type> TheMethodName(no-arguments);

If the method is abstract, the dynamically-generated subclass implements the method. Otherwise, the dynamically-generated subclass overrides the concrete method defined in the original class. Let's look at an example:

<!-- a stateful object deployed as a prototype (non-singleton) -->
<object id="command" class="Fiona.Apple.AsyncCommand, Fiona" singleton="false">
  <!-- inject dependencies here as required -->
</object>

<!-- commandProcessor uses a statefulCommandHelpder -->
<object id="commandManager" type="Fiona.Apple.CommandManager, Fiona">
  <lookup-method name="CreateCommand" object="command"/>
</object>

The object identified as commandManager will calls its own method CreateCommand whenever it needs a new instance of the command object. You must be careful to deploy the command object as prototype, if that is actually what is needed. If it is deployed as a singleton the same instance of singleShotHelper will be returned each time.

Note that lookup method injection can be combined with Constructor Injection (supplying optional constructor arguments to the object being constructed), and also with Setter Injection (settings properties on the object being constructed).

A less commonly useful form of method injection than Lookup Method Injection is the ability to replace arbitrary methods in a managed object with another method implementation.

With XML-based configuration meta data, you can use the replaced-method element to replace an existing method implementation with another, for a deployed object. Consider the following class, with a method ComputeValue, which we want to override:

public class MyValueCalculator {

  public virtual string ComputeValue(string input) {
    // ... some real code
  }

  // ... some other methods
}

A class implementing the Spring.Objects.Factory.Support.IMethodReplacer interface is needed to provide the new (injected) method definition.

/// <summary>
/// Meant to be used to override the existing ComputeValue(string)
/// implementation in MyValueCalculator.
/// </summary>
public class ReplacementComputeValue : IMethodReplacer 
{
	public object Implement(object target, MethodInfo method, object[] arguments)
	{
		// get the input value, work with it, and return a computed result...
		string value = (string) arguments[0];
		// compute...
		return result;
	}
}

The object definition to deploy the original class and specify the method override would look like this:

<object id="myValueCalculator" type="Examples.MyValueCalculator, ExampleAssembly">
  <!-- arbitrary method replacement -->
  <replaced-method name="ComputeValue" replacer="replacementComputeValue">
    <arg-type match="String"/>
  </replaced-method>
</object>

<object id="replacementComputeValue" type="Examples.ReplacementComputeValue, ExampleAssembly"/>

You can use one or more contained arg-type elements within the replaced-method element to indicate the method signature of the method being overridden. The signature for the arguments is necessaryonly if the method is overloaded and multiple variants exist within the class. For convenience, the type string for an argument may be a substring of the fully qualified type name. For example, the following all match System.String.

    System.String
    String
    Str

Because the number of arguments is often enough to distinguish between each possible choice, this shortcut can save a lot of typing, by allowing you to typ just the shortest string which will match an argument type.

The PropertyRetrievingFactoryObject is an IFactoryObject that addresses the scenario of setting one of the properties and / or constructor arguments of an object to the value of a property exposed on another object or class. One can use it to get the value of any public property exposed on either an instance or a class (in the case of a property exposed on a class, the property must obviously be static).

In the case of a property exposed on an instance, the target object that a PropertyRetrievingFactoryObject will evaluate can be either an object instance specified directly inline or a reference to another arbitrary object. In the case of a static property exposed on a class, the target object will be the class (the .NET System.Type) exposing the property.

The result of evaluating the property lookup may then be used in another object definition as a property value or constructor argument. Note that nested properties are supported for both instance and class property lookups. The IFactoryObject is discussed more generally in Section 5.9.3, “Customizing instantiation logic using IFactoryObjects”.

Here's an example where a property path is used against another object instance. In this case, an inner object definition is used and the property path is nested, i.e. spouse.age.

<object name="person" type="Spring.Objects.TestObject, Spring.Core.Tests">
  <property name="age" value="20"/>
  <property name="spouse">
    <object type="Spring.Objects.TestObject, Spring.Core.Tests">                      
      <property name="age" value="21"/>
    </object>
  </property>          
</object>
        
// will result in 21, which is the value of property 'spouse.age' of object 'person'        
<object name="theAge" type="Spring.Objects.Factory.Config.PropertyRetrievingFactoryObject, Spring.Core">
  <property name="TargetObject" ref="person"/>
  <property name="TargetProperty" value="spouse.age"/>
</object>

An example of using a PropertyRetrievingFactoryObject to evaluate a static property is shown below.

<object id="cultureAware" 
        type="Spring.Objects.Factory.Xml.XmlObjectFactoryTests+MyTestObject, Spring.Core.Tests">
  <property name="culture" ref="cultureFactory"/>
</object>

<object id="cultureFactory" 
        type="Spring.Objects.Factory.Config.PropertyRetrievingFactoryObject, Spring.Core">
  <property name="StaticProperty">
      <value>System.Globalization.CultureInfo.CurrentUICulture, Mscorlib</value>
  </property>
</object>

Similarly, an example showing the use of an instance property is shown below.

<object id="instancePropertyCultureAware" 
        type="Spring.Objects.Factory.Xml.XmlObjectFactoryTests+MyTestObject, Spring.Core.Tests">
  <property name="Culture" ref="instancePropertyCultureFactory"/>
</object>

<object id="instancePropertyCultureFactory" 
        type="Spring.Objects.Factory.Config.PropertyRetrievingFactoryObject, Spring.Core">
  <property name="TargetObject" ref="instancePropertyCultureAwareSource"/>
  <property name="TargetProperty" value="MyDefaultCulture"/>
</object>

<object id="instancePropertyCultureAwareSource" 
        type="Spring.Objects.Factory.Xml.XmlObjectFactoryTests+MyTestObject, Spring.Core.Tests"/>
    

The FieldRetrievingFactoryObject class addresses much the same area of concern as the PropertyRetrievingFactoryObject described in the previous section. However, as its name might suggest, the FieldRetrievingFactoryObject class is concerned with looking up the value of a public field exposed on either an instance or a class (and similarly, in the case of a field exposed on a class, the field must obviously be static).

The following example demonstrates using a FieldRetrievingFactoryObject to look up the value of a (public, static) field exposed on a class

<object id="withTypesField" 
        type="Spring.Objects.Factory.Xml.XmlObjectFactoryTests+MyTestObject, Spring.Core.Tests">
  <property name="Types" ref="emptyTypesFactory"/>
</object>

<object id="emptyTypesFactory" 
        type="Spring.Objects.Factory.Config.FieldRetrievingFactoryObject, Spring.Core">
  <property name="TargetType" value="System.Type, Mscorlib"/>
    <property name="TargetField" value="EmPTytypeS"/>
</object>
      

The example in the next section demonstrates the look up of a (public) field exposed on an object instance.

<object id="instanceCultureAware" 
        type="Spring.Objects.Factory.Xml.XmlObjectFactoryTests+MyTestObject, Spring.Core.Tests">
  <property name="Culture" ref="instanceCultureFactory"/>
</object>

<object id="instanceCultureFactory"
  type="Spring.Objects.Factory.Config.FieldRetrievingFactoryObject, Spring.Core">
  <property name="TargetObject" ref="instanceCultureAwareSource"/>
  <property name="TargetField" value="Default"/>
</object>

<object id="instanceCultureAwareSource" 
         type="Spring.Objects.Factory.Xml.XmlObjectFactoryTests+MyTestObject, Spring.Core.Tests"/>
    

The MethodInvokingFactoryObject rounds out the trio of classes that permit the setting of properties and constructor arguments using the members of other objects and classes. Whereas the PropertyRetrievingFactoryObject and FieldRetrievingFactoryObject classes dealt with simply looking up and returning the value of property or field on an object or class, the MethodInvokingFactoryObject allows one to set a constructor or property to the return value of an arbitrary method invocation,

The MethodInvokingFactoryObject class handles both the case of invoking an (instance) method on another object in the container, and the case of a static method call on an arbitrary class. Additionally, it is sometimes necessary to invoke a method just to perform some sort of initialization.... while the mechanisms for handling object initialization have yet to be introduced (see Section 5.6.1.1, “IInitializingObject / init-method”), these mechanisms do not permit any arguments to be passed to any initialization method, and are confined to invoking an initialization method on the object that has just been instantiated by the container. The MethodInvokingFactoryObject allows one to invoke pretty much any method on any object (or class in the case of a static method).

The following example (in an XML based IObjectFactory definition) uses the MethodInvokingFactoryObject class to force a call to a static factory method prior to the instantiation of the object...

<object id="force-init"
  type="Spring.Objects.Factory.Config.MethodInvokingFactoryObject, Spring.Core">
  <property name="StaticMethod">
    <value>ExampleNamespace.ExampleInitializerClass.Initialize</value>
  </property>
</object>
<object id="myService" depends-on="force-init"/>

Note that the definition for the myService object has used the depends-on attribute to refer to the force-init object, which will force the initialization of the force-init object first (and thus the calling of its configured StaticMethod static initializer method, when myService is first initialized. Please note that in order to effect this initialization, the MethodInvokingFactoryObject object must be operating in singleton mode (the default.. see the next paragraph).

Note that since this class is expected to be used primarily for accessing factory methods, this factory defaults to operating in singleton mode. As such, as soon as all of the properties for a MethodInvokingFactoryObject object have been set, and if the MethodInvokingFactoryObject object is still in singleton mode, the method will be invoked immediately and the return value cached for later access. The first request by the container for the factory to produce an object will cause the factory to return the cached return value for the current request (and all subsequent requests). The IsSingleton property may be set to false, to cause this factory to invoke the target method each time it is asked for an object (in this case there is obviously no caching of the return value).

A static target method may be specified by setting the targetMethod property to a string representing the static method name, with TargetType specifying the Type that the static method is defined on. Alternatively, a target instance method may be specified, by setting the TargetObject property to the name of another Spring.NET managed object definition (the target object), and the TargetMethod property to the name of the method to call on that target object.

Arguments for the method invocation may be specified in two ways (or even a mixture of both)... the first involves setting the Arguments property to the list of arguments for the method that is to be invoked. Note that the ordering of these arguments is significant... the order of the values passed to the Arguments property must be the same as the order of the arguments defined on the method signature, including the argument Type. This is shown in the example below

<object id="myObject" type="Spring.Objects.Factory.Config.MethodInvokingFactoryObject, Spring.Core">
  <property name="TargetType" value="Whatever.MyClassFactory, MyAssembly"/>
  <property name="TargetMethod" value="GetInstance"/>
  
  <!-- the ordering of arguments is significant -->
  <property name="Arguments">
    <list>
      <value>1st</value>
      <value>2nd</value>
      <value>and 3rd arguments</value>
      <!-- automatic Type-conversion will be performed prior to invoking the method -->
    </list>
  </property>
</object>

The second way involves passing an arguments dictionary to the NamedArguments property... this dictionary maps argument names (Strings) to argument values (any object). The argument names are not case-sensitive, and order is (obviously) not significant (since dictionaries by definition do not have an order). This is shown in the example below

<object id="myObject" type="Spring.Objects.Factory.Config.MethodInvokingFactoryObject, Spring.Core">
  <property name="TargetObject">
    <object type="Whatever.MyClassFactory, MyAssembly"/>
  </property>
  <property name="TargetMethod" value="Execute"/>
  
  <!-- the ordering of named arguments is not significant -->
  <property name="NamedArguments">
    <dictionary>
      <entry key="argumentName"><value>1st</value></entry>
      <entry key="finalArgumentName"><value>and 3rd arguments</value></entry>
      <entry key="anotherArgumentName"><value>2nd</value></entry>
    </dictionary>
  </property>
</object>

The following example shows how use MethodInvokingFactoryObject to call an instance method.

<object id="myMethodObject" type="Whatever.MyClassFactory, MyAssembly" />

<object id="myObject" type="Spring.Objects.Factory.Config.MethodInvokingFactoryObject, Spring.Core">
  <property name="TargetObject" ref="myMethodObject"/>
  <property name="TargetMethod" value="Execute"/>
</object>

The above example could also have been written using an anonymous inner object definition... if the object on which the method is to be invoked is not going to be used outside of the factory object definition, then this is the preferred idiom because it limits the scope of the object on which the method is to be invoked to the surrounding factory object.

Finally, if you want to use MethodInvokingFactoryObject in conjunction with a method that has a variable length argument list, then please note that the variable arguments need to be passed (and configured) as a list. Let us consider the following method definition that uses the params keyword (in C#), and its attendant (XML) configuration...

[C#]
public class MyClassFactory
{
    public object CreateObject(Type objectType, params string[] arguments)
    {
        return ... // implementation elided for clarity...
    }
}

<object id="myMethodObject" type="Whatever.MyClassFactory, MyAssembly" />

<object id="paramsMethodObject" type="Spring.Objects.Factory.Config.MethodInvokingFactoryObject, Spring.Core">
  <property name="TargetObject" ref="myMethodObject"/>
  <property name="TargetMethod" value="CreateObject"/>
  <property name="Arguments">
    <list>
      <value>System.String</value>
      <!-- here is the 'params string[] arguments' -->
      <list>
        <value>1st</value>
        <value>2nd</value>
      </list>
    </list>
</object>

The LogFactoryObject is useful when you would like to share a Common.Logging log object across a number of classes instead of creating a logging instance per class or class hierarchy. Information on the Common.Logging project can be found here. In the example shown below the same logging instance, with a logging category name of "DAOLogger", is used in both the SimpleAccountDao and SimpleProductDao data access objects.

<objects xmlns="http://www.springframework.net" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xsi:schemaLocation="http://www.springframework.net
         http://www.springframework.net/xsd/spring-objects.xsd" >

    <object name="daoLogger" type="Spring.Objects.Factory.Config.LogFactoryObject, Spring.Core">
      <property name="logName" value="DAOLogger"/>
    </object>
        
    <object name="productDao" type="PropPlayApp.SimpleProductDao, PropPlayApp ">
      <property name="maxResults" value="100"/>
      <property name="dbConnection" ref="myConnection"/>
      <property name="log" ref="daoLogger"/>
    </object>

    <object name="accountDao" type="PropPlayApp.SimpleAccountDao, PropPlayApp ">
      <property name="maxResults" value="100"/>
      <property name="dbConnection" ref="myConnection"/>
      <property name="log" ref="daoLogger"/>
    </object>
    
    <object name="myConnection" type="System.Data.Odbc.OdbcConnection, System.Data"> 
      <property name="connectionstring" value="dsn=MyDSN;uid=sa;pwd=myPassword;"/> 
    </object> 
    
</objects>

This section shows in detail how to define a custom type converter that does not use the .NET TypeConverter attribute. The type converter class is standalone and inherits from the TypeConverter class. It uses the legacy factory post-processor approach.

Consider a user class ExoticType, and another class DependsOnExoticType which needs ExoticType set as a property:

public class ExoticType
{
    private string name;
        
    public ExoticType(string name)
    {
        this.name = name;
    }

    public string Name
    {
        get { return this.name; }
    }
}

and

public class DependsOnExoticType
{
    public DependsOnExoticType() {}
    
    private ExoticType exoticType;
        
    public ExoticType ExoticType
    {
        get { return this.exoticType; }
        set { this.exoticType = value; }
    }
    
    public override string ToString()
    {
        return exoticType.Name;
    }
}

When things are properly set up, we want to be able to assign the type property as a string, which a TypeConverter will convert into a real ExoticType object behind the scenes:

<object name="sample" type="SimpleApp.DependsOnExoticType, SimpleApp">
  <property name="exoticType" value="aNameForExoticType"/>
</object>

The TypeConverter looks like this:

public class ExoticTypeConverter : TypeConverter
{
	public ExoticTypeConverter()
	{
	}

	public override bool CanConvertFrom (
		ITypeDescriptorContext context, 
		Type sourceType) 
	{
		if (sourceType == typeof (string)) 
		{
			return true;
		}
		return base.CanConvertFrom (context, sourceType);
	}

	public override object ConvertFrom (
		ITypeDescriptorContext context, 
		CultureInfo culture, object value) 
	{
		string s = value as string;
		if (s != null) 
		{          
			return new ExoticType(s.ToUpper());
		}
		return base.ConvertFrom (context, culture, value);
	}
}

Finally, we use the CustomConverterConfigurer to register the new TypeConverter with the IApplicationContext, which will then be able to use it as needed:

<object id="customConverterConfigurer" 
	type="Spring.Objects.Factory.Config.CustomConverterConfigurer, Spring.Core">
  <property name="CustomConverters">
    <dictionary>
      <entry key="SimpleApp.ExoticType">
        <object type="SimpleApp.ExoticTypeConverter"/>
      </entry>
    </dictionary>
  </property>
</object>

The Spring.Objects.Factory.IInitializingObject interface allows an object to perform initialization work after all the necessary properties on an object are set by the container. The IInitializingObject interface specifies a single method:

It is recommended that you do not use the IInitializingObject interface because it unnecessarily coupules the code to Spring. Alternatively, specify an POJO initialization method. In the case of XML-based configuration meta data, you use the init-method attribute to specify the name of the method that has a void no-argument signature. For example, the following definition:

<object id="exampleInitObject" type="Examples.ExampleObject" init-method="init"/>

[C#] 
public class ExampleObject 
{ 
    public void Init() 
    {
        // do some initialization work 
    }   
}

...is exactly the same as...

<object id="exampleInitObject" type="Examples.AnotherExampleObject"/>

[C#]
public class AnotherExampleObject : IInitializingObject
{
    public void AfterPropertiesSet()
    {
        // do some initialization work
    }
}

... but does not couple the code to Spring.NET.

Implementing the System.IDisposable interface allows an object to get a callback callback when the container containing it is destroyed. The IDisposable interface specifies a single method:

Since the IDisposable interface resides in the core .NET library, it does not couple your class to Spring as in the case with the IInitializingObject interface. However, you may also specify a destruction method that is not tied to the IDisposable interface. In the case of XML-based configuration meta data, you use the destroy-method attribute to specify the name of the method that has a void no-argument signature. For example, the following definition:

<object id="exampleInitObject" type="Examples.AnotherExampleObject" />

[C#]
public class AnotherExampleObject : IDisposable
{
    public void Dispose()
    {
        // do some destruction work
    }
}

The InitDestroyAttributeObjectPostProcessor recognizes lifecycle attributes such as [PostConstruct] and [PreDestroy]. Introduced in Spring.Net 2.0, the support for these attributes offers yet another alternative to those described in initialization callbacks and destruction callbacks. Provided that the InitDestroyAttributeObjectPostProcessor is registered within the Spring ApplicationContext, a method carrying one of these attributions is invoked at the same point in the lifecycle as the corresponding Spring lifecycle interface method or explicitly declared callback method. In the example below, the cache will be pre-populated upon initialization and cleared upon destruction.

The best way to illustrate the usage of this attribute is with an example.

public class MovieLister
{
  [PostConstruct]
  public void Init()
  {
    // do some initialization here
  }

  [PreDestroy]
  public void Destroy()
  {
    // do some destruction here
  }

  ...
}

There is one last little piece of Spring configuration that is required to actually 'switch on' this behaviour. Simply annotating the methods of your classes is not enough to get this behaviour. You need to enable a component that is aware of the [PostContrsuct] and [PreDestroy] attribute and that can process it appropriately.

This component is the InitDestroyAttributeObjectPostProcessor class. This is a special IObjectPostProcessor implementation that is [PostConstruct]- and [PreDestroy]-aware and actually provides the lifecycle logic. It is very easy to configure; simply drop the following object definition into your Spring XML configuration.

<object type="Spring.Objects.Factory.Attributes.InitDestroyAttributeObjectPostProcessor, Spring.Core"/>

Finally, you can configure an instance of the InitDestroyAttributeObjectPostProcessor class to look for other Attribute types. Simply plug it into the definition of a InitDestroyAttributeObjectPostProcessor and you are good to go, see example below:

<object type="Spring.Objects.Factory.Attributes.InitDestroyAttributeObjectPostProcessor, Spring.Core">
  <property name="InitAttributeType" value="MyApp.Attributes.InitAttribute, MyApp"/>
  <property name="DestroyAttributeType" value="MyApp.Attributes.DisposeAttribute, MyApp"/>
</object>

When you write initialization and destroy method callbacks that do not use the Spring-specific IInitializingObject and IDisposable callback interfaces, you typically write methods with names such as Init(), Initialize(), Dispose(), and so on. Ideally, the names of such lifecycle callback methods are standardized across a project so that all developers use the same method names and ensure consistency.

You can configure the Spring container to look for named initialization and destroy callback method names on every object. This means that you, as an application developer, can write your application classes and use an initialization callback called Init(), without having to configure an init-method="Init" attribute with each object definition. The Spring IoC container calls that method when the object is created (and in accordance with the standard lifecycle callback contract described previously). This feature also enforces a consistent naming convention for initialization and destroy method callbacks.

Suppose that your initialization callback methods are named Init() and destroy callback methods are named Destroy(). Your class will resemble the class in the following example.

public class DefaultBlogService : IBlogService
{
  private IBlogDao _blogDao;

  public void Init()
  {
      if (_blogDao == null) {
          throw new InvalidOperationException("The [_blogDao] property must be set.");
      }
  }

  public void Destroy()
  {
    // do some destruction work
  }
}

<objects default-init-method="Init"
         defauly-destroy-method="Destroy">

  <object id="BlogService" class="Examples.DefaultBlogService">
      <property name="_blogDao" ref="BlogDao" />
  </object>

</objects>

The presence of the default-init-method attribute on the top-level <objects/> element attribute causes the Spring IoC container to recognize a method called Init on objects as the initialization method callback. When an object is created and assembled, if the object class has such a method, it is invoked at the appropriate time. If the object does not have such a method an ObjectCreationException is thrown. To prevent this for objects that do not have such a method you need to define an empty init-method="" and/or destroy-method="" attributes on the object itself.

Where existing object classes already have callback methods that are named at variance with the convention, you can override the default by specifying (in XML, that is) the method name using the init-method and destroy-method attributes on the <object/> itself.

The Spring container guarantees that a configured initialization callback is called immediately after an object is supplied with all dependencies. Thus the initialization callback is called on the raw object reference, which means that AOP interceptors and so forth are not yet applied to the object. A target object is fully created first, then an AOP proxy (for example) with its interceptor chain is applied. If the target object and the proxy are defined separately, your code can even interact with the raw target object, bypassing the proxy. Hence, it would be inconsistent to apply the interceptors to the Init method, because doing so would couple the lifecycle of the target object with its proxy/interceptors and leave strange semantics when your code interacts directly to the raw target object.

When an IApplicationContext creates a class that implements the Spring.Objects.Factory.IObjectNameAware interface, the class is provided with a reference to the name defined in its associated object definition.

public interface IObjectNameAware 
{
    string ObjectName { set; }
}

The callback is invoked after population of normal object properties but before an initialization callback such as IInitializingObject 's AfterPropertiesSet method or a custom initialization method is invoked.

This first example is hardly compelling, but serves to illustrate basic usage. All we are going to do is code a custom IObjectPostProcessor implementation that simply invokes the ToString() method of each object as it is created by the container and prints the resulting string to the system console. Yes, it is not hugely useful, but serves to get the basic concepts across before we move into the second example which is actually useful. The basis of the example is the MovieFinder quickstart that is included with the Spring.NET distribution.

Find below the custom IObjectPostProcessor implementation class definition

using System;
using Spring.Objects.Factory.Config;

namespace Spring.IocQuickStart.MovieFinder
{
    public class TracingObjectPostProcessor : IObjectPostProcessor
    {
        public object PostProcessBeforeInitialization(object instance, string name)
        {
            return instance;
        }

        public object PostProcessAfterInitialization(object instance, string name)
        {
            Console.WriteLine("Object '" + name + "' created : " + instance.ToString());
            return instance;
        }
    }
}

And the following configuration

<?xml version="1.0" encoding="utf-8" ?>
<objects xmlns="http://www.springframework.net" >
  <description>An example that demonstrates simple IoC features.</description>

  <object id="MyMovieLister" 
          type="Spring.IocQuickStart.MovieFinder.MovieLister, Spring.IocQuickStart.MovieFinder">
    <property name="movieFinder" ref="MyMovieFinder"/>
  </object>

  <object id="MyMovieFinder" 
          type="Spring.IocQuickStart.MovieFinder.SimpleMovieFinder, Spring.IocQuickStart.MovieFinder"/>

  <!-- when the above objects are instantiated, this custom IObjectPostProcessor implementation 
       will output the fact to the system console -->
  <object type="Spring.IocQuickStart.MovieFinder.TracingObjectPostProcessor, Spring.IocQuickStart.MovieFinder"/>
</objects>

Notice how the TracingObjectPostProcessor is simply defined; it doesn't even have a name, and because it is a object it can be dependency injected just like any other object.

Find below a small driver script to exercise the above code and configuration;

IApplicationContext ctx =
        new XmlApplicationContext(
            "assembly://Spring.IocQuickStart.MovieFinder/Spring.IocQuickStart.MovieFinder/AppContext.xml");

MovieLister lister = (MovieLister) ctx.GetObject("MyMovieLister");
Movie[] movies = lister.MoviesDirectedBy("Roberto Benigni");
LOG.Debug("Searching for movie...");
foreach (Movie movie in movies)
{
  LOG.Debug(string.Format("Movie Title = '{0}', Director = '{1}'.", movie.Title, movie.Director));
}
LOG.Debug("MovieApp Done.");

The output of executing the above program will be:

INFO  - Object 'Spring.IocQuickStart.MovieFinder.TracingObjectPostProcessor' is not eligible for being processed by all IObjectPostProcessors 
       (for example: not eligible for auto-proxying).
Object 'MyMovieFinder' created : Spring.IocQuickStart.MovieFinder.SimpleMovieFinder
Object 'MyMovieLister' created : Spring.IocQuickStart.MovieFinder.MovieLister
DEBUG - Searching for movie...
DEBUG - Movie Title = 'La vita e bella', Director = 'Roberto Benigni'.
DEBUG - MovieApp Done.

Using callback interfaces or attributes in conjunction with a custom IObjectPostProcessor implementation is a common means of extending the Spring IoC container. The [Required] attribute in the Spring.Objects.Factory.Attributes namespace can be used to mark a property as being 'required-to-be-set' (i.e. an setter property with this attribute applied must be configured to be dependency injected with a value), else an ObjectInitializationException will be thrown by the container at runtime.

The best way to illustrate the usage of this attribute is with an example.

public class MovieLister
{
  // the MovieLister has a dependency on the MovieFinder
  private IMovieFinder _movieFinder;

  // a setter property so that the Spring container can 'inject' a MovieFinder
  [Required]
  public IMovieFinder MovieFinder
  {
    set { _movieFinder = value; }  
  }

  // business logic that actually 'uses' the injected MovieFinder is omitted...

}

Hopefully the above class definition reads easy on the eye. Any and all IObjectDefinitions for the MovieLister class must be provided with a value.

Let's look at an example of some XML configuraiton that will not pass validation.

<object id="MyMovieLister" 
          type="Spring.IocQuickStart.MovieFinder.MovieLister, Spring.IocQuickStart.MovieFinder">
      <!-- whoops, no MovieFinder is set (and this property is [Required]) -->
  </object>

At runtime the following message will be generated by the Spring container

Error creating context 'spring.root': Property 'MovieFinder' required for object 'MyMovieLister'

There is one last little piece of Spring configuration that is required to actually 'switch on' this behavior. Simply annotating the 'setter' properties of your classes is not enough to get this behavior. You need to enable a component that is aware of the [Required] attribute and that can process it appropriately.

This component is the RequiredAttributeObjectPostProcessor class. This is a special IObjectPostProcessor implementation that is [Required]-aware and actually provides the 'blow up if this required property has not been set' logic. It is very easy to configure; simply drop the following object definition into your Spring XML configuration.

<object type="Spring.Objects.Factory.Attributes.RequiredAttributeObjectPostProcessor, Spring.Core"/>

Finally, one can configure an instance of the RequiredAttributeObjectPostProcessor class to look for another Attribute type. This is great if you already have your own [Required]-style attribute. Simply plug it into the definition of a RequiredAttributeObjectPostProcessor and you are good to go. By way of an example, let's suppose you (or your organization / team) have defined an attribute called [Mandatory]. You can make a RequiredAttributeObjectPostProcessor instance [Mandatory]-aware like so:

<object type="Spring.Objects.Factory.Attributes.RequiredAttributeObjectPostProcessor, Spring.Core">
  <property name="RequiredAttributeType" value="MyApp.Attributes.MandatoryAttribute, MyApp"/>
</object>

The PropertyPlaceholderConfigurer is an excellent solution when you want to externalize a few properties from a file containing object definitions. This is useful to allow the person deploying an application to customize environment specific properties (for example database configuration strings, user names, and passwords), without the complexity or risk of modifying the main XML definition file or files for the container.

Variable substitution is performed on simple property values, lists, dictionaries, sets, constructor values, object type name, and object names in runtime object references. Furthermore, placeholder values can also cross-reference other placeholders.

Note that IApplicationContexts are able to automatically recognize and apply objects deployed in them that implement the IObjectFactoryPostProcessor interface. This means that as described here, applying a PropertyPlaceholderConfigurer is much more convenient when using an IApplicationContext. For this reason, it is recommended that users wishing to use this or other object factory postprocessors use an IApplicationContext instead of an IObjectFactory.

In the example below a data access object needs to be configured with a database connection and also a value for the maximum number of results to return in a query. Instead of hard coding the values into the main Spring.NET configuration file we use place holders, in the NAnt style of ${variableName}, and obtain their values from NameValueSections in the standard .NET application configuration file. The Spring.NET configuration file looks like:

<configuration>

  <configSections>
    <sectionGroup name="spring">
      <section name="context" type="Spring.Context.Support.ContextHandler, Spring.Core"/>
    </sectionGroup>
    <section name="DaoConfiguration" type="System.Configuration.NameValueSectionHandler"/>
    <section name="DatabaseConfiguration" type="System.Configuration.NameValueSectionHandler"/>
  </configSections>

  <DaoConfiguration>
    <add key="maxResults" value="1000"/>
  </DaoConfiguration>
  
  <DatabaseConfiguration>
    <add key="connection.string" value="dsn=MyDSN;uid=sa;pwd=myPassword;"/>
  </DatabaseConfiguration>
  
  <spring>
    <context>
      <resource uri="assembly://DaoApp/DaoApp/objects.xml"/>
    </context>
  </spring>

</configuration>

Notice the presence of two NameValueSections in the configuration file. These name value pairs will be referred to in the Spring.NET configuration file. In this example we are using an embedded assembly resource for the location of the Spring.NET configuration file so as to reduce the chance of accidental tampering in deployment. This Spring.NET configuration file is shown below.

<objects xmlns="http://www.springframework.net" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xsi:schemaLocation="http://www.springframework.net
         http://www.springframework.net/xsd/spring-objects.xsd" >
    
  <object name="productDao" type="DaoApp.SimpleProductDao, DaoApp ">
    <property name="maxResults" value="${maxResults}"/>
    <property name="dbConnection" ref="myConnection"/>
  </object>
   
  <object name="myConnection" type="System.Data.Odbc.OdbcConnection, System.Data"> 
    <property name="connectionstring" value="${connection.string}"/> 
  </object>

  <object name="appConfigPropertyHolder" 
          type="Spring.Objects.Factory.Config.PropertyPlaceholderConfigurer, Spring.Core">
    <property name="configSections">          
      <value>DaoConfiguration,DatabaseConfiguration</value>                              
    </property>              
  </object>

</objects>

The values of ${maxResults} and ${connection.string} match the key names used in the two NameValueSectionHandlers DaoConfiguration and DatabaseConfiguration. The PropertyPlaceholderConfigurer refers to these two sections via a comma delimited list of section names in the configSections property. If you are using section groups, prefix the section group name, for example myConfigSection/DaoConfiguraiton.

The PropertyPlaceholderConfigurer class also supports retrieving name value pairs from other IResource locations. These can be specified using the Location and Locations properties of the PropertyPlaceHolderConfigurer class.

If there are properties with the same name in different resource locations the default behavior is that the last property processed overrides the previous values. This is behavior is controlled by the LastLocationOverrides property. True enables overriding while false will append the values as one would normally expect using NameValueCollection.Add.

	Note
	In an ASP.NET environment you must specify the full, four-part name of the assembly when using a NameValueFileSectionHandler <section name="hibernateConfiguration" type="System.Configuration.NameValueFileSectionHandler, System, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>

<object id="MyMovieFinder" type="${custom.moviefinder.type}"/>

<object id="TestObject" type="Simple.TestObject, MyAssembly">
  <property name="age" expression="${ageExpression}"/>
  <property name="spouse" ref="${spouse-ref}"/>
</object>

<object name="appConfigPropertyHolder" 
        type="Spring.Objects.Factory.Config.PropertyPlaceholderConfigurer, Spring.Core">
        <property name="configSections" value="DaoConfiguration,DatabaseConfiguration"/>
        <property name="EnvironmentVariableMode" value="Override"/>
    </object>
</objects>

The PropertyOverrideConfigurer, another object factory post-processor, is similar to the PropertyPlaceholderConfigurer, but in contrast to the latter, the original definitions can have default values or no values at all for object properties. If an overriding configuration file does not have an entry for a certain object property, the default context definition is used.

Note that the object factory definition is not aware of being overridden, so it is not immediately obvious when looking at the XML definition file that the override configurer is being used. In case that there are multiple PropertyOverrideConfigurer instances that define different values for the same object property, the last one will win (due to the overriding mechanism).

The example usage is similar to when using PropertyPlaceHolderConfigurer except that the key name refers to the name given to the object in the Spring.NET configuration file and is suffixed via 'dot' notation with the name of the property For example, if the application configuration file is

<configuration>
  <configSections>
    <sectionGroup name="spring">
      <section name="context" type="Spring.Context.Support.ContextHandler, Spring.Core"/>
    </sectionGroup>
    <section name="DaoConfigurationOverride" type="System.Configuration.NameValueSectionHandler"/>
  </configSections>

  <DaoConfigurationOverride>
    <add key="productDao.maxResults" value="1000"/>
  </DaoConfigurationOverride>
  
  <spring>
    <context>
      <resource uri="assembly://DaoApp/DaoApp/objects.xml"/>
    </context>
  </spring>

</configuration>

Then the value of 1000 will be used to overlay the value of 2000 set in the Spring.NET configuration file shown below

<objects xmlns="http://www.springframework.net" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xsi:schemaLocation="http://www.springframework.net http://www.springframework.net/xsd/spring-objects.xsd" >

    <object name="productDao" type="PropPlayApp.SimpleProductDao, PropPlayApp " >
      <property name="maxResults" value="2000"/>
      <property name="dbConnection" ref="myConnection"/>
      <property name="log" ref="daoLog"/>
    </object>
    
    <object name="daoLog" type="Spring.Objects.Factory.Config.LogFactoryObject, Spring.Core">
      <property name="logName" value="DAOLogger"/>
    </object>
    
    <object name="myConnection" type="System.Data.Odbc.OdbcConnection, System.Data"> 
      <property name="connectionstring"> 
        <value>dsn=MyDSN;uid=sa;pwd=myPassword;</value>
      </property> 
    </object> 

    <object name="appConfigPropertyOverride" type="Spring.Objects.Factory.Config.PropertyOverrideConfigurer, Spring.Core">
      <property name="configSections">          
        <value>DaoConfigurationOverride</value>                              
      </property> 
    </object>

</objects>

The VariablePlaceholderConfigurer is an evolution of the PropertyPlaceHolderConfigurer. Out of the box, Spring.NET supports a number of variable sources that allow users to obtain variable values from .NET configuration files, Java-style property files, environment variables, command line arguments, the registry and the new connection strings configuration section in .NET 2.0. It is possible to add your own variable sources to a VariablePlaceholderConfigurer by implementing the IVariableSource interface.

You use this by defining an instance of Spring.Objects.Factory.Config.VariablePlaceholderConfigurer in your configuration and set the property VariableSource to a single IVariableSource instance or the list property VariableSources to a list of IVariableSource instances. In the case of the same property defined in multiple IVariableSource implementations, the first one in the list that contains the property value will be used.

<object type="Spring.Objects.Factory.Config.VariablePlaceholderConfigurer, Spring.Core">
  <property name="VariableSources">
    <list>
      <object type="Spring.Objects.Factory.Config.PropertyFileVariableSource, Spring.Core">
        <property name="Location" value="~\application.properties" />        
      </object>
      <object type="Spring.Objects.Factory.Config.ConfigSectionVariableSource, Spring.Core">
        <property name="SectionNames" value="CryptedConfiguration" />
      </object>
    </list>
  </property>
</object>     

The variable sources that Spring.NET provides out of the box are described in the following sections.

5.9.2.3.1. ConfigSectionVariableSource

The ConfigSectionVariableSource allows you to define variables in a custom configuration section in your configuration file:

<!-- app.config: -->
<configuration>
  <configSections>
    <section name="DonConfiguration" type="System.Configuration.NameValueSectionHandler"/>
  </configSections>
  <DonConfiguration>
    <add key="don_name" value="Dick Whitman"/>
    <add key="don_age" value="41" />
  </DonConfiguration>
</configuration>

<!-- VariableSource configuration: -->
<object type="Spring.Objects.Factory.Config.ConfigSectionVariableSource, Spring.Core">
  <property name="SectionNames" value="DonConfiguration" />
</object>

<!-- consume variables: -->
<object type="Example.Person, Spring.IocQuickStart.VariableSources">
  <property name="Name" value="${don_name}" />
  <property name="Age" value="${don_age}" />
</object>

This is similar to using the PropertyPlaceHolderConfigurer described above.

By simply configuring the appropriate section, you can use the ConfigSectionVariableSource to retrieve variables from .NET's application settings and user settings. Assuming your application's root namespace is MyApp, then your application- and user settings can be loaded as variables by configuring the following variable sources:

<!-- From .net's ApplicationSettings: -->
<object type="Spring.Objects.Factory.Config.ConfigSectionVariableSource, Spring.Core">
  <property name="SectionNames" value="applicationSettings/MyApp.Properties.Settings" />
</object>

<!-- From .net's UserSettings: -->
<object type="Spring.Objects.Factory.Config.ConfigSectionVariableSource, Spring.Core">
  <property name="SectionNames" value="userSettings/MyApp.Properties.Settings" />
</object>

If you configured your application settings as such:

Then you can use ${peggy_name}, ${peggy_age}, &{peter_name} and ${peter_age} as variables in your object definitions. They will be retrieved using the appropriate scope.

Note

Changes to user settings during the lifetime of your application context will not be be visible to the ConfigSectionVariableSource. Although variables based on user settings will be resolved using user scope, variables will only be resolved when the VariablePlaceholderConfigurer is initialized: that is when the context is created. Any object (including lazy-loaded singletons and non-singletons) you retrieve from the context will have the variable values injected as they were when the context was loaded.

5.9.2.3.2. PropertyFileVariableSource

A PropertyFileVariableSource allows to read properties defined in a Java-style property file as variables. Assume a file named application.properties in your application folder containing the following lines:

joan_name=Joan Harris
joan_age=35

You can use the ${joan_name} and ${joan_age} variables in your object definitions if you configure the following variable source:

<object type="Spring.Objects.Factory.Config.PropertyFileVariableSource, Spring.Core">
  <property name="Location" value="~\application.properties" />               <!-- specify a single ...  -->
  <property name="Locations" value="~\file1.properties,~\file2.properties" /> <!-- or multiple locations -->
  <property name="IgnoreMissingResources" value="true"/>
</object>

	Note
	The use of the IgnoreMissingResources property above will mean that if the property file is not found it will be silently ignored and the resolution will continue to the next variable source(s) of the VariablePlaceholderConfigurer.

Within PropertyFileVariableSources, precedence rules differ from the configuration of VariableSources in the VariablePlaceholderConfigurer. When the same property occurs more than once in a property file, the value of the last entry will be used. Same goes for specifying the same variable in more than one location in a single PropertyFileVariableSource: the entry from the last file will be used.

<object type="Spring.Objects.Factory.Config.ConfigurableVariableSource, Spring.Core">
  <property name="Variables">
    <name-values>
      <add key="midge_name" value="Midge Daniels"/>
      <add key="midge_age" value="33"/>
    </name-values>
  </property>
</object>

myapp /roger_name:"Roger Sterling" /roger_age:57

<object type="Spring.Objects.Factory.Config.CommandLineArgsVariableSource, Spring.Core">
  <property name="ArgumentPrefix" value ="/" /> <!-- optional; default: "/" -->
  <property name="ValueSeparator" value=":" />  <!-- optional; default: ":" -->
</object>

5.9.2.3.5. RegistryVariableSource

Entries in the Windows registry can be used as variables. When your registry contains the key HKEY_CURRENT_USER\MyKey with entries freddy_name and freddy_age, then you can configure the following variable source to use ${freddy_name} and ${freddy_age} as variables:

<object type="Spring.Objects.Factory.Config.RegistryVariableSource, Spring.Core">
  <property name="Key" value="HKEY_CURRENT_USER\MyKey" />
</object>

	Note
	The key must be present in the registry when the configuration is read, otherwise an ObjectCreationException will be thrown.

<object type="Spring.Objects.Factory.Config.EnvironmentVariableSource, Spring.Core" />

5.9.2.3.7. ConnectionStringsVariableSource

Visual Studio has support for configuring database connection strings in a connectionStrings section in your application configuration file. You can retrieve these connections as variables by configuring a ConnectionStringsVariableSource:

<object type="Spring.Objects.Factory.Config.ConnectionStringsVariableSource, Spring.Core" />

Assuming the following connection strings section in your application configuration file:

<connectionStrings>
  <add name="myConnection" 
       connectionString="Data Source=myserver;Integrated Security=True;..." 
       providerName="System.Data.SqlClient" />
</connectionStrings>

Then you would use the variables as in following object definition:

<object type="Example.MyClass, MyAssembly">
  <property name="ConnectionString" value="${myConnection.connectionString}" />
  <property name="ProviderName" value="${myConnection.providerName}" />
</object> 

	Note
	Append ".connectionString" to the connection name to get the connection string and append ".providerName" to the connection name to get the provider name.

	Note
	When adding a connection using Visual Studio's application settings user interface, your connection will be named similar to MyApp.Properties.Settings.myConnection and the corresponding variable name for the connection string would become MyApp.Properties.Settings.myConnection.connectionString.

<object type="Spring.Objects.Factory.Config.SpecialFolderVariableSource, Spring.Core" />

<object id="specials" type="Example.Specials, Spring.IocQuickStart.VariableSources">
  <property name="FullPathToDesktop" value="${Desktop}" />
  <property name="FullPathToPrgramFiles" value="${ProgramFiles}" />
</object>

public interface IVariableSource
{
  bool CanResolveVariable(string name);
  string ResolveVariable(string name);
}

The Spring.Objects.Factory.IConfigurableFactoryObject interface inherits from IFactoryObject interface and adds the following property.

IConfigurableFactoryObject implementions you already have examples of in Section 29.3, “Client-side” are WebServiceProxyFactory.