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文件的问题.