C# 动态编译与热更新：Roslyn 实现插件化系统实战解析

简介：这是一份面向.NET开发者、以C#动态加载与动态编译为核心的实例源码包，适用于插件系统、模块化应用、元编程等需要运行时按需加载和执行代码的场景。压缩包内共18个文件，包括8个.cs源码文件、项目工程文件（csproj/sln）、界面资源（resx/ico）以及一个可直接运行的exe演示程序，整体大小仅82KB。源码完整展示了如何通过Assembly.LoadFrom加载外部程序集，以及使用CSharpCodeProvider从字符串动态编译C#代码并反射调用目标方法的思路，并借助WinForm窗体提供可操作的演示界面。示例中还包括动态程序集的错误处理、引用添加等细节，便于理解运行时编译的完整流程。目前已有396人学习该资源，适合正在研究反射、动态代码生成或希望搭建轻量级扩展机制的中高级C#开发者参考。

1. 动态加载不是玄学：一次编译、随时替换的C#插件机制

C# 动态加载代码这事，很多项目用得比想象中保守。做业务系统最怕的不是需求变，而是每次改一个 if 条件都要重新发版。某开发者在维护计费系统时遇到过这样的场景：规则引擎里十几个税率节点，销售说某行业税率明天要调，按常规流程要测试、打包、发版，等审批跑完业务已经投诉了。后来他把规则整体改成 C# 动态编译加载——代码以字符串存在数据库里，业务人员改完保存，系统运行时把源码编译成程序集加载进内存，下一次调用立即生效，全程不用停服。这个实例源码拆的正是这条链路：字符串怎么变成程序集、怎么在运行时替换与卸载、做插件系统时的架构取舍和避坑记录。适合正在做规则引擎、报表平台、脚本化配置这类需要热更新能力的开发者，C# 基础过关就能跟读。

2. 技术选型与工程结构：三条动态加载路线为什么选了Roslyn

2.1 三条路线盘点：反射、独立进程与运行时编译

动态加载在 C# 里其实有三条路，很多人一上来就反射拉满，反而把问题搞复杂了。

第一条是反射加载已编译好的程序集。插件打成 dll 放到约定目录，主程序用 Assembly.LoadFile 或 LoadFrom 读进来，再用 Type.GetType 或 GetTypes 找类型。这条路适合插件市场、模块化单体——插件提前编译好，主程序只负责发现和调用。缺点也很直接：改插件逻辑仍然要先编译发布，并没有解决“改逻辑不发版”的问题。

第二条是独立进程。脚本逻辑放在单独进程里，用 gRPC、命名管道或 HTTP 通信。隔离性最强，进程崩了不影响宿主，也能随便杀。但跨进程通信要序列化、要定协议，一个内部规则引擎这么干明显太重了。

第三条是本项目的核心：运行时编译。用 Roslyn 的 CSharpScript 或 CSharpCompilation 把字符串形式的源码当场编译成内存程序集，再用 Assembly.Load 或 AssemblyLoadContext 加载进当前进程。源码放数据库、配置文件或者监控目录，改完保存即编译加载，宿主不用重启。这也是“动态加载”和“动态编译”两个关键词会同时出现在项目里的原因——加载只是后半段，前半段是编译。

三条路对比下来，反射路线最容易被低估。很多人觉得反射就是动态加载，其实反射解决的是“dll 已知、类型结构未知”的发现问题，它能在运行时遍历程序集的类型清单，但要执行一段新逻辑做不到——逻辑无论如何变化，都要先编译出 dll 才能被反射到。独立进程方案则把问题推给了进程边界，换来强隔离，代价是通信协议和序列化全是额外工程量。只有 Roslyn 运行时编译能做到“源码即逻辑”，把编译这个本属于构建期的事挪到了运行期。

.NET Framework 时代还有个 CodeDomProvider 可以做动态编译，但那套 API 已经停止演进，.NET Core 和 .NET 5+ 上官方统一走 Roslyn 管线。实例源码里用的 CSharpCompilation 就是 Roslyn 的公开编译入口，后续所有编译能力都围绕它展开。

2.2 工程目录与依赖准备：一个宿主加一个脚本目录

项目本身不复杂，落地结构推荐这样：

DynamicLoadDemo/ ├── src/ │ ├── HostApp/ # 宿主控制台程序 │ │ ├── Program.cs # 入口，负责装配 │ │ ├── ScriptEngine.cs # 编译 + 加载封装 │ │ ├── ScriptHost.cs # 插件生命周期管理 │ │ └── Contracts/ │ │ └── ICalcPlugin.cs # 插件约定接口 │ ├── Scripts/ # 脚本目录，Demo 用文件，生产可换数据库 │ │ └── tax_rule.csx # 示例税率脚本 │ └── DynamicLoadDemo.sln

宿主项目需要引两个 NuGet 包：Microsoft.CodeAnalysis.CSharp.Scripting 和 Microsoft.CodeAnalysis.CSharp。前者提供 CSharpScript 快捷 API，适合“执行一段代码拿结果”；后者暴露完整的编译管线，适合编译成程序集再走加载流程。Scripting 包底层依赖编译包，只引 Scripting 也能编译，但想拿到 Emit 结果、控制编译过程时，还是要显式引用编译包。

脚本目录里的 tax_rule.csx 是 Roslyn 脚本后缀，但宿主真正读取的是文件内容字符串，后缀名不参与逻辑。脚本内容长这样：

using System; using HostApp.Contracts; namespace DynamicRules { public class TaxRule : ICalcPlugin { public string PluginName => "default-tax"; public decimal Calculate(OrderContext order) { // 示例税率：按金额 4% 计算，业务侧改这里就行 return order.Amount * 0.04m; } } }

脚本里用 using 引入宿主契约命名空间，实现类签名必须和 ICalcPlugin 严格一致，否则编译阶段就会报错。这个“编译期强约束”正是接口方案相比纯反射的最大价值——错误在编译期暴露，而不是等运行到那一行才炸。

生产环境我通常会再进一步：把脚本内容从文件挪进数据库表，字段就三个——脚本标识、语言版本、源码文本，再配 updated_at 做版本判断。文件系统在单机部署没问题，集群环境每台机器同步脚本目录容易出“这台新版、那台旧版”的诡异事故。脚本入库后，分布式部署不依赖文件系统，脚本分发和回滚全走数据库事务。

提示：脚本入库的改造方向在第五章会给出可落地的做法，示例源码里保持文件系统是为了让首跑成本最低，拿到就改、改完就生效。

3. 核心模块拆解：源码字符串从编译进入内存到被调用的完整链路

3.1 最小可运行版本：CSharpScript 三行代码执行字符串

先看最小闭环。CSharpScript 把编译、加载、执行三步合并成两步，入门最快：

using Microsoft.CodeAnalysis.CSharp.Scripting; using Microsoft.CodeAnalysis.Scripting; var code = @" int Add(int a, int b) => a + b; return Add(20, 22); "; var script = CSharpScript.Create<int>(code, ScriptOptions.Default .WithReferences(typeof(Math).Assembly) .WithImports("System", "System.Linq")); script.Compile(); var result = await script.RunAsync(); Console.WriteLine(result.ReturnValue); // 输出 42

逻辑很直白：Create 声明脚本最终返回 int 类型，ScriptOptions 负责给脚本准备引用和 using 上下文，Compile 只编译不执行，RunAsync 才真正运行。ReturnValue 是脚本 return 出来的值。参数上两个关键：WithReferences 决定脚本里能访问哪些程序集的类型，漏了会编译阶段报 CS0246；WithImports 相当于脚本头部预置 using，脚本内部不用重复写。

这段代码有两个局限。第一，它只适合“跑一段代码拿个值”的场景，拿不到脚本里定义的类实例，也没法维持多次调用的状态。第二，ScriptOptions 默认引用是基类库，脚本要访问宿主自定义类型的话，得显式把宿主程序集加进去。规则引擎如果只是算个数值，用这个足够了；要定义类、有状态、被宿主反复调用，就得用下一节的编译管线。

3.2 编译成程序集：CSharpCompilation 的编译过程

规则脚本需要“定义类、宿主按接口调用”，就要用 CSharpCompilation 把源码编成程序集。这段是动态编译的核心，也是容易写跑偏的部分：

using Microsoft.CodeAnalysis; using Microsoft.CodeAnalysis.CSharp; using System.Reflection; public static Assembly CompileFromSource(string sourceCode) { // 1. 字符串解析成语法树 var syntaxTree = CSharpSyntaxTree.ParseText(sourceCode, new CSharpParseOptions(LanguageVersion.Latest)); // 2. 收集宿主进程里所有非动态程序集作为引用 var references = AppDomain.CurrentDomain.GetAssemblies() .Where(a => !a.IsDynamic) .Select(a => MetadataReference.CreateFromFile(a.Location)) .Cast<MetadataReference>() .ToList(); // 3. 创建编译单元，输出类库 var compilation = CSharpCompilation.Create( "DynamicGen_" + Guid.NewGuid().ToString("N"), new[] { syntaxTree }, references, new CSharpCompilationOptions(OutputKind.DynamicallyLinkedLibrary)); // 4. Emit 到内存流 using var ms = new MemoryStream(); var emitResult = compilation.Emit(ms); // 5. 编译失败时收集诊断信息 if (!emitResult.Success) { var errors = string.Join("\r\n", emitResult.Diagnostics .Where(d => d.Severity == DiagnosticSeverity.Error) .Select(d => d.ToString())); throw new InvalidOperationException("脚本编译失败:\r\n" + errors); } ms.Seek(0, SeekOrigin.Begin); // 6. 从内存加载程序集，不落盘 return Assembly.Load(ms.ToArray()); }

这段拆成六个阶段。ParseText 把字符串变成语法树，这步只做“分词定性”，不检查语义；收集引用时用 AppDomain.CurrentDomain.GetAssemblies() 是省事但好用的做法——进程已加载的程序集大概率都是脚本要用的，不用手写一长串路径。注意过滤 IsDynamic，动态程序集没有 Location，强转会抛异常。

CSharpCompilation.Create 的程序集名带 Guid 后缀，是为了避免同名程序集导致的加载歧义，这个点跟缓存的关联在避坑章节细说。Emit 到 MemoryStream 意味着编译产物只在内存里，进程重启即失效，正好符合“脚本源在库、程序集按需生成”的定位。emitResult.Diagnostics 里有错误也有警告，项目里只处理 Error 级别，警告留给日志慢慢看。

拿到 Assembly 后就是实例化脚本里的类。约定脚本里必须有一个公开类实现宿主接口，然后用 GetType 按全名取类型：

var assembly = CompileFromSource(scriptCode); var type = assembly.GetType("DynamicRules.TaxRule"); var plugin = (ICalcPlugin)Activator.CreateInstance(type); var result = plugin.Calculate(order);

GetType 参数是类型全名，含命名空间。这个约定必须写进脚本规范，因为编译出的程序集没有强类型引用关系，全靠命名约定对齐。改类型名而不改全名是新手最常犯的错，运行时报的是 null 引用而不是“找不到类型”，排起来很迷惑。

3.3 可卸载的载体：AssemblyLoadContext 替代 Assembly.Load

Assembly.Load 有个硬伤：加载进来的程序集不能卸载，除非进程退出。热更新场景下每次改逻辑就往进程塞一个新程序集，旧的永远占着内存和已加载列表，几轮迭代内存就涨上去了。AssemblyLoadContext（ALC）提供了真正可卸载的加载上下文：

using System.Runtime.Loader; public class CollectibleContext : AssemblyLoadContext { // isCollectible: true 表示这个上下文里的程序集可整体卸载 public CollectibleContext() : base(isCollectible: true) { } // 返回 null，让默认解析逻辑继续查宿主目录和依赖目录 protected override Assembly Load(AssemblyName assemblyName) => null; }

使用侧把 Assembly.Load 换成 context.LoadFromStream：

var context = new CollectibleContext(); try { ms.Seek(0, SeekOrigin.Begin); var assembly = context.LoadFromStream(ms); // 从内存流加载 var type = assembly.GetType("DynamicRules.TaxRule"); var plugin = (ICalcPlugin)Activator.CreateInstance(type); var result = plugin.Calculate(order); // 业务调用 } finally { context.Unload(); // 用完整段卸载 }

三点认知要记住。第一，ALC 的隔离粒度是“上下文”而不是“程序集”，一个 ALC 里可以放多个程序集，Unload 是一锅端。第二，ALC 卸载不是杀进程那么干净，要求上下文里所有对象引用都释放——plugin 实例一旦被存进静态字典，Unload 就会静默失败。第三，Load 方法返回 null 是让默认策略负责解析依赖，你想让动态程序集绑定某个固定版本的依赖，就在 Load 里接管返回对应 Assembly。

注意：ALC 的 Unload 是异步回收，调用后立刻判断程序集是否已释放不可靠，要以插件内部弱引用的 IsAlive 状态为准，排查章节会给验证写法。

3.4 调用约定：用接口抽象代替反射裸调

程序集加载完，调用方式决定代码质量和性能。最差的做法是全程反射：GetType 拿类型，再 GetMethod 拿方法，再 Invoke 传参——每层都是字符串，IDE 帮不上忙，方法参数一变动所有调用点全部静默损坏。项目里的做法是定义公共契约接口，编译进宿主程序集，脚本项目引用它：

namespace HostApp.Contracts { public interface ICalcPlugin { string PluginName { get; } decimal Calculate(OrderContext context); } }

脚本编译时引用宿主程序集里的接口，Activator.CreateInstance 出来的对象直接强转 ICalcPlugin。强转失败说明脚本没实现接口，抛出的类型转换异常一眼能定位，比反射的 TargetInvocationException 清晰得多。

接口方案还白赚一个能力：编译器在脚本编译阶段就能校验类型。脚本里 Calculate 的签名和接口不一致，CSharpCompilation 的 Emit 阶段直接报“类未实现接口成员”，错误信息定位到脚本源码行号——等于把运行时的黑匣子前移到了编译期。这也是避坑章节反复强调的原则：动态加载这条链路，宁可编译失败也不要运行时爆炸。

4. 避坑指南：动态加载最常见的五个坑与排查记录

动态编译加载这条路，网上源码不少，但真正跑起来版本冲突、程序集锁、卸载失败这些坑一个比一个隐蔽。下面五个问题都是实盘踩过的，按“现象 — 原因 — 解决”记录，照着实盘能省半天调试时间。

4.1 坑一：文件被锁定，脚本改了保存不了

现象：脚本目录里的 .csx 文件编译成功后，编辑保存时提示“文件正在被另一进程使用”。更隐蔽的情况是文件能保存，但编译用的还是旧内容。

原因：Assembly.LoadFrom 这类 API 默认把程序集文件映射进加载上下文，shadow copy 没开时文件句柄被进程持有，宿主不退出文件就锁着。

解决：编译产物改走 MemoryStream，文件只被 File.ReadAllText 读一次内容，不持有句柄。如果必须加载外部 dll，用 Assembly.LoadFile 读入后立即把文件拷走做备份，绝不能让运行中的进程占着源文件。改造后脚本目录怎么改都不再和进程抢锁。

4.2 坑二：改完源码结果没变，重启才生效

现象：脚本文件改完保存，日志出现“重新编译”，但计算结果还是老逻辑。

原因：缓存 key 设计不对。按脚本文件名做 key，内容变了但变更事件被合并丢掉，或者新旧编译结果在字典里哈希冲突被覆盖。FileSystemWatcher 的 Changed 事件本身会连续触发多次，没做去重时最后一次事件可能带着旧内容重新编译。

解决：缓存 key 改成“文件名 + 文件内容 SHA256 + 文件大小”，内容变哈希必变。监听事件加 500ms 合并窗口。替换缓存区的顺序是“先编译成功再 swap 引用”，编译失败保留旧版本，坏脚本打不垮线上逻辑。

4.3 坑三：编译成功，运行时报找不到程序集

现象：脚本引用了第三方库，宿主项目里也有同名不同版本。编译用的是引用列表里第一个，运行时加载的是另一个，抛 FileLoadException 或者 MissingMethodException。

原因：AppDomain.CurrentDomain.GetAssemblies() 把进程已加载的同名程序集都收集了，Roslyn 取第一个，运行时绑定按默认探测逻辑走，两边不一样。

解决：引用收集改成显式列表。项目里用一个 StaticReferences 静态类把宿主程序集、核心依赖路径列死，脚本要用的第三方库统一放 PluginDeps 目录，编译时只加这个目录的文件。依赖关系可审计，不再取决于进程加载顺序这种玄学。

4.4 坑四：Unload 之后内存还在涨，卸载假成功

现象：调用 context.Unload() 后 GC 不回收，内存持续上涨；插件实例居然还能访问、还能出结果。

原因：ALC 卸载要求上下文内对象引用全部释放，包括静态字段、静态事件、未释放的 Timer。实例里有个插件往静态事件总线挂了事件，那点引用没清，Unload 就是假操作。

解决：卸载前把静态引用全部置空。封装一个 TryUnload：先触达插件级别 Dispose，清空静态字典和事件，然后调 Unload()，最后用三连 GC 催促回收。验证是否真卸载，给插件塞一个内部 WeakReference，Unload 后隔几秒看 IsAlive 是否变成 false。

4.5 坑五：宿主内部类型全暴露给脚本，安全边界失守

现象：脚本里能 new 出宿主内部服务类，能直接读数据库上下文。一次误操作把线上配置改崩了，才发现脚本权限和宿主权限没有区分。

原因：编译引用把宿主所有程序集都传给了编译器，脚本想访问什么类型就访问什么，编译期没有任何阻拦。

解决：给脚本编译单独建最小引用集——只包含契约接口程序集和公开上下文对象程序集，宿主内部实现类不进引用列表。运行期再加一层壳子：脚本实例统一通过封装壳调用，壳里拦截不允许访问的成员。编译时少给引用，运行时少给对象，双重收紧。

5. 实战改造：做一个支持热更新的税率计算插件

前面把编译、加载、调用拆开了，这一章组装成可落地的热更新插件：启动加载脚本，文件变化自动重新编译切换，调用方无感知。按代码顺序讲。

5.1 定义契约：从 ICalcPlugin 到数据载体

热更新的核心是契约稳定。接口设计时就要决定哪些对象进出插件，进出对象的字段只能增不能删，否则历史脚本编译不过。税率计算场景，进出对象收敛成两个类型：

namespace HostApp.Contracts { public class OrderContext { public string OrderNo { get; set; } public decimal Amount { get; set; } public string Industry { get; set; } public DateTime OrderTime { get; set; } } public interface ICalcPlugin { string PluginName { get; } decimal Calculate(OrderContext order); } }

OrderContext 做成专用数据载体，而不是直接传业务领域实体。原因很简单：动态脚本和宿主之间要保持弱耦合，把领域实体传给脚本等于把整个实体依赖图暴露出去，实体字段一改名，线上脚本全部爆。数据载体是一次拷贝，多了映射开销，但换来契约边界清晰——脚本作者只知道 OrderContext 上有哪些字段，根本感知不到宿主内部结构。

5.2 热更新工作流：监听、编译、替换三步走

热更新的核心理念：编译发生在后台，生效发生在编译成功之后。文件系统事件里绝不能同步编译，编译几十到几百毫秒的耗时会把文件系统线程池和业务线程拖死。流程组织如下：

public class ScriptHost { private readonly Dictionary<string, ICalcPlugin> _plugins = new(); private readonly object _gate = new(); private DateTime _lastEventTime = DateTime.MinValue; public void StartWatching(string scriptDir) { var watcher = new FileSystemWatcher(scriptDir, "*.csx") { EnableRaisingEvents = true, NotifyFilter = NotifyFilters.LastWrite | NotifyFilters.Size }; watcher.Changed += OnScriptChanged; } private async void OnScriptChanged(object sender, FileSystemEventArgs e) { // 合并短时间内的重复事件，避免触发三五次 lock (_gate) { if (DateTime.UtcNow - _lastEventTime < TimeSpan.FromMilliseconds(500)) return; _lastEventTime = DateTime.UtcNow; } await Task.Run(() => ReloadPlugin(e.FullPath)); } private void ReloadPlugin(string path) { var source = File.ReadAllText(path); var assembly = ScriptEngine.CompileFromSource(source); // 编译失败这里就抛了 var type = assembly.GetType("DynamicRules.TaxRule"); var newPlugin = (ICalcPlugin)Activator.CreateInstance(type); lock (_gate) { _plugins[path] = newPlugin; // 编译成功才替换 } } public ICalcPlugin GetPlugin(string scriptPath) { lock (_gate) { return _plugins[scriptPath]; } } }

这段代码覆盖了五个细节：FileSystemWatcher 只监听 LastWrite 和 Size 变化，减少误触发；500ms 合并窗口消化 Changed 事件连续抖动；ReloadPlugin 放进 Task.Run，不阻塞请求线程；最关键是“先编译新插件成功，再锁内替换引用”——编译失败抛异常后，_plugins 里还是旧对象，线上逻辑不中断。GetPlugin 每次加锁取当前版本，调用方拿到的永远是最近一次成功编译的实例。

5.3 上下文传递：脚本怎么访问宿主服务

插件真正跑起来还差一环：脚本如何访问日志、配置中心、数据库连接这些宿主服务。直接把宿主服务塞进静态类是最省事但最危险的做法，脚本能直接操控宿主生命周期。实用做法是构造 PluginContext 传入，脚本只通过这个唯一入口拿服务：

public class PluginContext { private readonly Dictionary<Type, object> _services; public PluginContext(Dictionary<Type, object> services) => _services = services; public TService GetService<TService>() where TService : class { if (_services.TryGetValue(typeof(TService), out var service)) return (TService)service; throw new InvalidOperationException($"服务未注册: {typeof(TService).Name}"); } }

脚本实现类接收 PluginContext，实例化时代入：

public class TaxRule : ICalcPlugin { private readonly PluginContext _ctx; public TaxRule(PluginContext ctx) => _ctx = ctx; public decimal Calculate(OrderContext order) { var provider = _ctx.GetService<ITaxConfigProvider>(); var rate = provider.GetByIndustry(order.Industry).Rate; return order.Amount * rate; } }

宿主创建插件实例时，优先找接受 PluginContext 的构造函数，找不到再退回无参构造：

var ctor = type.GetConstructor(new[] { typeof(PluginContext) }); var plugin = ctor != null ? (ICalcPlugin)ctor.Invoke(new object[] { pluginContext }) : (ICalcPlugin)Activator.CreateInstance(type);

这样老脚本没有上下文依赖也能兼容运行。编译引用里只放 PluginContext 和契约接口程序集，脚本看不到任何宿主内部服务。“编译时少给引用、运行时少给对象”这条安全策略，在热更新链路里彻底落地。

6. 二次开发思路：把动态加载改装成通用脚本引擎脚手架

如果打算拿这份源码做二次开发，第一件事不是加功能，而是先把“契约稳定”写进项目文档。接口字段的增删要评估线上脚本的兼容性，脚本仓库的版本管理要跟上。我开始做的时候没在意，一次把 OrderContext 里一个字段名改掉，线上六个脚本全部编译失败，好在“编译失败不替换引用”的设计兜住了线上逻辑。从那以后，脚本契约任何变更都强制走“先加新字段、老字段标记过时、下个版本再删”的节奏。

改造方向给三个具体建议。第一，脚本分发渠道从文件系统换成数据库加版本号。文件系统单机没问题，集群环境每台机器同步脚本目录容易版本漂移。数据库存脚本源，用 updated_at 做增量拉取，主机定时轮询版本号，版本不同才重编译，脚本变更天然具备事务性和回滚能力。第二，编译器从 CSharpCompilation 升级到 Roslyn Workspace。现在的直接编译够用，但要做语法高亮、错误提示、代码补全这些编辑器体验时，要用 Workspace 和 Document 把脚本当作正式工程管理，编译缓存和增量编译可以借用 Roslyn 内部机制，不用自己造轮子。第三，给脚本加运行时沙箱。目前是编译期控制引用集、运行期控制上下文，但脚本本质是字符串变成可执行代码，恶意脚本依然能碰文件系统。成熟做法是把插件放进独立 ALC，再限制文件 IO 和反射调用，高危脚本干脆丢到独立进程，宿主只通过契约接口拿结果。

最后是验证习惯。动态加载的改动不像普通代码跑一次单测就完，它涉及编译、加载、卸载三个生命周期。从那以后我每次改脚本引擎都强制走一遍冒烟流程：修一个故意写错语法的脚本，确认编译失败且旧插件还在；修一个正常的脚本，确认新逻辑生效；连续改十次脚本，确认内存没涨；调用 Unload 后确认 WeakReference 变成死引用。四个验证跑通再谈上线。希望帮到你。

本文还有配套的精品资源，点击获取