AutoMapper Module

The AutoMapperModule provides integration with AutoMapper.

Installation

In order to use AutoMapper in your Suite application, it's enough with depending on the AutoMapperModule on the Suite Modules that require to either:

1. Declare Profiles
2. Use the IMapper.

Most likely these will be modules of your Application Layer, since this is where you will use DTOs and will use AutoMapper for the Entity to DTO mapping process.

public class SomeSuiteModule : SuiteModule
{
    /// </inheritdoc>
    public override void SetupModule(IModuleBuilder builder)
    {
        /// Other suite modules.
        builder.DependsOn<AutoMapperModule>();
    }
}

By declaring a dependency on the AutoMapperModule, your module now has access to IMapper instances through dependency injection (as usual)

```csharp hl_lines="3,5" public class SomeModuleSomeAppService : IAppService { private readonly IMapper mapper;

public SomeModuleSomeAppService(IMapper mapper)
{
    mapper.ThrowIfNull(nameof(mapper));

    this.mapper = mapper;
}

} ```

Profile Discovery

All your mappings will be declared inside classes extending AutoMapper's Profile class, as usual. The AutoMapperModule will auto discover these types and will be configured against the IMapper that will be registered in Dependency Injection. You can disable the auto-discover feature for profiles through AutoMapperModuleOptions. When doing so, you will need to add profiles manually by using the AddProfile<TProfile> method. csharp hl_lines="8,9" public class SomeSuiteModule : SuiteModule { public override void SetupModule(IModuleBuilder builder) { // Other suite modules. builder.DependsOn<AutoMapperModule, AutoMapperModuleOptions>(opt => { opt.AutoDiscoverProfiles = false; opt.AddProfile<SomeProfile>(); }); } }

Best Practices

Explicit mappings

The AutoMapper module requires explicit mapping definition. Meaning that you need to explicitly use the MapFrom instead of relying on the auto capabilities of the mapper. The reasoning behind this is that refactors and troubleshooting is easier, since there's a direct reference to the properties being of a class.

Important

The AutoMapper module will validate your mappings and throw if they are not explicitly mapped. However, this validation happens on development only.

No Extensibility providers

The use of extensibility providers is discouraged, seeing as how they're extremely easy to abuse. As a result of that, business logic ends up creeping into mapping logic, which should be simple, straight forward and fast.

Warning

Extensibility providers such as Converters and Resolvers are not registered as part of the AutoMapper configuration step, and therefore using them on profiles will result on an AutoMapperMappingException on runtime.

In case you really really need this feature, and understand the caveats of going that way (e.g. some features such as LINQ projections are not compatible), please contact the Suite Team for a one line workaround ^^.

Do not map Incoming DTOs to Entities

Do not map DTO objects to Domain Entities, we don´t want the side-effect of making all the domain entity's attributes mutable because this is hard to test, and in some cases could cause some domain business rules to be bypassed. Please take a look to this post to be clear about the downside effects. Keep in mind that only Domain Entity to DTO mappings are allowed.