Euonia.Mapping.Automapper
2026.5.0
dotnet add package Euonia.Mapping.Automapper --version 2026.5.0
NuGet\Install-Package Euonia.Mapping.Automapper -Version 2026.5.0
<PackageReference Include="Euonia.Mapping.Automapper" Version="2026.5.0" />
<PackageVersion Include="Euonia.Mapping.Automapper" Version="2026.5.0" />
<PackageReference Include="Euonia.Mapping.Automapper" />
paket add Euonia.Mapping.Automapper --version 2026.5.0
#r "nuget: Euonia.Mapping.Automapper, 2026.5.0"
#:package Euonia.Mapping.Automapper@2026.5.0
#addin nuget:?package=Euonia.Mapping.Automapper&version=2026.5.0
#tool nuget:?package=Euonia.Mapping.Automapper&version=2026.5.0
Euonia.Mapping.Automapper
Euonia 对象映射的 AutoMapper 实现:将 IMapper 适配为 ITypeAdapter,并通过 AutomapperModule 在模块初始化时设为当前映射工厂。
- 目标框架:
net10.0、net11.0 - 根命名空间:
Nerosoft.Euonia.Mapping - NuGet 包:
Euonia.Mapping.Automapper
安装
dotnet add package Euonia.Mapping.Automapper
主要功能
- 映射工厂:
AutomapperTypeAdapterFactory实现ITypeAdapterFactory。 - 模块集成:
AutomapperModule注册 AutoMapper 服务,并在应用初始化时调用TypeAdapterFactory.SetCurrent。 - Profile 管理:
AutomapperOptions.AddMaps、AddProfile注册并校验 Profile。 - 键控注册:以键
"automapper"注册ITypeAdapterFactory,可与 Mapster 并存。 - 配置校验:
assertConfiguration控制是否在构建前断言配置有效。
快速开始
using Nerosoft.Euonia.Mapping;
using Nerosoft.Euonia.Modularity;
[DependsOn(typeof(AutomapperModule))]
public sealed class ApplicationModule : ModuleContextBase
{
public override void ConfigureServices(ServiceConfigurationContext context)
{
context.Services.Configure<AutomapperOptions>(options =>
{
options.AddMaps(typeof(ApplicationModule).Assembly, validate: true);
});
}
}
定义 Profile:
using AutoMapper;
public sealed class OrderProfile : Profile
{
public OrderProfile()
{
CreateMap<Order, OrderDto>();
CreateMap<OrderLine, OrderLineDto>();
}
}
投影:
var dto = order.ProjectedAs<OrderDto>();
不使用模块时手动注册:
using AutoMapper;
using Nerosoft.Euonia.Mapping;
services.Configure<AutomapperOptions>(options =>
{
options.AddMaps(typeof(Program).Assembly);
});
services.AddAutomapper();
var mapper = serviceProvider.GetRequiredService<IMapper>();
TypeAdapterFactory.SetCurrent(new AutomapperTypeAdapterFactory(mapper));
AddAutomapper()只注册IMapper;键控工厂ITypeAdapterFactory(键"automapper")由AutomapperModule负责注册。
核心类型
| 类型 | 作用 |
|---|---|
AutomapperModule |
注册 AutoMapper 并设置当前工厂 |
AutomapperTypeAdapterFactory / AutomapperTypeAdapter |
ITypeAdapterFactory / ITypeAdapter 实现 |
AutomapperOptions |
Profile 与配置注册 |
AddAutomapper(...) |
注册 IMapper(键控工厂由模块注册) |
选项(代码配置)
Euonia.Mapping.Automapper 没有配置节或 *Options 配置绑定;AutomapperOptions 是纯代码配置对象:
| 配置点 | 说明 |
|---|---|
AutomapperOptions.AddMaps(Assembly, bool validate = false) |
添加程序集中的 Profile;validate 为 true 时把 Profile 类型加入校验列表 |
AutomapperOptions.AddProfile<TProfile>(bool validate = false) |
添加 Profile 类型,要求 TProfile : Profile, new() |
AutomapperOptions.AddProfile<TProfile>(TProfile profile, bool validate = false) |
添加 Profile 实例,适用于没有无参构造函数的 Profile |
AutomapperOptions.AddProfile(Type profileType, bool validate = false) |
按类型添加 Profile |
AutomapperOptions.AddProfile(ICollection<Type> profileTypes, bool validate = false) |
批量添加;null、空集合或全 null 时直接返回 |
AutomapperOptions.Configure(Action<IServiceProvider, MapperConfigurationExpression>) |
追加自定义映射配置委托 |
AddAutomapper(..., bool assertConfiguration = false) |
构建映射器时是否立即执行 AssertConfigurationIsValid() |
注意事项 / 限制
AutomapperOptions在解析IMapper时读取;必须在首次解析之前完成services.Configure<AutomapperOptions>(...),之后再修改不会影响已创建的映射器。AddAutomapper()注册的是IMapper单例;键为"automapper"的ITypeAdapterFactory由AutomapperModule注册。手动装配时还需要调用TypeAdapterFactory.SetCurrent(...),否则ProjectedAs会得到null适配器并抛出NullReferenceException。AutomapperModule调用的是无参AddAutomapper(),只应用AutomapperOptions中累积的配置;没有配置任何AddMaps/AddProfile时,映射器没有任何 Profile。AddProfile<TProfile>(bool validate = false)约束new();Profile 没有无参构造函数时改用实例重载或AddProfile(Type)。AddProfile(ICollection<Type>)对null、空集合或全null集合静默返回;集合中的null项会被跳过。ProjectedAs/ProjectedAsCollection定义在全局命名空间的Extensions类中,不需要using Nerosoft.Euonia.Mapping;;TypeAdapterFactory、ITypeAdapter、ITypeAdapterFactory才在Nerosoft.Euonia.Mapping命名空间。validate: true只是把 Profile 加入校验列表;真正的AssertConfigurationIsValid()在映射器构建阶段执行,配置错误会在首次解析IMapper时暴露。
常见问题与故障排查
ProjectedAs 抛 NullReferenceException
原因:ProjectedAs 通过全局 TypeAdapterFactory.CreateAdapter() 取适配器;没有调用 TypeAdapterFactory.SetCurrent(...)(模块未初始化或手动装配漏了这一步)时返回 null,随后调用 Adapt 触发空引用。
解决:模块化应用确认 [DependsOn(typeof(AutomapperModule))] 且应用已初始化;手动装配在解析 IMapper 后调用 TypeAdapterFactory.SetCurrent(new AutomapperTypeAdapterFactory(mapper))。
Profile 没注册,映射时抛 AutoMapper 配置异常
原因:AutomapperModule 调用无参 AddAutomapper(),只应用 AutomapperOptions 中累积的 AddMaps/AddProfile;没有配置任何 Profile 时,IMapper 没有任何映射。
解决:在解析 IMapper 之前配置 services.Configure<AutomapperOptions>(options => options.AddMaps(typeof(Program).Assembly));确认 Profile 在扫描程序集内且不是抽象/泛型类型。
validate: true 没有在启动时报配置错误
原因:AddMaps(..., validate: true) / AddProfile(..., validate: true) 只把 Profile 加入校验列表;真正的 AssertConfigurationIsValid() 在 IMapper 构建阶段执行,而 AddAutomapper() 的映射器是首次解析时才创建。
解决:在启动冒烟测试中显式 provider.GetRequiredService<IMapper>();或使用带 assertConfiguration: true 的 AddAutomapper 重载,让构建时立即断言。
找不到 ProjectedAs 或 AddAutomapper
原因:ProjectedAs/ProjectedAsCollection 在全局命名空间的 Extensions 类中,不在 Nerosoft.Euonia.Mapping;AddAutomapper 是 Microsoft.Extensions.DependencyInjection 的扩展方法。
解决:ProjectedAs 不需要额外 using;AddAutomapper 确保引入 Microsoft.Extensions.DependencyInjection;AutomapperOptions、TypeAdapterFactory 才需要 using Nerosoft.Euonia.Mapping;。
最佳实践
- 在首次解析
IMapper前完成AutomapperOptions配置;模块化应用把配置放在依赖AutomapperModule的模块里,避免顺序问题。 - 启动时解析一次
IMapper并开启validate: true/assertConfiguration: true,把映射配置错误挡在启动阶段。 - Profile 按聚合/场景拆分并放在应用程序集,统一
AddMaps(assembly);不要同时手工AddProfile同一类型造成重复配置。 - 需要与 Mapster 并存时保留
"automapper"键控ITypeAdapterFactory(模块已注册);手动装配时按相同键注册并设置当前工厂。
版本与兼容
- 目标框架:
net10.0、net11.0;包版本由仓库根project.props统一管理(当前2026.5.0)。 - 关键依赖:AutoMapper 17.0.0、Newtonsoft.Json 13.0.4(由
Directory.Packages.props锁定);AutomapperOptions为纯代码配置。 - 已知边界:
ProjectedAs在全局命名空间;AutomapperModule注册IMapper与键控工厂,并在初始化时设置当前工厂;配置校验延迟到映射器构建。 - 升级提示:升级 AutoMapper 后复核 Profile 注册方式、
MapperConfigurationExpressionAPI 与AssertConfigurationIsValid行为。
相关包
Euonia.Mapping—— 映射抽象Euonia.Mapping.Mapster—— Mapster 实现Euonia.Modularity—— 模块与依赖注入
许可证
本项目依据仓库根目录的 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
- AutoMapper (>= 17.0.0)
- Euonia.Core (>= 2026.5.0)
- Euonia.Mapping (>= 2026.5.0)
- Euonia.Modularity (>= 2026.5.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 11.0.0)
- Newtonsoft.Json (>= 13.0.4)
-
net11.0
- AutoMapper (>= 17.0.0)
- Euonia.Core (>= 2026.5.0)
- Euonia.Mapping (>= 2026.5.0)
- Euonia.Modularity (>= 2026.5.0)
- 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 | 180 | 11/13/2026 |
| 2026.4.7 | 122 | 11/3/2026 |
| 2026.4.6 | 115 | 10/28/2026 |
| 2026.4.5 | 173 | 10/19/2026 |
| 2026.4.4 | 112 | 10/19/2026 |
| 2026.4.3 | 140 | 10/1/2026 |
| 2026.4.1 | 125 | 9/24/2026 |
| 2026.4.0 | 123 | 9/22/2026 |
| 2026.3.16 | 156 | 9/8/2026 |
| 2026.3.15 | 135 | 9/2/2026 |
| 2026.3.14 | 148 | 8/30/2026 |
| 2026.3.13 | 136 | 8/29/2026 |
| 2026.3.12 | 135 | 8/28/2026 |
| 2026.3.11 | 132 | 8/27/2026 |
| 2026.3.10 | 132 | 8/26/2026 |
| 2026.3.9 | 141 | 8/25/2026 |
| 2026.3.8 | 134 | 8/24/2026 |
| 2026.3.7 | 147 | 8/20/2026 |
| 2026.3.6 | 138 | 8/20/2026 |
| 2026.3.5 | 144 | 8/19/2026 |