ClearScript 是一個 .NET 平台下的開源程式庫，用於在 C# 和其他 .NET 語言中執行指令碼程式碼。它提供了一種方便且安全的方式，將指令碼與應用程式整合，並允許將應用程式公開給指令碼，以進行更高層級的自訂與互動。本篇文章將深入介紹 ClearScript 的使用方法與特色，包括如何在 C# 中執行 JavaScript 指令碼、如何與指令碼互動、如何呼叫 C# 方法等內容。
安裝與設定
ClearScript 可以透過 NuGet 套件管理員進行安裝。要安裝 ClearScript，可以在 Visual Studio 中開啟 NuGet 套件管理員主控台，並執行以下命令：
Install-Package ClearScript
安裝完成後，還需要將 ClearScript NuGet 套件下的 runtimes 目錄複製到執行目錄，然後才能在專案中使用 ClearScript 程式庫。
執行 JavaScript 指令碼
要在 C# 中執行 JavaScript 指令碼，需要建立一個 JavaScript 引擎執行個體，並將指令碼傳遞給該執行個體。以下是一個簡單的範例，示範如何執行一個簡單的 JavaScript 程式：
using var engine = new V8ScriptEngine();
engine.Execute("var a = 10; var b = 20; var c = a + b;");
var result = engine.Script.c;
Console.WriteLine(result); // 輸出 30
在這個範例中，我們建立了一個名為 engine 的 V8ScriptEngine 物件，並呼叫其 Execute() 方法來執行一些 JavaScript 程式碼。在這裡，我們定義了三個變數（a、b 和 c），將它們相加，並將結果儲存在變數 c 中。然後，我們從 engine.Script 物件中取得變數 c 的值，並將其輸出到主控台。
與指令碼互動
在執行 JavaScript 指令碼時，可以將 C# 物件傳遞給指令碼，以便指令碼可以存取這些物件。要將物件傳遞給指令碼，需要使用 AddHostObject() 方法將物件新增到 JavaScript 引擎中。以下是一個簡單的範例，示範如何將 C# 物件傳遞給 JavaScript：
/// <summary>
/// Person 類別必須為 Public，V8 引擎才能正常存取
/// </summary>
public class Person
{
public string? Name { get; set; }
public int Age { get; set; }
}
/// <summary>
/// JS 與 C# 互動
/// </summary>
static void InteractionBetweenJsAndCsharp()
{
using var engine = new V8ScriptEngine();
var person = new Person { Name = "沙漠盡頭的狼", Age = 18 };
engine.AddHostObject("person", person);
engine.Execute("var c = person.Name + ' 才 ' + person.Age + ' 歲呀？';");
var result = engine.Script.c;
Console.WriteLine(result); // 沙漠盡頭的狼 才 18 歲呀？
}
在這個範例中，我們建立了一個名為 person 的 C# 物件，注意 Person 的定義存取修飾詞為 public，並使用 AddHostObject() 方法將其新增到 JavaScript 引擎中。然後，我們執行一個 JavaScript 程式，該程式拼接 person 物件的屬性組成一個 JS 變數，最後 C# 存取 JS 變數並輸出到主控台（嘗試在 JS 中使用 console.log 輸出未成功，有知道原因的朋友請留言告知）。
JS 呼叫 C# 方法
除了將 C# 物件傳遞給 JavaScript 外，還可以在 JavaScript 中呼叫 C# 方法。要在 JavaScript 中呼叫 C# 方法，需要建立一個包含方法的類別，並使用 AddHostObject() 方法將該類別新增到 JavaScript 引擎中。以下是一個簡單的範例，示範如何在 JavaScript 中呼叫 C# 方法：
/// <summary>
/// JS 呼叫 C# 的方法
/// </summary>
static void JsCallCSharpMethod()
{
using var engine = new V8ScriptEngine();
var calculator = new Calculator();
engine.AddHostObject("calculator", calculator);
engine.Execute("var result = calculator.Add(15, 20)");
var result = engine.Script.result;
Console.WriteLine(result); // 35
}
public class Calculator
{
public int Add(int a, int b)
{
return a + b;
}
}
在這個範例中，我們建立了一個名為 calculator 的 Calculator 物件，並使用 AddHostObject() 方法將其新增到 JavaScript 引擎中。然後，我們在 JavaScript 中執行一個程式，該程式呼叫 Calculator 物件的 Add() 方法，並將結果賦值給 JS 變數，最後在 C# 中取得變數值並輸出到主控台。
多執行緒使用
ClearScript 也支援在多個執行緒中使用 JavaScript 引擎。要在多個執行緒中使用 JavaScript 引擎，需要建立多個 JavaScript 引擎執行個體，並使用各自的執行緒來執行指令碼。以下是一個簡單的範例，示範如何在不同執行緒中使用 JavaScript 引擎：
using System.Threading.Tasks;
using Microsoft.ClearScript.V8;
var engine1 = new V8ScriptEngine();
var engine2 = new V8ScriptEngine();
Task.Run(() =>
{
engine1.Execute("var a = 'Hello from thread 1!'");
});
Task.Run(() =>
{
engine2.Execute("var b = 'Hello from thread 2!'");
});
在這個範例中，我們建立了兩個名為 engine1 和 engine2 的 V8ScriptEngine 物件，並在兩個不同的執行緒中分別執行了兩個 JavaScript 程式。這些程式定義了 JS 變數。
需要注意的是，在多個執行緒中使用 JavaScript 引擎時，應避免同時存取同一個 JavaScript 引擎執行個體，以避免執行緒安全問題。
總結
本文介紹了 ClearScript 的使用方法與特色，包括如何在 C# 中執行 JavaScript 指令碼、如何與指令碼互動、如何呼叫 C# 方法、多執行緒使用等內容。ClearScript 提供了一種方便且安全的方式，將指令碼與應用程式整合，並允許將應用程式公開給指令碼，以進行更高層級的自訂與互動。透過使用 ClearScript，可以為應用程式增加靈活性與擴充性，並在應用程式中實現動態指令碼執行功能。
參考資料
- ClearScript Examples：https://microsoft.github.io/ClearScript/Examples/Examples.html