Intent.DocumentDB.Dtos.AutoMapper

What This Module Does

Extends the base DTO + AutoMapper generation so that DTOs whose field mappings traverse DocumentDB aggregate boundaries are correctly populated. It injects repository lookups and mapping logic for cross-aggregate fields after AutoMapper's standard property mapping has run.

Why You Need It

When a DTO field maps to data located in a different aggregate (e.g. navigating through an association chain that crosses aggregate roots), a simple AutoMapper configuration cannot materialize that data because it requires additional repository queries. This module detects those situations and generates an AfterMap hook with a MappingAction class that performs the necessary loads.

Use it when:

  • You have DTOs whose field mapping path includes an aggregational association (collection or nullable end) not directly exposed on the source entity's public properties.
  • You need to populate DTO fields from related aggregates using repository access within AutoMapper.

How It Works

During template registration a factory extension (DtoAutoMapperFactoryExtension) runs CrossAggregateMappingConfigurator.Execute(...):

  1. Locates all DTO templates (DtoModelTemplate) that are mapped (templateModel.Mapping != null).
  2. For each DTO, inspects each mapped field's path segments. If any segment is an aggregational association and the source entity does not expose a matching property, the DTO is considered a cross-aggregate mapping candidate.
  3. Modifies the generated mapping profile (location determined by the Application.Dtos settings: Profile in DTO class or separate profile) to append AfterMap<MappingAction>() to the mapping chain.
  4. Generates a nested MappingAction class that implements IMappingAction<SourceEntity, Dto>.
  5. Injects required repositories (resolved via EntityRepositoryInterfaceTemplate) and IMapper into the MappingAction constructor.
  6. In Process(source, destination, context) it:
    • Computes ordered load instructions for each aggregate path (ensuring parent aggregates load first).
    • Uses repository FindByIdAsync / FindByIdsAsync to materialize each aggregate based on foreign key attributes.
    • Throws a NotFoundException when a required (non-nullable) single aggregate cannot be loaded.
    • Assigns destination DTO properties from loaded aggregates, mapping nested DTO-valued fields using generated MapTo{Dto} helper functions.
    • Handles optional and "expression optional" segments with null checks.
  7. If DTO property setter accessibility is configured as private or init (DTO Settings), property setters for affected fields are elevated to internal to allow mutation in the AfterMap stage.

Generated Artifacts

  • Augmented mapping chain: AfterMap<MappingAction>().
  • Nested MappingAction class containing repository fields and a Process method.
  • Internal setters for certain DTO properties (only when necessary to enable assignment post-map).

Key Implementation Details

  • Aggregational association detection: An association end is considered aggregational if the source end is a collection or nullable.
  • Load ordering: Aggregates load in ascending path length to respect dependency ordering.
  • Foreign key resolution: For each associated aggregate the code searches the target entity for a FK attribute referencing the association's target end; absence raises an exception.
  • Optional path handling: Two booleans distinguish optional association vs optional expression segment (IsOptional and IsExpressionOptional). Expression optionality currently relies on a simple ? presence check in the path expression.
  • Nested DTO mapping: DTO-type fields invoke generated MapTo{Dto} or MapTo{Dto}List helpers with _mapper.
  • Error handling: Required single aggregate null -> throws NotFoundException including the attempted key value.
  • Synchronous waits: Repository async calls are awaited via .Result inside the mapping action; consider refactoring for fully async pipelines if necessary.

Configuration & Dependencies

  • Depends on base modules: Intent.Application.Dtos, Intent.Application.Dtos.AutoMapper, Intent.Entities.Repositories.Api.
  • Respects setting: DTO AutoMapper Profile Location (profile in DTO vs separate profile affects where AfterMap is injected).
  • Respects DTO Settings: Property Setter Accessibility (may elevate to internal).

Performance Considerations

  • Multiple repository calls per mapped DTO can incur N+1 queries. Group or batch logic may be desirable for large collections – you can customize the generated MappingAction because its body is produced in merge mode.
  • .Result usage can block; in high-throughput asynchronous contexts consider customizing to use fully async mapping patterns.

Customization Points

  • The nested MappingAction class can be modified (merge mode) to add caching, batching, or alternative loading strategies.
  • You can introduce additional safety checks or logging around repository calls.
  • Adjust exception messages or replace with domain-specific error handling as needed.

Limitations

  • Optional expression detection is heuristic (searches for ? in path expression); complex optional patterns may require manual refinement.
  • Assumes FK attributes exist; if foreign key modeling is absent generation will throw at build time.
  • Does not attempt to minimize duplicate repository loads when multiple DTO fields traverse identical aggregate paths (can be manually optimized).

When Not To Use

  • DTOs confined to a single aggregate root (standard AutoMapper from Intent.Application.Dtos.AutoMapper suffices).
  • Read models where manual projection queries (e.g., LINQ with joins) are more efficient than per-field repository lookups.
  • Intent.DocumentDB (aggregate modeling & persistence abstraction)
  • Intent.Application.Dtos
  • Intent.Application.Dtos.AutoMapper
  • Intent.Entities.Repositories.Api

Example (Conceptual)

A OrderDetailsDto maps Customer.Email where Customer is a separate aggregate not directly exposed as a navigation property on Order. The module:

  1. Detects that Customer association segment requires cross-aggregate access.
  2. Adds AfterMap<MappingAction>().
  3. In MappingAction.Process loads the Customer via ICustomerRepository.FindByIdAsync(order.CustomerId).
  4. Assigns destination.CustomerEmail = customer.Email.

Extending Further

If you need batching, consider collecting all keys first, performing a single FindByIdsAsync per aggregate, and indexing results for assignment.

Published at: https://docs.intentarchitect.com/articles/modules-dotnet/intent-documentdb-dtos-automapper/intent-documentdb-dtos-automapper.html