动态编译库 Natasha 5.0 兼容版本发布

2022 年 10 月 10 日
筆記
.NET, c#, Compile, Natasha, Roslyn

Natasha 5.0 版本已于 2022/10/10 日发布, 此次大版本更迭带来了兼容性支持, 目前 Natasha 可以兼容 standard2.0 及 coreapp3.1 以上版本.

下载使用 NuGet\Install-Package DotNetCore.Natasha.CSharp -Version 5.0.0.

引擎分离

该版本分离了编译引擎, Natasha 将根据 <TargetFramework> {NET VERSION} </TargetFramework> 目标版本来适配对外的 API.

单域编译引擎
- 兼容 Standard2.0(Core3.1 以下) 版本, 动态构建将在主域中进行, 您无法体验到多域编程带来的好处, 也无法卸载动态编译输出的程序集.
- 不兼容旧版 Natasha API, 旧版 Natasha 仅支持多域编程, 并提供了多域方面的 API, 而单域引擎是从多域引擎分离简化而来, 它将失去一些非必要的 API.

多域编译引擎
- 兼容 Core3.1 以上版本, 支持程序集卸载, 域功能隔离, 插件加载卸载等操作.
- 兼容旧版 Natasha API, 本次升级保留了多域环境应有的 API, 未做改变, .

代码分离

本次版本在源码层,分为 MultiDomain / Public / SingleDomain 三部分, 并使用自定义宏 MULTI 来区分单/多域, 从工程文件上做兼容隔离允许 Natasha 后续的升级工作不必过多的关注兼容性代码, 多域引擎仍然是 Natasha 未来版本的主战场, 迭代优化工作将在 MultiDomain 文件夹中进行.
相比较有特色的 API {OperatorClass}.DefaultDomain/CreateDomain/RandomDomain/UseDomain 单域版仅有 {OperatorClass}.DefaultDomain 一个 API, 单域引擎的编译结果均加载到主域中, 因此也不具备隔离和卸载功能.

使用须知

编译前提 : 使用字符串脚本需要对编译原理有一定的了解, Roslyn 及 Natasha 简化了复杂的理论依据及构建过程, 使用 Natasha 您只需关注3点:
- 元数据管理, 熟悉 Emit / Expression 的同学应该清楚, 在构建过程中可能用到反射, 比如 propertyInfo / fieldInfo / methodInfo, 因为在编程中只关注使用,而忽视了元数据对动态编译的重要性, 从而切换到字符串编译的时候出现各种各样的问题, Roslyn 和 Natasha 同样是需要元数据的, 而元数据的来源有引用程序集,内存程序集,实际程序集, 除内存程序集外元数据均记录在 DLL 文件中, 因此您可以看到一些构建代码是这样: NatashaManagement.AddGlobalReference("1.dll"); 这一步的缺失可能导致错误: 找不到 RuntimeMetadataVersion 的值。找不到包含 System.Object 的程序集，或未通过选项为 RuntimeMetadataVersion 指定值。, 引用管理对程序来讲是有一定负担的, 因为目前还不能从内存程序集中提取元数据, 所以需要以文件方式来添加, 这也导致你发布动态编译的程序时需要有完备的引用文件跟随, 因此会导致您发布的包体积变大, 至于环境需要哪些引用文件我们交给 DotNetCore.Compile.Environment 环境包来解决, 如果您不能很好的管理引用, 请引入该包全面覆盖当前程序的元数据.
- Using 管理, 这关乎着元数据的引用来源, 任何动态构建都是以一个完整类方式进行, 那么完整的类 using 代码是必不可少的一部分, Natasha 的构建模板可以覆盖大部分 using 并有语义过滤处理异常 using, 如果您直接使用 AssemblyCSharpBuilder 来构建代码则需要注意脚本中的 using 部分.
编译环境 : 编译环境包已不在新版的 Natasha 中,推荐使用 Natasha 的 API NatashaManagement.AddGlobalReference/AddGlobalUsing 来管理全局引用及 Using 缓存, 如果您不能很好管理的元数据引用, 请引入 DotNetCore.Compile.Environment 包来解决元数据引用的问题.
输出环境 : 若您觉得生成文件中有较多的多语言适配, 可以使用 <SatelliteResourceLanguages>en</SatelliteResourceLanguages> 来指定默认的资源语言.
二义性错误 : 该问题仍然被归属到用户的错误编程行为中, 并不该由 IDE 或 Natasha 自动解决, 我仍倾向于在命名空间发生冲突时由用户手动改解决该问题, 上下文语义环境不能百分百推测出用户想使用某个命名空间.目前推荐的三种方法:
- 使用 Natasha.CSharp.Extension.Ambiguity 扩展包及 .Using()/.ConfigUsing() 模板自带的方法指定优先级最高的 Using. (该包将在不久后以独立项目存在,它并不属于 Natasha 项目, 晚于 Natasha5.0 发布)
- 直接使用引擎 AssemblyCSharpBuilder 编译字符串, 在字符串层面替换.
- 自写语义过滤方法, 更新编译单元中的语法树, 使用 Natasha 的语义扩展方法来添加您的过滤方法assemblyCSharpBuilder.AddSemanticAnalysistor(Func<AssemblyCSharpBuilder, CSharpCompilation, CSharpCompilation>) (需要有语法语义相关编程经验).

案例

一个尽可能复杂的案例:

var action = NDelegate

//使用随机域 也可以使用 CreateDomain / UseDomain / DefaultDomain 
//Core3.1以下仅能使用 DefaultDomain
.DefaultDomain()

//[可选API] 必要时使用 ConfigBuilder 配置编译单元(下面只为展示API, 有需求就用, 没需求不用写)
.ConfigBuilder(builder => builder

  //配置编译器选项
 .ConfigCompilerOption(opt => opt
    //配置平台
   .SetPlatform(Microsoft.CodeAnalysis.Platform.AnyCpu)
    //Release 方式编译
   .CompileAsRelease()
    //开启可空警告
   .SetNullableCompile(Microsoft.CodeAnalysis.NullableContextOptions.Warnings))

  //配置语法选项
 .ConfigSyntaxOptions(opt => opt
    //配置支持的脚本语言版本
   .WithLanguageVersion(Microsoft.CodeAnalysis.CSharp.LanguageVersion.CSharp8))

  //禁用语义检查与过滤
 .DisableSemanticCheck()
)

 //[可选API] 配置该方法所在的类模板
.ConfigClass(item => item
   //给类配置一个名字,不用随即名
  .Name("myClass")
   //不使用默认域的 Using 缓存
  .NoGlobalUsing())

 //[可选API] 为类模板添加 using 引用
.ConfigUsing("System")

 //这里的 API 参照定义的委托, 包括委托的参数
 //例如 Action<int> / Func<int,int> 拥有一个参数, 参数的名字请在 Action<int> / Func<int,int> 上 F12 查看定义获取参数名.
.Action("Console.WriteLine(\"Hello World!\");");

action(); /*Output: Hello World!*/

更多案例更多文档

更新日志

2022/09/05 – 2022/09/21
- 分离引擎, 项目分为多域和单域, 以部分类方式合并 API.
- 使用 IndexOf 替代 Contans 方法做兼容.
- 支持 netstandard2.0 及 coreapp3.1,net5.0,net6.0 版本.
- 升级 DotNetCore.SourceLink.Environment 依赖以支持 netstandard2.0/1 版本.
- 升级 DotNetCore.Compile.Environment 依赖以支持 netstandard2.0/1 版本.
2022/09/30 – 2022/10/09
- 使用 Assembly.ReflectionOnlyLoad 替代 MetadataLoadContext 解决单域引擎只读元数据的问题.
- 优化单域引擎初始化过程中扫描源dll文件的问题.

Tags: .NET c# Compile Natasha Roslyn