Asp.Net Mvc Using Automapper Complete Guide

ASP.NET MVC Using AutoMapper: A Detailed Guide

Introduction

Overview

AutoMapper operates based on established conventions that it uses to map source types to destination types automatically. If these conventions do not meet your requirements, you can provide custom mappings to handle more complex scenarios. When working with ASP.NET MVC, the typical use cases for AutoMapper involve mapping domain entities to view models.

Installation

First, you need to install the AutoMapper package via NuGet Package Manager in Visual Studio. Open the Package Manager Console and run the following command:

Install-Package AutoMapper

Alternatively, if you are using the .NET Core CLI, you can add the AutoMapper package by executing the below command:

dotnet add package AutoMapper

Basic Configuration

To configure AutoMapper in an ASP.NET MVC application, create a mapping profile that describes how the source types should be mapped to their corresponding destination types. Here’s a step-by-step guide to set up basic configuration:

1. Create a Mapping Profile Class:

   This class will inherit from Profile and will define mappings between various models.

   public class MappingProfile : Profile
   {
       public MappingProfile()
       {
           CreateMap<SourceModel, DestinationModel>();
       }
   }
   

2. Initialize AutoMapper in Global.asax.cs or Startup.cs:

   For traditional ASP.NET MVC apps, initialize AutoMapper using the static Mapper.Initialize method in the Application_Start method inside Global.asax.cs.

   protected void Application_Start()
   {
       AreaRegistration.RegisterAllAreas();
       FilterConfig.RegisterGlobalFilters(GlobalFilters.Filters);
       RouteConfig.RegisterRoutes(RouteTable.Routes);
       BundleConfig.RegisterBundles(BundleTable.Bundles);
   
       Mapper.Initialize(cfg =>
       {
           cfg.AddProfile(new MappingProfile());
       });
   }
   

   In ASP.NET Core MVC apps, you can use dependency injection to configure AutoMapper in the Startup.cs.

   public void ConfigureServices(IServiceCollection services)
   {
       services.AddControllersWithViews();
   
       // Register the mapping profile
       services.AddAutoMapper(typeof(MappingProfile));
   }
   

Mapping Entities to ViewModels

Assume you have two classes, User (domain entity) and UserViewModel (view model), and you want to map properties from one to another.

Domain Entity (User):

public class User
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public DateTime DateOfBirth { get; set; }
}

View Model (UserViewModel):

public class UserViewModel
{
    public int UserId { get; set; }
    public string FullName { get; set; }
    public int Age { get; set; }
}

In your mapping profile, you’ll define specific mappings for non-conventional property names and any other complex logic.

public class MappingProfile : Profile
{
    public MappingProfile()
    {
        CreateMap<User, UserViewModel>()
            .ForMember(dest => dest.UserId, opt => opt.MapFrom(src => src.Id))
            .ForMember(dest => dest.FullName, opt => opt.MapFrom(src => $"{src.FirstName} {src.LastName}"))
            .ForMember(dest => dest.Age, opt => opt.MapFrom(src => CalculateAge(src.DateOfBirth)));
    }

    private int CalculateAge(DateTime dateOfBirth)
    {
        var today = DateTime.Today;
        var age = today.Year - dateOfBirth.Year;
        if (dateOfBirth > today.AddYears(-age)) age--;
        return age;
    }
}

Utilizing AutoMapper

Once the AutoMapper profiles are configured, they can be utilized across the application wherever you need to map objects.

For example, within a controller action, you can easily convert an instance of the User entity to a UserViewModel like so:

public class UserController : Controller
{
    private readonly IUserRepository _userRepository;

    public UserController(IUserRepository userRepository)
    {
        _userRepository = userRepository;
    }

    public ActionResult Details(int id)
    {
        // Fetch user entity from the repository
        var user = _userRepository.GetUserById(id);
        
        // Map it to UserViewModel using AutoMapper
        var userModel = Mapper.Map<UserViewModel>(user);
        
        // Return the view with the mapped data
        return View(userModel);
    }
}

Custom Value Resolvers

Value resolvers allow for further customization in property mapping. For instance, if you have a more complex calculation or transformation needed beyond what a simple lambda expression can provide, you can implement a custom value resolver.

Here's an example of a custom value resolver calculating age:

public class AgeResolver : IValueResolver<User, UserViewModel, int>
{
    public int Resolve(User source, UserViewModel destination, int destMember, ResolutionContext context)
    {
        var today = DateTime.Today;
        var age = today.Year - source.DateOfBirth.Year;
        if (source.DateOfBirth.Date > today.AddYears(-age).Date)
        {
            age--;
        }
        return age;
    }
}

You can use this custom resolver in your mapping profile like so:

public class MappingProfile : Profile
{
    public MappingProfile()
    {
        CreateMap<User, UserViewModel>()
            .ForMember(dest => dest.UserId, opt => opt.MapFrom(src => src.Id))
            .ForMember(dest => dest.FullName, opt => opt.MapFrom(src => $"{src.FirstName} {src.LastName}"))
            .ForMember(dest => dest.Age, opt => opt.ResolveUsing<AgeResolver>());
    }
}

Collection Mapping

AutoMapper also supports mapping collections of objects. If you have a list of entities and want to map them to a list of view models, simply provide the types in the CreateMap method.

Domain Entity (List of Users):

public IEnumerable<User> GetAllUsers() 
{
    // Implementation fetching all users
}

Mapping to List of ViewModels:

public ActionResult Index()
{
    // Get all users from repository
    var users = _userRepository.GetAllUsers();

    // Map the users to a list of UserViewModels
    var userViewModels = Mapper.Map<IEnumerable<UserViewModel>>(users);

    // Pass the mapped collection to the view
    return View(userViewModels);
}

In your mapping profile, you would still just map the types for individual objects:

CreateMap<User, UserViewModel>().ConvertUsing<CustomUserToViewModelConverter>();

Validation and Error Handling

While AutoMapper makes the mapping process easier, it is important to keep in mind potential issues such as unmapped properties, naming conflicts, or type conversions errors. AutoMapper provides configuration options to handle such warnings and errors.

1. Unmapped Properties Warnings:

   By default, AutoMapper will warn you about properties that are left unmapped. This can be useful during development but often turned off on production by ignoring all unmapped properties.

   Mapper.Initialize(cfg =>
   {
       cfg.AddProfile(new MappingProfile());
       cfg.ForAllMaps((map, expr) => expr.ForAllOtherMembers(opt => opt.Ignore()));
   });
   

2. Error Handling:

   Automapper includes error handling through the IMappingOperationOptions interface. You might want to log failures or exceptions.

   try
   {
       var userModel = Mapper.Map<UserViewModel>(user);
   }
   catch (AutoMapperMappingException ex)
   {
       // Log the exception or take corrective actions
   }
   

3. Custom Type Converters:

   Sometimes, AutoMapper cannot determine how to map two types. In such cases, custom type converters can be used.

   public class CustomUserToViewModelConverter : ITypeConverter<User, UserViewModel>
   {
       public UserViewModel Convert(User source, UserViewModel destination, ResolutionContext context)
       {
           // Custom conversion logic here
           return new UserViewModel
           {
               UserId = source.Id,
               FullName = $"{source.FirstName} {source.LastName}",
               Age = CalculateAge(source.DateOfBirth)
           };
       }
   
       private int CalculateAge(DateTime dateOfBirth)
       {
           // Implementation of age calculation logic
       }
   }
   

   This converter can then be added in the mapping profile.

   CreateMap<User, UserViewModel>().ConvertUsing<CustomUserToViewModelConverter>();
   

Tips and Best Practices

1. Define Clear Conventions:

   Stick to common naming conventions to avoid unnecessary custom mappings, making your codebase maintainable.

2. Consolidate Mappings:

   Group related mappings into single profiles for better organization.

3. Use DTOs:

   Use Data Transfer Objects (DTOs) for passing data between layers, especially when dealing with complex data hierarchies.

4. Avoid Service/Repository Logic in Resolvers:

   Keep resolvers focused on transformation logic only, moving service/repository operations elsewhere.

5. Test Mappings Extensively:

   Thorough testing of your mappings ensures that data transformations meet expectations, preventing runtime errors.

6. Performance Considerations:

   Profiling your application can help identify performance bottlenecks introduced by AutoMapper usage. Optimize by pre-compiling maps and avoiding circular references.

Conclusion