Euonia.Mapping.Mapster
2026.5.0
dotnet add package Euonia.Mapping.Mapster --version 2026.5.0
NuGet\Install-Package Euonia.Mapping.Mapster -Version 2026.5.0
<PackageReference Include="Euonia.Mapping.Mapster" Version="2026.5.0" />
<PackageVersion Include="Euonia.Mapping.Mapster" Version="2026.5.0" />
<PackageReference Include="Euonia.Mapping.Mapster" />
paket add Euonia.Mapping.Mapster --version 2026.5.0
#r "nuget: Euonia.Mapping.Mapster, 2026.5.0"
#:package Euonia.Mapping.Mapster@2026.5.0
#addin nuget:?package=Euonia.Mapping.Mapster&version=2026.5.0
#tool nuget:?package=Euonia.Mapping.Mapster&version=2026.5.0
Euonia.Mapping.Mapster
Euonia 对象映射抽象的 Mapster 后端:把 Mapster 的 IMapper 适配为 ITypeAdapter,并由 MapsterModule 在应用初始化时安装为当前映射工厂。
- 目标框架:
net10.0、net11.0 - 根命名空间:
Nerosoft.Euonia.Mapping - NuGet 包:
Euonia.Mapping.Mapster
ProjectedAs/ProjectedAsCollection扩展方法来自Euonia.Mapping,位于全局命名空间;本包的模块、工厂与选项类型在Nerosoft.Euonia.Mapping。
安装
dotnet add package Euonia.Mapping.Mapster
快速开始
通过模块启用(模块初始化时会调用 TypeAdapterFactory.SetCurrent):
using Mapster;
using Microsoft.Extensions.DependencyInjection;
using Nerosoft.Euonia.Mapping;
using Nerosoft.Euonia.Modularity;
[DependsOn(typeof(MapsterModule))]
public sealed class ApplicationModule : ModuleContextBase
{
public override void ConfigureServices(ServiceConfigurationContext context)
{
context.Services.Configure<MapsterOptions>(options =>
{
options.AddProfile<OrderMappingRegister>();
options.AddProfiles(typeof(ApplicationModule).Assembly);
});
}
}
定义映射注册。config.NewConfig<,>() 是 Mapster 原生 API,不是 Euonia 的扩展:
using Mapster;
public sealed class OrderMappingRegister : IRegister
{
public void Register(TypeAdapterConfig config)
{
config.NewConfig<Order, OrderDto>();
config.NewConfig<OrderLine, OrderLineDto>();
}
}
投影:
var dto = order.ProjectedAs<OrderDto>();
主要功能
- 映射工厂:
MapsterTypeAdapterFactory实现ITypeAdapterFactory,MapsterTypeAdapter实现ITypeAdapter。 - 模块集成:
MapsterModule注册 Mapster 服务,并在OnApplicationInitialization中安装当前工厂。 - 映射注册:
MapsterOptions.AddProfile/AddProfiles支持IRegister实例、类型、工厂与程序集扫描。 - 键控注册:以键
"mapster"注册ITypeAdapterFactory,可与 AutoMapper 实现并存。 - 内置转换:
AddMapster()自动应用ByteArrayToInt64Converter,即byte[]→long的单向转换。 - 可选转换器:
JsonValueConverter<TDest>提供stringJSON →TDest的映射注册,需自行加入MapsterOptions。
核心类型
| 类型 | 作用 |
|---|---|
MapsterModule |
注册 Mapster 并设置当前工厂 |
MapsterTypeAdapterFactory / MapsterTypeAdapter |
ITypeAdapterFactory / ITypeAdapter 实现 |
MapsterOptions |
IRegister、程序集与配置委托注册 |
ByteArrayToInt64Converter |
byte[] → long 的内置 IRegister |
JsonValueConverter<TDest> |
string JSON → TDest 的 IRegister |
AddMapster() |
注册 TypeAdapterConfig 与作用域 IMapper |
选项(代码配置)
本包没有 IConfiguration 读取点,也不存在 Euonia:Mapping 配置节。MapsterOptions 只能通过 services.Configure<MapsterOptions>(...) 代码配置。
| 成员 | 说明 |
|---|---|
AddProfile<TRegister>() |
注册 IRegister 类型,构建配置时通过 ActivatorUtilities 创建实例 |
AddProfile<TRegister>(Func<TRegister>) |
用工厂创建并注册实例 |
AddProfile(Type) |
反射创建实例(要求可赋值给 IRegister) |
AddProfile(IRegister) |
直接注册实例 |
AddProfiles(IEnumerable<IRegister>) |
批量注册实例 |
AddProfiles(params Assembly[]) |
调用 TypeAdapterConfig.Scan 扫描程序集 |
using Microsoft.Extensions.DependencyInjection;
using Nerosoft.Euonia.Mapping;
services.Configure<MapsterOptions>(options =>
{
options.AddProfile(new OrderMappingRegister());
options.AddProfiles(typeof(Program).Assembly);
});
该包是代码配置:不要为它编写
appsettings.json节。
使用示例
在应用服务中直接投影,不需要注入 IMapper:
public sealed class OrderQueryService
{
public OrderDto Get(long id)
{
var order = LoadOrder(id);
return order.ProjectedAs<OrderDto>();
}
private static Order LoadOrder(long id) => new() { Id = id, Number = "SO-1" };
}
需要构造注入时使用 Mapster 的 IMapper:
using MapsterMapper;
public sealed class OrderQueryService(IMapper mapper)
{
public OrderDto Get(Order order) => mapper.Map<Order, OrderDto>(order);
}
注意事项 / 限制
TypeAdapterFactory.SetCurrent是进程级静态状态;同时安装 AutoMapper 与 Mapster 时,最后执行OnApplicationInitialization的模块获胜。MapsterTypeAdapterFactory以键"mapster"注册为键控单例,内部ServiceMapper持有单例TypeAdapterConfig;IMapper是 Scoped。不要在单例中捕获IMapper,否则会触发ValidateScopes失败。AddMapster()在首次解析TypeAdapterConfig时应用MapsterOptions;该单例构建完成后再修改 options 不会重新应用,需重启宿主。- 内置转换只有
byte[]→long;没有long→byte[]的反向映射,需要时自行注册。 ProjectedAs依赖当前工厂;未通过模块初始化或手动调用TypeAdapterFactory.SetCurrent时,CreateAdapter()返回null,扩展方法会失败。AddProfile重载按注册类型去重(TryAdd),同一类型重复注册只保留第一次;AddProfiles(Assembly[])添加的是Scan配置委托,不做去重。- 映射配置在全局
TypeAdapterConfig.GlobalSettings上生效;多个宿主共享同一进程时不要假设配置隔离。
相关包
Euonia.Mapping—— 映射抽象与ProjectedAsEuonia.Mapping.Automapper—— AutoMapper 实现Euonia.Modularity—— 模块与依赖注入
常见问题与故障排查
ProjectedAs 抛 NullReferenceException
扩展方法通过 TypeAdapterFactory.CreateAdapter() 取当前工厂;未执行 MapsterModule.OnApplicationInitialization、未手动 TypeAdapterFactory.SetCurrent(...),或当前工厂被其他映射后端覆盖时,CreateAdapter() 返回 null。确认模块已加载,且初始化顺序在首次投影之前。
MapsterOptions 里注册的 Profile 没有生效
AddMapster() 在首次解析 TypeAdapterConfig 时应用 MapsterOptions;如果在此之前已经解析过 IMapper/TypeAdapterConfig,后续修改 options 不会重新应用。把 services.Configure<MapsterOptions>(...) 放在首次解析之前,或重启宿主。
ValidateScopes 开启后启动失败
键控工厂 MapsterTypeAdapterFactory 依赖作用域的 IMapper,不能按普通单例注册;本包用键 "mapster" 注册键控单例并在内部构造 ServiceMapper。自定义注册时不要把 IMapper 捕获到单例,仓库的 MapsterModuleTests 覆盖了该场景。
AutoMapper 与 Mapster 同时安装后行为不确定
TypeAdapterFactory.SetCurrent 是进程级静态状态,最后执行 OnApplicationInitialization 的模块获胜。一个进程只保留一个当前映射后端;需要并存时使用键控 ITypeAdapterFactory 显式解析,不要依赖全局投影。
config.NewConfig<,>() 没有生效
NewConfig 是 Mapster 原生 API,只有在 IRegister.Register 被应用后才会进入配置。确认 Profile 已通过 AddProfile/AddProfiles(Assembly[]) 注册,且 AddMapster() 在解析映射器前执行;扫描不到的程序集不会自动加载。
最佳实践
- 用
[DependsOn(typeof(MapsterModule))]统一注册,避免手工AddMapster()与SetCurrent顺序不一致。 - 在模块
ConfigureServices中注册 Profile,并确保首次解析IMapper发生在所有MapsterOptions配置之后。 - 业务代码优先使用全局
ProjectedAs;需要构造注入时使用作用域IMapper,不要在单例中缓存。 - 同一进程只选 AutoMapper 或 Mapster 之一作为全局后端;多后端场景显式使用键控工厂。
版本与兼容
- 目标框架:
net10.0、net11.0(Source/common.props)。 - 关键依赖:
Euonia.Mapping、Euonia.Modularity、Mapster/Mapster.DependencyInjection;具体版本由仓库构建属性决定。 - 已知边界:
TypeAdapterConfig.GlobalSettings与TypeAdapterFactory都是进程级静态状态;MapsterOptions只在首次构建配置时应用;内置转换只有byte[]→long。
许可证
本项目依据仓库根目录的 GNU General Public License v3.0 发布。
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. net11.0 is compatible. |
-
net10.0
- Euonia.Core (>= 2026.5.0)
- Euonia.Mapping (>= 2026.5.0)
- Euonia.Modularity (>= 2026.5.0)
- Mapster (>= 10.0.14)
- Mapster.DependencyInjection (>= 10.0.14)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 11.0.0)
- Newtonsoft.Json (>= 13.0.4)
-
net11.0
- Euonia.Core (>= 2026.5.0)
- Euonia.Mapping (>= 2026.5.0)
- Euonia.Modularity (>= 2026.5.0)
- Mapster (>= 10.0.14)
- Mapster.DependencyInjection (>= 10.0.14)
- Newtonsoft.Json (>= 13.0.4)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 2026.5.0 | 87 | 11/13/2026 |
| 2026.4.7 | 120 | 11/3/2026 |
| 2026.4.6 | 182 | 10/28/2026 |
| 2026.4.5 | 110 | 10/19/2026 |
| 2026.4.4 | 106 | 10/19/2026 |
| 2026.4.3 | 147 | 10/1/2026 |
| 2026.4.1 | 114 | 9/24/2026 |
| 2026.4.0 | 114 | 9/22/2026 |
| 2026.3.16 | 166 | 9/8/2026 |
| 2026.3.15 | 167 | 9/2/2026 |
| 2026.3.14 | 148 | 8/30/2026 |
| 2026.3.13 | 129 | 8/29/2026 |
| 2026.3.12 | 139 | 8/28/2026 |
| 2026.3.11 | 130 | 8/27/2026 |
| 2026.3.10 | 141 | 8/26/2026 |
| 2026.3.9 | 145 | 8/25/2026 |
| 2026.3.8 | 134 | 8/24/2026 |
| 2026.3.7 | 130 | 8/20/2026 |
| 2026.3.6 | 137 | 8/20/2026 |
| 2026.3.5 | 133 | 8/19/2026 |