Natasha 编译单元

Posted 2023-04-24 摧残一生 涅槃重生

AssemblyCSharpBuilder

• 最基本编译单元，涵盖了编译流程所需的基本功能，包括创建域，加载dll文件，创建各种类，输出路径更换，调用特定域中的方法等。

• Natasha有两种方式编译流程，一种就是AssemblyCSharpBuilder ，相比较而言，它是轻量级的，个人怀疑另一种编译流程的底层也是使用了AssemblyCSharpBuilder 。

• 引用NuGet：DotNetCore.Natasha.CSharp

• 编译单元基本举例

  NatashaManagement.Preheating();
  //创建一个变量，用于参数带入和后期的参数比较
  String key = "HelloWorld";
  // 创建一个Test类，类中添加了一个变量和一个静态方法
  // 变量为key值，静态方法中放回声明的key值
  string code = "public class Test" +
      "public string Name=\\"" + key + "\\"; " +
          "public static string GetName()  " +
          "    return (new Test()).Name; " +
          "" +
      "";
  // 创建了一个myDomain域，指定了该域的使用范围
  using (DomainManagement.Create("myDomain").CreateScope())
  
      // 声明基础编译单元
      AssemblyCSharpBuilder builder = new();
      // 添加code
      builder.Add(code);
      ///////////////调用使用//////////////////////////////////
      // 获得Test类的GetName方法
      var func = builder.GetDelegateFromShortName<Func<string>>("Test", "GetName");
      // 调用GetName方法，并返回
      String result = func();
      // 判断返回值是否与key相同
      if (key.Equals(result))
      
          //相同
          System.Console.WriteLine("匹配");
      
      else 
          // 不同时返回result数值，可查看为什么不同
          System.Console.WriteLine($"不匹配:result");
      
  
  

  返回结果：

  

AssemblyCSharpBuilder相关属性方法

属性

• Domain 编译单元所在域

  为什么要着重描述域的概念？当代码量越来越大，所需的插件逐渐增多时，一旦引用版本出现问题，会给程序本身带来灾难，而且一旦全部引用，程序所占的内存也是灾难级的。例如我们加载了两个不同平台版本的相同dll，调用时，系统无法判断我们应该用哪个，特别是两个版本的dll方法不同时，都无法判定哪里错了。例如java中使用maven去管理版本，vue使用npm管理版本一样，而域中的版本管理也很重要。

  建议：

  1.写代码时，就要设计好引用管理问题，不然日积月累，会越来越臃肿

  2.建议类似maven的pom一样管理dll版本，这样不至于导致版本引用混乱

  3.划分不同的域，每个域用反射调用，主要用于解耦。

  4.封装每个域，让每个域成为独立的个体，完全解耦，适用于独立功能，功能简单的情况

  5.在LoadPluginWith**Dependency 时进行依赖引用判断

  ​ LoadPluginWithAllDependency ("*.dll", asmName=>依赖列表，返回true为不包含，false为包含)。

• 为空时先从上下文中获得，如上文例子中的myDomain域，当上下文也为空，则设置为：NatashaReferenceDomain.DefaultDomain。

• Domain为NatashaReferenceDomain类，因该类重载了AssemblyLoadContext类，因此会有基类的特性：

  1. LoadFromStream和LoadAssemblyFromFile等方法

     加载文件流或文件到该域中，也可以加载Natasha生成的相关文件

     当域中存在相同的文件时，直接跳过。

  2. 当遇到相同文件时，希望可以选择，则可以使用下列方法

     LoadPluginWithAllDependency [全加载]

     LoadPluginWithHighDependency[高版本加载]

     LoadPluginWithLowDependency [低版本加载]

     LoadPluginUseDefaultDependency[使用主域版本]

• DllFilePath，PdbFilePath，XmlFilePath

  生成的dll，pdb，xml文件的路径地址，绝对路径

• DefaultUsing.UsingScript 可以添加默认的引用

方法

• 引用相关方法

  // LoadBehaviorEnum
  // 		UseHighVersion		使用高版本
  //		UseLowVersion		使用低版本
  // 当编译后加载程序集时，程序集中依赖存在高版本，则使用高版本依赖
  CompileWithAssemblyLoadBehavior(LoadBehaviorEnum.UseHighVersion) 
  // 当合并引用时,引用列表中存在高版本, 则使用高版本引用           
  CompileWithReferenceLoadBehavior(LoadBehaviorEnum.UseHighVersion)
  // 引用过滤逻辑 
  CompileWithReferencesFilter((defaultAsmName, targetAsmName)=> LoadVersionResultEnum.UseDefault) 
  

• 更改输出路径

  // 参数可以更换目录
  builder.UseNatashaFileOut();
  builder.SetDllFilePath(path);               //设置生成的 DLL 文件路径  c:/1.dll
  builder.SetPdbFilePath(path);               //设置生成的 PDB 文件路径  c:/1.pdb
  builder.SetXmlFilePath(path);              //设置生成的 XML 文件路径  c:/1.xml
  

• 配置编译器参数

  目前水平碰不得

  ConfigCompilerOption(opt => );

• 配置语法树

  目前水平碰不得

  ConfigSyntaxOptions(opt => opt)

• 语义过滤器(委托)

  参数一和参数二返回一个参数二一致的类型

  AddSemanticAnalysistor((currentBuilder, currentCompiler) => currentCompiler)

  这个感觉知道就好，一般用不到

  builder1.AddSemanticAnalysistor((build, compla) =>
  
      // 重新创建了一个Test的动态编译
      var complation = CSharpCompilation.Create("Test")
          // 添加本地资源
          .AddReferences(
              MetadataReference.CreateFromFile(
                  typeof(object).Assembly.Location)
              )
          // 添加编译代码  
          .AddSyntaxTrees(CSharpSyntaxTree.ParseText("public class A public String Hello()return \\"Hello\\""))
          // 添加配置项
          .WithOptions(new CSharpCompilationOptions(OutputKind.DynamicallyLinkedLibrary));
      return complation;
  );
  

• 清除所有语义过滤器

  ClearInnerSemanticAnalysistor

  内部实际调用UsingAnalysistor._usingSemanticDelegate，在我理解就是删除了语义委托的缓存

• 添加代码

  Add(String code) 添加脚本

  Add(SyntaxTree tree) 添加语法树，例如：CSharpSyntaxTree.ParseText

• 获取编译后的动态程序集

  GetAssembly获得Assembly

  获得Assembly后可获得相关信息

  通过Assembly.GetType()获得具体类型信息，也可通过Activator.CreateInstance()进行实例化

• 获取到类型

  直接获得类型

  GetTypeFromShortName("Test")

  GetTypeFromFullName("xxNamespace.xxClassName")

已知问题

摘自官网

• 缺少引用文件报错 NatashaException:“找不到 RuntimeMetadataVersion 的值。找不到包含 System.Object 的程序集，或未通过选项为 RuntimeMetadataVersion 指定值。”
  • 使用 NatashaManagement.AddGlobalReference(); 来手动添加默认域的引用文件.
  • 使用 domain.LoadAssemblyFromFile / LoadPluginXXXDependency 来手东添加其他域的引用文件.
• 缺少 Using 引用;
  • 使用 NatashaManagement.AddGlobalUsing("mynamespace") 来手动添加全局 using.
  • 使用 domain.UsingRecorder.Using("mynamespace") 来手动添加其他域的 using.

动态编译库 Natasha 5.0 版本发布

动态编译库 Natasha 5.0 于十月份发布，此次大版本更新带来了强大的兼容性支持，目前 Natasha 已支持 .NET Standard 2.0 及 .NET Core 3.1 以上版本（包括 .NET Framework）了。

引入项目

NuGet\\Install-Package DotNetCore.Natasha.CSharp -Version 5.0.0

引擎分离

从 Natasha 5.0 开始，将支持根据 TargetFramework 目标版本来适配对外 APIs，为开发者自动选择提供单域编译引擎或多域编译引擎。

单域编译引擎

• 支持 .NET Standard 2.0（.NET Core 3.1 以下，以及.NET Framework）版本

• 动态构建工作将在主域 Main Domain 中进行

• 不具备多域编译引擎带来的优势，也无法卸载动态编译输出的程序集

• 简化了部分 APIs，移除一部分不必要的 APIs，不兼容上一版本的 Natasha APIs

多域编译引擎

• 兼容 .NET Core 3.1 及以上版本（包括 .NET Core 和 .NET 5+）

• 支持程序集卸载 Assembly Uninstall

• 支持域功能隔离 Domain Functions Isolation

• 支持插件加载与卸载 Plugin Load & Unload

• 兼容上一版本的全部 Natasha APIs

代码分离

Natasha 5.0 在源码层面分为 MultiDomain、Public 和 SingleDomain 三部分，并使用自定义宏 MULTI 来区分单域与多域。

Natasha 5.0 从工程文件层面上做了兼容性隔离，确保 Natasha 在后续版本的升级中不必过多关注兼容性问题，多域编译引擎依旧是 Natasha 未来版本的主要方向，后续的升级与优化工作也将在 MutliDomain 中开展。

如多域编译引擎提供了如下接口：

OperatorClass.DefaultDomain/CreateDomain/RandomDomain/UseDomain

其对应的单域编译引擎仅支持如下接口：

OperatorClass.DefaultDomain

单域编译引擎的编译结果会全部加载到主域当中，因此不具备域功能隔离与卸载能力。

使用须知

编译前提

使用 字符串脚本 需要对编译原理有一定程度的了解。Natasha 与 Roslyn 将为开发者极大地简化了复杂的理论依据和构建过程。开发者在使用 Natasha 时需要关注以下问题：

一、元数据管理问题

熟悉 Emit/Expression 的开发者了解，在构建过程中可能会使用到反射（如 PropertyInfo、FieldInfo、MethodInfo 等信息）。由于许多开发者在编写代码时，只关注反射的使用，忽视了这些元数据对动态编译的重要性，因此在通过字符串脚本进行编译时，时常会出现各种问题。

Natasha 和 Roslyn 同样需要元数据，而元数据的来源十分多样，如引用程序集、内存程序集、实际程序集等。其中，除内存程序集外，元数据均被记录在 DLL 文件中，因此当使用如下构建代码时：

NatashaManagement.AddGlobalReference("1.dll");

可能会引发如下异常：

找不到 RuntimeMetadataVersion 的值。找不到包含 System.Object 的程序集，或未通过选项为 RuntimeMetadataVersion 指定值。

引用管理对于程序来讲是具有一定负担的，因为目前还不能从内存程序集中提取到元数据，所以需要以文件的方式来添加，这也就导致了开发者在发布动态编译程序时，需要有完毕的引用文件跟随 —— 将导致所发布的包体积变大。至于环境需要哪些引用文件，可以交由 NCC 编译环境包来解决。如果开发者不能很好地管理引用，那么直接引入该包来全面覆盖当前程序的元数据是最好的选择。

二、Using 管理问题

Using 的管理关乎元数据的引用来源。任何一个动态构建，都是以一个完整类的方式进行的，因此完整的类 using 代码是必不可少的。Natasha 构建模板目前可以覆盖大部分 using，并能通过语义过滤来处理异常 using。如果开发者直接使用 AssemblyCSharpBuilder 来构建代码，那么就需要注意脚本中的 using 问题。

编译环境

编译环境包目前已不再包含于 Natasha Package 中，因此需要使用以下方法来加载编译环境：

• 使用 Natasha 接口来管理全局引用与 Using 缓存

  NatashaManagement.AddGlobalReference/AddGlobalUsing

• 使用 NCC 编译环境包来解决元信息的引用问题

  DotNetCore.Compile.Environment

输出环境

如果开发者认为生成的文件中有太多的多语言适配资源，那么可以使用 SatelliteResourceLanguages 来指定默认的资源语言：

<SatelliteResourceLanguages>en</SatelliteResourceLanguages>

二义性错误

二义性问题仍被归属到开发者的错误开发行为中，不应由 IDE 或 Natasha 来解决。Natasha 团队倾向于在命名空间发生冲突时，由开发者手工解决该问题，Natasha 的上下文语义环境并不能百分之百地推断出用户究竟想用哪一个命名空间。

目前有三种解决方案可供开发者选择：

1. 使用 Natasha.CSharp.Extension.Ambiguity 扩展包，通过 .Using() 或 .ConfigUsing() 模板自带的方法来指定优先级最高的 using 。该包将在不久之后将独立并进入 Natasha 生态社区 NMS 之中；

2. 直接使用引擎 AssemblyCSharpBuilder 编译字符串脚本，在字符串层面进行替换；

3. 定制语义过滤方法，更新编译单元中的语法树，使用 Natasha 的语义扩展方法，将自定义语义过滤方法添加到 Natasha 中：

   assemblyCSharpBuilder.AddSemanticAnalysistor(Func<AssembltCSharpBuilder, 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

• 分离引擎，项目分为多域和单域以部分类方式合并 APIs

• 使用 IndexOf 替代 Contans 方法做兼容

• 支持 .NET Standard 2.0、.NET Core 3.1+ 以及 .NET 5+ 版本

• 升级 DotNetCore.SourceLink.Environment 依赖，支持 .NET Standard 2.0/2.1 版本

• 升级 DotNetCore.Compile.Environment 依赖，支持 .NET Standard 2.0/2.1 版本

2022/09/30 - 2022/10/09

• 使用 Assembly.ReflectionOnlyLoad 替代 MetadataLoadContext 解决单域引擎只读元数据的问题

• 优化单域引擎初始化过程中扫描源 DLL 文件的问题