Merge pull request #23438 from abpframework/Mapperly

Add Mapperly integration documentation

docs/en/framework/fundamentals/object-extensions.md

@@ -394,6 +394,22 @@ public class MyProfile : Profile
 
 It has the same parameters with the `MapExtraPropertiesTo` method.
 
+#### Mapperly Integration
+
+If you're using the [Mapperly](https://github.com/riok/mapperly) library, the ABP also provides an extension method to utilize the `MapExtraPropertiesTo` method defined above.
+
+You can use the `MapExtraProperties` attribute to Mapperly class:
+
+````csharp
+[Mapper]
+[MapExtraProperties]
+public partial class IdentityUserToProfileDtoMapper : MapperBase<IdentityUser, IdentityUserDto>
+{
+    public override partial IdentityUserDto Map(IdentityUser source);
+    public override partial void Map(IdentityUser source, IdentityUserDto destination);
+}
+````
+
 ## Entity Framework Core Database Mapping
 
 If you're using the EF Core, you can map an extra property to a table field in the database. Example:

docs/en/framework/infrastructure/object-to-object-mapping.md

@@ -84,7 +84,7 @@ public class UserAppService : ApplicationService
 }
 ````
 
-You should have defined the mappings before to be able to map objects. See the AutoMapper integration section to learn how to define mappings.
+You should have defined the mappings before to be able to map objects. See the AutoMapper/Mapperly integration section to learn how to define mappings.
 
 ## AutoMapper Integration
 
@@ -217,13 +217,120 @@ public class MyProfile : Profile
 }
 ````
 
+## Mapperly Integration
+
+[Mapperly](https://github.com/riok/mapperly) is a .NET source generator for generating object mappings. [Volo.Abp.Mapperly](https://www.nuget.org/packages/Volo.Abp.Mapperly) package defines the Mapperly integration for the `IObjectMapper`.
+
+Once you define mappings class as below, you can use the `IObjectMapper` interface just like explained before.
+
+### Define Mapping Classes
+
+You can define a mapper class by using the `Mapper` attribute. The class and methods must be `partial` to allow the Mapperly to generate the implementation during the build process:
+
+````csharp
+[Mapper]
+public partial class UserToUserDtoMapper : MapperBase<User, UserDto>
+{
+    public override partial UserDto Map(User source);
+    public override partial void Map(User source, UserDto destination);
+}
+````
+
+If you also want to map `UserDto` to `User`, you can inherit from the `TwoWayMapperBase<User, UserDto>` class:
+
+````csharp
+[Mapper]
+public partial class UserToUserDtoMapper : TwoWayMapperBase<User, UserDto>
+{
+    public override partial UserDto Map(User source);
+    public override partial void Map(User source, UserDto destination);
+
+    public override partial User ReverseMap(UserDto destination);
+    public override partial void ReverseMap(UserDto destination, User source);
+}
+````
+
+### Before and After Mapping Methods
+
+The base class provides `BeforeMap` and `AfterMap` methods that can be overridden to perform actions before and after the mapping:
+
+````csharp
+[Mapper]
+public partial class UserToUserDtoMapper : TwoWayMapperBase<User, UserDto>
+{
+    public override partial UserDto Map(User source);
+    public override partial void Map(User source, UserDto destination);
+
+    public override partial void BeforeMap(User source)
+    {
+        //TODO: Perform actions before the mapping
+    }
+
+    public override partial void AfterMap(User source, UserDto destination)
+    {
+        //TODO: Perform actions after the mapping
+    }
+
+    public override partial User ReverseMap(UserDto destination);
+    public override partial void ReverseMap(UserDto destination, User source);
+
+    public override partial void BeforeReverseMap(UserDto destination)
+    {
+        //TODO: Perform actions before the reverse mapping
+    }
+
+    public override partial void AfterReverseMap(UserDto destination, User source)
+    {
+        //TODO: Perform actions after the reverse mapping
+    }
+}
+````
+
+### Mapping the Object Extensions
+
+[Object extension system](../fundamentals/object-extensions.md) allows to define extra properties for existing classes. ABP provides a mapping definition extension to properly map extra properties of two objects:
+
+````csharp
+[Mapper]
+[MapExtraProperties]
+public partial class UserToUserDtoMapper : MapperBase<User, UserDto>
+{
+    public override partial UserDto Map(User source);
+    public override partial void Map(User source, UserDto destination);
+}
+````
+
+It is suggested to use the `MapExtraPropertiesAttribute` attribute if both classes are extensible objects (implement the `IHasExtraProperties` interface). See the [object extension document](../fundamentals/object-extensions.md) for more.
+
+### Lists and Arrays Support
+
+ABP Mapperly integration also supports mapping lists and arrays as explained in the [IObjectMapper<TSource, TDestination> Interface](#iobjectmappertsource-tdestination-interface) section. 
+
+**Example**:
+
+````csharp
+[Mapper]
+public partial class UserToUserDtoMapper : MapperBase<User, UserDto>
+{
+    public override partial UserDto Map(User source);
+    public override partial void Map(User source, UserDto destination);
+}
+
+var users = await _userRepository.GetListAsync(); // returns List<User>
+var dtos = ObjectMapper.Map<List<User>, List<UserDto>>(users); // creates List<UserDto>
+````
+
+### More Mapperly Features
+
+Most of Mapperly's features such as `Ignore` can be configured through its attributes. See the [Mapperly documentation](https://mapperly.riok.app/docs/intro/) for more details.
+
 ## Advanced Topics
 
 ### IObjectMapper<TContext> Interface
 
-Assume that you have created a **reusable module** which defines AutoMapper profiles and uses `IObjectMapper` when it needs to map objects. Your module then can be used in different applications, by nature of the [modularity](../architecture/modularity/basics.md).
+Assume that you have created a **reusable module** which defines AutoMapper/Mapperly profiles and uses `IObjectMapper` when it needs to map objects. Your module then can be used in different applications, by nature of the [modularity](../architecture/modularity/basics.md).
 
-`IObjectMapper` is an abstraction and can be replaced by the final application to use another mapping library. The problem here that your reusable module is designed to use the AutoMapper library, because it only defines mappings for it. In such a case, you will want to guarantee that your module always uses AutoMapper even if the final application uses another default object mapping library.
+`IObjectMapper` is an abstraction and can be replaced by the final application to use another mapping library. The problem here that your reusable module is designed to use the AutoMapper/Mapperly library, because it only defines mappings for it. In such a case, you will want to guarantee that your module always uses AutoMapper/Mapperly even if the final application uses another default object mapping library.
 
 `IObjectMapper<TContext>` is used to contextualize the object mapper, so you can use different libraries for different modules/contexts.
 
@@ -281,6 +388,8 @@ public class UserAppService : ApplicationService
 
 While using the contextualized object mapper is same as the normal object mapper, you should register the contextualized mapper in your module's `ConfigureServices` method:
 
+When using AutoMapper:
+
 ````csharp
 [DependsOn(typeof(AbpAutoMapperModule))]
 public class MyModule : AbpModule
@@ -298,6 +407,20 @@ public class MyModule : AbpModule
 }
 ````
 
+When using Mapperly:
+
+````csharp
+[DependsOn(typeof(AbpMapperlyModule))]
+public class MyModule : AbpModule
+{
+    public override void ConfigureServices(ServiceConfigurationContext context)
+    {
+        //Use Mapperly for MyModule
+        context.Services.AddMapperlyObjectMapper<MyModule>();
+    }
+}
+````
+
 `IObjectMapper<MyModule>` is an essential feature for a reusable module where it can be used in multiple applications each may use a different library for object to object mapping. All pre-built ABP modules are using it. But, for the final application, you can ignore this interface and always use the default `IObjectMapper` interface.
 
 ### IObjectMapper<TSource, TDestination> Interface

docs/en/release-info/migration-guides/AutoMapper-To-Mapperly.md

@@ -0,0 +1,184 @@
+# Migrating from AutoMapper to Mapperly
+
+## Introduction
+
+The AutoMapper library is **no longer free for commercial use**. For more details, you can refer to [this announcement post](https://www.jimmybogard.com/automapper-and-mediatr-going-commercial/).
+
+ABP Framework provides both AutoMapper and Mapperly integrations. If your project currently uses AutoMapper and you don't have a commercial license, you can switch to Mapperly by following the steps outlined below.
+
+## Migration Steps
+
+Please open your project in an IDE(`Visual Studio`, `VS Code` or `JetBrains Rider`), then perform the following global search and replace operations:
+
+1. Replace `Volo.Abp.AutoMapper` with `Volo.Abp.Mapperly` in all `*.csproj` files.
+2. Replace `using Volo.Abp.AutoMapper;` with `using Volo.Abp.Mapperly;` in all `*.cs` files.
+3. Replace `AbpAutoMapperModule` with `AbpMapperlyModule` in all `*.cs` files.
+4. Replace `AddAutoMapperObjectMapper` with `AddMapperlyObjectMapper` in all `*.cs` files.
+5. Remove any code sections that configure `Configure<AbpAutoMapperOptions>`.
+6. Review any existing AutoMapper `Profile` classes and ensure all newly created Mapperly mapping classes are registered appropriately. (You can refer to the example below for guidance)
+
+**Example:**
+
+Here is an AutoMapper's `Profile` class:
+
+```csharp
+public class ExampleAutoMapper : Profile
+{
+    public AbpIdentityApplicationModuleAutoMapperProfile()
+    {
+        CreateMap<IdentityUser, IdentityUserDto>()
+            .MapExtraProperties()
+            .Ignore(x => x.IsLockedOut)
+            .Ignore(x => x.SupportTwoFactor)
+            .Ignore(x => x.RoleNames);
+
+        CreateMap<IdentityUserClaim, IdentityUserClaimDto>();
+
+        CreateMap<OrganizationUnit, OrganizationUnitDto>()
+            .MapExtraProperties();
+
+		CreateMap<OrganizationUnitRole, OrganizationUnitRoleDto>()
+			.ReverseMap();
+
+        CreateMap<IdentityRole, OrganizationUnitRoleDto>()
+            .ForMember(dest => dest.RoleId, src => src.MapFrom(r => r.Id));
+
+        CreateMap<IdentityUser, IdentityUserExportDto>()
+            .ForMember(dest => dest.Active, src => src.MapFrom(r => r.IsActive ? "Yes" : "No"))
+            .ForMember(dest => dest.EmailConfirmed, src => src.MapFrom(r => r.EmailConfirmed ? "Yes" : "No"))
+            .ForMember(dest => dest.TwoFactorEnabled, src => src.MapFrom(r => r.TwoFactorEnabled ? "Yes" : "No"))
+            .ForMember(dest => dest.AccountLookout, src => src.MapFrom(r => r.LockoutEnd != null && r.LockoutEnd > DateTime.UtcNow ? "Yes" : "No"))
+            .Ignore(x => x.Roles);
+    }
+}
+```
+
+And the Mapperly mapping class:
+
+```csharp
+[Mapper]
+[MapExtraProperties]
+public partial class IdentityUserToIdentityUserDtoMapper : MapperBase<IdentityUser, IdentityUserDto>
+{
+    [MapperIgnoreTarget(nameof(IdentityUserDto.IsLockedOut))]
+    [MapperIgnoreTarget(nameof(IdentityUserDto.SupportTwoFactor))]
+    [MapperIgnoreTarget(nameof(IdentityUserDto.RoleNames))]
+    public override partial IdentityUserDto Map(IdentityUser source);
+
+    [MapperIgnoreTarget(nameof(IdentityUserDto.IsLockedOut))]
+    [MapperIgnoreTarget(nameof(IdentityUserDto.SupportTwoFactor))]
+    [MapperIgnoreTarget(nameof(IdentityUserDto.RoleNames))]
+    public override partial void Map(IdentityUser source, IdentityUserDto destination);
+}
+
+[Mapper]
+public partial class IdentityUserClaimToIdentityUserClaimDtoMapper : MapperBase<IdentityUserClaim, IdentityUserClaimDto>
+{
+    public override partial IdentityUserClaimDto Map(IdentityUserClaim source);
+
+    public override partial void Map(IdentityUserClaim source, IdentityUserClaimDto destination);
+}
+
+[Mapper]
+[MapExtraProperties]
+public partial class OrganizationUnitToOrganizationUnitDtoMapper : MapperBase<OrganizationUnit, OrganizationUnitDto>
+{
+    public override partial OrganizationUnitDto Map(OrganizationUnit source);
+    public override partial void Map(OrganizationUnit source, OrganizationUnitDto destination);
+}
+
+[Mapper]
+public partial class OrganizationUnitRoleToOrganizationUnitRoleDtoMapper : TwoWayMapperBase<OrganizationUnitRole, OrganizationUnitRoleDto>
+{
+    public override partial OrganizationUnitRoleDto Map(OrganizationUnitRole source);
+    public override partial void Map(OrganizationUnitRole source, OrganizationUnitRoleDto destination);
+
+    public override partial OrganizationUnitRole ReverseMap(OrganizationUnitRoleDto destination);
+    public override partial void ReverseMap(OrganizationUnitRoleDto destination, OrganizationUnitRole source);
+}
+
+[Mapper]
+[MapExtraProperties]
+public partial class OrganizationUnitToOrganizationUnitWithDetailsDtoMapper : MapperBase<OrganizationUnit, OrganizationUnitWithDetailsDto>
+{
+    [MapperIgnoreTarget(nameof(OrganizationUnitWithDetailsDto.Roles))]
+    [MapperIgnoreTarget(nameof(OrganizationUnitWithDetailsDto.UserCount))]
+    public override partial OrganizationUnitWithDetailsDto Map(OrganizationUnit source);
+
+    [MapperIgnoreTarget(nameof(OrganizationUnitWithDetailsDto.Roles))]
+    [MapperIgnoreTarget(nameof(OrganizationUnitWithDetailsDto.UserCount))]
+    public override partial void Map(OrganizationUnit source, OrganizationUnitWithDetailsDto destination);
+}
+
+[Mapper]
+public partial class IdentityRoleToOrganizationUnitRoleDtoMapper : MapperBase<IdentityRole, OrganizationUnitRoleDto>
+{
+    [MapProperty(nameof(IdentityRole.Id), nameof(OrganizationUnitRoleDto.RoleId))]
+    public override partial OrganizationUnitRoleDto Map(IdentityRole source);
+
+    [MapProperty(nameof(IdentityRole.Id), nameof(OrganizationUnitRoleDto.RoleId))]
+    public override partial void Map(IdentityRole source, OrganizationUnitRoleDto destination);
+}
+
+[Mapper]
+public partial class IdentityUserToIdentityUserExportDtoMapper : MapperBase<IdentityUser, IdentityUserExportDto>
+{
+    [MapperIgnoreTarget(nameof(IdentityUserExportDto.Roles))]
+    public override partial IdentityUserExportDto Map(IdentityUser source);
+
+    [MapperIgnoreTarget(nameof(IdentityUserExportDto.Roles))]
+    public override partial void Map(IdentityUser source, IdentityUserExportDto destination);
+
+    public override void AfterMap(IdentityUser source, IdentityUserExportDto destination)
+    {
+        destination.Active = source.IsActive ? "Yes" : "No";
+        destination.EmailConfirmed = source.EmailConfirmed ? "Yes" : "No";
+        destination.TwoFactorEnabled = source.TwoFactorEnabled ? "Yes" : "No";
+        destination.AccountLookout = source.LockoutEnd != null && source.LockoutEnd > DateTime.UtcNow ? "Yes" : "No";
+    }
+}
+```
+
+## Mapperly Mapping Class
+
+To use Mapperly, you'll need to create a dedicated mapping class for each source and destination types.
+
+* Use the `[Mapper]` attribute to designate the class as a Mapperly mapper.
+* Replace AutoMapper's `Ignore()` method with the `[MapperIgnoreTarget]` attribute.
+* Replace the `MapExtraProperties()` method with the `[MapExtraProperties]` attribute.
+* Use the `TwoWayMapperBase` class as an alternative to AutoMapper’s `ReverseMap()` functionality.
+* Implement the `AfterMap()` method to execute logic after the mapping is completed.
+
+### Dependency Injection in Mapper Class
+
+All Mapperly mapping classes automatically registered in the the [dependency injection (DI)](../../framework/fundamentals/dependency-injection.md) container. To use a service within a Mapper class, simply add it to the constructor, Mapperly will inject it automatically.
+
+**Example:**
+
+```csharp
+public partial class IdentityUserToIdentityUserDtoMapper : MapperBase<IdentityUser, IdentityUserDto>
+{
+    public IdentityUserToIdentityUserDtoMapper(MyService myService)
+    {
+        _myService = myService;
+    }
+
+    public override partial IdentityUserDto Map(IdentityUser source);
+    public override partial void Map(IdentityUser source, IdentityUserDto destination);
+
+    public override void AfterMap(IdentityUser source, IdentityUserDto destination)
+    {
+        destination.MyProperty = _myService.GetMyProperty(source.MyProperty);
+    }
+}
+```
+
+## Mapperly Documentation
+
+Please refer to the [Mapperly documentation](https://mapperly.riok.app/docs/intro/) for more details.
+
+**Key points:**
+
+- [Mapperly Configuration](https://mapperly.riok.app/docs/configuration/mapper/)
+- [Mapperly Enums](https://mapperly.riok.app/docs/configuration/enum/)
+- [Mapperly Flattening and unflattening](https://mapperly.riok.app/docs/configuration/flattening/)