dotnet-mapping-standard

Overview

Standardise mapping between DTOs, domain models, and persistence models using source-generated mappers. Mappings live at explicit boundaries (API, infrastructure) with deterministic, testable conversion paths and no runtime reflection magic.

When to Use

• •Mapping between API request/response DTOs and domain models
• •Converting domain entities to/from persistence models
• •Handling integration event contracts at service boundaries
• •Reviewing PRs that introduce new mapping logic
• •Refactoring existing reflection-based mappers to source-generated alternatives

Core Workflow

1. •Identify mapping boundaries: Locate where DTOs cross into domain or persistence layers
2. •Choose source-generated mapper: Select Mapperly or similar compile-time mapper
3. •Create explicit mappers: Implement mapper classes at boundary projects (API, Infrastructure)
4. •Handle typed IDs explicitly: Map strongly typed IDs and value objects with explicit conversions
5. •Apply DI gating rules: Use static mappers unless mapper has injected dependencies
6. •Add mapping tests: Include round-trip tests for critical boundary conversions
7. •Verify side-effect free: Ensure mappings have no side effects or external calls

Core

Defaults

• •Prefer open-source, source-generated mapping tools.
• •Mappings live at boundaries (API project, Infrastructure project), not scattered across the domain.
• •Typed IDs and value objects must be mapped explicitly (see dotnet-domain-primitives).

Anti-patterns to avoid

• •Reflection-based "magic mapping" that fails at runtime.
• •Mapping logic embedded inside domain entities.
• •Implicit conversions that obscure boundary crossings.

Review rules

• •New DTO/domain/persistence types must have deterministic, testable mapping paths.
• •Mapping must be side-effect free.

Load: examples

• •API: map request DTO -> command with explicit typed ID parsing/creation.
• •Persistence: map EF entity -> domain aggregate using explicit value object construction.
• •Integration: map external event contract -> internal event with boundary validations.

Load: advanced

Projections / query scenarios

• •Prefer projection mappings that avoid materialising large object graphs when not needed.
• •Keep read models separate where pragmatic.

Error strategy

• •Invalid boundary inputs fail fast at the boundary (validation).
• •Domain invariants enforced by constructors/factories.

Load: enforcement

Review heuristic: mapper DI gating

• •

  If a mapper is injected into a constructor (controller/handler/service), reviewers must check whether the mapper implementation itself has injected dependencies.

• •

  If the mapper has no injected dependencies (pure/stateless mapping), require refactor to a static mapper and remove DI registration.

• •

  Injection is permitted only when mapping depends on external collaborators and those collaborators are injected into the mapper.

• •

  "Inject for testability" is not sufficient when mapping is deterministic; test the mapper directly.

• •

  Reject PRs introducing runtime reflection mapping unless justified per dotnet-source-generation-first.

• •

  Require mapping tests for critical boundary conversions (typed IDs and value objects).

Load: testing

Mapping Unit Test Template

public class OrderMapperTests
{
    [Fact]
    public void ToEntity_WithValidDto_MapsAllProperties()
    {
        // Arrange
        var dto = new CreateOrderRequest
        {
            CustomerId = "cust-123",
            Amount = 99.99m,
            Currency = "GBP"
        };

        // Act
        var entity = OrderMapper.ToEntity(dto);

        // Assert
        entity.CustomerId.Value.Should().Be("cust-123");
        entity.Amount.Value.Should().Be(99.99m);
        entity.Amount.Currency.Should().Be(Currency.GBP);
    }

    [Fact]
    public void ToDto_RoundTrip_PreservesData()
    {
        // Arrange
        var original = new Order(
            CustomerId.From("cust-123"),
            Money.From(99.99m, Currency.GBP));

        // Act
        var dto = OrderMapper.ToDto(original);
        var roundTripped = OrderMapper.ToEntity(dto);

        // Assert
        roundTripped.Should().BeEquivalentTo(original);
    }
}

DI Gating Checklist

When reviewing mappers registered in DI:

• • Does the mapper have zero injected dependencies?
  • •YES: Refactor to static mapper, remove DI registration
  • •NO: Proceed to next check
• • Are all injected dependencies used during mapping?
  • •NO: Remove unused dependencies
  • •YES: Proceed
• • Is injection for "testability only"?
  • •YES: Reject - test static mappers directly
  • •NO: Injection acceptable

Red Flags - STOP

These statements indicate mapping anti-patterns: