Mapster para C# (.NET): guia completo com exemplos práticos

Mapster é uma biblioteca de alto desempenho para mapeamento de objetos (object-to-object mapping) no ecossistema .NET. Ela permite transformar automaticamente objetos de um tipo em outro, eliminando a necessidade de escrever código repetitivo para copiar propriedades. Diferente de ferramentas como AutoMapper, o Mapster foca em velocidade e baixo consumo de memória, conforme comprovado por diversos benchmarks.

Por que o mapeamento de objetos é importante? Em projetos reais, constantemente precisamos converter dados: DTO (Data Transfer Object) para Entity, ViewModel para Model, Model para Response, entre outros. Copiar manualmente cada campo é tedioso, propenso a erros e dificulta a manutenção do código. O Mapster resolve esse problema oferecendo uma API simples, flexível e rápida para mapeamento automático.

O Mapster gera código de mapeamento em tempo de compilação (através de analisadores Roslyn) ou usa compilação dinâmica de expressões. Isso o torna um dos mapeadores mais rápidos do .NET, muitas vezes superando até mesmo a cópia manual em alguns cenários. A biblioteca suporta casos complexos: objetos aninhados, coleções, mapeamento condicional, ignorar campos, adaptadores para diferentes tipos e muito mais.

Instalação

A instalação do Mapster é feita através do NuGet Package Manager. Execute um dos seguintes comandos no console do gerenciador de pacotes:

dotnet add package Mapster

Ou via Package Manager Console:

Install-Package Mapster

Para trabalhar com ASP.NET Core e injeção de dependências (DI), recomenda-se instalar o pacote adicional:

dotnet add package Mapster.DependencyInjection

Após a instalação, adicione using Mapster; no início do seu arquivo.

Início rápido

Vamos ver um exemplo simples: temos uma classe User (modelo do banco de dados) e uma classe UserDto (para enviar ao cliente).

using Mapster;

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

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

// Exemplo de uso
public class Program
{
    public static void Main()
    {
        var user = new User
        {
            Id = 1,
            Name = "João Silva",
            Email = "joao@exemplo.com",
            CreatedAt = DateTime.Now
        };

        // Mapeamento com Mapster
        var dto = user.Adapt<UserDto>();

        Console.WriteLine($"Id: {dto.Id}, Nome: {dto.FullName}, Email: {dto.Email}");
        // Saída: Id: 1, Nome: João Silva, Email: joao@exemplo.com
    }
}

Observe: a propriedade Name foi automaticamente mapeada para FullName, pois o Mapster, por padrão, tenta encontrar correspondências pelo nome (ignorando maiúsculas/minúsculas). Se UserDto tivesse uma propriedade Name, ela também seria mapeada.

Métodos e classes principais

Vamos explorar os principais métodos do Mapster. Para cada um, mostramos a assinatura, descrição e exemplo.

1. Adapt<TDestination>(object source)

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

Descrição: Método de extensão básico para mapear um objeto em outro. Cria uma nova instância de TDestination e copia os valores das propriedades de source.

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