Automapper C# (How it Works For Developers)

Automapper is a versatile and powerful library in C# designed to facilitate object-to-object mapping, making transferring data between complex object models easier and more maintainable. In this article, we will explore how Automapper can efficiently map properties, flatten complex object models, and work with various types of objects like user domain objects and data transfer objects.

Introduction to Automapper

Automapper in C# is an object-object mapper, a tool that simplifies converting and transferring data between different object types. This is particularly useful in scenarios involving data entities and their transformation into data transfer objects (DTOs).

Key Features of Automapper

• Simplification of Code: Automapper drastically reduces the need for manual code by automating the mapping of properties, thus preventing errors and saving time.
• Flexibility in Mapping Configurations: Automapper allows detailed customization of mapping configurations, accommodating a wide range of mapping scenarios.
• Performance Efficiency: The library is designed to handle large and complex object models without significant performance overhead.

Getting Started with Automapper

To utilize Automapper, it must first be installed through the package manager console, a component of the development environment that facilitates the management of software packages.

Installation via Package Manager Console

You can easily install Automapper in your project by executing a simple command in your package manager console:

Install-Package AutoMapper

Setting Up Basic Mapping Configuration

The foundational step in using Automapper is to define the mapping configuration. This involves specifying how the input object (source) properties should be transferred to the output object (destination).

var config = new MapperConfiguration(cfg => 
{
    cfg.CreateMap<SourceClass, DestinationClass>();
});
IMapper mapper = config.CreateMapper();

var config = new MapperConfiguration(cfg => 
{
    cfg.CreateMap<SourceClass, DestinationClass>();
});
IMapper mapper = config.CreateMapper();

Dim config = New MapperConfiguration(Sub(cfg)
	cfg.CreateMap(Of SourceClass, DestinationClass)()
End Sub)
Dim mapper As IMapper = config.CreateMapper()

• In the example above, a mapping configuration is created to map properties from SourceClass to DestinationClass.
• An instance of IMapper is then created using this configuration.

Advanced Mapping Techniques with Automapper

Automapper's capabilities extend far beyond simple property-to-property mapping. It can adeptly handle more intricate scenarios.

Flattening Complex Object Models

One of Automapper's strengths is its ability to flatten complex object models. This feature is particularly useful when dealing with nested objects, enabling the mapping of these nested properties to a flat destination class structure.

Versatile Object Type Handling

Automapper can proficiently map between various object types, including user domain objects, DTOs, and even view models, providing a versatile solution for different data transfer needs.

Practical Usage Examples

To better understand Automapper's utility, let's explore some practical examples.

Example 1: Simple Mapping

Consider a scenario where we need to map properties from a user entity to a user DTO:

public class User
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Address { get; set; }
    public string City { get; set; }
}

public class UserDTO
{
    public string FullName { get; set; }
    public string Address { get; set; }
    public string City { get; set; }
}

// Mapping Configuration
var config = new MapperConfiguration(cfg =>
{
    cfg.CreateMap<User, UserDTO>()
       .ForMember(dest => dest.FullName, opt => opt.MapFrom(src => src.FirstName + " " + src.LastName));
});
IMapper mapper = config.CreateMapper();
User user = new User { FirstName = "John", LastName = "Doe", Address = "123 Street", City = "CityName" };
UserDTO userDto = mapper.Map<UserDTO>(user);

public class User
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Address { get; set; }
    public string City { get; set; }
}

public class UserDTO
{
    public string FullName { get; set; }
    public string Address { get; set; }
    public string City { get; set; }
}

// Mapping Configuration
var config = new MapperConfiguration(cfg =>
{
    cfg.CreateMap<User, UserDTO>()
       .ForMember(dest => dest.FullName, opt => opt.MapFrom(src => src.FirstName + " " + src.LastName));
});
IMapper mapper = config.CreateMapper();
User user = new User { FirstName = "John", LastName = "Doe", Address = "123 Street", City = "CityName" };
UserDTO userDto = mapper.Map<UserDTO>(user);

Public Class User
	Public Property FirstName() As String
	Public Property LastName() As String
	Public Property Address() As String
	Public Property City() As String
End Class

Public Class UserDTO
	Public Property FullName() As String
	Public Property Address() As String
	Public Property City() As String
End Class

' Mapping Configuration
Private config = New MapperConfiguration(Sub(cfg)
	cfg.CreateMap(Of User, UserDTO)().ForMember(Function(dest) dest.FullName, Function(opt) opt.MapFrom(Function(src) src.FirstName & " " & src.LastName))
End Sub)
Private mapper As IMapper = config.CreateMapper()
Private user As New User With {
	.FirstName = "John",
	.LastName = "Doe",
	.Address = "123 Street",
	.City = "CityName"
}
Private userDto As UserDTO = mapper.Map(Of UserDTO)(user)

• This example showcases mapping between User and UserDTO where the FullName in UserDTO is a concatenation of FirstName and LastName from User.

Example 2: Advanced Mapping with Complex Objects

In a more complex scenario, let's map an order object with nested user details to a simplified order DTO:

public class Order
{
    public User OrderedBy { get; set; }
    // Other properties...
}

public class OrderDTO
{
    public string FullName { get; set; }
    // Other properties...
}

// Mapping Configuration
var config = new MapperConfiguration(cfg =>
{
    cfg.CreateMap<Order, OrderDTO>()
       .ForMember(dest => dest.FullName, opt => opt.MapFrom(src => src.OrderedBy.FirstName + " " + src.OrderedBy.LastName));
});
IMapper mapper = config.CreateMapper();
Order order = new Order { OrderedBy = new User { FirstName = "Jane", LastName = "Doe" } };
OrderDTO orderDto = mapper.Map<OrderDTO>(order);

public class Order
{
    public User OrderedBy { get; set; }
    // Other properties...
}

public class OrderDTO
{
    public string FullName { get; set; }
    // Other properties...
}

// Mapping Configuration
var config = new MapperConfiguration(cfg =>
{
    cfg.CreateMap<Order, OrderDTO>()
       .ForMember(dest => dest.FullName, opt => opt.MapFrom(src => src.OrderedBy.FirstName + " " + src.OrderedBy.LastName));
});
IMapper mapper = config.CreateMapper();
Order order = new Order { OrderedBy = new User { FirstName = "Jane", LastName = "Doe" } };
OrderDTO orderDto = mapper.Map<OrderDTO>(order);

Public Class Order
	Public Property OrderedBy() As User
	' Other properties...
End Class

Public Class OrderDTO
	Public Property FullName() As String
	' Other properties...
End Class

' Mapping Configuration
Private config = New MapperConfiguration(Sub(cfg)
	cfg.CreateMap(Of Order, OrderDTO)().ForMember(Function(dest) dest.FullName, Function(opt) opt.MapFrom(Function(src) src.OrderedBy.FirstName & " " & src.OrderedBy.LastName))
End Sub)
Private mapper As IMapper = config.CreateMapper()
Private order As New Order With {
	.OrderedBy = New User With {
		.FirstName = "Jane",
		.LastName = "Doe"
	}
}
Private orderDto As OrderDTO = mapper.Map(Of OrderDTO)(order)

• This example demonstrates mapping from an Order object, containing nested OrderedBy details, to a flat OrderDTO, extracting and combining user names into a single FullName property.

With version 9.0, AutoMapper has transitioned from a static API (Mapper.Initialize) to an instance-based API. This change enhances flexibility and is more suitable for modern applications, especially those using dependency injection. If you are working with versions older than 9.0, the static API approach is applicable. However, for newer versions, it's recommended to adopt the instance-based API as outlined in the examples above.

Overview of Iron Software Suite

The Iron Software Suite for .NET is a robust package with a series of libraries, each serving a specific purpose. It covers functionalities like creating, reading, and editing PDFs, converting HTML to PDF, and processing images into text in multiple languages. This suite caters to various development needs, making it a versatile addition to any C# project.

Key Components of Iron Software Suite

1. IronPDF for PDF Management: This component allows developers to create, read, edit, and sign PDFs. It also offers the capability to convert HTML to PDF, a feature that can be particularly useful in generating reports or documentation from web-based data.

   

2. IronXL Excel File Handling: IronXL facilitates working with Excel files without needing Office Interop, streamlining data manipulation and analysis tasks.

   

3. IronOCR for Text Extraction: It enables text extraction from images, supporting a diverse array of 125 languages, thus making it highly versatile for international projects.

   

4. IronBarcode for QR and Barcode Support: A library that allows for reading and writing QR codes and barcodes, enhancing the capabilities for inventory management, tracking, and other related tasks.

Complementarity with Automapper

While Automapper excels in mapping properties between different object models in C#, Iron Software's Libraries extend the functionality by offering tools for handling various data formats and types. For instance, after using Automapper to transform a user domain object into a DTO, IronPDF could be used to generate a comprehensive report in PDF format. Similarly, data extracted or transformed using Automapper could be further manipulated or analyzed using IronXL for Excel file operations.

Conclusion

Automapper is an invaluable tool for C# developers, streamlining the task of mapping between objects. Its robust capabilities in mapping properties, handling complex object models, and offering customizable mapping configurations make it an essential tool for efficient software development. Understanding the intricacies of object models and how Automapper can be configured to suit specific needs is crucial for maximizing its potential in any project.

The Iron Software's Iron Suite offers various licensing options, including a free trial of Iron Software, to suit different project needs. Its licenses are tiered as Lite, Plus, and Professional, catering to different team sizes and providing comprehensive support features. Integrating this suite with Automapper can greatly enhance C# projects, adding data processing and document manipulation capabilities.