Exergy 注册表实战：保姆级教程解决代码跑不通
刚把网上抄的 Exergy 注册表代码跑起来，是不是满屏报错？别慌，这种“复制粘贴即崩溃”的情况太常见了。很多教程只给结果，不讲底层逻辑，导致你面对报错完全懵圈。这篇保姆级教程不玩虚的，直接带你从环境配置到核心代码，一步步把坑填平。
咱们先搞清楚，为什么你之前的代码跑不通？大概率是三个原因：版本不匹配、依赖缺失、或者 Exergy 的底层机制没搞懂。Exergy 是 .NET 生态中一个强大的运行时注册表工具，它允许你在编译时和运行时动态注册、发现和调用组件。如果你把 Exergy 当成普通的 IoC 容器来用，大概率会踩坑。它更像是一个“服务发现中心”，强调的是约定优于配置。
项目目标：我们要做什么
在这个实战项目中，我们要搭建一个基于 Exergy 的模块化微服务架构。目标不是造轮子，而是解决三个具体问题：
- 动态插件加载：实现主程序无需重新编译，就能加载新的业务模块。
- 依赖自动注入：通过 Exergy 的特性标记，实现复杂对象的自动组装。
- 健康检查与监控：利用 Exergy 的生命周期钩子，实时监控系统状态。
这个项目适合有 .NET 基础，但被 Exergy 的文档绕晕的开发者。我们会用最直白的方式，把每个步骤拆解清楚。
目录结构：清晰是成功的一半
在动手写代码前，先把项目结构理清楚。混乱的结构是后期调试噩梦的根源。
ExergyDemo/
├── src/
│ ├── Exergy.Core/ # 核心抽象层，定义接口和基础特性
│ ├── Exergy.Modules/ # 业务模块层，包含具体的实现
│ │ ├── UserModule/ # 用户模块
│ │ └── OrderModule/ # 订单模块
│ └── Exergy.Host/ # 宿主项目，负责启动和配置
├── tests/
│ └── Exergy.IntegrationTests/ # 集成测试
└── ExergyDemo.sln
关键点解析：
Exergy.Core必须保持纯净，不要引入任何具体业务逻辑。Exergy.Modules下的每个文件夹就是一个独立的 NuGet 包雏形，方便后续拆分。Exergy.Host是唯一的入口，所有配置和启动逻辑都在这里。
这种分层结构不仅符合 Exergy 的设计哲学，也方便你后续进行模块化测试。
核心代码实现：逐行拆解避坑
这里是重头戏。很多教程在这里就开始跳步，导致读者卡住。我们一步步来。
1. 安装依赖
打开 Exergy.Core 项目，安装官方包。注意版本，Exergy 更新较快，建议锁定稳定版。
dotnet add package Exergy --version 2.0.1
为什么强调版本号？ 因为 Exergy 2.x 和 1.x 的 API 差异巨大，很多网上教程还是 1.x 的写法，直接复制过来必报错。
2. 定义基础特性
在 Exergy.Core 中，我们需要定义一些自定义特性，用于标记组件。
// Exergy.Core/Attributes/ModuleAttribute.cs
using System;namespace Exergy.Core.Attributes
{[AttributeUsage(AttributeTargets.Class)]public class ExergyModuleAttribute : Attribute{public string Name { get; set; }public ExergyModuleAttribute(string name){Name = name;}}
}
这段代码很简单，但务必注意命名空间。Exergy 在反射查找类型时，依赖完整的类型名称。如果命名空间写错，注册表就是空的，这就是你之前代码“能跑但没反应”的原因。
3. 实现模块注册逻辑
这是最容易出错的地方。Exergy 的注册不是简单的 AddSingleton，它有一套扫描机制。
// Exergy.Core/Registrations/ModuleRegistrar.cs
using System;
using System.Linq;
using System.Reflection;
using Exergy.Core.Attributes;namespace Exergy.Core.Registrations
{public static class ModuleRegistrar{public static void RegisterAllModules(ExergyRegistry registry, params Assembly[] assemblies){// 遍历所有程序集foreach (var assembly in assemblies){// 获取所有标记了 [ExergyModule] 的类型var moduleTypes = assembly.GetTypes().Where(t => t.GetCustomAttribute<ExergyModuleAttribute>() != null).ToList();foreach (var type in moduleTypes){// 关键步骤：通过反射实例化并注册var instance = Activator.CreateInstance(type);var attr = (ExergyModuleAttribute)type.GetCustomAttribute<ExergyModuleAttribute>();// 注册到 Exergy 注册表registry.RegisterInstance(attr.Name, instance);}}}}
}
逐行讲解：
assembly.GetTypes()：这是反射的核心，但也是性能瓶颈。在生产环境中，建议只扫描指定的程序集，不要扫描整个 AppDomain。Activator.CreateInstance：这里假设模块是无参构造函数的。如果你的模块有依赖，需要改成注入参数，这部分代码要大幅修改。registry.RegisterInstance：这是 Exergy 的核心 API。它把实例绑定到一个名称上，后续可以通过名称查找。
4. 编写具体模块
现在我们在 UserModule 中实现一个具体的服务。
// Exergy.Modules/UserModule/UserService.cs
using Exergy.Core.Attributes;namespace Exergy.Modules.UserModule
{[ExergyModule("UserService")]public class UserService{public string GetUserName(int id){return $"User_{id}";}}
}
注意，这个类上打了 [ExergyModule("UserService")] 标签。这意味着，当 Exergy 扫描到这个程序集时，它会自动把 UserService 实例注册到注册表中，键名为 "UserService"。
5. 宿主启动配置
在 Exergy.Host 的 Program.cs 中，我们需要初始化 Exergy 并加载模块。
// Exergy.Host/Program.cs
using System;
using System.Reflection;
using Exergy.Core.Registrations;
using Exergy.Modules.UserModule;namespace Exergy.Host
{class Program{static void Main(string[] args){// 1. 创建 Exergy 注册表实例var registry = new ExergyRegistry();// 2. 加载模块// 注意：这里传入的是程序集，不是类型var userAssembly = typeof(UserService).Assembly;ModuleRegistrar.RegisterAllModules(registry, userAssembly);// 3. 从注册表获取服务if (registry.TryGetInstance("UserService", out var userService)){var service = (UserService)userService;Console.WriteLine(service.GetUserName(1));}else{Console.WriteLine("服务未找到！请检查模块是否正确加载。");}}}
}
避坑指南：
TryGetInstance比GetInstance更安全。GetInstance在找不到时会抛异常，而TryGetInstance返回布尔值，适合做优雅降级。- 如果控制台输出“服务未找到”，90% 的原因是
userAssembly没有被正确加载，或者[ExergyModule]特性没打上。
运行与测试：验证你的理解
代码写完别急着跑，先跑测试。Exergy 的动态性使得单元测试变得复杂，我们需要集成测试来验证整个链路。
在 Exergy.IntegrationTests 中，添加一个测试类。
// tests/Exergy.IntegrationTests/ModuleLoadingTests.cs
using System;
using System.Reflection;
using Exergy.Core.Registrations;
using Exergy.Modules.UserModule;
using Xunit;namespace Exergy.IntegrationTests
{public class ModuleLoadingTests{[Fact]public void Can_Load_And_Resolve_UserService(){// Arrangevar registry = new ExergyRegistry();var assembly = typeof(UserService).Assembly;ModuleRegistrar.RegisterAllModules(registry, assembly);// Actvar found = registry.TryGetInstance("UserService", out var instance);// AssertAssert.True(found);Assert.NotNull(instance);var service = Assert.IsType<UserService>(instance);Assert.Equal("User_1", service.GetUserName(1));}}
}
常见报错及解决方案：
| 报错信息 | 原因 | 解决方案 |
|---|---|---|
TypeLoadException |
依赖的 DLL 缺失 | 检查 NuGet 包是否还原成功，清理 bin/obj 文件夹 |
NullReferenceException |
注册表中未找到实例 | 检查 [ExergyModule] 名称是否与查找时的键名一致 |
FileNotFoundException |
程序集未加载 | 确保 Assembly.Load 或引用正确，检查目标框架是否匹配 |
如果测试通过，说明你的核心逻辑没问题。这时候再跑主程序，应该能看到 User_1 的输出。
优化扩展：从玩具到生产
现在的项目能跑，但离生产还有距离。我们需要解决性能和可维护性问题。
1. 缓存反射结果
每次启动都进行全量反射扫描是很慢的。我们可以缓存已扫描的程序集。
private static readonly ConcurrentDictionary<Assembly, List<Type>> _typeCache = new();public static void RegisterAllModules(ExergyRegistry registry, params Assembly[] assemblies)
{foreach (var assembly in assemblies){var types = _typeCache.GetOrAdd(assembly, asm => asm.GetTypes().Where(t => t.GetCustomAttribute<ExergyModuleAttribute>() != null).ToList());// ... 注册逻辑}
}
2. 支持 DI 容器集成
Exergy 可以与其他 DI 容器（如 Microsoft.Extensions.DependencyInjection）协同工作。你可以将 Exergy 注册的实例作为单例注入到 DI 容器中。
services.AddSingleton<UserService>(sp => (UserService)registry.GetInstance("UserService"));
3. 日志与监控
在注册失败时，记录详细的日志。不要吞掉异常，尤其是反射相关的异常，它们通常包含类型名称和程序集信息，这对排查问题至关重要。
小结：掌握核心，举一反三
这篇保姆级教程带你走完了 Exergy 从安装到实战的全过程。核心要点回顾：
- 版本锁定：Exergy 版本迭代快，务必使用稳定版并锁定依赖。
- 特性标记：
[ExergyModule]是连接的桥梁，命名空间和键名必须一致。 - 安全获取：使用
TryGetInstance避免运行时异常。 - 性能优化：缓存反射结果，避免重复扫描。
Exergy 的强大之处在于它的灵活性和低侵入性。它不像 Spring 那样强制你遵循一套庞大的规范，而是让你自己定义规则。这种自由度既是优势，也是挑战。你需要根据自己的业务场景，设计出合理的模块划分和注册策略。
如果你在实际项目中遇到了更复杂的问题，比如跨进程通信、热更新模块等，Exergy 也能提供解决方案，但需要更深入的底层知识。
还有什么不懂的？评论区留言挨个回。特别是那些被 TypeLoadException 折磨过的兄弟，把你的报错信息贴出来，我们一起看怎么破。
