发布最新扩展库文档

Author: NMSAzulX

src/docs/compile/004-Metadata.md

@@ -30,6 +30,8 @@ loadContext.AddReferenceAndUsingCode(refAssemblyFilePath);
 
 单独添加 [元数据引用]
 ```cs
+loadContext.AddReferences()
+//或
 loadContext.ReferenceRecorder.AddReference(
     AssemblyName assemblyName, 
     MetadataReference reference, 
@@ -39,6 +41,8 @@ loadContext.ReferenceRecorder.AddReference(
 
 ### 单独增加 [Using Code]
 ```cs
+loadContext.AddUsing()
+//或
 loadContext.UsingRecorder.Using(string? @using);
 loadContext.UsingRecorder.Using(IEnumerable<string> @using);
 loadContext.UsingRecorder.Using(Assembly assembly);

src/docs/compile/007-EvenAndException.md

@@ -0,0 +1,41 @@
+---
+title: "7. Natasha 的异常"
+---
+
+## 使用方法
+
+Natasha 在编译时出错会抛出异常，异常 Model 如下：
+```cs
+public sealed class NatashaException : Exception
+{
+
+    //格式化后的脚本字符串
+    public string Formatter;
+
+    //错误类型
+    public NatashaExceptionKind ErrorKind;
+
+    //roslyn诊断集合
+    public List<Diagnostic> Diagnostics;
+
+    /// <summary>
+    /// 详细的编译信息
+    /// </summary>
+    public string CompileMessage;
+
+}
+```
+
+### 如何监控和获取异常
+
+Natasha 的事件执行流程如下：
+1. 添加语法树时：
+ - 使用 FastAddScriptWithoutCheck，则不会抛出异常。
+ - 使用 Add 则会进行语法检查，并抛出异常。
+2. 编译时：
+ - 编译后先触发 LogCompilationEvent 事件，用来获取编译后的信息。
+ - 如果编译成功会继续引发 CompileSucceedEvent 事件。
+ - 如果编译失败会继续引发 CompileFailedEvent 事件。
+3. 编译周期之外：
+ - 编译过后，可以通过 GetException() 获取异常（可能为空）。
+

src/docs/compile/008-extensions-samples.md renamed to src/docs/compile/008-ExtensionType.md

@@ -1,5 +1,5 @@
 ---
-title: "7. 使用 Codecov 的扩展"
+title: "9. 使用 Codecov 的扩展"
 ---
 
 ## 使用方法

src/docs/compile/007-Codecov.md renamed to src/docs/compile/009-Codecov.md

@@ -0,0 +1,53 @@
+---
+title: "10. 使用 CompileDirector 的扩展"
+---
+## 介绍
+
+这是一个可以让编译单元不断学习和矫正 using code 的库，在重复的编译场景中，几乎每次 using code 和元数据引用都大同小异，甚至不会改变，
+该库允编译单元在编译成功时学习有用的 using code 以备后用。
+
+## 使用方法
+
+1. 引入 `DotNetCore.Natasha.CSharp.Extension.CompileDirector` 扩展包。
+2. 编码。
+
+### 编译导演
+```cs
+//传入采样计数阈值，不传默认为 2.
+//采样计数会影响 CompileDirector 的“学习”效率.
+//每次编译成功，该编译单元成功的 using 计数 + 1.
+//当 using 计数大于采样计数阈值时，将被 CompileDirector 内部的 UsingCache 录用为正式 using.
+//正式 using 每次会优先覆盖脚本
+CompileDirector director = new CompileDirector(3);
+
+//配置每次从该场景中产生的 编译单元。
+director.ConfigBuilder(builder => builder
+.ConfigSyntaxOptions(opt => opt.WithPreprocessorSymbols("DEBUG"))
+.WithDebugCompile()
+.ConfigLoadContext(ctx => ctx
+    .AddReferenceAndUsingCode<object>()
+    .AddReferenceAndUsingCode(typeof(Math))
+    .AddReferenceAndUsingCode(typeof(File))
+));
+
+//生产编译单元
+//由 director 生产的编译单元会自动覆盖已经被录用的 using code.
+var builder = director.CreateBuilder();
+
+//编译单元
+builder.Add(@"public static class A
+{  
+    public static void Show()
+    { 
+        File.WriteAllText(""1.txt"", ""1"");
+        Console.WriteLine(Math.Abs(-4));   
+    }
+}");
+
+//通过 director 获取程序集
+// 成功时继续挑选和计数录用 using code
+// 失败时将使用对应的 using 覆盖策略进行重编译
+//     通过 ConfigUsingConverSrategy API 配置失败时的覆盖策略      
+var asm = director.GetAssembly(builder);
+asm.GetDelegateFromShortName<Action>("A", "Show")!();
+```

src/docs/compile/010-CompileDirector.md

@@ -0,0 +1,29 @@
+---
+title: "11. 使用 MethodCreator 的扩展"
+---
+## 介绍
+
+MethodCreator 扩展库允许开发者快速构建动态委托。
+
+## 使用方法
+
+1. 引入 `DotNetCore.Natasha.CSharp.Extension.MethodCreator` 扩展包。
+2. 编码。
+
+### 共分为两种模式
+#### 精简构造模式
+精简构造模式需要自己管理元数据和using
+```cs
+ var func = "return arg1 + arg2 + 0.1;"
+    .WithMetadata<double>()
+    .ToFunc<double, double, double>();
+```
+#### 智能构造模式
+智能构造模式将自动覆盖元数据和 using
+```cs
+ var func = "return arg1 + arg2 + 0.1;"
+    .ToFunc<double, double, double>();
+```
+
+<br/>
+<br/>

src/docs/compile/011-MethodCreator.md

@@ -30,6 +30,8 @@ loadContext.AddReferenceAndUsingCode(refAssemblyFilePath);
 
 单独添加 [元数据引用]
 ```cs
+loadContext.AddReferences()
+//或
 loadContext.ReferenceRecorder.AddReference(
     AssemblyName assemblyName, 
     MetadataReference reference, 
@@ -39,6 +41,8 @@ loadContext.ReferenceRecorder.AddReference(
 
 ### 单独增加 [Using Code]
 ```cs
+loadContext.AddUsing()
+//或
 loadContext.UsingRecorder.Using(string? @using);
 loadContext.UsingRecorder.Using(IEnumerable<string> @using);
 loadContext.UsingRecorder.Using(Assembly assembly);

src/i18n/zh-Hans/docusaurus-plugin-content-docs/current/compile/004-Metadata.md

@@ -0,0 +1,41 @@
+---
+title: "7. Natasha 的异常"
+---
+
+## 使用方法
+
+Natasha 在编译时出错会抛出异常，异常 Model 如下：
+```cs
+public sealed class NatashaException : Exception
+{
+
+    //格式化后的脚本字符串
+    public string Formatter;
+
+    //错误类型
+    public NatashaExceptionKind ErrorKind;
+
+    //roslyn诊断集合
+    public List<Diagnostic> Diagnostics;
+
+    /// <summary>
+    /// 详细的编译信息
+    /// </summary>
+    public string CompileMessage;
+
+}
+```
+
+### 如何监控和获取异常
+
+Natasha 的事件执行流程如下：
+1. 添加语法树时：
+ - 使用 FastAddScriptWithoutCheck，则不会抛出异常。
+ - 使用 Add 则会进行语法检查，并抛出异常。
+2. 编译时：
+ - 编译后先触发 LogCompilationEvent 事件，用来获取编译后的信息。
+ - 如果编译成功会继续引发 CompileSucceedEvent 事件。
+ - 如果编译失败会继续引发 CompileFailedEvent 事件。
+3. 编译周期之外：
+ - 编译过后，可以通过 GetException() 获取异常（可能为空）。
+

src/i18n/zh-Hans/docusaurus-plugin-content-docs/current/compile/007-EvenAndException.md

@@ -1,5 +1,5 @@
 ---
-title: "7. 使用 Codecov 的扩展"
+title: "9. 使用 Codecov 的扩展"
 ---
 
 ## 使用方法