ASP.NET Core Blazor dependency injection

By Rainer Stropek and Mike Rousos

Blazor supports dependency injection (DI). Apps can use built-in services by injecting them into components. Apps can also define and register custom services and make them available throughout the app via DI.

DI is a technique for accessing services configured in a central location. This can be useful in Blazor apps to:

  • Share a single instance of a service class across many components, known as a singleton service.
  • Decouple components from concrete service classes by using reference abstractions. For example, consider an interface IDataAccess for accessing data in the app. The interface is implemented by a concrete DataAccess class and registered as a service in the app's service container. When a component uses DI to receive an IDataAccess implementation, the component isn't coupled to the concrete type. The implementation can be swapped, perhaps for a mock implementation in unit tests.

Default services

Default services are automatically added to the app's service collection.

Service Lifetime Description
HttpClient Transient Provides methods for sending HTTP requests and receiving HTTP responses from a resource identified by a URI.

The instance of HttpClient in a Blazor WebAssembly app uses the browser for handling the HTTP traffic in the background.

Blazor Server apps don't include an HttpClient configured as a service by default. Provide an HttpClient to a Blazor Server app.

For more information, see Call a web API from ASP.NET Core Blazor WebAssembly.
IJSRuntime Singleton (Blazor WebAssembly)
Scoped (Blazor Server)
Represents an instance of a JavaScript runtime where JavaScript calls are dispatched. For more information, see Call JavaScript functions from .NET methods in ASP.NET Core Blazor.
NavigationManager Singleton (Blazor WebAssembly)
Scoped (Blazor Server)
Contains helpers for working with URIs and navigation state. For more information, see URI and navigation state helpers.

A custom service provider doesn't automatically provide the default services listed in the table. If you use a custom service provider and require any of the services shown in the table, add the required services to the new service provider.

Add services to an app

Blazor WebAssembly

Configure services for the app's service collection in the Main method of Program.cs. In the following example, the MyDependency implementation is registered for IMyDependency:

public class Program
{
    public static async Task Main(string[] args)
    {
        var builder = WebAssemblyHostBuilder.CreateDefault(args);
        builder.Services.AddSingleton<IMyDependency, MyDependency>();
        builder.RootComponents.Add<App>("app");

        await builder.Build().RunAsync();
    }
}

Once the host is built, services can be accessed from the root DI scope before any components are rendered. This can be useful for running initialization logic before rendering content:

public class Program
{
    public static async Task Main(string[] args)
    {
        var builder = WebAssemblyHostBuilder.CreateDefault(args);
        builder.Services.AddSingleton<WeatherService>();
        builder.RootComponents.Add<App>("app");

        var host = builder.Build();

        var weatherService = host.Services.GetRequiredService<WeatherService>();
        await weatherService.InitializeWeatherAsync();

        await host.RunAsync();
    }
}

The host also provides a central configuration instance for the app. Building on the preceding example, the weather service's URL is passed from a default configuration source (for example, appsettings.json) to InitializeWeatherAsync:

public class Program
{
    public static async Task Main(string[] args)
    {
        var builder = WebAssemblyHostBuilder.CreateDefault(args);
        builder.Services.AddSingleton<WeatherService>();
        builder.RootComponents.Add<App>("app");

        var host = builder.Build();

        var weatherService = host.Services.GetRequiredService<WeatherService>();
        await weatherService.InitializeWeatherAsync(
            host.Configuration["WeatherServiceUrl"]);

        await host.RunAsync();
    }
}

Blazor Server

After creating a new app, examine the Startup.ConfigureServices method:

public void ConfigureServices(IServiceCollection services)
{
    // Add custom services here
}

The ConfigureServices method is passed an IServiceCollection, which is a list of service descriptor objects (ServiceDescriptor). Services are added by providing service descriptors to the service collection. The following example demonstrates the concept with the IDataAccess interface and its concrete implementation DataAccess:

public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<IDataAccess, DataAccess>();
}

Service lifetime

Services can be configured with the lifetimes shown in the following table.

Lifetime Description
Scoped Blazor WebAssembly apps don't currently have a concept of DI scopes. Scoped-registered services behave like Singleton services. However, the Blazor Server hosting model supports the Scoped lifetime. In Blazor Server apps, a scoped service registration is scoped to the connection. For this reason, using scoped services is preferred for services that should be scoped to the current user, even if the current intent is to run client-side in the browser.
Singleton DI creates a single instance of the service. All components requiring a Singleton service receive an instance of the same service.
Transient Whenever a component obtains an instance of a Transient service from the service container, it receives a new instance of the service.

The DI system is based on the DI system in ASP.NET Core. For more information, see Dependency injection in ASP.NET Core.

Request a service in a component

After services are added to the service collection, inject the services into the components using the @inject Razor directive. @inject has two parameters:

  • Type: The type of the service to inject.
  • Property: The name of the property receiving the injected app service. The property doesn't require manual creation. The compiler creates the property.

For more information, see Dependency injection into views in ASP.NET Core.

Use multiple @inject statements to inject different services.

The following example shows how to use @inject. The service implementing Services.IDataAccess is injected into the component's property DataRepository. Note how the code is only using the IDataAccess abstraction:

@page "/customer-list"
@using Services
@inject IDataAccess DataRepository

@if (customers != null)
{
    <ul>
        @foreach (var customer in customers)
        {
            <li>@customer.FirstName @customer.LastName</li>
        }
    </ul>
}

@code {
    private IReadOnlyList<Customer> customers;

    protected override async Task OnInitializedAsync()
    {
        customers = await DataRepository.GetAllCustomersAsync();
    }
}

Internally, the generated property (DataRepository) uses the [Inject] attribute. Typically, this attribute isn't used directly. If a base class is required for components and injected properties are also required for the base class, manually add the [Inject] attribute:

public class ComponentBase : IComponent
{
    // DI works even if using the InjectAttribute in a component's base class.
    [Inject]
    protected IDataAccess DataRepository { get; set; }
    ...
}

In components derived from the base class, the @inject directive isn't required. The InjectAttribute of the base class is sufficient:

@page "/demo"
@inherits ComponentBase

<h1>Demo Component</h1>

Use DI in services

Complex services might require additional services. In the prior example, DataAccess might require the HttpClient default service. @inject (or the [Inject] attribute) isn't available for use in services. Constructor injection must be used instead. Required services are added by adding parameters to the service's constructor. When DI creates the service, it recognizes the services it requires in the constructor and provides them accordingly.

public class DataAccess : IDataAccess
{
    // The constructor receives an HttpClient via dependency
    // injection. HttpClient is a default service.
    public DataAccess(HttpClient client)
    {
        ...
    }
}

Prerequisites for constructor injection:

  • One constructor must exist whose arguments can all be fulfilled by DI. Additional parameters not covered by DI are allowed if they specify default values.
  • The applicable constructor must be public.
  • One applicable constructor must exist. In case of an ambiguity, DI throws an exception.

Utility base component classes to manage a DI scope

In ASP.NET Core apps, scoped services are typically scoped to the current request. After the request completes, any scoped or transient services are disposed by the DI system. In Blazor Server apps, the request scope lasts for the duration of the client connection, which can result in transient and scoped services living much longer than expected. In Blazor WebAssembly apps, services registered with a scoped lifetime are treated as singletons, so they live longer than scoped services in typical ASP.NET Core apps.

An approach that limits a service lifetime in Blazor apps is use of the OwningComponentBase type. OwningComponentBase is an abstract type derived from ComponentBase that creates a DI scope corresponding to the lifetime of the component. Using this scope, it's possible to use DI services with a scoped lifetime and have them live as long as the component. When the component is destroyed, services from the component's scoped service provider are disposed as well. This can be useful for services that:

  • Should be reused within a component, as the transient lifetime is inappropriate.
  • Shouldn't be shared across components, as the singleton lifetime is inappropriate.

Two versions of the OwningComponentBase type are available:

  • OwningComponentBase is an abstract, disposable child of the ComponentBase type with a protected ScopedServices property of type IServiceProvider. This provider can be used to resolve services that are scoped to the lifetime of the component.

    DI services injected into the component using @inject or the [Inject] attribute aren't created in the component's scope. To use the component's scope, services must be resolved using GetRequiredService or GetService. Any services resolved using the ScopedServices provider have their dependencies provided from that same scope.

    @page "/preferences"
    @using Microsoft.Extensions.DependencyInjection
    @inherits OwningComponentBase
    
    <h1>User (@UserService.Name)</h1>
    
    <ul>
        @foreach (var setting in SettingService.GetSettings())
        {
            <li>@setting.SettingName: @setting.SettingValue</li>
        }
    </ul>
    
    @code {
        private IUserService UserService { get; set; }
        private ISettingService SettingService { get; set; }
    
        protected override void OnInitialized()
        {
            UserService = ScopedServices.GetRequiredService<IUserService>();
            SettingService = ScopedServices.GetRequiredService<ISettingService>();
        }
    }
    
  • OwningComponentBase<TService> derives from OwningComponentBase and adds a Service property that returns an instance of T from the scoped DI provider. This type is a convenient way to access scoped services without using an instance of IServiceProvider when there's one primary service the app requires from the DI container using the component's scope. The ScopedServices property is available, so the app can get services of other types, if necessary.

    @page "/users"
    @attribute [Authorize]
    @inherits OwningComponentBase<AppDbContext>
    
    <h1>Users (@Service.Users.Count())</h1>
    
    <ul>
        @foreach (var user in Service.Users)
        {
            <li>@user.UserName</li>
        }
    </ul>
    

Use of Entity Framework DbContext from DI

One common service type to retrieve from DI in web apps is Entity Framework (EF) DbContext objects. Registering EF services using AddDbContext adds the DbContext as a scoped service by default. Registering as a scoped service can lead to problems in Blazor apps because it causes DbContext instances to be long-lived and shared across the app. DbContext isn't thread-safe and must not be used concurrently.

Depending on the app, using OwningComponentBase to limit the scope of a DbContext to a single component may solve the issue. If a component doesn't use a DbContext in parallel, deriving the component from OwningComponentBase and retrieving the DbContext from ScopedServices is sufficient because it ensures that:

  • Separate components don't share a DbContext.
  • The DbContext lives only as long as the component depending on it.

If a single component might use a DbContext concurrently (for example, every time a user selects a button), even using OwningComponentBase doesn't avoid issues with concurrent EF operations. In that case, use a different DbContext for each logical EF operation. Use either of the following approaches:

  • Create the DbContext directly using DbContextOptions<TContext> as an argument, which can be retrieved from DI and is thread safe.

    @page "/example"
    @inject DbContextOptions<AppDbContext> DbContextOptions
    
    <ul>
        @foreach (var item in data)
        {
            <li>@item</li>
        }
    </ul>
    
    <button @onclick="LoadData">Load Data</button>
    
    @code {
        private List<string> data = new List<string>();
    
        private async Task LoadData()
        {
            data = await GetAsync();
            StateHasChanged();
        }
    
        public async Task<List<string>> GetAsync()
        {
            using (var context = new AppDbContext(DbContextOptions))
            {
                return await context.Products.Select(p => p.Name).ToListAsync();
            }
        }
    }
    
  • Register the DbContext in the service container with a transient lifetime:

    • When registering the context, use ServiceLifetime.Transient. The AddDbContext extension method takes two optional parameters of type ServiceLifetime. To use this approach, only the contextLifetime parameter needs to be ServiceLifetime.Transient. optionsLifetime can keep its default value of ServiceLifetime.Scoped.

      services.AddDbContext<AppDbContext>(options =>
           options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection")),
           ServiceLifetime.Transient);
      
    • The transient DbContext can be injected as normal (using @inject) into components that will not execute multiple EF operations in parallel. Those that may perform multiple EF operations simultaneously can request separate DbContext objects for each parallel operation using GetRequiredService.

      @page "/example"
      @using Microsoft.Extensions.DependencyInjection
      @inject IServiceProvider ServiceProvider
      
      <ul>
          @foreach (var item in data)
          {
              <li>@item</li>
          }
      </ul>
      
      <button @onclick="LoadData">Load Data</button>
      
      @code {
          private List<string> data = new List<string>();
      
          private async Task LoadData()
          {
              data = await GetAsync();
              StateHasChanged();
          }
      
          public async Task<List<string>> GetAsync()
          {
              using (var context = ServiceProvider.GetRequiredService<AppDbContext>())
              {
                  return await context.Products.Select(p => p.Name).ToListAsync();
              }
          }
      }
      

Additional resources