Using Lifetime Managers

The Unity container manages the creation and resolution of objects based on a lifetime you specify when you register the type of an existing object, or on the default lifetime if you do not specify a lifetime manager for it to use.

When you register a type using the RegisterType method, the default behavior is for the container to use a transient lifetime manager. It will create a new instance of the registered, mapped, or requested type each time you call the Resolve or ResolveAll method or when the dependency mechanism injects instances into other classes based on attributes or constructor parameters within that class. The container will not store a reference to the object. However, when you want singleton behavior for objects Unity creates, the container must store a reference to these objects. It also takes over management of the lifetime of the objects.

Unity uses specific types that inherit from the LifetimeManager base class (collectively referred to as lifetime managers) to control how it stores references to object instances, and how the container will dispose of these instances.

When you register an existing object using the RegisterInstance method, the default behavior is for the container to take over management of the lifetime of the object you pass to this method using the ContainerControlledLifetimeManager. This means that the existing object will remain in scope as long as the container is in scope, and will be disposed when the container goes out of scope and is garbage-collected—or when code explicitly disposes the container. You can also use this lifetime manager with the RegisterType method to specify that Unity should manage the object as a singleton instance.

The Unity Application Block includes two lifetime managers that you can use directly in your code, but you can create your own lifetime managers to implement specific lifetime scenarios. Unity includes the following lifetime managers:

ContainerControlledLifetimeManager. Unity will return the same instance of the registered type or object each time you call the Resolve or ResolveAll method or when the dependency mechanism injects instances into other classes based on attributes or constructor parameters within that class. This lifetime manager effectively implements a singleton behavior for objects. Unity uses this lifetime manager by default for the RegisterInstance method if you do not specify a different lifetime manager. If you want singleton behavior for an object that Unity will create when you use the RegisterType method, you must explicitly specify this lifetime manager. The behavior is as follows:

• If you used the RegisterType method to register a type, Unity will create a new instance of the registered type during the first call to the Resolve or ResolveAll method or when the dependency mechanism injects instances into other classes based on attributes or constructor parameters within that class. Subsequent requests will return the same instance.
• If you used the RegisterInstance method to register an existing object, Unity will return this instance every time you call the Resolve or ResolveAll method or when the dependency mechanism injects instances into other classes based on attributes or constructor parameters within that class.

ExternallyControlledLifetimeManager. This lifetime manager allows you to register type mappings and existing objects with the container so that it will maintain only a weak reference to the objects it creates when you call the Resolve or ResolveAll method or when the dependency mechanism injects instances into other classes based on attributes or constructor parameters within that class. Unity will return the same instance of the registered type or object each time you call the Resolve or ResolveAll method or when the dependency mechanism injects instances into other classes based on attributes or constructor parameters within that class. However, the container does not hold onto a strong reference to the object after it creates it, which means that the garbage collector can dispose of the object if no other code is holding a strong reference to it.

The following sections show some examples of how you can use lifetime managers with the RegisterType and RegisterInstance methods to specify the container behavior:

• Using a Lifetime Manager with the RegisterType Method
• Using a Lifetime Manager with the RegisterInstance Method

Using a Lifetime Manager with the RegisterType Method

The following code shows how you can use the RegisterType method with a lifetime manager to specify the container behavior. It shows how you can generate both default and named mappings for a type registration. This example uses the generic overloads of the container methods.

IUnityContainer myContainer = new UnityContainer();

// Register a default (un-named) type mapping with a transient lifetime
myContainer.RegisterType<IMyObject, MyRealObject>();
// Following code will return a new instance of MyRealObject
myContainer.Resolve<IMyObject>();

// Register a named type mapping with a transient lifetime
myContainer.RegisterType<IMyObject, MyRealObject>("MyMapping");
// Following code will return a new instance of MyRealObject
myContainer.Resolve<IMyObject>("MyMapping");

// Specify a default type mapping with an externally-controlled lifetime
myContainer.RegisterType<IMyObject, MyRealObject>(new ExternallyControlledLifetimeManager());
// Following code will return a singleton instance of MyRealObject
// Container will hold only a weak reference to the object
myContainer.Resolve<IMyObject>();

// Same as above, but with a name for the registration
myContainer.RegisterType<IMyObject, MyRealObject>("MyMapping", new ExternallyControlledLifetimeManager());
// Following code will return a singleton instance of MyRealObject
// Container will hold only a weak reference to the object
myContainer.Resolve<IMyObject>("MyMapping");

// Register a default (un-named) type mapping with a singleton lifetime
myContainer.RegisterType<IMyObject, MySingletonObject>(new ContainerControlledLifetimeManager());
// Following code will return a singleton instance of MySingletonObject
// Container will take over lifetime management of the object
myContainer.Resolve<IMyObject>();

// Register a named type mapping with a singleton lifetime
myContainer.RegisterType<IMyObject, MySingletonObject>("MyMapping", new ContainerControlledLifetimeManager());
// Following code will return a singleton instance of MySingletonObject
// Container will take over lifetime management of the object
myContainer.Resolve<IMyObject>();

// Register a type to have a singleton lifetime without mapping the type
// Uses the container only to implement singleton behavior
myContainer.RegisterType<MySingletonObject>(new ContainerControlledLifetimeManager());
// Following code will return a singleton instance of MySingletonObject
// Container will take over lifetime management of the object
myContainer.Resolve<MySingletonObject>();

// Same as above, but specify a name for the registration
myContainer.RegisterType<MySingletonObject>("MyMapping", new ContainerControlledLifetimeManager());
// Following code will return a singleton instance of MySingletonObject
// Container will take over lifetime management of the object
myContainer.Resolve<MySingletonObject>("MyMapping");

'Usage
Dim myContainer As IUnityContainer = New UnityContainer()

' Register a default (un-named) type mapping with a transient lifetime
myContainer.RegisterType(Of IMyObject, MyRealObject)()
' Following code will return a new instance of MyRealObject
myContainer.Resolve(Of IMyObject)()

' Register a named type mapping with a transient lifetime
myContainer.RegisterType(Of IMyObject, MyRealObject)("MyMapping")
' Following code will return a new instance of MyRealObject
myContainer.Resolve(Of IMyObject)("MyMapping")

' Specify a default type mapping with an externally-controlled lifetime
myContainer.RegisterType(Of IMyObject, MyRealObject)(new ExternallyControlledLifetimeManager())
' Following code will return a singleton instance of MyRealObject
' Container will hold only a weak reference to the object
myContainer.Resolve(Of IMyObject)()

' Same as above, but with a name for the registration
myContainer.RegisterType(Of IMyObject, MyRealObject)("MyMapping", new ExternallyControlledLifetimeManager())
' Following code will return a singleton instance of MyRealObject
' Container will hold only a weak reference to the object
myContainer.Resolve(Of IMyObject)("MyMapping")

' Register a default (un-named) type mapping with a singleton lifetime
myContainer.RegisterType(Of IMyObject, MySingletonObject)(new ContainerControlledLifetimeManager())
' Following code will return a singleton instance of MySingletonObject
' Container will take over lifetime management of the object
myContainer.Resolve(Of IMyObject)()

' Register a named type mapping with a singleton lifetime
myContainer.RegisterType(Of IMyObject, MySingletonObject)("MyMapping", new ContainerControlledLifetimeManager())
' Following code will return a singleton instance of MySingletonObject
' Container will take over lifetime management of the object
myContainer.Resolve(Of IMyObject)()

' Register a type to have a singleton lifetime without mapping the type
' Uses the container only to implement singleton behavior
myContainer.RegisterType(Of MySingletonObject)(new ContainerControlledLifetimeManager())
' Following code will return a singleton instance of MySingletonObject
' Container will take over lifetime management of the object
myContainer.Resolve(Of MySingletonObject)()

' Same as above, but specify a name for the registration
myContainer.RegisterType(Of MySingletonObject)("MySingleton", new ContainerControlledLifetimeManager())
' Following code will return a singleton instance of MySingletonObject
' Container will take over lifetime management of the object
myContainer.Resolve(Of MySingletonObject)("MySingleton")

Using a Lifetime Manager with the RegisterInstance Method

The following code shows how you can use the RegisterInstance method with a lifetime manager to specify the container behavior. It also shows how you can generate both default and named mappings when you register an existing object. This example uses the generic overloads of the container methods.

IUnityContainer myContainer = new UnityContainer();

// Register an existing object as a default (un-named) registration with 
// the default container-controlled lifetime. 
myContainer.RegisterInstance<IMyObject>(MyRealObject);
// Following code will return a singleton instance of MyRealObject
// Container will take over lifetime management of the object
myContainer.Resolve<IMyObject>();

// Register an existing object as a named registration with the default
// container-controlled lifetime.
myContainer.RegisterInstance<IMyObject>("MySingleton", MyRealObject);
// Following code will return a singleton instance of MyRealObject
// Container will take over lifetime management of the object
myContainer.Resolve<IMyObject>("MySingleton");

// Same as above, but specify the default lifetime manager
myContainer.RegisterInstance<IMyObject>("MySingleton", MyRealObject, new ContainerControlledLifetimeManager());
// Following code will return a singleton instance of MyRealObject
// Container will take over lifetime management of the object
myContainer.Resolve<IMyObject>("MySingleton");

// Register an existing object as a default (un-named) registration 
// with an externally controlled lifetime.
myContainer.RegisterInstance<IMyObject>(MyRealObject, new ExternallyControlledLifetimeManager());
// Following code will return a singleton instance of MyRealObject
// Container will hold only a weak reference to the object
myContainer.Resolve<IMyObject>();

// Register an existing object as a named registration 
// with an externally controlled lifetime.
myContainer.RegisterInstance<IMyObject>("MySingleton", MyRealObject, new ExternallyControlledLifetimeManager());
// Following code will return a singleton instance of MyRealObject
// Container will hold only a weak reference to the object
myContainer.Resolve<IMyObject>("MySingleton");

'Usage
Dim myContainer As IUnityContainer = New UnityContainer()

' Register an existing object as a default (un-named) registration with 
' the default container-controlled lifetime. 
myContainer.RegisterInstance(Of IMyObject)(MyRealObject)
' Following code will return a singleton instance of MyRealObject
' Container will take over lifetime management of the object
myContainer.Resolve(Of IMyObject)()

' Register an existing object as a named registration with the default
' container-controlled lifetime.
myContainer.RegisterInstance(Of IMyObject)("MySingleton", MyRealObject)
' Following code will return a singleton instance of MyRealObject
' Container will take over lifetime management of the object
myContainer.Resolve(Of IMyObject)("MySingleton")

' Same as above, but specify the default lifetime manager
myContainer.RegisterInstance(Of IMyObject)("MySingleton", MyRealObject, new ContainerControlledLifetimeManager())
' Following code will return a singleton instance of MyRealObject
' Container will take over lifetime management of the object
myContainer.Resolve(Of IMyObject)("MySingleton")

' Register an existing object as a default (un-named) registration 
' with an externally controlled lifetime.
myContainer.RegisterInstance(Of IMyObject)(MyRealObject, new ExternallyControlledLifetimeManager())
' Following code will return a singleton instance of MyRealObject
' Container will hold only a weak reference to the object
myContainer.Resolve(Of IMyObject)()

' Register an existing object as a named registration 
' with an externally controlled lifetime.
myContainer.RegisterInstance(Of IMyObject)("MySingleton", MyRealObject, new ExternallyControlledLifetimeManager())
' Following code will return a singleton instance of MyRealObject
' Container will hold only a weak reference to the object
myContainer.Resolve(Of IMyObject)("MySingleton")