diff --git a/docs/en/Object-To-Object-Mapping.md b/docs/en/Object-To-Object-Mapping.md index 7d08637d79..52260402f1 100644 --- a/docs/en/Object-To-Object-Mapping.md +++ b/docs/en/Object-To-Object-Mapping.md @@ -28,7 +28,7 @@ public class UserAppService : ApplicationService } ``` -`CreateUserInput ` is a simple [DTO](Data-Transfer-Objects.md) class and the `User` is a simple [entity](Entities.md). The code above creates a `User` entity from the given input object. The `User` entity will have more properties in a real-world application and manually creating it will become tedious and error-prone. You also have to change the mapping code when you add new properties to `User` and `CreateUserInput` classes. +`CreateUserInput` is a simple [DTO](Data-Transfer-Objects.md) class and the `User` is a simple [entity](Entities.md). The code above creates a `User` entity from the given input object. The `User` entity will have more properties in a real-world application and manually creating it will become tedious and error-prone. You also have to change the mapping code when you add new properties to `User` and `CreateUserInput` classes. We can use a library to automatically handle these kind of mappings. ABP provides abstractions for object to object mapping and has an integration package to use [AutoMapper](http://automapper.org/) as the object mapper. @@ -182,7 +182,7 @@ public class UserAppService : ApplicationService } ```` -`UserAppService ` injects the `IObjectMapper`, the specific object mapper for this module. It's usage is exactly same of the `IObjectMapper`. +`UserAppService` injects the `IObjectMapper`, the specific object mapper for this module. It's usage is exactly same of the `IObjectMapper`. The example code above don't use the `ObjectMapper` property defined in the `ApplicationService`, but injects the `IObjectMapper`. However, it is still possible to use the base property since the `ApplicationService` defines an `ObjectMapperContext` property that can be set in the class constructor. So, the example about can be re-written as like below: diff --git a/docs/zh-Hans/Object-To-Object-Mapping.md b/docs/zh-Hans/Object-To-Object-Mapping.md index 9bb22e0c66..67d580ae54 100644 --- a/docs/zh-Hans/Object-To-Object-Mapping.md +++ b/docs/zh-Hans/Object-To-Object-Mapping.md @@ -1,3 +1,255 @@ -## Object To Object Mapping +# 对象到对象映射 -TODO \ No newline at end of file +将对象映射到另一个对象是常用并且繁琐重复的工作,大部分情况下两个类都具有相同或相似的属性. 例如下面的 [应用服务](Application-Services.md)方法: + +```csharp +public class UserAppService : ApplicationService +{ + private readonly IRepository _userRepository; + + public UserAppService(IRepository userRepository) + { + _userRepository = userRepository; + } + + public void CreateUser(CreateUserInput input) + { + //Manually creating a User object from the CreateUserInput object + var user = new User + { + Name = input.Name, + Surname = input.Surname, + EmailAddress = input.EmailAddress, + Password = input.Password + }; + + _userRepository.Insert(user); + } +} +``` + +`CreateUserInput` 和 `User` 是一个简单的[DTO](Data-Transfer-Objects.md)和[实体](Entities.md)类. 上面的代码使用input对象创建了一个 `User` 实体. 上面的代码很简单,但在实际应用程序中 `User` 实体会拥有很多属性,手动创建实体乏味且容易出错. `User` 和 `CreateUserInput` 添加新属性时还需要再去修改代码. + +我们需要一个库自动处理类到类的映射. ABP提供了对象到对象映射的抽象并集成了[AutoMapper](http://automapper.org/)做为对象映射器. + +## IObjectMapper + +`IObjectMapper` 接口 (在 [Volo.Abp.ObjectMapping](https://www.nuget.org/packages/Volo.Abp.ObjectMapping)包中) 定义了一个简单的 `Map` 方法. 上面的手动映射示例可以用以下方式重写: + +````csharp +public class UserAppService : ApplicationService +{ + private readonly IRepository _userRepository; + + public UserAppService(IRepository userRepository) + { + _userRepository = userRepository; + } + + public void CreateUser(CreateUserInput input) + { + //Automatically creating a new User object using the CreateUserInput object + var user = ObjectMapper.Map(input); + + _userRepository.Insert(user); + } +} +```` + +> 示例中的 `ObjectMapper` 属性在 `ApplicationService` 基类中属性注入. 在其他地方也可以直接注入 `IObjectMapper` 接口. + +Map方法有两个泛型参数: 第一个是源对象类型,第二个是目标对象类型. + +如果想要设置现有对象属性,可以使用 `Map` 的重载方法: + +````csharp +public class UserAppService : ApplicationService +{ + private readonly IRepository _userRepository; + + public UserAppService(IRepository userRepository) + { + _userRepository = userRepository; + } + + public async Task UpdateUserAsync(Guid id, UpdateUserInput input) + { + var user = await _userRepository.GetAsync(id); + + //Automatically set properties of the user object using the UpdateUserInput + ObjectMapper.Map(input, user); + + await _userRepository.UpdateAsync(user); + } +} +```` + +必须先定义映射,然后才能映射对象. 请参阅AutoMapper集成部分了解如何定义映射. + +## AutoMapper 集成 + +[AutoMapper](http://automapper.org/) 是最流行的对象到对象映射库之一. [Volo.Abp.AutoMapper](https://www.nuget.org/packages/Volo.Abp.AutoMapper)程序包使用AutoMapper实现了 `IObjectMapper`. + +定义了以下部分的映射后就可以使 `IObjectMapper` 接口. + +### 定义映射 + +AutoMapper提供了多种定义类之间映射的方法. 有关详细信息请参阅[AutoMapper的文档](https://docs.automapper.org). + +其中定义一种映射的方法是创建一个[Profile](https://docs.automapper.org/en/stable/Configuration.html#profile-instances) 类. 例如: + +````csharp +public class MyProfile : Profile +{ + public MyProfile() + { + CreateMap(); + } +} +```` + +然后使用`AbpAutoMapperOptions`注册配置文件: + +````csharp +[DependsOn(typeof(AbpAutoMapperModule))] +public class MyModule : AbpModule +{ + public override void ConfigureServices(ServiceConfigurationContext context) + { + Configure(options => + { + //Add all mappings defined in the assembly of the MyModule class + options.AddMaps(); + }); + } +} +```` + +`AddMaps` 注册给定类的程序集中所有的配置类,通常使用模块类. 它还会注册 [attribute 映射](https://docs.automapper.org/en/stable/Attribute-mapping.html). + +### 配置验证 + +`AddMaps` 使用可选的 `bool` 参数控制[模块](Module-Development-Basics.md)的[配置验证](https://docs.automapper.org/en/stable/Configuration-validation.html): + +````csharp +options.AddMaps(validate: true); +```` + +如果此选项默认是 `false` , 但最佳实践建议启用. + +可以使用 `AddProfile` 而不是 `AddMaps` 来控制每个配置文件类的配置验证: + +````csharp +options.AddProfile(validate: true); +```` + +> 如果你有多个配置文件,并且只需要为其中几个启用验证,那么首先使用`AddMaps`而不进行验证,然后为你想要验证的每个配置文件使用`AddProfile`. + +## 高级主题 + +### IObjectMapper 接口 + +假设你已经创建了一个**可重用的模块**,其中定义了AutoMapper配置文件,并在需要映射对象时使用 `IObjectMapper`. 根据[模块化](Module-Development-Basics.md)的性质,你的模块可以用于不同的应用程序. + +`IObjectMapper` 是一个抽象,可以由最终应用程序替换使用另一个映射库. 这里的问题是你的可重用模块设计为使用AutoMapper,因为它为其定义映射配置文件. 这种情况下即使最终应用程序使用另一个默认对象映射库,你也要保证模块始终使用AutoMapper. + +`IObjectMapper`将对象映射器上下文化,你可以为不同的 模块/上下文 使用不同的库. + +用法示例: + +````csharp +public class UserAppService : ApplicationService +{ + private readonly IRepository _userRepository; + + private readonly IObjectMapper _objectMapper; + + public UserAppService( + IRepository userRepository, + IObjectMapper objectMapper) //Inject module specific mapper + { + _userRepository = userRepository; + _objectMapper = objectMapper; + } + + public async Task CreateUserAsync(CreateUserInput input) + { + //Use the module specific mapper + var user = _objectMapper.Map(input); + + await _userRepository.InsertAsync(user); + } +} +```` + +`UserAppService` 注入 `IObjectMapper`, 它是模块的特定对象映射器,用法与 `IObjectMapper` 完全相同. + +上面的示例代码未使用 `ApplicationService` 中定义的 `ObjectMapper` 属性,而是注入了 `IObjectMapper`. 但是 `ApplicationService` 定义了可以在类构造函数中设置的 `ObjectMapperContext` 属性, 因此仍然可以使用基类属性. 示例可以进行以下重写: + +````csharp +public class UserAppService : ApplicationService +{ + private readonly IRepository _userRepository; + + public UserAppService(IRepository userRepository) + { + _userRepository = userRepository; + //Set the object mapper context + ObjectMapperContext = typeof(MyModule); + } + + public async Task CreateUserAsync(CreateUserInput input) + { + var user = ObjectMapper.Map(input); + + await _userRepository.InsertAsync(user); + } +} +```` + +虽然使用上下文化的对象映射器与普通的对象映射器相同, 但是也应该在模块的 `ConfigureServices` 方法中注册上下文化的映射器: + +````csharp +[DependsOn(typeof(AbpAutoMapperModule))] +public class MyModule : AbpModule +{ + public override void ConfigureServices(ServiceConfigurationContext context) + { + //Use AutoMapper for MyModule + context.Services.AddAutoMapperObjectMapper(); + + Configure(options => + { + options.AddMaps(validate: true); + }); + } +} +```` + +`IObjectMapper`是可重用模块的一项基本功能,可在多个应用程序中使用,每个模块可以使用不同的库进行对象到对象的映射. 所有预构建的ABP模块都在使用它. 但是对于最终应用程序,你可以忽略此接口,始终使用默认的 `IObjectMapper` 接口. + +### IObjectMapper 接口 + +ABP允许自定义特定类的映射代码. 假设你要创建一个自定义类从 `User` 映射到 `UserDto`. 这种情况下,你可以创建一个实现 `IObjectMapper`的类 : + +````csharp +public class MyCustomUserMapper : IObjectMapper, ITransientDependency +{ + public UserDto Map(User source) + { + //TODO: Create a new UserDto + } + + public UserDto Map(User source, UserDto destination) + { + //TODO: Set properties of an existing UserDto + return destination; + } +} +```` + +ABP会自动发现注册 `MyCustomUserMapper`, 在你使用IObjectMapper将用户映射到UserDto时会自动使用自定义映射. + +一个类可以为不同的对象实现多个 `IObjectMapper`. + +> 这种方法功能强大, `MyCustomUserMapper`可以注入任何其他服务并在Map方法中使用. \ No newline at end of file diff --git a/docs/zh-Hans/docs-nav.json b/docs/zh-Hans/docs-nav.json index f50edace6a..e8922454cc 100644 --- a/docs/zh-Hans/docs-nav.json +++ b/docs/zh-Hans/docs-nav.json @@ -117,7 +117,9 @@ "path": "CurrentUser.md" }, { - "text": "对象序列化" + "text": "对象到对象映射", + "path": "Object-To-Object-Mapping.md" + }, { "text": "JSON序列化"