動態編譯庫 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