Introducción

En aplicaciones corporativas con alto volumen de procesamiento, no todo puede — ni debe — ocurrir dentro de una solicitud HTTP. Importaciones masivas, consumo de colas de mensajería, sincronizaciones periódicas, envío de notificaciones en lote, procesamiento de eventos de dominio — estos escenarios exigen procesos en segundo plano que se ejecuten de forma continua, independientes de las solicitudes, y que sobrevivan a reinicios de forma controlada.

.NET 8+ ofrece una infraestructura robusta para esto: los Worker Services y la clase BackgroundService. Construidos sobre el Generic Host (IHost), comparten el mismo pipeline de inyección de dependencias, configuración y logging de las Web APIs — pero sin el overhead de Kestrel y del middleware HTTP. Esto significa que todo lo que ya sabes sobre IOptions<T>, ILogger<T>, IServiceProvider y ciclos de vida de DI se aplica directamente a los Workers.

En este artículo, voy a explorar los tipos de Workers, cómo se comportan los ciclos de vida Singleton, Scoped y Transient en este contexto (con trampas que sorprenden a muchos desarrolladores) y cómo los Workers se integran de forma nativa con paginación de grandes volúmenes, mensajería para desacoplamiento, paralelismo con Parallel y Tasks y programación asíncrona con async/await.

💡 Consejo: Si tu aplicación usa hoy un Task.Run() dentro de un controller para “procesar en segundo plano”, este artículo te mostrará el enfoque correcto y listo para producción para ese escenario.

📦 Código fuente: La implementación completa de este artículo está en el repositorio blog-zocateli-sample en GitHub. Clónalo, explóralo y adáptalo a tu contexto.


Qué Es un .NET Worker Service

Un Worker Service es una aplicación .NET sin interfaz web, diseñada para ejecutar tareas en segundo plano de forma continua o periódica. Usa el Generic Host — la misma infraestructura que una Web API usa internamente — pero sin el servidor HTTP (Kestrel).

Creando un Worker Service

1
2
3
4
5
6
7
8
9
# Crear un nuevo proyecto Worker
dotnet new worker -n MeuWorker -o src/MeuWorker

# Estructura generada:
# src/MeuWorker/
# ├── Program.cs           ← registro del host y DI
# ├── Worker.cs            ← clase BackgroundService
# ├── appsettings.json     ← configuración (mismo pipeline que las Web APIs)
# └── MeuWorker.csproj
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
// Program.cs — punto de entrada del Worker
var builder = Host.CreateApplicationBuilder(args);

// Misma configuración que una Web API:
// appsettings.json → appsettings.{Env}.json → User Secrets → Env Vars → CLI args
// Para detalles del pipeline de configuración, ver:
// /es/posts/2026/pipeline-configuracao-dotnet8-ioptions-secrets-docker/

builder.Services.AddHostedService<MeuWorker>();

var host = builder.Build();
host.Run();
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
// Worker.cs — BackgroundService predeterminado
public class MeuWorker(ILogger<MeuWorker> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            logger.LogInformation("Worker ejecutándose en: {Time}", DateTimeOffset.Now);
            await Task.Delay(TimeSpan.FromSeconds(30), stoppingToken);
        }
    }
}

Generic Host vs WebApplication

AspectoHost.CreateApplicationBuilderWebApplication.CreateBuilder
Pipeline de configuración✅ Idéntico✅ Idéntico
Inyección de dependencias✅ Idéntica✅ Idéntica
Logging✅ Idéntico✅ Idéntico
IOptions✅ Idéntico✅ Idéntico
Servidor HTTP (Kestrel)❌ No incluido✅ Incluido
Pipeline de middleware❌ No aplicable✅ Incluido
Endpoints / Controllers❌ No aplicable✅ Incluido
Uso típicoProcesamiento en segundo plano, colasAPIs HTTP, apps web

ℹ️ Información: Como el pipeline de configuración es idéntico, todo lo explicado en Pipeline de Configuración en .NET 8+ — orden de los providers, IOptions<T>, Docker secrets, AddKeyPerFile — se aplica directamente a los Workers.


IHostedService vs BackgroundService

.NET ofrece dos abstracciones para servicios en segundo plano. Entender la diferencia es fundamental:

IHostedService — Control Total

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
public class MeuServicoHosted : IHostedService, IDisposable
{
    private Timer? _timer;

    public Task StartAsync(CancellationToken cancellationToken)
    {
        // Ejecutado UNA VEZ cuando el host inicia
        _timer = new Timer(
            callback: ExecutarTarefa,
            state: null,
            dueTime: TimeSpan.Zero,
            period: TimeSpan.FromMinutes(5));

        return Task.CompletedTask;
    }

    private void ExecutarTarefa(object? state)
    {
        // Lógica ejecutada cada 5 minutos
        // ⚠️ CUIDADO: este callback se ejecuta en un hilo del ThreadPool,
        // no en un contexto async — evite operaciones bloqueantes largas
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        // Ejecutado UNA VEZ cuando el host se está deteniendo
        _timer?.Change(Timeout.Infinite, 0);
        return Task.CompletedTask;
    }

    public void Dispose() => _timer?.Dispose();
}

BackgroundService — Abstracción Simplificada

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
public class MeuWorker(ILogger<MeuWorker> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        // Se ejecuta en bucle mientras la aplicación esté activa
        // El CancellationToken se dispara automáticamente en el shutdown
        while (!stoppingToken.IsCancellationRequested)
        {
            await ProcessarAsync(stoppingToken);
            await Task.Delay(TimeSpan.FromMinutes(5), stoppingToken);
        }
    }

    private async Task ProcessarAsync(CancellationToken ct)
    {
        logger.LogInformation("Procesando...");
        // Lógica asíncrona aquí
    }
}
AspectoIHostedServiceBackgroundService
ControlStartAsync + StopAsync manualExecuteAsync con bucle automático
Timer/PollingImplementar manualmente con TimerUsar Task.Delay dentro del bucle
Escenario idealInicialización/limpieza complejaBucles de procesamiento continuo
CancellationTokenRecibido en StartAsync/StopAsyncRecibido en ExecuteAsync
Hereda deInterfaz (IHostedService)Clase abstracta (BackgroundService)

⚠️ Atención: El ExecuteAsync del BackgroundService se ejecuta en segundo plano. Si lanzaba una excepción no tratada antes de .NET 8, el host seguía ejecutándose silenciosamente con el worker muerto. A partir de .NET 8, las excepciones no tratadas en ExecuteAsync detienen todo el host de forma predeterminada (comportamiento configurable vía HostOptions.BackgroundServiceExceptionBehavior).


Tipos de Workers y Sus Casos de Uso

En la práctica corporativa, los Workers se dividen en patrones recurrentes. Elegir el tipo correcto para cada escenario evita complejidad innecesaria:

1. Timer Worker (Polling)

Ejecuta una tarea a intervalos regulares. Ideal para sincronizaciones periódicas, limpieza de datos expirados y health checks:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
public class SincronizacaoWorker(
    ILogger<SincronizacaoWorker> logger,
    IServiceScopeFactory scopeFactory) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                using var scope = scopeFactory.CreateScope();
                var servico = scope.ServiceProvider
                    .GetRequiredService<ISincronizacaoService>();

                await servico.SincronizarAsync(stoppingToken);
            }
            catch (Exception ex) when (ex is not OperationCanceledException)
            {
                logger.LogError(ex, "Error en la sincronización periódica");
            }

            await Task.Delay(TimeSpan.FromMinutes(10), stoppingToken);
        }
    }
}

2. Queue Worker (Mensajería)

Consume mensajes de una cola (RabbitMQ, Azure Service Bus, Amazon SQS) en un bucle continuo. Este es el patrón más común para desacoplar servicios — exactamente el escenario descrito en Cuello de Botella en Bases de Datos: Mensajería y Paginación:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
public class FilaPedidosWorker(
    ILogger<FilaPedidosWorker> logger,
    IServiceScopeFactory scopeFactory,
    IConnection rabbitConnection) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        using var channel = await rabbitConnection.CreateChannelAsync(
            cancellationToken: stoppingToken);

        await channel.QueueDeclareAsync(
            queue: "pedidos-processamento",
            durable: true,
            exclusive: false,
            autoDelete: false,
            cancellationToken: stoppingToken);

        var consumer = new AsyncEventingBasicConsumer(channel);
        consumer.ReceivedAsync += async (_, ea) =>
        {
            try
            {
                using var scope = scopeFactory.CreateScope();
                var processador = scope.ServiceProvider
                    .GetRequiredService<IProcessadorPedido>();

                var pedido = JsonSerializer.Deserialize<PedidoEvento>(
                    ea.Body.Span);

                await processador.ProcessarAsync(pedido!, stoppingToken);

                await channel.BasicAckAsync(ea.DeliveryTag, false,
                    stoppingToken);
            }
            catch (Exception ex)
            {
                logger.LogError(ex, "Error al procesar pedido");
                await channel.BasicNackAsync(ea.DeliveryTag, false, true,
                    stoppingToken);
            }
        };

        await channel.BasicConsumeAsync(
            queue: "pedidos-processamento",
            autoAck: false,
            consumer: consumer,
            cancellationToken: stoppingToken);

        // Mantener el worker en ejecución mientras no sea cancelado
        await Task.Delay(Timeout.Infinite, stoppingToken);
    }
}

3. Batch Processing Worker

Procesa grandes volúmenes de datos en lotes paginados, evitando cargar todo en memoria. Se combina naturalmente con paginación Keyset para procesar millones de registros de forma eficiente:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
public class ProcessamentoLoteWorker(
    ILogger<ProcessamentoLoteWorker> logger,
    IServiceScopeFactory scopeFactory) : BackgroundService
{
    private const int TamanhoPagina = 500;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            var processados = await ProcessarLoteAsync(stoppingToken);

            if (processados == 0)
            {
                // Sin elementos pendientes — esperar antes de verificar de nuevo
                await Task.Delay(TimeSpan.FromSeconds(30), stoppingToken);
            }
        }
    }

    private async Task<int> ProcessarLoteAsync(CancellationToken ct)
    {
        using var scope = scopeFactory.CreateScope();
        var dbContext = scope.ServiceProvider.GetRequiredService<AppDbContext>();

        // Paginación Keyset — eficiente para grandes volúmenes
        var pendentes = await dbContext.Pedidos
            .Where(p => p.Status == StatusPedido.Pendente)
            .OrderBy(p => p.Id)
            .Take(TamanhoPagina)
            .ToListAsync(ct);

        if (pendentes.Count == 0) return 0;

        foreach (var pedido in pendentes)
        {
            pedido.Status = StatusPedido.Processado;
            pedido.ProcessadoEm = DateTimeOffset.UtcNow;
        }

        await dbContext.SaveChangesAsync(ct);
        logger.LogInformation("Procesados {Count} pedidos", pendentes.Count);

        return pendentes.Count;
    }
}

4. Worker con Paralelismo

Para escenarios donde el procesamiento individual es lento (llamadas HTTP, cálculos pesados), el Worker puede usar paralelismo controlado. Esto se conecta directamente con los conceptos de Paralelismo en C#: Parallel, PLINQ y Tasks en la Práctica:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
public class ProcessamentoParaleloWorker(
    ILogger<ProcessamentoParaleloWorker> logger,
    IServiceScopeFactory scopeFactory,
    IOptions<WorkerConfig> options) : BackgroundService
{
    private readonly int _maxParallelism = options.Value.MaxParallelism;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            using var scope = scopeFactory.CreateScope();
            var dbContext = scope.ServiceProvider
                .GetRequiredService<AppDbContext>();

            var itens = await dbContext.FilaProcessamento
                .Where(f => f.Status == StatusFila.Aguardando)
                .OrderBy(f => f.CriadoEm)
                .Take(100)
                .ToListAsync(stoppingToken);

            if (itens.Count == 0)
            {
                await Task.Delay(TimeSpan.FromSeconds(10), stoppingToken);
                continue;
            }

            // Procesar con paralelismo controlado vía SemaphoreSlim
            using var semaphore = new SemaphoreSlim(_maxParallelism);
            var tasks = itens.Select(async item =>
            {
                await semaphore.WaitAsync(stoppingToken);
                try
                {
                    // Cada elemento se procesa en su propio scope
                    using var itemScope = scopeFactory.CreateScope();
                    var processador = itemScope.ServiceProvider
                        .GetRequiredService<IProcessadorItem>();

                    await processador.ProcessarAsync(item, stoppingToken);
                }
                finally
                {
                    semaphore.Release();
                }
            });

            await Task.WhenAll(tasks);
            logger.LogInformation("Lote procesado: {Count} elementos", itens.Count);
        }
    }
}

💡 Consejo: Observa el patrón SemaphoreSlim + Task.WhenAll — permite paralelismo controlado sin sobrecargar recursos. Cada elemento usa su propio scope de DI (CreateScope), garantizando que DbContext y otros servicios Scoped sean independientes entre las tareas. Para más detalles sobre paralelismo controlado, consulta Paralelismo en C#.


Ciclos de Vida en un Worker Service

Esta es la sección más importante del artículo — y la que más bugs causa en producción. Los ciclos de vida de DI (Singleton, Scoped, Transient) se comportan de forma diferente en Workers en comparación con las Web APIs, porque no existe el concepto de “solicitud HTTP” para crear scopes automáticamente.

El Problema: Los Workers Son Singleton

El BackgroundService se registra como Singleton mediante AddHostedService<T>(). Esto significa que todas sus dependencias inyectadas por el constructor también deben ser Singleton — o tendrás problemas:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
// ❌ INCORRECTO — DbContext es Scoped, Worker es Singleton
public class WorkerErrado(
    ILogger<WorkerErrado> logger,
    AppDbContext dbContext) : BackgroundService  // ⚠️ ¡Lanzará InvalidOperationException!
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        // Este código NUNCA se ejecuta — la DI falla en la resolución
        var itens = await dbContext.Pedidos.ToListAsync(stoppingToken);
    }
}

// Error en runtime:
// InvalidOperationException: Cannot consume scoped service 'AppDbContext'
// from singleton 'WorkerErrado'.

La Solución: IServiceScopeFactory

El patrón correcto es inyectar IServiceScopeFactory (que es Singleton) y crear scopes manualmente:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
// ✅ CORRECTO — crea un scope manual para servicios Scoped
public class WorkerCorreto(
    ILogger<WorkerCorreto> logger,
    IServiceScopeFactory scopeFactory) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            // Cada iteración crea un scope nuevo — como un "request virtual"
            using (var scope = scopeFactory.CreateScope())
            {
                var dbContext = scope.ServiceProvider
                    .GetRequiredService<AppDbContext>();

                var servico = scope.ServiceProvider
                    .GetRequiredService<IProcessadorPedido>();

                await servico.ProcessarPendentesAsync(stoppingToken);
            }
            // El scope se descarta aquí — DbContext se libera,
            // las conexiones se devuelven al pool

            await Task.Delay(TimeSpan.FromSeconds(30), stoppingToken);
        }
    }
}

Comportamiento de los Ciclos de Vida en Workers

Ciclo de vida¿Inyectar en el constructor del Worker?¿Vía CreateScope?Comportamiento
Singleton✅ Sí✅ SíMisma instancia durante toda la vida del host
Scoped❌ InvalidOperationException✅ Sí (obligatorio)Nueva instancia por scope creado manualmente
Transient⚠️ Funciona, pero es peligroso✅ Sí (recomendado)Nueva instancia en cada resolución — sin scope, fuga de memoria

Por Qué Transient en el Constructor Es Peligroso

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
// ⚠️ PELIGROSO — Transient en el constructor de un Singleton
public class WorkerPerigoso(
    ILogger<WorkerPerigoso> logger,
    IServiceScopeFactory scopeFactory,
    HttpClient httpClient) : BackgroundService  // HttpClient es Transient...
{
    // httpClient se crea UNA VEZ y nunca se descarta
    // → fuga de memoria (connection pool agotado)
    // → DNS stale (no respeta el TTL del DNS)
}

// ✅ CORRECTO — usar IHttpClientFactory (Singleton-safe)
public class WorkerSeguro(
    ILogger<WorkerSeguro> logger,
    IServiceScopeFactory scopeFactory,
    IHttpClientFactory httpClientFactory) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            // Crea un HttpClient con pool gestionado (Singleton-safe)
            using var client = httpClientFactory.CreateClient("meu-servico");
            var response = await client.GetAsync("/api/status", stoppingToken);
            // ...
        }
    }
}

⚠️ Atención: En las Web APIs, ASP.NET Core crea scopes automáticamente para cada solicitud HTTP. En los Workers, tú eres responsable de crear scopes manualmente siempre que necesites servicios Scoped o Transient. Olvidar crear el scope es la causa n.º 1 de fugas de memoria y de agotamiento del connection pool en Workers.

Diagrama: Scope de DI en Web API vs Worker

Diagrama comparando el comportamiento de los ciclos de vida de DI (Singleton, Scoped, Transient) entre una Web API con scope automático por solicitud y un Worker Service con scope manual vía IServiceScopeFactory

En una Web API, cada solicitud HTTP crea automáticamente un scope de DI. En el Worker, ExecuteAsync se ejecuta en un único scope Singleton — por eso necesitas crear scopes manualmente con IServiceScopeFactory.CreateScope() para simular el mismo aislamiento.


Workers en la Práctica Corporativa

Worker como Consumidor de Mensajería

El patrón más potente de Workers en entornos corporativos es el consumo de colas de mensajería. En lugar de procesar todo de forma síncrona dentro de la API, la API publica un evento en la cola y el Worker lo consume y procesa en segundo plano — exactamente el patrón descrito en Cuello de Botella en Bases de Datos: Mensajería y Paginación:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
// Program.cs — registro completo de un Worker con mensajería
var builder = Host.CreateApplicationBuilder(args);

// Configuración tipada
builder.Services.Configure<RabbitMqConfig>(
    builder.Configuration.GetSection("RabbitMq"));

// Conexión RabbitMQ (Singleton)
builder.Services.AddSingleton<IConnection>(sp =>
{
    var config = sp.GetRequiredService<IOptions<RabbitMqConfig>>().Value;
    var factory = new ConnectionFactory
    {
        HostName = config.Host,
        Port = config.Port,
        UserName = config.Username,
        Password = config.Password,
        DispatchConsumersAsync = true  // Obligatorio para AsyncEventingBasicConsumer
    };
    return factory.CreateConnectionAsync().GetAwaiter().GetResult();
});

// Servicios de dominio (Scoped — resueltos vía CreateScope en el Worker)
builder.Services.AddScoped<IProcessadorPedido, ProcessadorPedido>();
builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(builder.Configuration
        .GetConnectionString("Default")));

// Worker (Singleton)
builder.Services.AddHostedService<FilaPedidosWorker>();

var host = builder.Build();
host.Run();

Worker para Procesamiento de Grandes Volúmenes con Paginación

Cuando necesitas procesar millones de registros (migración de datos, recálculo de saldos, reindexación), el Worker se combina con la paginación Keyset para procesar en bloques sin sobrecargar la memoria:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
public class MigracaoWorker(
    ILogger<MigracaoWorker> logger,
    IServiceScopeFactory scopeFactory) : BackgroundService
{
    private const int TamanhoPagina = 1000;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        long ultimoId = 0;
        var totalProcessados = 0;

        while (!stoppingToken.IsCancellationRequested)
        {
            using var scope = scopeFactory.CreateScope();
            var dbContext = scope.ServiceProvider
                .GetRequiredService<AppDbContext>();

            // Paginación Keyset — sin OFFSET, rendimiento constante
            // Ver: /es/posts/2026/paginacao-api-rest-csharp-efcore-sqlserver-oracle-postgres/
            var lote = await dbContext.Clientes
                .Where(c => c.Id > ultimoId && !c.Migrado)
                .OrderBy(c => c.Id)
                .Take(TamanhoPagina)
                .ToListAsync(stoppingToken);

            if (lote.Count == 0)
            {
                logger.LogInformation(
                    "Migración completada. Total: {Total}", totalProcessados);
                return; // El Worker termina cuando no hay más datos
            }

            foreach (var cliente in lote)
            {
                cliente.NovoFormatoCpf = FormatarCpf(cliente.Cpf);
                cliente.Migrado = true;
            }

            await dbContext.SaveChangesAsync(stoppingToken);

            ultimoId = lote[^1].Id; // Último ID del lote para la próxima página
            totalProcessados += lote.Count;

            logger.LogInformation(
                "Lote procesado: {Count} | Total: {Total} | Último ID: {Id}",
                lote.Count, totalProcessados, ultimoId);
        }
    }

    private static string FormatarCpf(string cpf) =>
        cpf.Length == 11
            ? $"{cpf[..3]}.{cpf[3..6]}.{cpf[6..9]}-{cpf[9..]}"
            : cpf;
}

Worker con Async/Await y CancellationToken

El CancellationToken es el contrato de graceful shutdown del Worker. Cuando el host recibe una señal de parada (SIGTERM en Linux, Ctrl+C, docker stop), dispara el token — y el Worker tiene un tiempo limitado para terminar lo que está haciendo. Este mecanismo se conecta directamente con los conceptos de Programación Asíncrona con async/await:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
public class WorkerGraceful(
    ILogger<WorkerGraceful> logger,
    IServiceScopeFactory scopeFactory) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        logger.LogInformation("Worker iniciando...");

        // Registrar callback para el shutdown
        stoppingToken.Register(() =>
            logger.LogWarning("Shutdown solicitado — finalizando la operación actual"));

        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                using var scope = scopeFactory.CreateScope();
                var processador = scope.ServiceProvider
                    .GetRequiredService<IProcessadorRelatorio>();

                // Propagar el CancellationToken a TODAS las operaciones async
                await processador.GerarRelatorioAsync(stoppingToken);
            }
            catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
            {
                // Shutdown graceful — no es un error
                logger.LogInformation("Worker finalizado de forma ordenada");
                break;
            }
            catch (Exception ex)
            {
                logger.LogError(ex, "Error en el procesamiento — reintentando en 30s");
                await Task.Delay(TimeSpan.FromSeconds(30), stoppingToken);
            }
        }
    }
}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
// Program.cs — configurar timeout de shutdown
var builder = Host.CreateApplicationBuilder(args);

builder.Services.Configure<HostOptions>(options =>
{
    // Tiempo que el host espera a que ExecuteAsync termine después de
    // que el CancellationToken se dispare. Predeterminado: 30s.
    // En procesos pesados, auméntelo para evitar un kill forzado.
    options.ShutdownTimeout = TimeSpan.FromMinutes(2);

    // .NET 8: comportamiento cuando ExecuteAsync lanza una excepción
    options.BackgroundServiceExceptionBehavior =
        BackgroundServiceExceptionBehavior.StopHost; // predeterminado en .NET 8
});

ℹ️ Información: En contenedores Docker/Podman, docker stop envía SIGTERM y espera 10 segundos de forma predeterminada antes de enviar SIGKILL. Si tu Worker necesita más tiempo para un graceful shutdown, configura ShutdownTimeout en el código y --stop-timeout en el contenedor.


Múltiples Workers en el Mismo Host

Una aplicación puede registrar varios Workers en el mismo host — cada uno se ejecuta en su propia Task:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
var builder = Host.CreateApplicationBuilder(args);

// Cada Worker se ejecuta en paralelo en el mismo proceso
builder.Services.AddHostedService<ImportacaoWorker>();
builder.Services.AddHostedService<NotificacaoWorker>();
builder.Services.AddHostedService<LimpezaWorker>();
builder.Services.AddHostedService<SincronizacaoWorker>();

// Todos comparten: IConfiguration, ILogger, IServiceProvider
var host = builder.Build();
host.Run();

⚠️ Atención: Los Workers se inician en el orden en que fueron registrados, pero se ejecutan en paralelo. El StartAsync de cada uno se llama secuencialmente (en el orden de registro), pero el ExecuteAsync del BackgroundService se ejecuta en segundo plano inmediatamente. Si un Worker depende de que otro ya esté en ejecución, usa IHostApplicationLifetime para coordinarlos.

Cuándo Separar en Procesos Distintos vs el Mismo Host

EscenarioMismo HostProcesos Separados
Workers ligeros (timers, health checks)✅ RecomendadoOverhead innecesario
Workers con requisitos de escalado diferentes❌✅ Escalar de forma independiente
Workers con dependencias conflictivas❌✅ Aislamiento de dependencias
Workers consumiendo colas diferentesDepende del volumen✅ Escalar por cola
Deploy en Kubernetes❌✅ Un Deployment por Worker
Deploy en VPS/VM✅ (servicios systemd)Gestión compleja

Ejecutando Workers como Servicio del Sistema Operativo

En producción, los Workers se ejecutan como servicios gestionados por el sistema operativo:

Linux — systemd

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
# Publicar el Worker
dotnet publish src/MeuWorker -c Release -o /opt/meu-worker

# Crear el archivo de servicio systemd
sudo tee /etc/systemd/system/meu-worker.service > /dev/null << 'EOF'
[Unit]
Description=MeuWorker Background Service
After=network.target

[Service]
Type=notify
ExecStart=/opt/meu-worker/MeuWorker
WorkingDirectory=/opt/meu-worker
Environment=DOTNET_ENVIRONMENT=Production
Environment=ConnectionStrings__Default=Host=db;Database=prod;Password=S3cret!
Restart=always
RestartSec=10
User=workeruser
Group=workergroup

# Shutdown graceful
TimeoutStopSec=120

[Install]
WantedBy=multi-user.target
EOF

# Habilitar e iniciar
sudo systemctl daemon-reload
sudo systemctl enable meu-worker
sudo systemctl start meu-worker

# Verificar logs
journalctl -u meu-worker -f

Docker / Podman

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# Dockerfile — multi-stage build
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["src/MeuWorker/MeuWorker.csproj", "MeuWorker/"]
RUN dotnet restore "MeuWorker/MeuWorker.csproj"
COPY src/MeuWorker/ MeuWorker/
RUN dotnet publish "MeuWorker/MeuWorker.csproj" -c Release -o /app/publish

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime
WORKDIR /app
COPY --from=build /app/publish .

# Ejecutar como non-root (seguridad)
USER app
ENTRYPOINT ["dotnet", "MeuWorker.dll"]
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# docker-compose.yml / podman-compose.yml
services:
  meu-worker:
    build: .
    restart: always
    environment:
      - DOTNET_ENVIRONMENT=Production
      - ConnectionStrings__Default=Host=db;Database=prod;Password=${DB_PASSWORD}
    secrets:
      - db_password
    depends_on:
      db:
        condition: service_healthy

secrets:
  db_password:
    file: ./secrets/db_password.txt

Consejos y Buenas Prácticas

  1. Usa siempre IServiceScopeFactory para servicios Scoped — nunca inyectes DbContext, repositorios o servicios Scoped directamente en el constructor del Worker. Crea scopes manualmente dentro del bucle.

  2. Propaga el CancellationToken a todas las operaciones async — desde ExecuteAsync hasta la llamada a la base de datos, a la cola de mensajería y al HttpClient. Un Worker que ignora el token tarda en detenerse y puede perder datos en el shutdown.

  3. Trata las excepciones dentro del bucle — en .NET 8, las excepciones no tratadas en ExecuteAsync detienen el host. Usa try/catch con retry y logging para evitar que un error transitorio mate al Worker.

  4. Configura HostOptions.ShutdownTimeout adecuadamente — el valor predeterminado de 30 segundos puede ser insuficiente para Workers que procesan lotes grandes. Alinéalo con el --stop-timeout de Docker/Podman.

  5. Usa IHttpClientFactory en lugar de new HttpClient() — en servicios Singleton como los Workers, instanciar HttpClient directamente causa fuga de sockets y DNS stale. IHttpClientFactory gestiona el pool de handlers.

  6. Prefiere la paginación Keyset para procesamiento por lotes — evita Skip/Take con OFFSET para grandes datasets. Keyset (WHERE Id > ultimoId) mantiene el rendimiento constante independientemente del volumen.

  7. Separa los Workers por responsabilidad — un Worker debe hacer una sola cosa bien. Los Workers “navaja suiza” con múltiples responsabilidades son difíciles de escalar, monitorear y depurar.

  8. Añade health checks al Worker — usa IHealthCheck y expón un endpoint HTTP mínimo (con MapHealthChecks) para que los orquestadores (Kubernetes, Docker) puedan verificar si el Worker está sano.


Conclusión

Los .NET Workers y Background Services son la solución nativa de .NET para el procesamiento en segundo plano — sin chapuzas con Task.Run() dentro de controllers, sin bibliotecas de terceros para escenarios que el framework ya resuelve. El Generic Host proporciona la misma infraestructura de configuración, DI y logging de las Web APIs, permitiendo que los equipos compartan patrones y conocimiento entre proyectos HTTP y Workers.

El punto más crítico — y el que genera más bugs en producción — es entender que los Workers son Singleton. Esto cambia fundamentalmente cómo tratas DbContext, repositorios y cualquier servicio Scoped. El patrón IServiceScopeFactory.CreateScope() no es opcional: es la base de todo Worker que accede a una base de datos o a servicios con estado.

Para aplicaciones corporativas de alto volumen, la combinación de Workers con mensajería para desacoplamiento, paginación Keyset para procesamiento por lotes, paralelismo controlado con SemaphoreSlim y async/await con CancellationToken forma un arsenal completo para construir sistemas que procesan millones de registros de forma confiable, sin bloquear la API y sin perder datos en el shutdown.


Lee También


Referencias