Mapster for C# (.NET): Complete Guide with Examples

Mapster is a high-performance object-to-object mapping library for the .NET ecosystem. It automatically converts objects from one type to another, saving developers from writing repetitive property-copying code. Unlike heavyweights like AutoMapper, Mapster focuses on speed and minimal memory usage, as confirmed by numerous benchmarks.

Why do you need object mapping? In real-world projects, you constantly deal with data transformations: DTOs to Entities, ViewModels to Models, Models to Responses, and so on. Manually copying each field is tedious, error-prone, and makes code harder to maintain. Mapster solves this by providing a simple, flexible, and fast API for automatic mapping.

Mapster generates mapping code at compile time (via Roslyn analyzers) or uses dynamic expression compilation. This makes it one of the fastest mappers in .NET, often outperforming even manual copying in certain scenarios. The library supports complex cases: nested objects, collections, conditional mapping, field ignoring, type adapters, and much more.

Installation

Install Mapster via NuGet Package Manager. Run one of the following commands in the package manager console:

dotnet add package Mapster

Or via Package Manager Console:

Install-Package Mapster

For ASP.NET Core and dependency injection (DI), install the additional package:

dotnet add package Mapster.DependencyInjection

After installation, add using Mapster; at the top of your file.

Quick Start

Let's look at a simple example: we have a User class (database model) and a UserDto class (for client transmission).

using Mapster;

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

// Target class
public class UserDto
{
    public int Id { get; set; }
    public string FullName { get; set; }
    public string Email { get; set; }
}

// Usage example
public class Program
{
    public static void Main()
    {
        var user = new User
        {
            Id = 1,
            Name = "John Smith",
            Email = "john@example.com",
            CreatedAt = DateTime.Now
        };

        // Mapping with Mapster
        var dto = user.Adapt<UserDto>();

        Console.WriteLine($"Id: {dto.Id}, Name: {dto.FullName}, Email: {dto.Email}");
        // Output: Id: 1, Name: John Smith, Email: john@example.com
    }
}

Notice: the Name property was automatically mapped to FullName, because Mapster by default tries to find matches by name (case-insensitive). If UserDto had a Name property, it would also map.

Key Methods and Classes

Let's explore Mapster's core methods. Each includes its signature, description, and an example.

1. Adapt<TDestination>(object source)

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

Description: The basic extension method for mapping one object to another. Creates a new TDestination instance and copies property values from source.

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