Background tasks with hosted services in ASP.NET Core

By Luke Latham

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 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 (how to download)

IHostedService interface

Hosted services implement the IHostedService interface. The interface defines two methods for objects that are managed by the host:

The hosted service is a singleton that’s activated once at app startup and gracefully shutdown at app shutdown. When 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 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:

internal class TimedHostedService : IHostedService, IDisposable

    private readonly ILogger _logger;
    private Timer _timer;

    public TimedHostedService(ILogger<TimedHostedService> logger)
        _logger = logger;

    public Task StartAsync(CancellationToken cancellationToken)
        _logger.LogInformation("Timed Background Service is starting.");

        _timer = new Timer(DoWork, null, TimeSpan.Zero, 

        return Task.CompletedTask;

    private void DoWork(object state)
        _logger.LogInformation("Timed Background Service is working.");

    public Task StopAsync(CancellationToken cancellationToken)
        _logger.LogInformation("Timed Background Service is stopping.");

        _timer?.Change(Timeout.Infinite, 0);

        return Task.CompletedTask;

    public void Dispose()

The service is registered in Startup.ConfigureServices:

services.AddSingleton<IHostedService, TimedHostedService>();

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 is injected into the service:

internal interface IScopedProcessingService

    void DoWork();

internal class ScopedProcessingService : IScopedProcessingService

    private readonly ILogger _logger;
    public ScopedProcessingService(ILogger<ScopedProcessingService> logger)
        _logger = logger;

    public void DoWork()
        _logger.LogInformation("Scoped Processing Service is working.");

The hosted service creates a scope to resolve the scoped background task service to call its DoWork method:

internal class ConsumeScopedServiceHostedService : IHostedService

    private readonly ILogger _logger;

    public ConsumeScopedServiceHostedService(IServiceProvider services, 
        ILogger<ConsumeScopedServiceHostedService> logger)
        Services = services;
        _logger = logger;

    public IServiceProvider Services  get; 

    public Task StartAsync(CancellationToken cancellationToken)
            "Consume Scoped Service Hosted Service is starting.");


        return Task.CompletedTask;

    private void DoWork()
            "Consume Scoped Service Hosted Service is working.");

        using (var scope = Services.CreateScope())
            var scopedProcessingService = 


    public Task StopAsync(CancellationToken cancellationToken)
            "Consume Scoped Service Hosted Service is stopping.");

        return Task.CompletedTask;

The services are registered in Startup.ConfigureServices:

services.AddSingleton<IHostedService, ConsumeScopedServiceHostedService>();
services.AddScoped<IScopedProcessingService, ScopedProcessingService>();

Queued background tasks

A background task queue is based on the .NET 4.x QueueBackgroundWorkItem (tentatively scheduled to be built-in for ASP.NET Core 2.2):

public interface IBackgroundTaskQueue

    void QueueBackgroundWorkItem(Func<CancellationToken, Task> workItem);

    Task<Func<CancellationToken, Task>> DequeueAsync(
        CancellationToken cancellationToken);

public class BackgroundTaskQueue : IBackgroundTaskQueue

    private ConcurrentQueue<Func<CancellationToken, Task>> _workItems = 
        new ConcurrentQueue<Func<CancellationToken, Task>>();
    private SemaphoreSlim _signal = new SemaphoreSlim(0);

    public void QueueBackgroundWorkItem(
        Func<CancellationToken, Task> workItem)
        if (workItem == null)
            throw new ArgumentNullException(nameof(workItem));


    public async Task<Func<CancellationToken, Task>> DequeueAsync(
        CancellationToken cancellationToken)
        await _signal.WaitAsync(cancellationToken);
        _workItems.TryDequeue(out var workItem);

        return workItem;

In QueueHostedService, background tasks (workItem) in the queue are dequeued and executed:

public class QueuedHostedService : IHostedService
    private CancellationTokenSource _shutdown = 
        new CancellationTokenSource();
    private Task _backgroundTask;
    private readonly ILogger _logger;

    public QueuedHostedService(IBackgroundTaskQueue taskQueue, 
        ILoggerFactory loggerFactory)
        TaskQueue = taskQueue;
        _logger = loggerFactory.CreateLogger<QueuedHostedService>();

    public IBackgroundTaskQueue TaskQueue  get; 

    public Task StartAsync(CancellationToken cancellationToken)
        _logger.LogInformation("Queued Hosted Service is starting.");

        _backgroundTask = Task.Run(BackgroundProceessing);

        return Task.CompletedTask;

    private async Task BackgroundProceessing()
        while (!_shutdown.IsCancellationRequested)
            var workItem = 
                await TaskQueue.DequeueAsync(_shutdown.Token);

                await workItem(_shutdown.Token);
            catch (Exception ex)
                    $"Error occurred executing nameof(workItem).");

    public Task StopAsync(CancellationToken cancellationToken)
        _logger.LogInformation("Queued Hosted Service is stopping.");


        return Task.WhenAny(_backgroundTask, 
            Task.Delay(Timeout.Infinite, cancellationToken));

The services are registered in Startup.ConfigureServices:

services.AddSingleton<IHostedService, QueuedHostedService>();
services.AddSingleton<IBackgroundTaskQueue, BackgroundTaskQueue>();

In the Index page model class, the IBackgroundTaskQueue is injected into the constructor and assigned to Queue:

public IndexModel(IBackgroundTaskQueue queue, 
    IApplicationLifetime appLifetime,
    ILogger<IndexModel> logger)

    Queue = queue;
    _appLifetime = appLifetime;
    _logger = logger;

public IBackgroundTaskQueue Queue  get; 

When the Add Task button is selected on the Index page, the OnPostAddTask method is executed. QueueBackgroundWorkItem is called to enqueue the work item:

public IActionResult OnPostAddTask()

    Queue.QueueBackgroundWorkItem(async token =>
        var guid = Guid.NewGuid().ToString();

        for (int delayLoop = 0; delayLoop < 3; delayLoop++)
                $"Queued Background Task guid is running. delayLoop/3");
            await Task.Delay(TimeSpan.FromSeconds(5), token);

            $"Queued Background Task guid is complete. 3/3");

    return RedirectToPage();

Additional resources