Creating Instance Registrations

This topic explains how to register existing objects in the container that you can resolve in your application. This technique is useful if you already have an instance of an object that you have previously created and want Unity to manage its lifetime, or if you want Unity to inject that object into other objects that it is resolving.

The RegisterInstance method registers an existing instance with the container. You specify the instance type and optional lifetime in the parameter list. The container will return the specified existing instance for the duration of the specified lifetime. The RegisterInstance method overloads are very similar to the RegisterType method overloads, but they accept an additional parameter, the object instance to register. The use of the registration type and an optional name are identical for the two methods.

When resolving types with dependencies, instances of objects added to the container with the RegisterInstance method act just like those registered through RegisterType. The RegisterType method with a ContainerControlledLifetimeManager automatically generates this single instance the first time your code calls it, while the RegisterInstance method accepts an existing instance for which it will return references. If you do not specify a lifetime manager, the container will use a ContainerControlledLifetimeManager and it will return a reference to the original object on each call to Resolve.

This topic contains the following sections, which explain the use of the RegisterInstance method:

• Registering an Existing Object Instance of an Interface or Type to a Container
• Using a Lifetime Manager with the RegisterInstance Method
• Summary of the RegisterInstances Method Overloads
• More Information on Using the RegisterInstance Method

Registering an Existing Object Instance of an Interface or Type to a Container

Instance registration is similar to type registration, except that instead of the container creating the instance you first create the instance directly and then use the RegisterInstance method to add that instance to the container. Therefore, the container does not need to create the instance on the first Resolve request. The LifetimeManager still controls the lifetime of the object, including when object instances are created and disposed, and the container returns the existing instance for the duration of the specified lifetime. For example, you first create the instance but the lifetime manager determines whether that instance is a singleton or has a per-thread lifetime.

The Unity container exposes overloads of the RegisterInstance method that allow you to register dependency injection mappings that return references to a single existing instance of an object. Each of these methods accepts a type parameter that identifies the object interface or type and an existing instance of the object. Optionally, you can provide a name to disambiguate instances when there is more than one registration for the same type. In all cases you must first create or obtain a reference to a container.

Once you have a reference to the proper container, call the RegisterInstance method of that container to register the existing object. Specify as the registration type an interface that the target object implements, an object type from which the target object inherits, or the concrete type of the target object.

The following example creates a default (unnamed) registration for an object of type EmailService that implements the IMyService interface.

EmailService myEmailService = new EmailService();
myContainer.RegisterInstance<IMyService>(myEmailService);

Dim myEmailService As New EmailService()
myContainer.RegisterInstance(Of IMyService)(myEmailService)

The registration type controls how you will retrieve objects from the container. It is the type that you will specify when you call the Resolve or ResolveAll method to retrieve the concrete object instance. In this case, IMyService theDataService = myContainer.Resolve<IMyService>().

If you do not want to map the existing object type to an interface or base class type, you can specify the actual concrete type, myEmailService, for the registered type, EmailService, as shown in the following example.

myContainer.RegisterInstance<EmailService>(myEmailService);

myContainer.RegisterInstance(Of EmailService)(myEmailService)

If you want to create more than one existing object registration using the same registered type, you can create named (non-default) mappings by specifying a name as a parameter, such as "Email" as shown in the following example.

myContainer.RegisterInstance<EmailService>("Email", myEmailService);

myContainer.RegisterInstance(Of EmailService)("Email", myEmailService)

If you want to manage the instance lifetime, provide a reference to the existing object and an instance of the lifetime manager. The following example creates a default (unnamed) externally managed registration using an interface, IMyService, as the registered type and specifies the lifetime manager by providing the ExternallyControlledLifetimeManager class as a parameter of the RegisterInstance method.

EmailService myEmailService = new EmailService();
myContainer.RegisterInstance<IMyService>(myEmailService, 
                            new ExternallyControlledLifetimeManager());

Dim myEmailService As New EmailService()
myContainer.RegisterInstance(Of IMyService)(myEmailService, _ 
                            New ExternallyControlledLifetimeManager())

The following example uses the RegisterInstance method to register existing instances of objects that implement the IMyService interface. This example uses both the generic and the non-generic overloads of the container methods and shows the Resolve method call for each instance.

DataService myDataService = new DataService();
EmailService myEmailService = new EmailService();
LoggingService myLoggingService = new LoggingService();

// Create container and register existing object instance
IUnityContainer myContainer = new UnityContainer();

myContainer.RegisterInstance<IMyService>(myDataService);
myContainer.RegisterInstance<IMyService>("Email", myEmailService);
myContainer.RegisterInstance(typeof(IMyService), "Logging", myLoggingService);

// Retrieve an instance of each type
IMyService theDataService = myContainer.Resolve<IMyService>();
IMyService theEmailService = myContainer.Resolve<IMyService>("Email");
IMyService theLoggingService
  = (IMyService)myContainer.Resolve(typeof(IMyService), "Logging");

Dim myDataService As New DataService()
Dim myEmailService As New EmailService()
Dim myLoggingService As New LoggingService()

' Create container and register existing object instance
Dim myContainer As IUnityContainer = New UnityContainer()
myContainer.RegisterInstance(Of IMyService)(myDataService)
myContainer.RegisterInstance(Of IMyService)("Email", myEmailService)
myContainer.RegisterInstance(GetType(IMyService), "Logging", myLoggingService)

' Retrieve an instance of each type
Dim theDataService As IMyService = myContainer.Resolve(Of IMyService)()
Dim theEmailService As IMyService = myContainer.Resolve(Of IMyService)("Email")
Dim theLoggingService As IMyService = myContainer.Resolve(GetType(IMyService), "Logging")

You can use the RegisterInstance method to register simple types and more complex or custom types. For example, you can register String values such as database connection strings with the container and have them injected into your code as required.

Using a Lifetime Manager with the RegisterInstance Method

The lifetime manager you specify when you register an existing object enables you to manage object lifetimes. If you do not specify a lifetime manager for your instance registration, by default, the object instances returned by the container when you use the RegisterInstance method have a container-controlled lifetime. If you want to specify the lifetime of the object, specify a lifetime manager when you call the RegisterInstance method.

The most common scenario is to create an instance that behaves like a singleton, so that the container creates the object the first time you call Resolve and then returns the same instance for all subsequent calls to Resolve for as long as the container is in scope. You can specify one of the following Unity Built-In Lifetime Managers types or your custom type when you call the RegisterInstance method:

• ContainerControlledLifetimeManager
• ExternallyControlledLifetimeManager
• HierarchicalLifetimeManager

The following example summarizes how you can use the RegisterInstance method with a lifetime manager to specify the container behavior. It 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");

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

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")
' Register an existing object as a named registration 
' with a per thread lifetime.
myContainer.RegisterInstance(Of IMyObject)("MySingleton", MyRealObject, new PerThreadLifetimeManager())
' Following code will return a singleton instance of MyRealObject
' Container will hold only a weak reference to the object
myContainer.Resolve(Of IMyObject)("MySingleton")

For more information about lifetime managers see Understanding Lifetime Managers.

Summary of the RegisterInstance Overloads

The following table summarizes the method overloads you can use to register existing object instances with the container at run time.

More Information

For more information about the techniques discussed in this topic, see the following topics:

• Resolving Objects by Using Overrides
• Understanding Lifetime Managers.

Next Topic | Previous Topic | Home | Community