JScriptEngine

Namespace: Wisej.Ext.ClearScript

Assembly: Wisej.Ext.ClearScript (4.1.0.0)

Thread safe implementation of the JScriptEngine scripting engine: every call into the script engine is automatically marshaled to the thread that created the engine.

C#

public class JScriptEngine : JScriptEngine

VB.NET

Public Class JScriptEngine
    Inherits JScriptEngine

The Microsoft Windows script engines (JScript and VBScript) have thread affinity: they capture the Dispatcher of the thread that creates them and must always be used from that thread. This class removes that limitation by routing all script invocations through Dispatcher, so the engine can be shared safely by the threads of a Wisej session.

In most cases you should not instantiate this class directly. Use Create with JScript: it creates the engine on a dedicated thread bound to the current Wisej session and starts the dispatcher loop that the engine needs.

info

Always dispose the engine when you are done with it in order to release the dedicated thread. If you don't dispose it and don't keep a reference, the thread is terminated when the garbage collector kicks in.

Example:

This example creates a JScript engine, exposes a server object to the script, runs a script and reads back a value.

using (var engine = Wisej.Ext.ClearScript.ClearScript.Create(
    Wisej.Ext.ClearScript.EngineType.JScript, "calculator"))
{
    // expose a host object to the script code.
    engine.AddHostObject("customer", this.customer);

    // run the script.
    engine.Execute(@"
        function discount(total) {
            return customer.IsPreferred ? total * 0.9 : total;
        }
        var net = discount(1000);
    ");

    // read a global back, or invoke a script function.
    var net = Convert.ToDouble(engine.Script.net);
    var other = engine.Script.discount(250);
}

See also: ClearScript, VBScriptEngine, V8JavaScriptEngine

Constructors

JScriptEngine(name, flags)

Initializes a new instance of the JScriptEngine class with the specified name and options.

Name	Type	Description
name	String	A user defined name for the engine instance. It is used only for identification purposes, e.g. in debugger user interfaces. May be null.
flags	WindowsScriptEngineFlags	A bitwise combination of WindowsScriptEngineFlags values that configure the engine. Pass None for the defaults.

The engine binds itself to the thread that executes this constructor: that thread must run a Dispatcher message loop (Run) for as long as the engine is alive, otherwise the calls marshaled to it will never be serviced.

Prefer Create, which takes care of creating the thread, starting the dispatcher loop and binding the thread to the current Wisej session.

Example:

Recommended: let ClearScript create the engine and its thread.

var engine = (Wisej.Ext.ClearScript.JScriptEngine)
    Wisej.Ext.ClearScript.ClearScript.Create(
        Wisej.Ext.ClearScript.EngineType.JScript,
        "rules",
        windowsflags: Microsoft.ClearScript.Windows.WindowsScriptEngineFlags.EnableDebugging);

engine.Execute("var version = 1;");

Direct instantiation: you are responsible for the thread and for its dispatcher loop.

Wisej.Ext.ClearScript.JScriptEngine engine = null;
var ready = new System.Threading.ManualResetEventSlim();

Wisej.Web.Application.StartTask(() =>
{
    engine = new Wisej.Ext.ClearScript.JScriptEngine(
        "rules", Microsoft.ClearScript.Windows.WindowsScriptEngineFlags.None);

    ready.Set();

    // the engine's thread must pump the dispatcher queue.
    System.Windows.Threading.Dispatcher.Run();
});

ready.Wait();

// from here the engine can be used from any thread of the session.
engine.Execute("var version = 1;");

// releases the engine and shuts down its dedicated thread.
engine.Dispose();

Methods

Dispose(disposing)

Releases the resources used by the JScriptEngine and terminates the dedicated thread that hosts the engine.

Parameter	Type	Description
disposing	Boolean	true to release both managed and unmanaged resources; false to release only unmanaged resources.

Shuts down the engine's Dispatcher and then disposes the base engine on its own thread. After this call the engine can no longer execute script code.

Example:

// "using" is the simplest way to guarantee that the engine thread is released.
using (var engine = Wisej.Ext.ClearScript.ClearScript.Create(
    Wisej.Ext.ClearScript.EngineType.JScript))
{
    engine.Execute("var x = 1 + 1;");
}