Entity.Mapper.Asp 2.2.1

EntityMapper Documentation

Introducion

EntityMapper is a powerful and flexible object-to-object mapping library for .NET applications. It simplifies the process of mapping one object's properties to another, allowing you to focus on writing clean and maintainable code. This documentation provides a detailed guide on how to use EntityMapper in your .NET projects. It covers the basic setup, configuration, mapping, and integration with the ServiceCollection.

Installation

Using .NET CLI

To install EntityMapper using the .NET CLI, open your command-line interface and navigate to your project's directory. Run the following command to add the EntityMapper package to your project:

dotnet add package Entity.Mapper.Asp --version 1.0.0

Using NuGet Package Manager Console

If you prefer to use Visual Studio and its integrated development environment, you can install EntityMapper using the NuGet Package Manager Console. Open Visual Studio. Go To "Tools" > "NuGet Package Manager" > "Package Manager Console." In the Package Manager Console, run the following command to install EntityMapper:

NuGet\Install-Package Entity.Mapper.Asp -Version 1.0.0

This command will install the latest version of EntityMapper into your project.

Using PackageReference (MSBuild)

In some cases, you may want to integrate EntityMapper into your project using MSBuild. This method is useful when you need more control over how EntityMapper is incorporated into your build process. Open your project file (e.g., .csproj) in a text editor or Visual Studio or Rider By F4. Add a PackageReference element for EntityMapper in the ItemGroup section:

<ItemGroup>
  <PackageReference Include="EntityMapper" Version="X.Y.Z" />
</ItemGroup>

Replace "X.Y.Z" with the desired version of EntityMapper. Save the project file. To restore the packages, you can use the following command in the command-line interface:

dotnet restore

This command will download and install EntityMapper and its dependencies into your project.

Basic Configuration

EntityMapper provides a straightforward way to configure object mapping. You can create a mapping configuration using the EntityMapper class and the AddConfiguration method.

var entityMapper = new EntityMapper();
entityMapper.AddConfiguration<UserDto, User>((user) => new UserDto()
{
    Id = user.Id,
    Name = user.Name
});

This code sets up a mapping from User objects to UserDto objects. It specifies how properties should be mapped from the source (User) to the destination (UserDto).

Disposable Mapper Configurations

EntityMapper traditionally uses a global configuration to define how objects of one type should be mapped to another. While this approach works well for most cases, it can lead to memory overhead when configuring mappings that are seldom used, especially in applications where memory efficiency is crucial.

To address this issue, EntityMapper introduced Disposable Mapper Configurations. This feature allows you to define and configure a mapping for a specific use case, and once that mapping is no longer needed, it is automatically disposed of. This can be particularly beneficial for scenarios where you want to minimize memory consumption, such as handling infrequent or specialized mappings.

entityMapper.AddDisposableMapperConfiguration<User, UserDto>((user) => new UserDto()
{
    Id = user.Id,
    Name = user.Name
});

In this code snippet, we define a mapping from the User class to the UserDto class. The unique aspect is that this mapping is treated as disposable. Once the mapping has been used (typically after the first request), EntityMapper automatically disposes of it, freeing up any resources associated with it.

Asynchronous Configuration

EntityMapper provides the capability to define asynchronous mapping functions, allowing you to perform asynchronous operations during the mapping process. This is achieved by using asynchronous delegates (lambda expressions) in the AddAsyncMapperConfiguration method. Let's look at an example of using asynchronous configuration:

entityMapper.AddAsyncMapperConfiguration<User, UserDto>(async (user) =>
{
    // Perform an asynchronous operation (e.g., delay)
    await Task.Delay(500);

    // Create a UserDtoStrange object with asynchronously retrieved data
    return new UserDto()
    {
        Id = user.Id,
        FullName = $"{user.Name} {user.LastName}"
    };
});

In this example, we create an asynchronous mapping configuration between the UserStrange and UserDtoStrange types. Inside the lambda expression, we use the async keyword to define an asynchronous mapping function. Within the mapping function, we perform an asynchronous operation, such as Task.Delay, to introduce an artificial delay of 500 milliseconds. Then, we create a UserDtoStrange object with data retrieved asynchronously.

Bidirectional Mapping Configuration

EntityMapper simplifies bidirectional mapping by allowing you to set up mappings in both directions using a single configuration. Let's examine an example of bidirectional mapping configuration:

var user = new User()
{
    Id = 20,
    Name = "Test Name"
};

entityMapper.AddABidirectionalMapperConfiguration<User, UserDto>((user) => new UserDto()
{
    Id = user.Id,
    Name = user.Name
});

var dto = entityMapper.Map<User, UserDto>(user);
var userNew = entityMapper.Map<UserDto, User>(dto);

In this code snippet, we perform the following steps:

1. We create a User object with some initial data.
2. We use the AddABidirectionalMapperConfiguration method to configure bidirectional mapping between User and UserDto. This method accepts a mapping function that defines how User objects are mapped to UserDto objects.
3. We use the Map method to map a User object (user) to a UserDto object (dto).
4. Finally, we use the Map method again to map the UserDto object (dto) back to a User object (userNew). The bidirectional mapping configuration allows you to effortlessly switch between User and UserDto objects while maintaining the integrity of your data.

Mapping Objects

Once you have configured EntityMapper, you can easily map objects using the Map method.

var userDto = EntityMapper.Map<User, UserDto>(user);

In this example, we map a User object to a UserDto object, and EntityMapper takes care of copying the properties according to the configuration.

ServiceCollection Integration

EntityMapper can be integrated with the ServiceCollection in ASP.NET Core applications to enable dependency injection of mappers. Here's how to set it up:

var serviceCollection = new ServiceCollection();
var entityMapper = serviceCollection.UseMapper();
entityMapper.AddMapperConfiguration<User, UserDto>((user) => new UserDto()
{
    Id = user.Id,
    Name = user.Name
});

This code configures EntityMapper to work with the ServiceCollection. It allows you to inject the mapper into your services, making it easy to use EntityMapper within your application's services and controllers.

Conclusion

EntityMapper is a powerful tool for simplifying object-to-object mapping in your .NET applications. By following this documentation, you can quickly set up and use EntityMapper to streamline your code and improve maintainability. It's worth noting that EntityMapper is extensively tested, with a test suite that achieves 100% code coverage to ensure its reliability and correctness in various scenarios. This comprehensive testing ensures that EntityMapper works seamlessly in your projects, providing confidence in its behavior and robustness.