> cat /etc/kylin-build Kylin-Desktop V10-SP1 Build 20220316 > cat /etc/.kyinfo [dist] name=Kylin milestone=Desktop-V10-SP1-General-RC6-Build21-2203 ar ...
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文件的問題.
