Introducción

Si desarrollas aplicaciones con C# y .NET, ya te has encontrado con async, await, Task y CancellationToken repartidos por todo el código — especialmente en APIs ASP.NET Core. Pero ¿realmente entiendes qué ocurre cuando marcas un método como async? Y, más importante: ¿la programación asíncrona es lo mismo que el paralelismo? La respuesta corta es no, y confundir estos dos conceptos es uno de los errores más comunes entre desarrolladores.

En este artículo, desmitifico la programación asíncrona en C# de forma práctica y didáctica. Vas a entender la diferencia fundamental entre código asíncrono y paralelo, cómo funcionan los threads (incluido lo que significa ser thread-safe), los beneficios reales de usar async/await correctamente y por qué el CancellationToken es esencial para construir aplicaciones responsivas y resilientes — también en los controllers de ASP.NET Core. Al final, tendrás ejemplos completos que puedes copiar, pegar y ejecutar para sentir en la práctica la diferencia entre síncrono y asíncrono.

Este contenido está dirigido a desarrolladores back-end y full-stack que trabajan con .NET y quieren escribir código asíncrono correcto, eficiente y seguro. Si ya dominas conceptos de seguridad en APIs, como Autenticación y Autorización: JWT, OAuth2 y OpenID Connect, o usas automatizaciones en el día a día como describo en Makefile: Automatizando tareas para Python, Hugo y Docker, entender la programación asíncrona elevará aún más la calidad de tu código.

📦 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.


Asíncrono No Es Paralelismo

Este es el punto más importante de este artículo, y debe quedar claro desde el principio: la programación asíncrona y el paralelismo son conceptos diferentes. Muchos desarrolladores usan los términos como sinónimos, pero resuelven problemas distintos.

¿Qué Es la Programación Asíncrona?

La programación asíncrona consiste en no bloquear el thread actual mientras se espera que termine una operación lenta. Cuando haces una llamada HTTP, lees un archivo del disco o consultas una base de datos, esas operaciones implican I/O (entrada/salida) — y el procesador queda ocioso esperando la respuesta. Con código asíncrono, el thread queda liberado para hacer otras cosas mientras ocurre la operación de I/O.

¿Qué Es el Paralelismo?

El paralelismo consiste en ejecutar múltiples tareas simultáneamente, usando múltiples núcleos del procesador. Es útil para operaciones CPU-bound — tareas que realmente necesitan procesamiento pesado, como cálculos matemáticos, compresión de imágenes o procesamiento de datos.

La Analogía del Restaurante

Imagina un restaurante con un camarero (el thread):

  • Síncrono: El camarero toma el pedido de una mesa, va a la cocina, se queda parado esperando a que el plato esté listo, vuelve y lo entrega. Solo entonces atiende la siguiente mesa. Si el plato tarda 20 minutos, el camarero se queda 20 minutos parado.
  • Asíncrono: El camarero toma el pedido, lo entrega en la cocina y va a atender otras mesas mientras se prepara el plato. Cuando el plato está listo, lo recoge y lo entrega. Un único camarero atiende varias mesas.
  • Paralelo: El restaurante contrata varios camareros (varios threads) para atender mesas al mismo tiempo. Cada camarero trabaja de forma independiente.

Ilustración que compara un único camarero atendiendo varias mesas (asíncrono) con varios camareros trabajando a la vez (paralelo)

ℹ️ Información: Lo asíncrono trata de eficiencia — hacer más con menos recursos. El paralelismo trata de velocidad — hacer más cosas al mismo tiempo usando más recursos. En APIs web, lo asíncrono es casi siempre lo que quieres; el paralelismo es para escenarios específicos de procesamiento pesado.

Comparación Directa

AspectoAsíncronoParalelo
Problema que resuelveOperaciones de I/O (red, disco, base de datos)Procesamiento pesado (CPU)
ThreadsLibera el thread durante la esperaUsa múltiples threads simultáneamente
Recurso principalasync/await, TaskParallel.ForEach, Task.Run, PLINQ
EjemploLlamada HTTP, lectura de archivoCálculo de hash, compresión de imagen
Cuándo usarAPIs web, I/O-boundProcesamiento batch, CPU-bound

Cómo Funcionan los Threads en C#

Para entender la programación asíncrona, es fundamental entender qué son los threads y cómo los gestiona .NET.

¿Qué Es un Thread?

Un thread es la unidad mínima de ejecución de un programa. Cuando tu aplicación .NET arranca, recibe al menos un thread — el main thread. Cada thread tiene su propia pila de ejecución (stack), pero todos comparten el mismo espacio de memoria (heap) del proceso.

.NET utiliza el ThreadPool — un pool gestionado de threads reutilizables. En lugar de crear y destruir threads constantemente (lo cual es caro), el runtime mantiene un conjunto de threads listos para usar. Cuando una operación asíncrona termina, se asigna un thread del pool para continuar la ejecución.

Thread-Safe vs Thread-Unsafe

Cuando múltiples threads acceden al mismo recurso compartido (una variable, lista, diccionario), pueden ocurrir race conditions — situaciones en las que el resultado depende del orden de ejecución de los threads, que es impredecible.

Ejemplo Thread-Unsafe (Race Condition)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
// ❌ PROBLEMA: Este código NO es thread-safe
// Múltiples continuaciones asíncronas acceden a la misma variable sin protección

var contador = 0;

// Método asíncrono que modifica estado compartido
async Task IncrementarSemProtecaoAsync()
{
    await Task.Yield(); // Fuerza la continuación en otro thread del pool
    contador++;         // ❌ Race condition: no es una operación atómica
}

// Dispara 1000 llamadas asíncronas concurrentes
var tasks = Enumerable.Range(0, 1000)
    .Select(_ => IncrementarSemProtecaoAsync());

await Task.WhenAll(tasks);

Console.WriteLine($"Esperado: 1000, Obtenido: {contador}");
// Output puede ser: Esperado: 1000, Obtenido: 987 (u otro valor < 1000)

El contador++ parece una operación simple, pero internamente son tres pasos: leer el valor, sumar 1, escribir el nuevo valor. Si dos threads leen el valor 500 al mismo tiempo, ambos escriben 501 y se pierde un incremento. Esto ocurre porque contador++ no es una operación atómica.

Ejemplo Thread-Safe (con lock)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
// ✅ CORRECTO: Acceso protegido con lock
var contador = 0;
var lockObj = new object();

async Task IncrementarComLockAsync()
{
    await Task.Yield();
    lock (lockObj)
    {
        contador++; // Solo un thread a la vez ejecuta este bloque
    }
}

var tasks = Enumerable.Range(0, 1000)
    .Select(_ => IncrementarComLockAsync());

await Task.WhenAll(tasks);

Console.WriteLine($"Esperado: 1000, Obtenido: {contador}");
// Output: Esperado: 1000, Obtenido: 1000 ✅

¿Qué Son las Operaciones Atómicas?

Una operación atómica es una operación que se completa por entero o no ocurre — no hay término medio. Desde el punto de vista de otros threads, la operación es instantánea: ningún thread puede observar el estado intermedio.

El problema con contador++ es que no es atómico. Son tres operaciones separadas:

  1. Leer el valor actual de contador de la memoria.
  2. Sumar 1 al valor leído.
  3. Escribir el nuevo valor de vuelta en la memoria.

Entre el paso 1 y el paso 3, otro thread puede leer el mismo valor antiguo — generando la race condition mostrada arriba. Una operación atómica garantiza que esos tres pasos ocurran como si fueran uno solo, sin que otro thread pueda interferir a mitad de camino.

.NET ofrece operaciones atómicas listas para usar en la clase Interlocked, que utiliza instrucciones especiales del procesador (como lock cmpxchg en x86) para garantizar la atomicidad sin necesidad de lock — lo que hace el código más rápido en escenarios de alta concurrencia.

OperaciónMétodo InterlockedEquivalente no atómico
IncrementarInterlocked.Increment(ref x)x++
DecrementarInterlocked.Decrement(ref x)x--
Sumar valorInterlocked.Add(ref x, valor)x += valor
Intercambiar valorInterlocked.Exchange(ref x, novo)x = novo
Intercambiar si es igualInterlocked.CompareExchange(ref x, novo, esperado)if (x == esperado) x = novo

Ejemplo Thread-Safe (con Interlocked)

Para operaciones simples como el incremento, Interlocked es más eficiente que lock porque no bloquea otros threads — la operación es atómica a nivel de hardware:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
// ✅ CORRECTO y más eficiente: Interlocked para operaciones atómicas
var contador = 0;

async Task IncrementarAtomicoAsync()
{
    await Task.Yield();
    Interlocked.Increment(ref contador); // ✅ Operación atómica — sin lock
}

var tasks = Enumerable.Range(0, 1000)
    .Select(_ => IncrementarAtomicoAsync());

await Task.WhenAll(tasks);

Console.WriteLine($"Esperado: 1000, Obtenido: {contador}");
// Output: Esperado: 1000, Obtenido: 1000 ✅

ℹ️ Información: Usa lock cuando necesites proteger un bloque de código con múltiples operaciones (leer + modificar + escribir una estructura compleja). Usa Interlocked cuando necesites proteger una única variable con operaciones simples (incremento, intercambio). Interlocked es entre 10× y 50× más rápido que lock para esas operaciones individuales.

Colecciones Thread-Safe de .NET

.NET ofrece colecciones en el namespace System.Collections.Concurrent diseñadas para el acceso seguro desde múltiples threads:

Colección Thread-UnsafeEquivalente Thread-SafeCuándo usar
List<T>ConcurrentBag<T>Colección no ordenada
Dictionary<K,V>ConcurrentDictionary<K,V>Diccionario con acceso concurrente
Queue<T>ConcurrentQueue<T>Cola productor/consumidor
Stack<T>ConcurrentStack<T>Pila con acceso concurrente

💡 Consejo: Si usas async/await puro (sin Task.Run ni Parallel), en muchos escenarios no necesitas colecciones thread-safe, porque el código asíncrono normalmente se ejecuta de forma secuencial en un único thread de contexto. La preocupación por el thread safety surge cuando introduces paralelismo real.


async/await en la Práctica: Síncrono vs Asíncrono

Ahora, a lo que importa: código que puedes ejecutar y sentir la diferencia. Crea un proyecto de consola para probar:

1
2
dotnet new console -n AsyncDemo
cd AsyncDemo

Ejemplo 1: Código Síncrono (Bloqueante)

 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
// Program.cs — Versión SÍNCRONA
using System.Diagnostics;

var sw = Stopwatch.StartNew();

Console.WriteLine("Iniciando operaciones SÍNCRONAS...\n");

// Simula 3 llamadas HTTP que tardan 2 segundos cada una
var resultado1 = BuscarDadosSincrono("Servicio A", 2000);
var resultado2 = BuscarDadosSincrono("Servicio B", 2000);
var resultado3 = BuscarDadosSincrono("Servicio C", 2000);

Console.WriteLine($"\n{resultado1}");
Console.WriteLine(resultado2);
Console.WriteLine(resultado3);

sw.Stop();
Console.WriteLine($"\n⏱️ Tiempo total: {sw.ElapsedMilliseconds}ms");
// Output esperado: ~6000ms (2s + 2s + 2s — secuencial)

static string BuscarDadosSincrono(string servico, int delayMs)
{
    Console.WriteLine($"  [{DateTime.Now:HH:mm:ss.fff}] Buscando {servico}...");
    Thread.Sleep(delayMs); // ❌ Bloquea el thread
    Console.WriteLine($"  [{DateTime.Now:HH:mm:ss.fff}] {servico} completado.");
    return $"Datos de {servico}";
}

Salida esperada:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
Iniciando operaciones SÍNCRONAS...

  [19:00:00.001] Buscando Servicio A...
  [19:00:02.003] Servicio A completado.
  [19:00:02.004] Buscando Servicio B...
  [19:00:04.006] Servicio B completado.
  [19:00:04.006] Buscando Servicio C...
  [19:00:06.008] Servicio C completado.

Datos de Servicio A
Datos de Servicio B
Datos de Servicio C

⏱️ Tiempo total: 6015ms

Ejemplo 2: Código Asíncrono (No Bloqueante)

 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
// Program.cs — Versión ASÍNCRONA
using System.Diagnostics;

var sw = Stopwatch.StartNew();

Console.WriteLine("Iniciando operaciones ASÍNCRONAS...\n");

// Inicia las 3 llamadas al mismo tiempo
var task1 = BuscarDadosAsync("Servicio A", 2000);
var task2 = BuscarDadosAsync("Servicio B", 2000);
var task3 = BuscarDadosAsync("Servicio C", 2000);

// Espera a que TODAS terminen (sin bloquear el thread)
var resultados = await Task.WhenAll(task1, task2, task3);

Console.WriteLine($"\n{resultados[0]}");
Console.WriteLine(resultados[1]);
Console.WriteLine(resultados[2]);

sw.Stop();
Console.WriteLine($"\n⏱️ Tiempo total: {sw.ElapsedMilliseconds}ms");
// Output esperado: ~2000ms (todas se ejecutan "al mismo tiempo")

static async Task<string> BuscarDadosAsync(string servico, int delayMs)
{
    Console.WriteLine($"  [{DateTime.Now:HH:mm:ss.fff}] Buscando {servico}...");
    await Task.Delay(delayMs); // ✅ Libera el thread durante la espera
    Console.WriteLine($"  [{DateTime.Now:HH:mm:ss.fff}] {servico} completado.");
    return $"Datos de {servico}";
}

Salida esperada:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
Iniciando operaciones ASÍNCRONAS...

  [19:00:00.001] Buscando Servicio A...
  [19:00:00.002] Buscando Servicio B...
  [19:00:00.002] Buscando Servicio C...
  [19:00:02.005] Servicio A completado.
  [19:00:02.005] Servicio B completado.
  [19:00:02.006] Servicio C completado.

Datos de Servicio A
Datos de Servicio B
Datos de Servicio C

⏱️ Tiempo total: 2008ms

⚠️ Atención: Observa la diferencia: 6 segundos vs 2 segundos. En el código asíncrono, las tres operaciones de I/O empezaron casi al mismo tiempo. Mientras cada una esperaba, el thread estaba libre. Esto no es paralelismo — es un único thread gestionando múltiples operaciones de I/O de forma concurrente. Task.Delay libera el thread; Thread.Sleep lo bloquea.

¿Qué Ocurre por Debajo?

Cuando escribes await Task.Delay(2000), el compilador de C# transforma tu método async en una máquina de estados (state machine). Simplificando:

  1. El código antes del await se ejecuta normalmente.
  2. En el punto del await, si la Task todavía no ha terminado, el thread se devuelve al ThreadPool.
  3. Cuando la operación de I/O termina, se asigna un thread del pool para continuar la ejecución desde donde se detuvo.
  4. Esto se repite para cada await del método.

Por eso async/await es tan poderoso en APIs web: mientras una solicitud espera la respuesta de la base de datos, el thread puede atender otras solicitudes.


CancellationToken: Por Qué y Cómo Usarlo

El CancellationToken es un mecanismo de .NET para señalizar la cancelación cooperativa de operaciones asíncronas. Sin él, si un usuario cierra el navegador, se desconecta o la solicitud alcanza el timeout, tu API sigue procesando innecesariamente — consumiendo recursos del servidor sin nadie que reciba la respuesta.

¿Por Qué Es Importante?

Considera estos escenarios:

  1. El usuario hace una solicitud que tarda 30 segundos y cierra la pestaña del navegador tras 5 segundos.
  2. Se alcanza un timeout en el gateway o el load balancer.
  3. Tu API consulta un servicio externo que está lento y quieres imponer un límite de tiempo.

Sin CancellationToken, tu código sigue ejecutando la operación completa, desperdiciando CPU, memoria y conexiones de base de datos — recursos que podrían atender a otros usuarios.

Ejemplo Básico de CancellationToken

 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
// Demostración básica de CancellationToken
using var cts = new CancellationTokenSource();

// Cancela automáticamente tras 3 segundos
cts.CancelAfter(TimeSpan.FromSeconds(3));

try
{
    Console.WriteLine("Iniciando operación larga...");
    await OperacaoDemoradaAsync(cts.Token);
    Console.WriteLine("¡Operación completada con éxito!");
}
catch (OperationCanceledException)
{
    Console.WriteLine("⛔ ¡Operación cancelada! Recursos liberados.");
}

static async Task OperacaoDemoradaAsync(CancellationToken cancellationToken)
{
    for (int i = 1; i <= 10; i++)
    {
        // Verifica si se solicitó la cancelación
        cancellationToken.ThrowIfCancellationRequested();

        Console.WriteLine($"  Procesando etapa {i}/10...");
        await Task.Delay(1000, cancellationToken);
    }
}

Salida esperada:

1
2
3
4
5
Iniciando operación larga...
  Procesando etapa 1/10...
  Procesando etapa 2/10...
  Procesando etapa 3/10...
⛔ ¡Operación cancelada! Recursos liberados.

CancellationToken en Métodos de Servicio

Propaga siempre el CancellationToken por toda la cadena de llamadas:

 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
// Interfaz del servicio
public interface IProdutoService
{
    Task<List<Produto>> ObterTodosAsync(CancellationToken cancellationToken = default);
    Task<Produto?> ObterPorIdAsync(int id, CancellationToken cancellationToken = default);
}

// Implementación del servicio
public class ProdutoService : IProdutoService
{
    private readonly HttpClient _httpClient;
    private readonly AppDbContext _dbContext;

    public ProdutoService(HttpClient httpClient, AppDbContext dbContext)
    {
        _httpClient = httpClient;
        _dbContext = dbContext;
    }

    public async Task<List<Produto>> ObterTodosAsync(
        CancellationToken cancellationToken = default)
    {
        // Entity Framework acepta CancellationToken de forma nativa
        return await _dbContext.Produtos
            .AsNoTracking()
            .ToListAsync(cancellationToken);
    }

    public async Task<Produto?> ObterPorIdAsync(
        int id,
        CancellationToken cancellationToken = default)
    {
        // HttpClient también acepta CancellationToken
        var response = await _httpClient.GetAsync(
            $"/api/produtos/{id}",
            cancellationToken);

        response.EnsureSuccessStatusCode();

        return await response.Content
            .ReadFromJsonAsync<Produto>(cancellationToken: cancellationToken);
    }
}

💡 Consejo: Usa CancellationToken cancellationToken = default como último parámetro. El default de CancellationToken es CancellationToken.None, que significa “sin cancelación” — manteniendo la compatibilidad con el código que no necesita cancelación.


CancellationToken en el Controller de ASP.NET Core

Usar CancellationToken en el controller es una de las mejores prácticas para APIs ASP.NET Core, y tiene todo el sentido: el framework ya proporciona un token de cancelación automáticamente cuando el cliente aborta la solicitud.

¿Cómo Funciona?

Cuando añades CancellationToken como parámetro de una action, ASP.NET Core inyecta automáticamente un token vinculado a la conexión HTTP. Si el cliente se desconecta (cierra la pestaña, timeout, cancela el fetch), el token se marca como cancelado.

 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
55
56
57
58
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
public class ProdutosController : ControllerBase
{
    private readonly IProdutoService _produtoService;

    public ProdutosController(IProdutoService produtoService)
    {
        _produtoService = produtoService;
    }

    // ✅ CancellationToken inyectado automáticamente por ASP.NET Core
    [HttpGet]
    public async Task<ActionResult<List<Produto>>> ObterTodos(
        CancellationToken cancellationToken)
    {
        var produtos = await _produtoService
            .ObterTodosAsync(cancellationToken);

        return Ok(produtos);
    }

    [HttpGet("{id:int}")]
    public async Task<ActionResult<Produto>> ObterPorId(
        int id,
        CancellationToken cancellationToken)
    {
        var produto = await _produtoService
            .ObterPorIdAsync(id, cancellationToken);

        if (produto is null)
            return NotFound();

        return Ok(produto);
    }

    // Endpoint con operación larga — perfecto para CancellationToken
    [HttpPost("relatorio")]
    public async Task<ActionResult<Relatorio>> GerarRelatorio(
        [FromBody] RelatorioRequest request,
        CancellationToken cancellationToken)
    {
        try
        {
            var relatorio = await _produtoService
                .GerarRelatorioAsync(request, cancellationToken);

            return Ok(relatorio);
        }
        catch (OperationCanceledException)
        {
            // Log opcional — ASP.NET Core ya lo trata de forma limpia
            return StatusCode(499, "Solicitud cancelada por el cliente");
        }
    }
}

Cadena Completa: Controller → Service → Repository

El verdadero poder del CancellationToken aparece cuando recorre toda la cadena de llamadas:

1
2
Cliente HTTP → Controller → Service → Repository → Base de Datos
                  ↓ cancellationToken pasado por toda la cadena ↓
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// Repository
public class ProdutoRepository
{
    private readonly AppDbContext _dbContext;

    public ProdutoRepository(AppDbContext dbContext)
    {
        _dbContext = dbContext;
    }

    public async Task<List<Produto>> ObterComFiltroAsync(
        string? categoria,
        CancellationToken cancellationToken = default)
    {
        var query = _dbContext.Produtos.AsNoTracking();

        if (!string.IsNullOrEmpty(categoria))
            query = query.Where(p => p.Categoria == categoria);

        // Si el cliente se desconecta, la query en la base de datos se cancela
        return await query.ToListAsync(cancellationToken);
    }
}

⚠️ Atención: Cuando una query a la base de datos se cancela vía CancellationToken, Entity Framework envía un comando de cancelación a la base de datos. Esto libera la conexión y los recursos en el servidor de base de datos, no solo en la aplicación. Es una doble ganancia: libera recursos tanto en la API como en la base de datos.


Ejemplo Completo: Probando Síncrono vs Asíncrono

Para que puedas ejecutarlo y ver la diferencia en la práctica, aquí tienes un ejemplo completo con una API mínima que demuestra ambos escenarios:

 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
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
// Program.cs — API Minimal que demuestra Síncrono vs Asíncrono
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// Endpoint SÍNCRONO — bloquea el thread durante la "consulta"
app.MapGet("/api/sincrono", () =>
{
    var sw = System.Diagnostics.Stopwatch.StartNew();

    // Simula 3 consultas secuenciales de 1 segundo cada una
    Thread.Sleep(1000); // consulta 1
    Thread.Sleep(1000); // consulta 2
    Thread.Sleep(1000); // consulta 3

    sw.Stop();
    return Results.Ok(new
    {
        modo = "síncrono",
        tempoMs = sw.ElapsedMilliseconds,
        mensagem = "El thread estuvo bloqueado durante toda la ejecución"
    });
});

// Endpoint ASÍNCRONO — libera el thread durante la "consulta"
app.MapGet("/api/assincrono", async (CancellationToken cancellationToken) =>
{
    var sw = System.Diagnostics.Stopwatch.StartNew();

    // Inicia 3 consultas asíncronas al mismo tiempo
    var t1 = Task.Delay(1000, cancellationToken);
    var t2 = Task.Delay(1000, cancellationToken);
    var t3 = Task.Delay(1000, cancellationToken);

    await Task.WhenAll(t1, t2, t3);

    sw.Stop();
    return Results.Ok(new
    {
        modo = "asíncrono",
        tempoMs = sw.ElapsedMilliseconds,
        mensagem = "El thread fue liberado durante las esperas"
    });
});

// Endpoint que demuestra CancellationToken
app.MapGet("/api/demorado", async (CancellationToken cancellationToken) =>
{
    var etapas = new List<string>();

    try
    {
        for (int i = 1; i <= 10; i++)
        {
            cancellationToken.ThrowIfCancellationRequested();
            etapas.Add($"Etapa {i} completada");
            await Task.Delay(1000, cancellationToken);
        }

        return Results.Ok(new
        {
            status = "completado",
            etapas
        });
    }
    catch (OperationCanceledException)
    {
        return Results.Json(new
        {
            status = "cancelado",
            etapasCompletadas = etapas,
            mensagem = "El cliente se desconectó. Recursos liberados."
        }, statusCode: 499);
    }
});

app.Run();

Para probar:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# Terminal 1: Iniciar la API
dotnet run

# Terminal 2: Probar el endpoint síncrono
curl http://localhost:5000/api/sincrono
# Respuesta: { "modo": "síncrono", "tempoMs": 3005, ... }

# Terminal 2: Probar el endpoint asíncrono
curl http://localhost:5000/api/assincrono
# Respuesta: { "modo": "asíncrono", "tempoMs": 1003, ... }

# Terminal 2: Probar CancellationToken (cancela con Ctrl+C tras 3s)
curl http://localhost:5000/api/demorado
# Si cancelas tras 3s: { "status": "cancelado", "etapasCompletadas": [...] }

📝 Ejemplo: Compara los tiempos: el endpoint síncrono tarda ~3 segundos (3 × 1s secuencial), mientras que el asíncrono tarda ~1 segundo (3 × 1s concurrente). La misma lógica se aplica a consultas reales de base de datos, llamadas HTTP y lectura de archivos.


Consejos y Buenas Prácticas

Estas son las prácticas esenciales para escribir código asíncrono correcto y eficiente en C#:

  • Usa siempre async/await para operaciones de I/O. Llamadas HTTP, consultas a base de datos, lectura/escritura de archivos — todas estas operaciones deben ser asíncronas. Nunca uses .Result o .Wait() en código asíncrono, porque puede causar deadlocks.

  • Prefiere await Task.WhenAll() para operaciones independientes. Si necesitas consultar tres servicios diferentes que no dependen entre sí, inicia todas las tasks y usa Task.WhenAll para esperar. Esto puede reducir drásticamente el tiempo total de respuesta.

  • Propaga siempre el CancellationToken. ¿Recibiste un CancellationToken? Pásalo a todos los métodos asíncronos de la cadena. Entity Framework, HttpClient, Task.Delay — todos aceptan CancellationToken.

  • Usa ConfigureAwait(false) en bibliotecas. Si estás escribiendo una library (no una aplicación), usa await task.ConfigureAwait(false) para evitar capturar el SynchronizationContext innecesariamente. En APIs ASP.NET Core no es necesario porque no hay SynchronizationContext.

  • Nunca uses async void. La única excepción son los event handlers. Los métodos async void no se pueden esperar y las excepciones no tratadas pueden tumbar la aplicación. Devuelve siempre Task o Task<T>.

  • No uses Task.Run para envolver código síncrono en APIs web. Esto no hace tu código verdaderamente asíncrono — solo traslada el bloqueo a otro thread del pool. En APIs web, esto puede empeorar el rendimiento porque consume un thread extra.

  • Nombra los métodos asíncronos con el sufijo Async. Es una convención de .NET: ObterTodosAsync, SalvarAsync, EnviarEmailAsync. Deja claro que el método devuelve una Task y debe esperarse.


Errores Comunes (y Cómo Evitarlos)

❌ Usar .Result o .Wait() (puede causar deadlock)

1
2
3
4
5
// ❌ INCORRECTO — puede causar deadlock en contextos con SynchronizationContext
var dados = ObterDadosAsync().Result;

// ✅ CORRECTO — usa await
var dados = await ObterDadosAsync();

❌ No propagar el CancellationToken

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
// ❌ INCORRECTO — ignora la cancelación del cliente
public async Task<List<Produto>> ObterTodosAsync(CancellationToken ct)
{
    return await _dbContext.Produtos.ToListAsync(); // ¡Token no propagado!
}

// ✅ CORRECTO — propaga el token
public async Task<List<Produto>> ObterTodosAsync(CancellationToken ct)
{
    return await _dbContext.Produtos.ToListAsync(ct);
}

❌ Usar Thread.Sleep en código asíncrono

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
// ❌ INCORRECTO — bloquea el thread del ThreadPool
public async Task ProcessarAsync()
{
    Thread.Sleep(5000); // ¡Bloquea!
    await FazerAlgoAsync();
}

// ✅ CORRECTO — libera el thread
public async Task ProcessarAsync()
{
    await Task.Delay(5000); // No bloquea
    await FazerAlgoAsync();
}

Conclusión

La programación asíncrona en C# con async/await es una de las herramientas más poderosas de .NET para construir aplicaciones escalables y responsivas. Como mostré a lo largo de este artículo, lo asíncrono no es paralelismo — son conceptos complementarios que resuelven problemas diferentes. Lo asíncrono brilla en operaciones de I/O, liberando threads para atender más solicitudes con menos recursos.

Entender cómo funcionan los threads y qué significa ser thread-safe es esencial para evitar bugs sutiles y difíciles de reproducir, como las race conditions. Y el CancellationToken es indispensable para aplicaciones profesionales: permite que tu API libere recursos inmediatamente cuando se cancela una solicitud, mejorando la escalabilidad y la experiencia del usuario.

En la práctica, recuerda: usa async/await para toda operación de I/O, propaga el CancellationToken por toda la cadena de llamadas (del controller a la base de datos), evita .Result y .Wait(), y nunca confundas Thread.Sleep con Task.Delay. Si sigues estas reglas, tu código C# será más eficiente, más resiliente y más profesional.

Si te gustó este artículo y quieres seguir mejorando tus habilidades, explora los demás contenidos del blog — desde seguridad con BFF Backend For Frontend hasta automatización de tareas con Makefile.

💡 Consejo final: Si el lenguaje o framework que usas en el día a día no ofrece soporte nativo a la programación asíncrona — o lo implementa de forma compleja, verbosa y propensa a errores — vale la pena considerar seriamente añadir a tu portafolio un lenguaje maduro que trate la asincronía como ciudadana de primera clase. C# es una excelente opción: como mostré a lo largo de este artículo, basta con usar async, await y CancellationToken para escribir código asíncrono limpio, seguro y eficiente — sin callbacks anidados, sin gestión manual de threads y sin bibliotecas externas. El ecosistema .NET ofrece soporte asíncrono nativo en prácticamente todo: Entity Framework, HttpClient, file I/O, streams, canales gRPC e incluso todo ASP.NET Core. Invertir en un lenguaje que facilita escribir código asíncrono no es solo una cuestión de productividad — es una ventaja competitiva en el mercado.


Lee También


Referencias