Docs / Auto Mapping

Auto Mapping

What this page covers#

This page explains how MooDb automatically maps database results to .NET types.

Why this exists#

Most of the time, when you query the database, you want the returned data copied into a .NET object without writing manual SqlDataReader code for every query.

Auto mapping exists to make that common case simple.

The simple version#

If the returned columns match the target type closely enough, MooDb can usually map the result for you automatically.

</> C# 
var user = await db.SingleAsync<User>(
    "dbo.usp_User_GetById",
    new MooParams().AddInt("@UserId", 1));

What MooDb can map automatically#

Auto mapping supports:

  • classes with public writable properties
  • constructor-based models where parameter names match result columns
  • mixed models where some values are supplied by constructor parameters and remaining values are assigned to public writable properties

Column and member names are matched case-insensitively.

Example model with public writable properties#

</> C# 
public sealed class UserRow
{
    public int UserId { get; set; }
    public string Email { get; set; } = string.Empty;
    public string DisplayName { get; set; } = string.Empty;
}

Example model with constructor mapping#

</> C# 
public sealed class UserHeader
{
    public UserHeader(int userId, string email)
    {
        UserId = userId;
        Email = email;
    }

    public int UserId { get; }
    public string Email { get; }
    public string DisplayName { get; set; } = string.Empty;
}

This mixed model is supported. MooDb can satisfy the constructor parameters first and then assign remaining public writable properties from the same result shape.

Strict auto mapping#

Strict mode is for cases where you want the result shape and target shape to line up exactly enough that nothing important is silently ignored.

Enable it through MooDbContextOptions:

</> C# 
var db = new MooDbContext(connectionString, new MooDbContextOptions
{
    StrictAutoMapping = true
});

Strict mode applies consistently across both constructor mapping and property mapping.

In practical terms:

  • every result column must match either a constructor parameter or a public writable property
  • every public writable property must be satisfied by either a constructor parameter or a matching result column
  • values that cannot be converted to the destination type cause mapping to fail

That means strict mode now behaves consistently for normal classes, constructor-based models, and mixed constructor-plus-setter models.

Conversion support#

Auto mapping uses MooDb's central conversion pipeline.

That means MooDb can map more than just obvious one-to-one CLR types.

Notable supported conversions include:

  • enum values from integer columns
  • enum values from string columns when the text matches the enum name
  • nullable enums
  • Guid
  • DateOnly
  • TimeOnly

Performance note#

MooDb does not rebuild mapping work from scratch on every call.

It caches internal mapping plans for reuse and performance. In the codebase, this internal infrastructure is referred to as MooMapper, but that is not part of the public API surface.

Strict mode is part of the mapping cache identity. That means a permissive mapping plan is not reused for strict mode accidentally.

What counts as writable#

For auto mapping assignment purposes, MooDb treats publicly settable properties as writable.

This is important because auto mapping is about what can actually be assigned safely and predictably from the result shape.

When auto mapping is a good fit#

Use auto mapping when:

  • the result shape lines up naturally with your target type
  • you want the shortest and clearest call site
  • you do not need row-by-row custom materialisation logic

When to switch to custom mapping#

Use custom mapping when:

  • the shape does not line up neatly
  • you want to transform values manually while reading
  • you want explicit control over null handling or conversions
  • you want hand-written mapping code for a hot path

Important notes#

  • Auto mapping supports public writable property models.
  • Auto mapping also supports constructor-based and mixed constructor-plus-setter models.
  • Strict mode applies to both constructor matching and property assignment.
  • Strict mode is not used for explicit custom mapper functions.
  • Enum, Guid, DateOnly, and TimeOnly conversions are supported through the normal conversion pipeline.
  • MooMapper is an internal implementation detail, not public API.