Flurl para C# (.NET): guía completa con ejemplos prácticos

Flurl es una biblioteca moderna y elegante para .NET que combina un constructor de URLs fluido con un cliente HTTP. Está diseñada para hacer que el trabajo con peticiones HTTP sea extremadamente simple, legible y cómodo. En lugar de código verboso con HttpClient, UriBuilder y múltiples concatenaciones de cadenas, Flurl ofrece una sintaxis concisa y expresiva, similar a las cadenas de métodos en LINQ.

¿Por qué usar Flurl? El principal problema del HttpClient estándar es su verbosidad. Para enviar una simple petición GET con parámetros y cabeceras, necesitas escribir entre 10 y 15 líneas de código. Flurl lo reduce a 2 o 3 líneas, haciendo que el código se documente por sí mismo. Además, Flurl resuelve el problema de la construcción segura de URLs: codifica automáticamente los parámetros, maneja rutas y cadenas de consulta, evitando errores por escape incorrecto de caracteres.

Esta biblioteca es ideal para cualquier escenario que requiera interactuar con APIs REST: desde aplicaciones móviles simples hasta sistemas empresariales complejos. Flurl soporta todos los métodos HTTP principales, trabajo con JSON, carga de archivos, tiempos de espera, reintentos y mucho más. Es completamente asíncrona y compatible con .NET Standard 2.0+, lo que permite usarla en .NET Framework, .NET Core y .NET 5/6/7/8.

Instalación

Flurl se puede instalar a través del Administrador de Paquetes NuGet. Para trabajar con peticiones HTTP necesitas el paquete Flurl.Http, que incluye también Flurl (el constructor de URLs).

Mediante .NET CLI:

dotnet add package Flurl.Http

Mediante la Consola del Administrador de Paquetes:

Install-Package Flurl.Http

Mediante Visual Studio: Haz clic derecho en el proyecto → Manage NuGet Packages → busca "Flurl.Http" → Install.

Si solo necesitas el constructor de URLs sin el cliente HTTP, puedes instalar:

dotnet add package Flurl

Inicio rápido

Un ejemplo mínimo funcional: obtener datos de una API pública y mostrarlos en consola:

using Flurl.Http;
using System;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        // Petición GET a una API JSON
        var response = await "https://jsonplaceholder.typicode.com/posts/1"
            .GetJsonAsync<dynamic>();

        Console.WriteLine($"Título: {response.title}");
        Console.WriteLine($"Cuerpo: {response.body}");
    }
}

Este código realiza una petición GET, deserializa automáticamente la respuesta JSON en un objeto dinámico y muestra los campos. Observa cómo Flurl permite llamar métodos directamente sobre la cadena de la URL: ese es el estilo "fluido".

Métodos y clases principales

1. Url.Combine() — combinación segura de URLs

Firma: public static string Combine(params string[] parts)

Qué hace: Combina varias partes de una URL, agregando o eliminando automáticamente las barras inclinadas sobrantes. Evita la duplicación de barras.

using Flurl;

string fullUrl = Url.Combine("https://api.ejemplo.com", "/v1/", "usuarios", "/123");
Console.WriteLine(fullUrl); // https://api.ejemplo.com/v1/usuarios/123

2. Url.SetQueryParams() — agregar parámetros de forma fluida

Firma: public static string SetQueryParams(this string url, object values)

Qué hace: Agrega parámetros de consulta a la URL a partir de un objeto anónimo o un diccionario. Codifica automáticamente los valores.

using Flurl;

string url = "https://api.ejemplo.com/buscar"
    .SetQueryParams(new { q = "hola mundo", pagina = 1, limite = 10 });

Console.WriteLine(url); 
// https://api.ejemplo.com/buscar?q=hola%20mundo&pagina=1&limite=10

3. GetJsonAsync<T>() — petición GET con deserialización JSON

Firma: public static Task<T> GetJsonAsync<T>(this string url, ...)

Qué hace: Realiza una petición GET y deserializa automáticamente la respuesta JSON en el tipo especificado.

using Flurl.Http;

var usuario = await "https://api.ejemplo.com/usuarios/1"
    .GetJsonAsync<Usuario>();

Console.WriteLine(usuario.Nombre);

4. PostJsonAsync() — petición POST con cuerpo JSON

Firma: public static Task<HttpResponseMessage> PostJsonAsync(this string url, object data, ...)

Qué hace: Envía una petición POST serializando automáticamente el objeto proporcionado a JSON en el cuerpo de la solicitud.

using Flurl.Http;

var nuevoUsuario = new { Nombre = "Ana", Email = "ana@ejemplo.com" };
var respuesta = await "https://api.ejemplo.com/usuarios"
    .PostJsonAsync(nuevoUsuario);

if (respuesta.StatusCode == 201)
    Console.WriteLine("Usuario creado exitosamente");

5. SetHeaders() — agregar cabeceras HTTP

Firma: public static IFlurlRequest SetHeaders(this IFlurlRequest request, object headers)

Qué hace: Agrega múltiples cabeceras HTTP a la petición de forma fluida, usando un objeto anónimo o un diccionario.

using Flurl.Http;

var datos = await "https://api.ejemplo.com/datos"
    .WithHeaders(new { 
        Authorization = "Bearer token123", 
        Accept = "application/json" 
    })
    .GetJsonAsync<dynamic>();

6. AllowHttpStatus() — manejar códigos de error HTTP

Firma: public static IFlurlRequest AllowHttpStatus(this IFlurlRequest request, params int[] statusCodes)

Qué hace: Permite que ciertos códigos de estado HTTP (como 404 o 500) no lancen excepciones, sino que se manejen como respuestas normales.

using Flurl.Http;

var respuesta = await "https://api.ejemplo.com/recurso-inexistente"
    .AllowHttpStatus(404)
    .GetAsync();

if (respuesta.StatusCode == 404)
    Console.WriteLine("Recurso no encontrado");

Conclusión

Flurl es una herramienta indispensable para cualquier desarrollador .NET que trabaje con APIs REST. Su sintaxis fluida, su capacidad para reducir drásticamente la cantidad de código necesario y su manejo inteligente de URLs la convierten en una opción superior frente al HttpClient tradicional. Ya sea que estés construyendo una aplicación pequeña o un sistema empresarial, Flurl hará que tu código sea más limpio, legible y fácil de mantener.

¿Te ha sido útil esta guía? ¡Compártela con otros desarrolladores y no olvides explorar la documentación oficial de Flurl para descubrir todas sus capacidades!