88 lines
5.1 KiB
Markdown
88 lines
5.1 KiB
Markdown
---
|
|
title: Background tasks with hosted services in ASP.NET Core
|
|
author: guardrex
|
|
description: Learn how to implement background tasks with hosted services in ASP.NET Core.
|
|
manager: wpickett
|
|
ms.author: riande
|
|
ms.custom: mvc
|
|
ms.date: 02/15/2018
|
|
ms.prod: asp.net-core
|
|
ms.technology: aspnet
|
|
ms.topic: article
|
|
uid: fundamentals/hosted-services
|
|
---
|
|
# Background tasks with hosted services in ASP.NET Core
|
|
|
|
By [Luke Latham](https://github.com/guardrex)
|
|
|
|
In ASP.NET Core, background tasks can be implemented as *hosted services*. A hosted service is a class with background task logic that implements the [IHostedService](/dotnet/api/microsoft.extensions.hosting.ihostedservice) interface. This topic provides three hosted service examples:
|
|
|
|
* Background task that runs on a timer.
|
|
* Hosted service that activates a scoped service. The scoped service can use dependency injection.
|
|
* Queued background tasks that run sequentially.
|
|
|
|
[View or download sample code](https://github.com/aspnet/Docs/tree/master/aspnetcore/fundamentals/hosted-services/samples/2.x) ([how to download](xref:tutorials/index#how-to-download-a-sample))
|
|
|
|
## IHostedService interface
|
|
|
|
Hosted services implement the [IHostedService](/dotnet/api/microsoft.extensions.hosting.ihostedservice) interface. The interface defines two methods for objects that are managed by the host:
|
|
|
|
* [StartAsync(CancellationToken)](/dotnet/api/microsoft.extensions.hosting.ihostedservice.startasync) - Called after the server has started and [IApplicationLifetime.ApplicationStarted](/dotnet/api/microsoft.aspnetcore.hosting.iapplicationlifetime.applicationstarted) is triggered. `StartAsync` contains the logic to start the background task.
|
|
|
|
* [StopAsync(CancellationToken)](/dotnet/api/microsoft.extensions.hosting.ihostedservice.stopasync) - Triggered when the host is performing a graceful shutdown. `StopAsync` contains the logic to end the background task and dispose of any unmanaged resources. If the app shuts down unexpectedly (for example, the app's process fails), `StopAsync` might not be called.
|
|
|
|
The hosted service is a singleton that's activated once at app startup and gracefully shutdown at app shutdown. When [IDisposable](/dotnet/api/system.idisposable) is implemented, resources can be disposed when the service container is disposed. If an error is thrown during background task execution, `Dispose` should be called even if `StopAsync` isn't called.
|
|
|
|
## Timed background tasks
|
|
|
|
A timed background task makes use of the [System.Threading.Timer](/dotnet/api/system.threading.timer) class. The timer triggers the task's `DoWork` method. The timer is disabled on `StopAsync` and disposed when the service container is disposed on `Dispose`:
|
|
|
|
[!code-csharp[](hosted-services/samples/2.x/Services/TimedHostedService.cs?name=snippet1&highlight=15-16,30,37)]
|
|
|
|
The service is registered in `Startup.ConfigureServices`:
|
|
|
|
[!code-csharp[](hosted-services/samples/2.x/Startup.cs?name=snippet1)]
|
|
|
|
## Consuming a scoped service in a background task
|
|
|
|
To use scoped services within an `IHostedService`, create a scope. No scope is created for a hosted service by default.
|
|
|
|
The scoped background task service contains the background task's logic. In the following example, [ILogger](/dotnet/api/microsoft.extensions.logging.ilogger) is injected into the service:
|
|
|
|
[!code-csharp[](hosted-services/samples/2.x/Services/ScopedProcessingService.cs?name=snippet1)]
|
|
|
|
The hosted service creates a scope to resolve the scoped background task service to call its `DoWork` method:
|
|
|
|
[!code-csharp[](hosted-services/samples/2.x/Services/ConsumeScopedServiceHostedService.cs?name=snippet1&highlight=29-36)]
|
|
|
|
The services are registered in `Startup.ConfigureServices`:
|
|
|
|
[!code-csharp[](hosted-services/samples/2.x/Startup.cs?name=snippet2)]
|
|
|
|
## Queued background tasks
|
|
|
|
A background task queue is based on the .NET 4.x [QueueBackgroundWorkItem](/dotnet/api/system.web.hosting.hostingenvironment.queuebackgroundworkitem) ([tentatively scheduled to be built-in for ASP.NET Core 2.2](https://github.com/aspnet/Hosting/issues/1280)):
|
|
|
|
[!code-csharp[](hosted-services/samples/2.x/Services/BackgroundTaskQueue.cs?name=snippet1)]
|
|
|
|
In `QueueHostedService`, background tasks (`workItem`) in the queue are dequeued and executed:
|
|
|
|
[!code-csharp[](hosted-services/samples/2.x/Services/QueuedHostedService.cs?name=snippet1&highlight=30-31,35)]
|
|
|
|
The services are registered in `Startup.ConfigureServices`:
|
|
|
|
[!code-csharp[](hosted-services/samples/2.x/Startup.cs?name=snippet3)]
|
|
|
|
In the Index page model class, the `IBackgroundTaskQueue` is injected into the constructor and assigned to `Queue`:
|
|
|
|
[!code-csharp[](hosted-services/samples/2.x/Pages/Index.cshtml.cs?name=snippet1)]
|
|
|
|
When the **Add Task** button is selected on the Index page, the `OnPostAddTask` method is executed. `QueueBackgroundWorkItem` is called to enqueue the work item:
|
|
|
|
[!code-csharp[](hosted-services/samples/2.x/Pages/Index.cshtml.cs?name=snippet2)]
|
|
|
|
## Additional resources
|
|
|
|
* [Implement background tasks in microservices with IHostedService and the BackgroundService class](/dotnet/standard/microservices-architecture/multi-container-microservice-net-applications/background-tasks-with-ihostedservice)
|
|
* [System.Threading.Timer](/dotnet/api/system.threading.timer)
|