Events
Power BI DataViz World Championships
Feb 14, 4 PM - Mar 31, 4 PM
With 4 chances to enter, you could win a conference package and make it to the LIVE Grand Finale in Las Vegas
Learn moreThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Note
This isn't the latest version of this article. For the current release, see the .NET 9 version of this article.
Warning
This version of ASP.NET Core is no longer supported. For more information, see the .NET and .NET Core Support Policy. For the current release, see the .NET 9 version of this article.
Important
This information relates to a pre-release product that may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
For the current release, see the .NET 9 version of this article.
By Rainer Stropek and Mike Rousos
This article explains how Blazor apps can inject services into components.
Dependency injection (DI) is a technique for accessing services configured in a central location:
Note
We recommend reading Dependency injection in ASP.NET Core before reading this topic.
The services shown in the following table are commonly used in Blazor apps.
Service | Lifetime | Description |
---|---|---|
HttpClient | Scoped | Provides methods for sending HTTP requests and receiving HTTP responses from a resource identified by a URI. Client-side, an instance of HttpClient is registered by the app in the Server-side, an HttpClient isn't configured as a service by default. In server-side code, provide an HttpClient. For more information, see Call a web API from an ASP.NET Core Blazor app. An HttpClient is registered as a scoped service, not singleton. For more information, see the Service lifetime section. |
IJSRuntime | Client-side: Singleton Server-side: Scoped The Blazor framework registers IJSRuntime in the app's service container. |
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. When seeking to inject the service into a singleton service on the server, take either of the following approaches:
|
NavigationManager | Client-side: Singleton Server-side: Scoped The Blazor framework registers NavigationManager in the app's service container. |
Contains helpers for working with URIs and navigation state. For more information, see URI and navigation state helpers. |
Additional services registered by the Blazor framework are described in the documentation where they're used to describe Blazor features, such as configuration and logging.
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.
Configure services for the app's service collection in the Program
file. In the following example, the ExampleDependency
implementation is registered for IExampleDependency
:
var builder = WebAssemblyHostBuilder.CreateDefault(args);
...
builder.Services.AddSingleton<IExampleDependency, ExampleDependency>();
...
await builder.Build().RunAsync();
After the host is built, services are available from the root DI scope before any components are rendered. This can be useful for running initialization logic before rendering content:
var builder = WebAssemblyHostBuilder.CreateDefault(args);
...
builder.Services.AddSingleton<WeatherService>();
...
var host = builder.Build();
var weatherService = host.Services.GetRequiredService<WeatherService>();
await weatherService.InitializeWeatherAsync();
await host.RunAsync();
The host 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
:
var builder = WebAssemblyHostBuilder.CreateDefault(args);
...
builder.Services.AddSingleton<WeatherService>();
...
var host = builder.Build();
var weatherService = host.Services.GetRequiredService<WeatherService>();
await weatherService.InitializeWeatherAsync(
host.Configuration["WeatherServiceUrl"]);
await host.RunAsync();
After creating a new app, examine part of the Program
file:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorComponents()
.AddInteractiveServerComponents();
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.AddServerSideBlazor();
builder.Services.AddSingleton<WeatherForecastService>();
The builder
variable represents a WebApplicationBuilder with an IServiceCollection, which is a list of service descriptor objects. 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
:
builder.Services.AddSingleton<IDataAccess, DataAccess>();
After creating a new app, examine the Startup.ConfigureServices
method in Startup.cs
:
using Microsoft.Extensions.DependencyInjection;
...
public void ConfigureServices(IServiceCollection services)
{
...
}
The ConfigureServices method is passed an IServiceCollection, which is a list of service descriptor objects. Services are added in the ConfigureServices
method 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>();
}
If one or more common services are required client- and server-side, you can place the common service registrations in a method client-side and call the method to register the services in both projects.
First, factor common service registrations into a separate method. For example, create a ConfigureCommonServices
method client-side:
public static void ConfigureCommonServices(IServiceCollection services)
{
services.Add...;
}
For the client-side Program
file, call ConfigureCommonServices
to register the common services:
var builder = WebAssemblyHostBuilder.CreateDefault(args);
...
ConfigureCommonServices(builder.Services);
In the server-side Program
file, call ConfigureCommonServices
to register the common services:
var builder = WebApplication.CreateBuilder(args);
...
Client.Program.ConfigureCommonServices(builder.Services);
For an example of this approach, see ASP.NET Core Blazor WebAssembly additional security scenarios.
This section only applies to WebAssembly components in Blazor Web Apps.
Blazor Web Apps normally prerender client-side WebAssembly components. If an app is run with a required service only registered in the .Client
project, executing the app results in a runtime error similar to the following when a component attempts to use the required service during prerendering:
InvalidOperationException: Cannot provide a value for {PROPERTY} on type '{ASSEMBLY}}.Client.Pages.{COMPONENT NAME}'. There is no registered service of type '{SERVICE}'.
Use either of the following approaches to resolve this problem:
For more information, see Client-side services fail to resolve during prerendering.
Services can be configured with the lifetimes shown in the following table.
Lifetime | Description |
---|---|
Scoped | Client-side doesn't currently have a concept of DI scopes. Server-side development supports the
For more information on preserving user state in server-side apps, see ASP.NET Core Blazor state management. |
Singleton | DI creates a single instance of the service. All components requiring a Singleton service receive the same instance of the 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.
For injecting services into components, Blazor supports constructor injection and property injection.
After services are added to the service collection, inject one or more services into components with constructor injection. The following example injects the NavigationManager
service.
ConstructorInjection.razor
:
@page "/constructor-injection"
<button @onclick="HandleClick">
Take me to the Counter component
</button>
ConstructorInjection.razor.cs
:
using Microsoft.AspNetCore.Components;
public partial class ConstructorInjection(NavigationManager navigation)
{
private void HandleClick()
{
navigation.NavigateTo("/counter");
}
}
After services are added to the service collection, inject one or more services into components with the @inject
Razor directive, which has two parameters:
For more information, see Dependency injection into views in ASP.NET Core.
Use multiple @inject
statements to inject different services.
The following example demonstrates shows how to use the @inject
directive. The service implementing Services.NavigationManager
is injected into the component's property Navigation
. Note how the code is only using the NavigationManager
abstraction.
PropertyInjection.razor
:
@page "/property-injection"
@inject NavigationManager Navigation
<button @onclick="@(() => Navigation.NavigateTo("/counter"))">
Take me to the Counter component
</button>
Internally, the generated property (Navigation
) 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:
using Microsoft.AspNetCore.Components;
public class ComponentBase : IComponent
{
[Inject]
protected NavigationManager Navigation { get; set; } = default!;
...
}
Note
Since injected services are expected to be available, the default literal with the null-forgiving operator (default!
) is assigned in .NET 6 or later. For more information, see Nullable reference types (NRTs) and .NET compiler null-state static analysis.
In components derived from a base class, the @inject
directive isn't required. The InjectAttribute of the base class is sufficient. The component only requires the @inherits
directive. In the following example, any injected services of CustomComponentBase
are available to the Demo
component:
@page "/demo"
@inherits CustomComponentBase
Complex services might require additional services. In the following example, DataAccess
requires 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. In the following example, the constructor receives an HttpClient via DI. HttpClient is a default service.
using System.Net.Http;
public class DataAccess : IDataAccess
{
public DataAccess(HttpClient http)
{
...
}
...
}
Constructor injection is supported with primary constructors in C# 12 (.NET 8) or later:
using System.Net.Http;
public class DataAccess(HttpClient http) : IDataAccess
{
...
}
Prerequisites for constructor injection:
public
.Blazor supports injecting keyed services using the [Inject]
attribute. Keys allow for scoping of registration and consumption of services when using dependency injection. Use the InjectAttribute.Key property to specify the key for the service to inject:
[Inject(Key = "my-service")]
public IMyService MyService { get; set; }
In non-Blazor ASP.NET Core apps, scoped and transient services are typically scoped to the current request. After the request completes, scoped and transient services are disposed by the DI system.
In interactive server-side Blazor apps, the DI scope lasts for the duration of the circuit (the SignalR connection between the client and server), which can result in scoped and disposable transient services living much longer than the lifetime of a single component. Therefore, don't directly inject a scoped service into a component if you intend the service lifetime to match the lifetime of the component. Transient services injected into a component that don't implement IDisposable are garbage collected when the component is disposed. However, injected transient services that implement IDisposable are maintained by the DI container for the lifetime of the circuit, which prevents service garbage collection when the component is disposed and results in a memory leak. An alternative approach for scoped services based on the OwningComponentBase type is described later in this section, and disposable transient services shouldn't be used at all. For more information, see Design for solving transient disposables on Blazor Server (dotnet/aspnetcore
#26676).
Even in client-side Blazor apps that don't operate over a circuit, services registered with a scoped lifetime are treated as singletons, so they live longer than scoped services in typical ASP.NET Core apps. Client-side disposable transient services also live longer than the components where they're injected because the DI container, which holds references to disposable services, persists for the lifetime of the app, preventing garbage collection on the services. Although long-lived disposable transient services are of greater concern on the server, they should be avoided as client service registrations as well. Use of the OwningComponentBase type is also recommended for client-side scoped services to control service lifetime, and disposable transient services shouldn't be used at all.
An approach that limits a service lifetime 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, a component can inject 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 reused within a component but not shared across components.
Two versions of OwningComponentBase type are available and described in the next two sections:
OwningComponentBase is an abstract, disposable child of the ComponentBase type with a protected ScopedServices property of type IServiceProvider. The 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 ScopedServices with either GetRequiredService or GetService. Any services resolved using the ScopedServices provider have their dependencies provided in the component's scope.
The following example demonstrates the difference between injecting a scoped service directly and resolving a service using ScopedServices on the server. The following interface and implementation for a time travel class include a DT
property to hold a DateTime value. The implementation calls DateTime.Now to set DT
when the TimeTravel
class is instantiated.
ITimeTravel.cs
:
public interface ITimeTravel
{
public DateTime DT { get; set; }
}
TimeTravel.cs
:
public class TimeTravel : ITimeTravel
{
public DateTime DT { get; set; } = DateTime.Now;
}
The service is registered as scoped in the server-side Program
file. Server-side, scoped services have a lifetime equal to the duration of the circuit.
In the Program
file:
builder.Services.AddScoped<ITimeTravel, TimeTravel>();
In the following TimeTravel
component:
@inject
as TimeTravel1
.TimeTravel2
.TimeTravel.razor
:
@page "/time-travel"
@inject ITimeTravel TimeTravel1
@inherits OwningComponentBase
<h1><code>OwningComponentBase</code> Example</h1>
<ul>
<li>TimeTravel1.DT: @TimeTravel1?.DT</li>
<li>TimeTravel2.DT: @TimeTravel2?.DT</li>
</ul>
@code {
private ITimeTravel TimeTravel2 { get; set; } = default!;
protected override void OnInitialized()
{
TimeTravel2 = ScopedServices.GetRequiredService<ITimeTravel>();
}
}
@page "/time-travel"
@inject ITimeTravel TimeTravel1
@inherits OwningComponentBase
<h1><code>OwningComponentBase</code> Example</h1>
<ul>
<li>TimeTravel1.DT: @TimeTravel1?.DT</li>
<li>TimeTravel2.DT: @TimeTravel2?.DT</li>
</ul>
@code {
private ITimeTravel TimeTravel2 { get; set; } = default!;
protected override void OnInitialized()
{
TimeTravel2 = ScopedServices.GetRequiredService<ITimeTravel>();
}
}
Initially navigating to the TimeTravel
component, the time travel service is instantiated twice when the component loads, and TimeTravel1
and TimeTravel2
have the same initial value:
TimeTravel1.DT: 8/31/2022 2:54:45 PM
TimeTravel2.DT: 8/31/2022 2:54:45 PM
When navigating away from the TimeTravel
component to another component and back to the TimeTravel
component:
TimeTravel1
is provided the same service instance that was created when the component first loaded, so the value of DT
remains the same.TimeTravel2
obtains a new ITimeTravel
service instance in TimeTravel2
with a new DT value.TimeTravel1.DT: 8/31/2022 2:54:45 PM
TimeTravel2.DT: 8/31/2022 2:54:48 PM
TimeTravel1
is tied to the user's circuit, which remains intact and isn't disposed until the underlying circuit is deconstructed. For example, the service is disposed if the circuit is disconnected for the disconnected circuit retention period.
In spite of the scoped service registration in the Program
file and the longevity of the user's circuit, TimeTravel2
receives a new ITimeTravel
service instance each time the component is initialized.
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>
Custom code can be added to a client-side Blazor app to detect disposable transient services in an app that should use OwningComponentBase. This approach is useful if you're concerned that code added to the app in the future consumes one or more transient disposable services, including services added by libraries. Demonstration code is available in the Blazor samples GitHub repository (how to download).
Inspect the following in .NET 6 or later versions of the BlazorSample_WebAssembly
sample:
DetectIncorrectUsagesOfTransientDisposables.cs
Services/TransientDisposableService.cs
Program.cs
:
Services
namespace is provided at the top of the file (using BlazorSample.Services;
).DetectIncorrectUsageOfTransients
is called immediately after the builder
is assigned from WebAssemblyHostBuilder.CreateDefault.TransientDisposableService
is registered (builder.Services.AddTransient<TransientDisposableService>();
).EnableTransientDisposableDetection
is called on the built host in the processing pipeline of the app (host.EnableTransientDisposableDetection();
).TransientDisposableService
service without throwing an exception. However, attempting to resolve the service in TransientService.razor
throws an InvalidOperationException when the framework attempts to construct an instance of TransientDisposableService
.Custom code can be added to a server-side Blazor app to detect server-side disposable transient services in an app that should use OwningComponentBase. This approach is useful if you're concerned that code added to the app in the future consumes one or more transient disposable services, including services added by libraries. Demonstration code is available in the Blazor samples GitHub repository (how to download).
Inspect the following in .NET 8 or later versions of the BlazorSample_BlazorWebApp
sample:
Inspect the following in .NET 6 or .NET 7 versions of the BlazorSample_Server
sample:
DetectIncorrectUsagesOfTransientDisposables.cs
Services/TransitiveTransientDisposableDependency.cs
:Program.cs
:
Services
namespace is provided at the top of the file (using BlazorSample.Services;
).DetectIncorrectUsageOfTransients
is called on the host builder (builder.DetectIncorrectUsageOfTransients();
).TransientDependency
service is registered (builder.Services.AddTransient<TransientDependency>();
).TransitiveTransientDisposableDependency
is registered for ITransitiveTransientDisposableDependency
(builder.Services.AddTransient<ITransitiveTransientDisposableDependency, TransitiveTransientDisposableDependency>();
).TransientDependency
service without throwing an exception. However, attempting to resolve the service in TransientService.razor
throws an InvalidOperationException when the framework attempts to construct an instance of TransientDependency
.Transient service registrations for IHttpClientFactory/HttpClient handlers are recommended. If the app contains IHttpClientFactory/HttpClient handlers and uses the IRemoteAuthenticationBuilder<TRemoteAuthenticationState,TAccount> to add support for authentication, the following transient disposables for client-side authentication are also discovered, which is expected and can be ignored:
Other instances of IHttpClientFactory/HttpClient are also discovered. These instances can also be ignored.
The Blazor sample apps in the Blazor samples GitHub repository (how to download) demonstrate the code to detect transient disposables. However, the code is deactivated because the sample apps include IHttpClientFactory/HttpClient handlers.
To activate the demonstration code and witness its operation:
Uncomment the transient disposable lines in Program.cs
.
Remove the conditional check in NavLink.razor
that prevents the TransientService
component from displaying in the app's navigation sidebar:
- else if (name != "TransientService")
+ else
Run the sample app and navigate to the TransientService
component at /transient-service
.
For more information, see ASP.NET Core Blazor with Entity Framework Core (EF Core).
Circuit activity handlers provide an approach for accessing scoped Blazor services from other non-Blazor dependency injection (DI) scopes, such as scopes created using IHttpClientFactory.
Prior to the release of ASP.NET Core in .NET 8, accessing circuit-scoped services from other dependency injection scopes required using a custom base component type. With circuit activity handlers, a custom base component type isn't required, as the following example demonstrates:
public class CircuitServicesAccessor
{
static readonly AsyncLocal<IServiceProvider> blazorServices = new();
public IServiceProvider? Services
{
get => blazorServices.Value;
set => blazorServices.Value = value!;
}
}
public class ServicesAccessorCircuitHandler(
IServiceProvider services, CircuitServicesAccessor servicesAccessor)
: CircuitHandler
{
public override Func<CircuitInboundActivityContext, Task> CreateInboundActivityHandler(
Func<CircuitInboundActivityContext, Task> next) =>
async context =>
{
servicesAccessor.Services = services;
await next(context);
servicesAccessor.Services = null;
};
}
public static class CircuitServicesServiceCollectionExtensions
{
public static IServiceCollection AddCircuitServicesAccessor(
this IServiceCollection services)
{
services.AddScoped<CircuitServicesAccessor>();
services.AddScoped<CircuitHandler, ServicesAccessorCircuitHandler>();
return services;
}
}
Access the circuit-scoped services by injecting the CircuitServicesAccessor
where it's needed.
For an example that shows how to access the AuthenticationStateProvider from a DelegatingHandler set up using IHttpClientFactory, see ASP.NET Core server-side and Blazor Web App additional security scenarios.
There may be times when a Razor component invokes asynchronous methods that execute code in a different DI scope. Without the correct approach, these DI scopes don't have access to Blazor's services, such as IJSRuntime and Microsoft.AspNetCore.Components.Server.ProtectedBrowserStorage.
For example, HttpClient instances created using IHttpClientFactory have their own DI service scope. As a result, HttpMessageHandler instances configured on the HttpClient aren't able to directly inject Blazor services.
Create a class BlazorServiceAccessor
that defines an AsyncLocal
, which stores the Blazor IServiceProvider for the current asynchronous context. A BlazorServiceAccessor
instance can be acquired from within a different DI service scope to access Blazor services.
BlazorServiceAccessor.cs
:
internal sealed class BlazorServiceAccessor
{
private static readonly AsyncLocal<BlazorServiceHolder> s_currentServiceHolder = new();
public IServiceProvider? Services
{
get => s_currentServiceHolder.Value?.Services;
set
{
if (s_currentServiceHolder.Value is { } holder)
{
// Clear the current IServiceProvider trapped in the AsyncLocal.
holder.Services = null;
}
if (value is not null)
{
// Use object indirection to hold the IServiceProvider in an AsyncLocal
// so it can be cleared in all ExecutionContexts when it's cleared.
s_currentServiceHolder.Value = new() { Services = value };
}
}
}
private sealed class BlazorServiceHolder
{
public IServiceProvider? Services { get; set; }
}
}
To set the value of BlazorServiceAccessor.Services
automatically when an async
component method is invoked, create a custom base component that re-implements the three primary asynchronous entry points into Razor component code:
The following class demonstrates the implementation for the base component.
CustomComponentBase.cs
:
using Microsoft.AspNetCore.Components;
public class CustomComponentBase : ComponentBase, IHandleEvent, IHandleAfterRender
{
private bool hasCalledOnAfterRender;
[Inject]
private IServiceProvider Services { get; set; } = default!;
[Inject]
private BlazorServiceAccessor BlazorServiceAccessor { get; set; } = default!;
public override Task SetParametersAsync(ParameterView parameters)
=> InvokeWithBlazorServiceContext(() => base.SetParametersAsync(parameters));
Task IHandleEvent.HandleEventAsync(EventCallbackWorkItem callback, object? arg)
=> InvokeWithBlazorServiceContext(() =>
{
var task = callback.InvokeAsync(arg);
var shouldAwaitTask = task.Status != TaskStatus.RanToCompletion &&
task.Status != TaskStatus.Canceled;
StateHasChanged();
return shouldAwaitTask ?
CallStateHasChangedOnAsyncCompletion(task) :
Task.CompletedTask;
});
Task IHandleAfterRender.OnAfterRenderAsync()
=> InvokeWithBlazorServiceContext(() =>
{
var firstRender = !hasCalledOnAfterRender;
hasCalledOnAfterRender |= true;
OnAfterRender(firstRender);
return OnAfterRenderAsync(firstRender);
});
private async Task CallStateHasChangedOnAsyncCompletion(Task task)
{
try
{
await task;
}
catch
{
if (task.IsCanceled)
{
return;
}
throw;
}
StateHasChanged();
}
private async Task InvokeWithBlazorServiceContext(Func<Task> func)
{
try
{
BlazorServiceAccessor.Services = Services;
await func();
}
finally
{
BlazorServiceAccessor.Services = null;
}
}
}
Any components extending CustomComponentBase
automatically have BlazorServiceAccessor.Services
set to the IServiceProvider in the current Blazor DI scope.
Finally, in the Program
file, add the BlazorServiceAccessor
as a scoped service:
builder.Services.AddScoped<BlazorServiceAccessor>();
Finally, in Startup.ConfigureServices
of Startup.cs
, add the BlazorServiceAccessor
as a scoped service:
services.AddScoped<BlazorServiceAccessor>();
ASP.NET Core feedback
ASP.NET Core is an open source project. Select a link to provide feedback:
Events
Power BI DataViz World Championships
Feb 14, 4 PM - Mar 31, 4 PM
With 4 chances to enter, you could win a conference package and make it to the LIVE Grand Finale in Las Vegas
Learn moreTraining
Module
Configure services with dependency injection in ASP.NET Core - Training
Understand and implement dependency injection in an ASP.NET Core app. Use ASP.NET Core's built-in service container to manage dependencies. Register services with the service container.