Inversion of Control / Dependency injection
Inversion of Control/Dependency Injection in Umbraco
Umbraco supports dependency injection out of the box using the ASP.NET Core built-in dependency injection. This means that working with dependencies in Umbraco is similar to working with them in ASP.NET Core.
IUmbracoBuilder
is a Umbraco-specific abstraction on top of the IServiceCollection
. Its purpose is to aid in adding and replacing Umbraco-specific services, such as notification handlers, filesystems, server role accessors, and so on. You can access the IServiceCollection
directly to add custom services through the Services
property. See below for a concrete example:
Registering dependencies
There are different strategies for registering your dependencies and not one strategy is better than the other.
In this article, we will cover the following three strategies:
Which strategy to choose depends on the scenario requiring dependency registration.
Choosing a strategy for registering dependencies
Are you working directly on your site? You can choose whichever strategy you prefer working with.
Are you building a package and do not have access to the Program.cs
file? In this case, you have the option to register the dependencies in a composer.
Are you in a situation where you need to register more than a few dependencies? You can bundle your dependencies in custom extension methods and register them in a single call.
Registering dependencies in the Program.cs
file
Program.cs
fileWhen working with your Umbraco site, dependencies can be registered within the Program.cs
file.
In the example below, a custom notification handler is added to the CreateUmbracoBuilder()
builder chain:
Learn more about the uses of the Program.cs
file in the official ASP.NET Core Fundamentals documentation.
Registering dependencies in a composer
When working with packages, you do not have access to the Program.cs
file. Instead, you can use a composer to register your dependencies.
Below is an example of a composer using the Services
property of the IUmbracoBuilder
:
To access the IUmbracoBuilder
, you need to add Umbraco.Cms.Core.DependencyInjection
and Microsoft.Extensions.DependencyInjection
as using statements when registering your services. This, in turn, will also give you access to the IUmbracoBuilder
extension methods as well as the Microsoft IServiceProvider
.
Registering dependencies in bundles
Depending on your scenario, you may have a lot of dependencies you need to register. In this case, your Program.cs
or Composer can become cluttered and hard to manage.
You can manage multiple services in one place by creating your custom extension methods for the IUmbracoBuilder
. This way you can bundle similar dependencies in extension methods and register them all in a single call.
In the following code sample two dependencies, RegisterCustomNotificationHandlers
and RegisterCustomServices
are bundled together in a custom AddCustomServices
extension method.
It is not required to have an interface registering your dependencies:
With the dependencies bundled together, you can call the AddCustomServices
method in either the Program.cs
file or your composer:
Service lifetime
During registration of your dependencies, you have to define the lifetime of your service:
There are three possible lifetimes:
Name | Lifetime | Description |
---|---|---|
Transient | Creates a new instance | A new instance will be created each time it's injected. |
Scoped | One unique instance per web request (connection) | Scoped services are disposed of at the end of the request. Be careful not to resolve a scoped service from a singleton, as it may lead to an incorrect state in subsequent requests. |
Singleton | One unique instance for the whole web application | The single instance will be shared across all web requests. |
For more information, read the official Microsoft documentation on dependency injections.
Injecting dependencies
Once you have registered the dependencies inject them into your project where needed.
Injecting dependencies into a class
If you need to inject your service into a controller or another service, you will do so through the class.
The example below uses UmbracoApiController which is obsolete in Umbraco 14 and will be removed in Umbraco 15.
If you place a breakpoint on var bar = _foobar.Foo()
, open /Umbraco/Api/foo/foo
in your browser and inspect the variable, you'll see that the value is bar
. This is what you would expect as all the Foobar.Foo()
method does is to return Bar
as a string:
Injecting dependencies into a View or Template
In some cases you might need to use services within your templates or view files. Services can be injected directly into your views using the @inject
keyword. This means that you can inject the Foobar
from above into a view like shown below:
When loading a page using the template above, you will see the "Bar" heading which is retrieved from the service.
To use the service a using statement for the namespace of the service needs to be added.
Other things you can inject
In this section, you can find examples of what you can inject when working with Umbraco.
UmbracoHelper
Read more about the UmbracoHelper
The UmbracoHelper
is a scoped service, which means you can only use it in services that are also scoped or transient. To get the UmbracoHelper you must inject IUmbracoHelperAccessor
and use that to resolve it:
Using the UmbracoHelper is only possible when there is an instance of the UmbracoContext. You can read more in the implementation article about services.
ExamineManager
Read more about the ExamineManager in the Searching articles.
ILogger
Read more about logging in the debugging section
Using DI in Services and Helpers
In the Services and Helpers documentation, you can find more examples of using dependency injection and gaining access to the different services and helpers.
You will also find information about creating custom services and helpers to inject and use in your Umbraco project.
Last updated