JavaScriptScriptEngine Class

Gets the JavaScript engine (the agent of the windows).

Whether JavaScript code is running: the .NET code that calls into the engine uses JavaScriptScriptEngine.EnterJavaScript.

Gets the options of the engine, also used by the engines of the workers.

Gets whether the engine supports the module scripts (<script type="module">, import()). When it is false (the default), the module scripts are not fetched nor run.

Calls a function in the realm of a window, as a callback of the host (e.g. a function returned by JavaScriptScriptEngine.Evaluate). The microtasks are not run: call DomEventLoop.PerformMicrotaskCheckpoint afterwards. The strings the function compiles while it runs (eval(), Function()) are not restricted by the content security policy of the document.

https://html.spec.whatwg.org/multipage/webappapis.html#getting-the-current-value-of-the-event-handler (step 1.9)

The realms are created on first use: most windows (e.g. the initial about:blank documents) never run scripts.

Creates the engine of a worker: a new engine with the same options (a subclass should override it to create an instance of its own type).

Enters a separate microtask queue: until the returned scope is disposed, the jobs of the engine and the microtasks queued with ScriptEngine.QueueMicrotask go to a new queue, which ScriptEngine.PerformMicrotaskCheckpoint runs; the microtasks that were pending are kept, and are not run in the scope. The scopes nest. A script is considered running in the scope (ScriptEngine.IsScriptRunning): the callbacks invoked in it perform no microtask checkpoint.

Runs a classic script (https://html.spec.whatwg.org/multipage/webappapis.html#run-a-classic-script) in the realm of ClassicScript.Global. The library owns the ordering of the scripts and the "clean up after running script" steps: the engine only evaluates the code.

Runs a module script (https://html.spec.whatwg.org/multipage/webappapis.html#run-a-module-script): links and evaluates the module graph, and reports the error to rethrow or the evaluation errors (including the errors of a top-level await) to the global object.

Extracts the information of an exception (https://html.spec.whatwg.org/multipage/webappapis.html#extract-error): its message, the location of the script, and the value of the error attribute of the ErrorEvent.

Fetches the graph of an external module script ("fetch a module script graph", https://html.spec.whatwg.org/multipage/webappapis.html#fetch-a-module-script-tree): the root is fetched ("fetch a single module script"), then its descendants are loaded. onComplete is called with the module script, or with null when a module of the graph cannot be fetched. A parse error is stored in ModuleScript.ErrorToRethrow.

Converts a value of the realm of a window to a .NET value, as the IDL type any: the wrapper object of a platform object is the .NET object (e.g. a Node), a string, a number and a boolean are the .NET values, undefined and null are null, and the other values (e.g. a plain object) are returned as they are.

Returns the base URL of the active script (https://html.spec.whatwg.org/multipage/webappapis.html#active-script), or null when no script is running: the base URL of the strings compiled by setTimeout() and setInterval().

Returns the fetch options of the active script (https://html.spec.whatwg.org/multipage/webappapis.html#active-script), or null when no script is running: the options of the modules imported by import() in a classic script.

The incumbent global object while a script runs (https://html.spec.whatwg.org/multipage/webappapis.html#incumbent): the global object of the realm of the code that calls the platform (e.g. the source of the messages of postMessage()), the code of the bindings runs in the realm of its caller.

Returns the location of the code that is running (the source file, line and column of the innermost running script), or null when no script is running or when the engine cannot extract it: the source location of the violations of the content security policies (https://w3c.github.io/webappsec-csp/#create-violation-for-global, step 2).

Gets whether a promise has a handler (its [[PromiseIsHandled]] internal slot). The promises rejected without handler are given to GlobalScope.TrackPromiseRejection by the engine.

Parses a module script and loads its descendants ("fetch the descendants of and link a module script", https://html.spec.whatwg.org/multipage/webappapis.html#fetch-the-descendants-of-and-link-a-module-script): the engine resolves the module specifiers and fetches the modules with the library. onComplete is called once the graph is loaded, with true, or with false when a module of the graph cannot be fetched (the script element then fires an error event). A parse error is stored in ModuleScript.ErrorToRethrow.

Called when the realm of a window is created, before a script runs in it: the host can add its own functions to the global object.

Parses a classic script (https://html.spec.whatwg.org/multipage/webappapis.html#creating-a-classic-script) without running it: returns the error to rethrow of a script that cannot be parsed (e.g. the SyntaxError of a worker script, which fires an error event at the Worker object instead of being reported), or null.

Runs the jobs of the engine and the microtasks queued with ScriptEngine.QueueMicrotask until the queue is empty (https://html.spec.whatwg.org/multipage/webappapis.html#perform-a-microtask-checkpoint). The exceptions of the jobs are reported by the engine.

Fetches a module script without loading its descendants nor running it ("fetch a modulepreload module script graph", https://html.spec.whatwg.org/multipage/webappapis.html#fetch-a-modulepreload-module-script-graph): the module of a <link rel=modulepreload> element. onComplete is called with true when the module is fetched (even when it has a parse error), or with false when it cannot be fetched.

https://html.spec.whatwg.org/multipage/webappapis.html#prepare-to-run-script: the JavaScript execution context stack is not empty until the returned scope is disposed, which cleans up after running script (a microtask checkpoint when the stack becomes empty). The callbacks invoked in the scope do not perform a microtask checkpoint.

Queues a microtask of the library (e.g. a mutation observer notification) in the job queue of the engine, so that the microtasks of the library and the jobs of the engine (promise reactions) run in order (https://html.spec.whatwg.org/multipage/webappapis.html#queue-a-microtask).

Deserializes a value serialized by ScriptEngine.StructuredSerialize in the realm of global (https://html.spec.whatwg.org/multipage/structured-data.html#structureddeserialize): the result is a new value of the realm (e.g. the MessageEvent.Data of the message events).

Serializes a value for another agent (https://html.spec.whatwg.org/multipage/structured-data.html#structuredserializewithtransfer), e.g. a message posted to a worker or to a MessagePort: the result is given to ScriptEngine.StructuredDeserialize of another engine instance, on another thread, so it must not reference the values of this engine. The objects of transferList are transferred: the ArrayBuffer objects of the engine, and the MessagePort objects.

Serializes a value for storage (https://html.spec.whatwg.org/multipage/structured-data.html#structuredserializeforstorage), e.g. the state of History.PushState: a SharedArrayBuffer throws a DataCloneError.

Converts a .NET value to a value of the realm of a window, as the IDL type any: a platform object (e.g. a Node, an Event) is its wrapper object, as the scripts of the window see it; a string, a number and a boolean are the primitive values; null is null.

Runs the success steps once all the values are fulfilled promises, or the failure steps with the reason of the first rejected one (https://webidl.spec.whatwg.org/#wait-for-all). The values are values of the engine, resolved as promises of the realm of global, or RejectedPromise for a promise rejected with an exception.