ClearScript

Namespace: Wisej.Ext.ClearScript

Assembly: Wisej.Ext.ClearScript (4.1.0.0)

Provides functionality for creating and managing instances of the ClearScript scripting engines. For comprehensive documentation on the usage of the scripting engine, please refer to the following link: R_Project_Reference.

C#

public static class ClearScript

VB.NET

Public Class ClearScript

The ClearScript Windows engines (VBScript and JScript) are tied to a specific thread. Once an engine instance has been created, it must always run within the thread that instantiated it.

When Create is invoked with VBScript or JScript, a new scripting engine is instantiated on a dedicated thread, and all operations are marshaled to this engine-bound thread.

Conversely, when Create is called with V8, the new scripting engine runs without being assigned a dedicated thread, as the V8 engine can handle

info

When using the VBScript or JScript engines, it is essential to DISPOSE of the engine instance once it is no longer in use. This action is necessary to release the dedicated thread associated with the engine.

If you don't dispose and don't keep a reference, the thread will be automatically terminated when the garbage collector kicks in.

Methods

Create(type, name, v8constraints, v8flags, windowsflags)

Creates and initializes a new instance of the specified type script engine.

Parameter	Type	Description
type	EngineType	The EngineType enum value specifying the type of script engine to create.
name	String	A user-defined name for the script engine instance. This name is primarily used for identification purposes in presentation contexts, such as debugger interfaces.
v8constraints	V8RuntimeConstraints	An optional instance of V8RuntimeConstraints that defines constraints for initializing the V8 script engine. Pass null to use default constraints.
v8flags	V8ScriptEngineFlags	An optional bitwise combination of V8ScriptEngineFlags flags for customizing the behavior of the V8 script engine. Pass 0 for default behavior.
windowsflags	WindowsScriptEngineFlags	An optional bitwise combination of WindowsScriptEngineFlags flags for configuring the JScript or VBScript engines. Pass 0 for default settings.

Returns: ScriptEngine. A new instance of the ScriptEngine corresponding to the specified type .

JScript and VBScript engines are created on a dedicated thread bound to the current Wisej session and must be disposed to release that thread. V8 engines have no thread affinity, but should still be disposed since they hold unmanaged memory.

The v8constraints and v8flags arguments are ignored unless type is V8; windowsflags is ignored unless it is JScript or VBScript.

Throws:

• NotSupportedException Thrown when type is not one of the values defined by EngineType.

Example:

Running a script in a V8 engine, exposing a server object and a .NET type to the script code:

using (var engine = Wisej.Ext.ClearScript.ClearScript.Create(
    Wisej.Ext.ClearScript.EngineType.V8, "calculator"))
{
    engine.AddHostObject("customer", this.customer);
    engine.AddHostType("Math", typeof(System.Math));

    engine.Execute(@"
        function discount(total) {
            return customer.IsPreferred ? Math.Round(total * 0.9) : total;
        }
    ");

    // evaluate an expression, or invoke a script function.
    var net = Convert.ToDouble(engine.Evaluate("discount(1000)"));
    var other = engine.Script.discount(250);
}

The same code in a thread-bound JScript engine, with debugging enabled. The engine runs on its own thread, but can be used from any thread of the session:

using (var engine = Wisej.Ext.ClearScript.ClearScript.Create(
    Wisej.Ext.ClearScript.EngineType.JScript,
    "calculator",
    windowsflags: WindowsScriptEngineFlags.EnableDebugging))
{
    engine.AddHostObject("customer", this.customer);
    engine.Execute("function discount(total) { return customer.IsPreferred ? total * 0.9 : total; }");

    var net = Convert.ToDouble(engine.Evaluate("discount(1000)"));
}

Limiting the memory a V8 engine may use, and keeping the engine alive for the whole session:

// Application.Session is a dynamic object: the engine lives until the session ends.
Application.Session.Engine = Wisej.Ext.ClearScript.ClearScript.Create(
    Wisej.Ext.ClearScript.EngineType.V8,
    "rules",
    v8constraints: new V8RuntimeConstraints { MaxOldSpaceSize = 64, MaxNewSpaceSize = 8 },
    v8flags: V8ScriptEngineFlags.EnableDebugging);