ClearScript is an open-source library for the .NET platform that enables script execution in C# and other .NET languages. It provides a convenient and secure way to integrate scripting into applications, allowing applications to be exposed to scripts for higher-level customization and interaction. This article provides an in-depth introduction to ClearScript's usage and features, including how to execute JavaScript scripts in C#, interact with scripts, and call C# methods.
Installation and Configuration
ClearScript can be installed via the NuGet Package Manager. To install ClearScript, open the NuGet Package Manager Console in Visual Studio and run the following command:
Install-Package ClearScript
After installation, you also need to copy the runtimes directory from the ClearScript NuGet package to your runtime directory. Then, you can use the ClearScript library in your project.
Executing JavaScript Scripts
To execute JavaScript scripts in C#, you need to create a JavaScript engine instance and pass the script to it. Here's a simple example demonstrating how to execute a basic JavaScript program:
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); // Outputs 30
In this example, we create a V8ScriptEngine object named "engine" and call its Execute() method to run some JavaScript code. Here, we define three variables (a, b, and c), add them together, and store the result in variable c. Then, we retrieve the value of variable c from the engine.Script object and output it to the console.
Interacting with Scripts
When executing JavaScript scripts, you can pass C# objects to the scripts so that the scripts can access them. To pass an object to the script, you need to use the AddHostObject() method to add the object to the JavaScript engine. Here's a simple example demonstrating how to pass a C# object to JavaScript:
/// <summary>
/// The Person class must be public for the V8 engine to access it properly.
/// </summary>
public class Person
{
public string? Name { get; set; }
public int Age { get; set; }
}
/// <summary>
/// Interaction between JavaScript and 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 岁呀？
}
In this example, we create a C# object named "person" (note that the Person class's access modifier is public) and add it to the JavaScript engine using the AddHostObject() method. Then, we execute a JavaScript program that concatenates the properties of the person object into a JS variable. Finally, C# accesses the JS variable and outputs it to the console (attempts to use console.log in JS for output were unsuccessful; if you know why, please leave a comment).
Calling C# Methods from JavaScript
Besides passing C# objects to JavaScript, you can also call C# methods from within JavaScript. To call a C# method in JavaScript, you need to create a class containing the method and add that class to the JavaScript engine using the AddHostObject() method. Here's a simple example demonstrating how to call a C# method from JavaScript:
/// <summary>
/// JavaScript calls C# methods
/// </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;
}
}
In this example, we create a Calculator object named "calculator" and add it to the JavaScript engine using the AddHostObject() method. Then, we execute a JavaScript program that calls the Add() method of the Calculator object, assigns the result to a JS variable, and finally, C# retrieves the variable value and outputs it to the console.
Multithreading Usage
ClearScript also supports using the JavaScript engine in multiple threads. To use the JavaScript engine across multiple threads, you need to create separate JavaScript engine instances and execute scripts on their respective threads. Here's a simple example demonstrating how to use the JavaScript engine in multiple threads:
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!'");
});
In this example, we create two V8ScriptEngine objects named "engine1" and "engine2" and execute two JavaScript programs on two different threads. These programs define JS variables.
Note that when using the JavaScript engine across multiple threads, you should avoid accessing the same JavaScript engine instance simultaneously to prevent thread safety issues.
Summary
This article introduces the usage and features of ClearScript, including how to execute JavaScript scripts in C#, interact with scripts, call C# methods, and use it in multithreading scenarios. ClearScript provides a convenient and secure way to integrate scripting into applications, allowing applications to be exposed to scripts for higher-level customization and interaction. By using ClearScript, you can add flexibility and extensibility to your applications and implement dynamic script execution functionality.
References
- ClearScript Examples: https://microsoft.github.io/ClearScript/Examples/Examples.html