Tareas en segundo plano con servicios hospedados en ASP.NET Core

Por Jeow Li Huan

Note

Esta no es la versión más reciente de este artículo. Para obtener la versión actual, consulte la versión .NET 11 de este artículo.

En ASP.NET Core, las tareas en segundo plano se pueden implementar como servicios hospedados. Un servicio hospedado es una clase con lógica de tarea en segundo plano que implementa la interfaz IHostedService. Los servicios hospedados se pueden usar en aplicaciones de Worker Service y en aplicaciones web. En este artículo se incluyen tres ejemplos de servicio hospedado:

  • Una tarea en segundo plano que se ejecuta mediante un temporizador.
  • Un servicio hospedado que activa un servicio delimitado. El servicio con ámbito puede usar la inserción de dependencias (DI).
  • Tareas en segundo plano en cola que se ejecutan en secuencia.

Plantilla Worker Service

La plantilla Worker Service de ASP.NET Core sirve de punto de partida para escribir aplicaciones de servicio de larga duración. Una aplicación creada a partir de la plantilla Worker Service especifica el SDK de trabajo en su archivo del proyecto:

<Project Sdk="Microsoft.NET.Sdk.Worker">

Para usar la plantilla como base de una aplicación de servicios hospedados:

  1. Cree un nuevo proyecto.
  2. Seleccione Worker Service (Servicio de Trabajo). Seleccione Siguiente.
  3. Proporcione un nombre para el proyecto en el campo Nombre del proyecto o acepte el predeterminado. Seleccione Siguiente.
  4. En el cuadro de diálogo Información adicional, elija Marco de trabajo. Selecciona Crear.

Package

Una aplicación basada en la plantilla de servicio de trabajo usa el Microsoft.NET.Sdk.Worker SDK y tiene una referencia de paquete explícita al Microsoft.Extensions.Hosting paquete NuGet. Por ejemplo, consulte el archivo de proyecto de la aplicación de ejemplo de Worker Service (BackgroundTasksSample.csproj).

En el caso de las aplicaciones web que usan el Microsoft.NET.Sdk.Web SDK, se hace referencia implícitamente al Microsoft.Extensions.Hosting paquete NuGet desde el marco compartido. No se requiere una referencia de paquete explícita en el archivo del proyecto de la aplicación.

Servicios hospedados en una aplicación web

Los servicios hospedados no se limitan a las aplicaciones de Worker Service. Una aplicación web que usa el Microsoft.NET.Sdk.Web SDK registra los servicios hospedados en el archivo Program llamando al mismo método de extensión AddHostedService en WebApplicationBuilder.Services. El host inicia y detiene automáticamente los servicios hospedados registrados, tal y como se describe en la sección IHostedService Interfaz.

El siguiente Program archivo procede de la aplicación de ejemplo web (BackgroundTasksWebSample). Registra los tres servicios hospedados que se describen en el resto de este artículo, asigna un punto de conexión raíz que devuelve un mensaje de estado y agrega un punto de conexión que pone en cola un elemento de trabajo para uno de ellos:

using BackgroundTasksWebSample.Services;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHostedService<TimedHostedService>();

builder.Services.AddHostedService<ConsumeScopedServiceHostedService>();
builder.Services.AddScoped<IScopedProcessingService, ScopedProcessingService>();

builder.Services.AddHostedService<QueuedHostedService>();
builder.Services.AddSingleton<IBackgroundTaskQueue>(_ =>
    new BackgroundTaskQueue(builder.Configuration.GetValue("QueueCapacity", 100)));

var app = builder.Build();

app.MapGet("/", () => "Hosted service is running in the background.");

app.MapPost("/queue", async (
    IBackgroundTaskQueue taskQueue,
    ILogger<Program> logger,
    CancellationToken cancellationToken) =>
{
    await taskQueue.QueueBackgroundWorkItemAsync(async token =>
    {
        var guid = Guid.NewGuid();

        logger.LogInformation("Queued Background Task {Guid} is starting.", guid);

        try
        {
            await Task.Delay(TimeSpan.FromSeconds(5), token);
        }
        catch (OperationCanceledException)
        {
            logger.LogInformation("Queued Background Task {Guid} was cancelled.", guid);

            return;
        }

        logger.LogInformation("Queued Background Task {Guid} is complete.", guid);
    }, cancellationToken);

    return Results.Accepted();
});

app.Run();

En el código anterior:

  • TimedHostedService, ConsumeScopedServiceHostedServicey QueuedHostedService se registran con el método de AddHostedService extensión.
  • Un servicio hospedado se registra como un singleton, por lo que no puede recibir servicios con ámbito, como un Entity Framework Core DbContext, mediante inyección de compilador. IScopedProcessingService se registra como un servicio con ámbito y ConsumeScopedServiceHostedService crea un ámbito para resolverlo. Para obtener más información, consulte la sección Consumo de un servicio con ámbito en una tarea en segundo plano .
  • El singleton IBackgroundTaskQueue es consumido por el punto de conexión /queue y QueuedHostedService. Una POST solicitud a /queue devuelve una 202 Accepted respuesta una vez que el elemento de trabajo está en cola sin esperar a que se ejecute. Si la cola delimitada está llena, la solicitud espera hasta que haya espacio disponible para poner en cola el elemento de trabajo. QueuedHostedService ejecuta los elementos de trabajo en cola en segundo plano. Para obtener más información, consulte la sección Tareas en segundo plano en cola .

Los siguientes fragmentos de código de registro de servicio proceden de la aplicación de ejemplo de Servicio de trabajo (BackgroundTasksSample), donde services es el IServiceCollection parámetro pasado a ConfigureServices. En una aplicación web, use builder.Services en lugar de services.

Interfaz IHostedService

La interfaz IHostedService define dos métodos para los objetos administrados por el host:

StartAsync

StartAsync(CancellationToken) contiene la lógica para iniciar la tarea en segundo plano. StartAsync se llama antes de:

StartAsync debe limitarse a las tareas de ejecución corta porque los servicios hospedados se ejecutan secuencialmente y no se inician otros servicios hasta que StartAsync se complete.

Las instancias de los servicios hospedados se inician en el orden en que se registran en el contenedor de inyección de dependencias, a menos que la aplicación opte por un inicio simultáneo estableciendo ServicesStartConcurrently en true:

builder.Services.Configure<HostOptions>(options =>
{
    options.ServicesStartConcurrently = true;
});

StopAsync

El token de cancelación tiene un tiempo de espera predeterminado de 30 segundos para indicar que el proceso de cierre ya no será suave. Cuando se solicita la cancelación en el token:

  • Se deben anular las operaciones restantes en segundo plano que realiza la aplicación.
  • Los métodos llamados en StopAsync deberían devolver de inmediato.

Pero las tareas no se abandonan después de solicitar la cancelación, sino que el autor de la llamada espera a que se completen todas las tareas.

Si la aplicación se cierra inesperadamente (por ejemplo, porque se produzca un error en el proceso de la aplicación), puede que no sea posible llamar a StopAsync. Por lo tanto, los métodos invocados o las operaciones llevadas a cabo en StopAsync puede que no se realicen.

Para ampliar el tiempo de espera predeterminado de apagado de 30 segundos, establezca:

El servicio hospedado se activa una vez al inicio de la aplicación y se cierra de manera estable cuando dicha aplicación se cierra. Si se produce un error durante la ejecución de una tarea en segundo plano, hay que llamar a Dispose, aun cuando no se haya llamado a StopAsync.

Las instancias de servicio hospedadas se detienen en el orden inverso a aquel en que se hayan registrado en el contenedor de inyección de dependencias, a menos que la aplicación opte por el comportamiento de apagado en paralelo estableciendo ServicesStopConcurrently en true:

builder.Services.Configure<HostOptions>(options =>
{
    options.ServicesStopConcurrently = true;
});

Clase base BackgroundService

BackgroundService es una clase base para implementar un IHostedService de larga duración.

Se llama a ExecuteAsync(CancellationToken) en el grupo de subprocesos para ejecutar el servicio en segundo plano. La implementación devuelve Task, que representa toda la duración del servicio en segundo plano. El host se bloquea en StopAsync(CancellationToken) a la espera de que ExecuteAsync se complete.

El token de cancelación se desencadena cuando se llama a IHostedService.StopAsync. La implementación de ExecuteAsync debe finalizar rápidamente cuando se active el token de cancelación para cerrar correctamente el servicio. De lo contrario, el servicio se cierra de manera abrupta durante el tiempo de expiración del cierre. Para más información, consulte la sección sobre la interfaz IHostedService.

Para obtener más información, vea el código fuente de BackgroundService.

Tareas en segundo plano temporizadas

Una tarea en segundo plano temporizada hace uso de la clase System.Threading.Timer. El temporizador activa el método DoWork de la tarea. El temporizador está deshabilitado en StopAsync y se desecha cuando el contenedor de servicios se elimina en Dispose:

public class TimedHostedService(ILogger<TimedHostedService> logger) : IHostedService, IDisposable
{
    private int executionCount = 0;
    private Timer? _timer = null;

    public Task StartAsync(CancellationToken stoppingToken)
    {
        logger.LogInformation("Timed Hosted Service running.");

        _timer = new Timer(DoWork, null, TimeSpan.Zero,
            TimeSpan.FromSeconds(5));

        return Task.CompletedTask;
    }

    private void DoWork(object? state)
    {
        var count = Interlocked.Increment(ref executionCount);

        logger.LogInformation(
            "Timed Hosted Service is working. Count: {Count}", count);
    }

    public Task StopAsync(CancellationToken stoppingToken)
    {
        logger.LogInformation("Timed Hosted Service is stopping.");

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

        return Task.CompletedTask;
    }

    public void Dispose()
    {
        _timer?.Dispose();
    }
}

Timer no espera a que finalicen las ejecuciones anteriores de DoWork, por lo que es posible que el enfoque mostrado no sea adecuado para todos los escenarios. Interlocked.Increment se usa para incrementar el contador de ejecución como una operación atómica, lo que garantiza que varios subprocesos no se actualicen executionCount simultáneamente.

El servicio se registra en el archivo Program con el método de extensión AddHostedService:

services.AddHostedService<TimedHostedService>();

Consumir un servicio de ámbito definido en una tarea en segundo plano

Para usar servicios con ámbito dentro de un BackgroundService, cree un ámbito. No se crean ámbitos de forma predeterminada para los servicios hospedados.

El servicio de tareas en segundo plano acotado contiene la lógica de la tarea en segundo plano. En el ejemplo siguiente:

  • El servicio es asincrónico. El método DoWork devuelve un objeto Task. Para fines de demostración, se espera un retraso de diez segundos en el método DoWork.
  • ILogger se inserta en el servicio.
internal interface IScopedProcessingService
{
    Task DoWork(CancellationToken stoppingToken);
}

internal class ScopedProcessingService(
    ILogger<ScopedProcessingService> logger) : IScopedProcessingService
{
    private int executionCount = 0;

    public async Task DoWork(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            executionCount++;

            logger.LogInformation(
                "Scoped Processing Service is working. Count: {Count}", executionCount);

            await Task.Delay(10000, stoppingToken);
        }
    }
}

El servicio hospedado crea un ámbito con el fin de resolver el servicio de tareas en segundo plano con ámbito para llamar a su método DoWork. DoWork devuelve un objeto Task, del que se espera su finalización en ExecuteAsync:

public class ConsumeScopedServiceHostedService(
    IServiceProvider services,
    ILogger<ConsumeScopedServiceHostedService> logger) : BackgroundService
{
    public IServiceProvider Services { get; } = services;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        logger.LogInformation(
            "Consume Scoped Service Hosted Service running.");

        await DoWork(stoppingToken);
    }

    private async Task DoWork(CancellationToken stoppingToken)
    {
        logger.LogInformation(
            "Consume Scoped Service Hosted Service is working.");

        using (var scope = Services.CreateScope())
        {
            var scopedProcessingService =
                scope.ServiceProvider
                    .GetRequiredService<IScopedProcessingService>();

            await scopedProcessingService.DoWork(stoppingToken);
        }
    }

    public override async Task StopAsync(CancellationToken stoppingToken)
    {
        logger.LogInformation(
            "Consume Scoped Service Hosted Service is stopping.");

        await base.StopAsync(stoppingToken);
    }
}

Los servicios se registran en el Program archivo. El servicio hospedado se registra con el método de extensión AddHostedService:

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

Tareas en segundo plano en cola

Una cola de tareas en segundo plano se basa en .NET Framework 4.x QueueBackgroundWorkItem:

public interface IBackgroundTaskQueue
{
    ValueTask QueueBackgroundWorkItemAsync(Func<CancellationToken, ValueTask> workItem);

    ValueTask<Func<CancellationToken, ValueTask>> DequeueAsync(
        CancellationToken cancellationToken);
}

public class BackgroundTaskQueue(int capacity) : IBackgroundTaskQueue
{
    // Capacity should be set based on the expected application load and
    // number of concurrent threads accessing the queue.
    // BoundedChannelFullMode.Wait causes calls to WriteAsync() to return a task,
    // which only completes when space becomes available. In the event that many
    // publishers/calls start accumulating, using BoundedChannelFullMode.Wait can
    // lead to backpressure.
    private readonly Channel<Func<CancellationToken, ValueTask>> _queue =
        Channel.CreateBounded<Func<CancellationToken, ValueTask>>(new BoundedChannelOptions(capacity)
        {
            FullMode = BoundedChannelFullMode.Wait
        });

    public async ValueTask QueueBackgroundWorkItemAsync(
        Func<CancellationToken, ValueTask> workItem)
    {
        if (workItem == null)
        {
            throw new ArgumentNullException(nameof(workItem));
        }

        await _queue.Writer.WriteAsync(workItem);
    }

    public async ValueTask<Func<CancellationToken, ValueTask>> DequeueAsync(
        CancellationToken cancellationToken)
    {
        var workItem = await _queue.Reader.ReadAsync(cancellationToken);

        return workItem;
    }
}

En el ejemplo QueueHostedService siguiente:

  • El método BackgroundProcessing devuelve Task, que se espera en ExecuteAsync.
  • Las tareas en segundo plano que están en cola se quitan de ella y se ejecutan en BackgroundProcessing.
  • Se esperan elementos de trabajo antes de que el servicio se detenga en StopAsync.
public class QueuedHostedService(
    IBackgroundTaskQueue taskQueue,
    ILogger<QueuedHostedService> logger) : BackgroundService
{
    public IBackgroundTaskQueue TaskQueue { get; } = taskQueue;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        logger.LogInformation(
            $"Queued Hosted Service is running.{Environment.NewLine}" +
            $"{Environment.NewLine}Tap W to add a work item to the " +
            $"background queue.{Environment.NewLine}");

        await BackgroundProcessing(stoppingToken);
    }

    private async Task BackgroundProcessing(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            var workItem =
                await TaskQueue.DequeueAsync(stoppingToken);

            try
            {
                await workItem(stoppingToken);
            }
            catch (Exception ex)
            {
                logger.LogError(ex,
                    "Error occurred executing {WorkItem}.", nameof(workItem));
            }
        }
    }

    public override async Task StopAsync(CancellationToken stoppingToken)
    {
        logger.LogInformation("Queued Hosted Service is stopping.");

        await base.StopAsync(stoppingToken);
    }
}

Un servicio MonitorLoop controla las tareas de puesta en cola para el servicio hospedado cada vez que se selecciona la tecla w en un dispositivo de entrada:

  • IBackgroundTaskQueue se inserta en el servicio MonitorLoop.
  • IBackgroundTaskQueue.QueueBackgroundWorkItem se llama para poner en cola un elemento de trabajo.
  • El elemento de trabajo simula una tarea en segundo plano de larga duración:
    • Se ejecutan tres pausas de 5 segundos (Task.Delay).
    • Una instrucción try-catch captura OperationCanceledException si se cancela la tarea.
public class MonitorLoop(
    IBackgroundTaskQueue taskQueue,
    ILogger<MonitorLoop> logger,
    IHostApplicationLifetime applicationLifetime)
{
    private readonly CancellationToken _cancellationToken = applicationLifetime.ApplicationStopping;

    public void StartMonitorLoop()
    {
        logger.LogInformation("MonitorAsync Loop is starting.");

        // Run a console user input loop in a background thread
        Task.Run(async () => await MonitorAsync());
    }

    private async ValueTask MonitorAsync()
    {
        while (!_cancellationToken.IsCancellationRequested)
        {
            var keyStroke = Console.ReadKey();

            if (keyStroke.Key == ConsoleKey.W)
            {
                // Enqueue a background work item
                await taskQueue.QueueBackgroundWorkItemAsync(BuildWorkItem);
            }
        }
    }

    private async ValueTask BuildWorkItem(CancellationToken token)
    {
        // Simulate three 5-second tasks to complete
        // for each enqueued work item

        int delayLoop = 0;
        var guid = Guid.NewGuid().ToString();

        logger.LogInformation("Queued Background Task {Guid} is starting.", guid);

        while (!token.IsCancellationRequested && delayLoop < 3)
        {
            try
            {
                await Task.Delay(TimeSpan.FromSeconds(5), token);
            }
            catch (OperationCanceledException)
            {
                // Prevent throwing if the Delay is cancelled
            }

            delayLoop++;

            logger.LogInformation("Queued Background Task {Guid} is running. "
                                   + "{DelayLoop}/3", guid, delayLoop);
        }

        if (delayLoop == 3)
        {
            logger.LogInformation("Queued Background Task {Guid} is complete.", guid);
        }
        else
        {
            logger.LogInformation("Queued Background Task {Guid} was cancelled.", guid);
        }
    }
}

Los servicios se registran en el Program archivo. El servicio hospedado se registra con el método de extensión AddHostedService:

services.AddSingleton<MonitorLoop>();
services.AddHostedService<QueuedHostedService>();
services.AddSingleton<IBackgroundTaskQueue>(ctx =>
{
    if (!int.TryParse(hostContext.Configuration["QueueCapacity"], out var queueCapacity))
        queueCapacity = 100;
    return new BackgroundTaskQueue(queueCapacity);
});

MonitorLoop se inicia en el Program archivo :

var monitorLoop = host.Services.GetRequiredService<MonitorLoop>();
monitorLoop.StartMonitorLoop();

En una aplicación web, un punto de conexión puede poner en cola elementos de trabajo en lugar de usar un bucle de entrada por consola. Para obtener un ejemplo, consulte la sección Servicios hospedados en una aplicación web .

Tarea en segundo plano asincrónica temporizada

El código siguiente crea una tarea en segundo plano asincrónica temporizada:

namespace TimedBackgroundTasks;

public class TimedHostedService : BackgroundService
{
    private readonly ILogger<TimedHostedService> _logger;
    private int _executionCount;

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

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        _logger.LogInformation("Timed Hosted Service running.");

        // When the timer should have no due-time, then do the work once now.
        await DoWork();

        using PeriodicTimer timer = new(TimeSpan.FromSeconds(30));

        try
        {
            while (await timer.WaitForNextTickAsync(stoppingToken))
            {
                await DoWork();
            }
        }
        catch (OperationCanceledException)
        {
            _logger.LogInformation("Timed Hosted Service is stopping.");
        }
    }

    private async Task DoWork()
    {
        int count = Interlocked.Increment(ref _executionCount);

        // Simulate work
        await Task.Delay(TimeSpan.FromSeconds(2));

        _logger.LogInformation("Timed Hosted Service is working. Count: {Count}", count);
    }
}

AOT nativo

Las plantillas de servicio de trabajo admiten .NET ahead-of-time (AOT) nativa con la marca --aot:

  1. Cree un nuevo proyecto.
  2. Seleccione Worker Service (Servicio de Trabajo). Seleccione Siguiente.
  3. Proporcione un nombre para el proyecto en el campo Nombre del proyecto o acepte el predeterminado. Seleccione Siguiente.
  4. En el cuadro de diálogo Información adicional:
  5. Seleccione un entorno de desarrollo.
  6. Active la casilla Habilitar publicación nativa mediante AOT.
  7. Selecciona Crear.

La opción AOT agrega <PublishAot>true</PublishAot> al archivo del proyecto:


<Project Sdk="Microsoft.NET.Sdk.Worker">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <InvariantGlobalization>true</InvariantGlobalization>
+   <PublishAot>true</PublishAot>
    <UserSecretsId>dotnet-WorkerWithAot-e94b2</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="10.0.0" />
  </ItemGroup>
</Project>