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

Mapster es una biblioteca de alto rendimiento para el mapeo de objetos (object-to-object mapping) en el ecosistema .NET. Permite transformar automáticamente objetos de un tipo a otro, eliminando la necesidad de escribir código repetitivo para copiar propiedades. A diferencia de herramientas como AutoMapper, Mapster se enfoca en la velocidad de ejecución y el mínimo consumo de memoria, como lo demuestran numerosos benchmarks.

¿Para qué sirve el mapeo de objetos? En proyectos reales, constantemente necesitamos transformar datos: DTO (Data Transfer Object) a Entity, ViewModel a Model, Model a Response, etc. Copiar manualmente cada campo es tedioso, propenso a errores y dificulta el mantenimiento del código. Mapster resuelve este problema ofreciendo una API simple, flexible y rápida para el mapeo automático.

Mapster genera el código de mapeo en tiempo de compilación (mediante analizadores Roslyn) o utiliza compilación dinámica de expresiones. Esto lo convierte en uno de los mapeadores más rápidos en .NET, superando incluso la copia manual en algunos escenarios. La biblioteca soporta casos complejos: objetos anidados, colecciones, mapeo condicional, ignorar campos, adaptadores para diferentes tipos y mucho más.

Instalación

La instalación de Mapster se realiza a través del Administrador de Paquetes NuGet. Ejecuta uno de los siguientes comandos en la consola del administrador de paquetes:

dotnet add package Mapster

O a través de la Consola del Administrador de Paquetes:

Install-Package Mapster

Para trabajar con ASP.NET Core e inyección de dependencias (DI), se recomienda instalar el paquete adicional:

dotnet add package Mapster.DependencyInjection

Después de la instalación, agrega using Mapster; al inicio de tu archivo.

Inicio rápido

Veamos un ejemplo sencillo: tenemos una clase User (modelo de base de datos) y una clase UserDto (para enviar al cliente).

using Mapster;

// Clase de origen
public class User
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
    public DateTime CreatedAt { get; set; }
}

// Clase de destino
public class UserDto
{
    public int Id { get; set; }
    public string FullName { get; set; }
    public string Email { get; set; }
}

// Ejemplo de uso
public class Program
{
    public static void Main()
    {
        var user = new User
        {
            Id = 1,
            Name = "Juan Pérez",
            Email = "juan@example.com",
            CreatedAt = DateTime.Now
        };

        // Mapeo con Mapster
        var dto = user.Adapt<UserDto>();

        Console.WriteLine($"Id: {dto.Id}, Nombre: {dto.FullName}, Email: {dto.Email}");
        // Salida: Id: 1, Nombre: Juan Pérez, Email: juan@example.com
    }
}

Observa que la propiedad Name se asignó automáticamente a FullName, ya que Mapster por defecto intenta encontrar coincidencias por nombre (sin distinguir mayúsculas/minúsculas). Si UserDto tuviera una propiedad Name, también se asignaría.

Métodos y clases principales

Veamos los métodos clave de Mapster. Para cada uno se incluye la firma, descripción y un ejemplo.

1. Adapt<TDestination>(object source)

Firma: public static TDestination Adapt<TDestination>(this object source)

Descripción: Método de extensión básico para mapear un objeto a otro. Crea una nueva instancia de TDestination y copia los valores de las propiedades desde source.

var user = new User { Id = 1, Name = "Ana" };
var dto = user.Adapt<UserDto>();
Console.WriteLine(dto.FullName); // Salida: Ana