JsRealm Class
A realm (https://tc39.es/ecma262/#sec-code-realms): a global object, its global environment and the intrinsics.
public sealed class JsRealmProperties
| Name | Description |
|---|---|
| AbstractModuleSource | Gets %AbstractModuleSource% of the realm (https://tc39.es/proposal-source-phase-imports/#sec-abstractmodulesource-objects): the abstract class that the classes of the module source objects (e.g. WebAssembly.Module) extend. It is not a global. See JsModule.ModuleSource. |
| Engine | Gets the engine (the agent) of the realm. |
| FunctionPrototype | Gets %Function.prototype% of the realm. |
| GlobalObject | Gets the global object ([[GlobalObject]]). |
| GlobalThis | Gets the this value of the global code ([[GlobalThisValue]] of the global environment): the global object, unless the host set another object with JsRealm.SetGlobalThis. |
| ObjectPrototype | Gets %Object.prototype% of the realm. |
AbstractModuleSource
JsRealm.Public.csGets %AbstractModuleSource% of the realm (https://tc39.es/proposal-source-phase-imports/#sec-abstractmodulesource-objects): the abstract class that the classes of the module source objects (e.g. WebAssembly.Module) extend. It is not a global. See JsModule.ModuleSource.
public JsFunction AbstractModuleSource { get; }Property value
Engine
JsRealm.csFunctionPrototype
JsRealm.Public.csGlobalObject
JsRealm.csGlobalThis
JsRealm.csGets the this value of the global code ([[GlobalThisValue]] of the global environment): the global object, unless the host set another object with JsRealm.SetGlobalThis.
public JsValue GlobalThis { get; }Property value
ObjectPrototype
JsRealm.Public.csMethods
| Name | Description |
|---|---|
| CreateArray(ReadOnlySpan<JsValue>) | Creates an array (CreateArrayFromList). |
| CreateArrayBuffer(Memory<byte>, JsValue) | Creates an ArrayBuffer whose data block is memory (the bytes are shared, not copied). When detachKey is not undefined, the scripts cannot detach nor transfer the buffer (e.g. the buffer of a WebAssembly.Memory); JsBinaryData.DetachArrayBuffer detaches it with the key. |
| CreateArrayBuffer(ReadOnlySpan<byte>) | Creates an ArrayBuffer containing a copy of bytes. |
| CreateBufferView(JsBufferKind, JsObject, int, int) | Creates a typed array or a DataView viewing buffer. |
| CreateBytesModule(ReadOnlySpan<byte>, string?, object?) | Creates a bytes module (CreateBytesModule, the import bytes proposal): a module whose default export is a Uint8Array over an immutable ArrayBuffer that contains a copy of the bytes, imported with with { type: "bytes" }. |
| CreateConstructor(string, int, JsNativeConstructor) | Creates a built-in function that is a constructor; its prototype property is not defined. |
| CreateDate(double) | Creates a Date object. |
| CreateError(JsErrorType, string) | Creates a native error of the realm, with its stack trace. |
| CreateException(JsErrorType, string) | Creates the exception that throws a new native error of the realm. |
| CreateFunction(string, Action) | Creates a function that calls action and returns undefined (see JsRealm.CreateFunction). |
| CreateFunction(string, int, JsNativeFunction) | Creates a built-in function (CreateBuiltinFunction): its name and length are set; it is not a constructor. |
| CreateFunction(string, int, JsNativeFunction, bool) | Creates a built-in function (CreateBuiltinFunction): its name and length are set; it is not a constructor. |
| CreateFunction<T1>(string, Action<T1>) | Creates a function that calls action and returns undefined (see JsRealm.CreateFunction). |
| CreateFunction<TResult>(string, Func<TResult>) | Creates a function that calls function: the arguments are converted with JsEngine.ToDotNet, and the result with JsRealm.FromDotNet. A conversion that fails throws a TypeError (or a RangeError) to the script; the other exceptions of the function are not JavaScript errors (throw a JsException to throw a JavaScript error). |
| CreateFunction<T1, T2>(string, Action<T1, T2>) | Creates a function that calls action and returns undefined (see JsRealm.CreateFunction). |
| CreateFunction<T1, TResult>(string, Func<T1, TResult>) | Creates a function that calls function: the arguments are converted with JsEngine.ToDotNet, and the result with JsRealm.FromDotNet. A conversion that fails throws a TypeError (or a RangeError) to the script; the other exceptions of the function are not JavaScript errors (throw a JsException to throw a JavaScript error). |
| CreateFunction<T1, T2, TResult>(string, Func<T1, T2, TResult>) | Creates a function that calls function: the arguments are converted with JsEngine.ToDotNet, and the result with JsRealm.FromDotNet. A conversion that fails throws a TypeError (or a RangeError) to the script; the other exceptions of the function are not JavaScript errors (throw a JsException to throw a JavaScript error). |
| CreateFunction<T1, T2, T3, TResult>(string, Func<T1, T2, T3, TResult>) | Creates a function that calls function: the arguments are converted with JsEngine.ToDotNet, and the result with JsRealm.FromDotNet. A conversion that fails throws a TypeError (or a RangeError) to the script; the other exceptions of the function are not JavaScript errors (throw a JsException to throw a JavaScript error). |
| CreateJsonModule(string, string?, object?) | Creates a JSON module (ParseJSONModule): a module whose default export is the parsed JSON value. |
| CreateObject() | Creates an ordinary object whose prototype is %Object.prototype%. |
| CreateObject(JsObject?) | Creates an ordinary object (OrdinaryObjectCreate(proto)). |
| CreatePromise(Task) | Creates a promise of the realm that settles when the task completes: it is fulfilled with undefined, or rejected (see JsRealm.CreatePromise). |
| CreatePromise(Task<JsValue>) | Creates a promise of the realm that settles when the task completes (see JsRealm.CreatePromise). The value of the task must not be an object created out of the thread of the engine: use JsRealm.CreatePromise to create it when the promise settles. |
| CreatePromise<T>(Task<T>, Func<T, JsValue>) | Creates a promise of the realm that settles when the task completes. The task can complete on any thread: the engine settles the promise on its own thread, as work posted by JsEngine.Post, so the host runs the jobs (JsEngine.RunJobs, or JsEngine.RunUntilSettledAsync). The promise is:
|
| CreateSharedArrayBuffer(JsSharedDataBlock) | Creates a SharedArrayBuffer whose data is a Shared Data Block (e.g. the block of a SharedArrayBuffer of another engine). |
| CreateSyntheticModule(IEnumerable<string>, Action<JsSyntheticModule>, string?, object?) | Creates a synthetic module whose exports are set by evaluate with JsSyntheticModule.SetExport when the module is evaluated. |
| CreateTextModule(string, string?, object?) | Creates a text module (CreateTextModule, the import text proposal): a module whose default export is the text, imported with with { type: "text" }. |
| Evaluate(string) | Evaluates code in this realm as an indirect eval and returns its completion value. |
| Execute(JsPreparedScript, object?, bool) | Runs a prepared script in this realm (ScriptEvaluation) and returns its completion value. |
| Execute(string, string?) | Runs a script in this realm (ScriptEvaluation) and returns its completion value. |
| FromDotNet(object?) | Converts a .NET value to a JavaScript value, creating the objects in this realm:
|
| FromDotNet<T>(T) | Converts a .NET value of type T to a JavaScript value, as JsRealm.FromDotNet does (without boxing the primitive types). |
| ParseModule(string, string?, object?) | Parses a module (ParseModule). The module is then loaded, linked and evaluated with the methods of JsModule. |
| ParseModule(string, string?, object?, int, int) | Parses a module (ParseModule) whose source text is a part of a document (e.g. an inline module script of an HTML document). |
| SetGlobalThis(JsObject) | Sets the this value of the global code ([[GlobalThisValue]] of the global environment), the host-defined this value of InitializeHostDefinedRealm (https://tc39.es/ecma262/#sec-initializehostdefinedrealm): e.g. the WindowProxy of a window, whose global object is the Window. It is the this of the scripts, of the sloppy functions called without a this value and of the indirect evals, and the value of the globalThis property. Call it before any code runs in the realm. |
CreateArray(ReadOnlySpan<JsValue>)
JsRealm.Public.csCreates an array (CreateArrayFromList).
public JsArray CreateArray(ReadOnlySpan<JsValue> items)CreateArrayBuffer overloads
CreateArrayBuffer(Memory<byte>, JsValue)
JsRealm.Public.csCreates an ArrayBuffer whose data block is memory (the bytes are shared, not copied). When detachKey is not undefined, the scripts cannot detach nor transfer the buffer (e.g. the buffer of a WebAssembly.Memory); JsBinaryData.DetachArrayBuffer detaches it with the key.
CreateArrayBuffer(ReadOnlySpan<byte>)
JsRealm.Public.csCreates an ArrayBuffer containing a copy of bytes.
public JsObject CreateArrayBuffer(ReadOnlySpan<byte> bytes)CreateBufferView(JsBufferKind, JsObject, int, int)
JsRealm.Public.csCreates a typed array or a DataView viewing buffer.
public JsObject CreateBufferView(JsBufferKind kind, JsObject buffer, int byteOffset, int length)Parameters
kindJsBufferKind- The kind of view:
JsBufferKind.DataViewor a typed array. bufferJsObject- An ArrayBuffer or a SharedArrayBuffer.
byteOffsetint- The offset of the view in the buffer.
lengthint- The number of elements (the byte length of a DataView).
Returns
Exceptions
ArgumentException- The byte offset of a typed array is not a multiple of its element size.
ArgumentOutOfRangeException- The view does not fit in the buffer.
CreateBytesModule(ReadOnlySpan<byte>, string?, object?)
JsRealm.csCreates a bytes module (CreateBytesModule, the import bytes proposal): a module whose default export is a Uint8Array over an immutable ArrayBuffer that contains a copy of the bytes, imported with with { type: "bytes" }.
public JsSyntheticModule CreateBytesModule(ReadOnlySpan<byte> bytes, string? url = null, object? hostDefined = null)Parameters
bytesReadOnlySpan<byte>urlstring?hostDefinedobject?
Returns
Exceptions
JsException- The ArrayBuffer cannot be allocated (a RangeError).
CreateConstructor(string, int, JsNativeConstructor)
JsRealm.Public.csCreates a built-in function that is a constructor; its prototype property is not defined.
public JsFunction CreateConstructor(string name, int length, JsNativeConstructor constructor)CreateDate(double)
JsRealm.Public.csCreateError(JsErrorType, string)
JsRealm.Public.csCreates a native error of the realm, with its stack trace.
public JsObject CreateError(JsErrorType type, string message)CreateException(JsErrorType, string)
JsRealm.Public.csCreates the exception that throws a new native error of the realm.
public JsException CreateException(JsErrorType type, string message)CreateFunction overloads
CreateFunction(string, Action)
JsMarshalling.csCreates a function that calls action and returns undefined (see JsRealm.CreateFunction).
public JsFunction CreateFunction(string name, Action action)Parameters
Returns
Exceptions
NotSupportedException- A type of the delegate is not supported by the conversions.
CreateFunction(string, int, JsNativeFunction)
JsRealm.Public.csCreates a built-in function (CreateBuiltinFunction): its name and length are set; it is not a constructor.
public JsFunction CreateFunction(string name, int length, JsNativeFunction function)CreateFunction(string, int, JsNativeFunction, bool)
JsRealm.Public.csCreates a built-in function (CreateBuiltinFunction): its name and length are set; it is not a constructor.
public JsFunction CreateFunction(string name, int length, JsNativeFunction function, bool runInCallerRealm)Parameters
namestring- The name of the function.
lengthint- The number of parameters of the function.
functionJsNativeFunction- The implementation of the function.
runInCallerRealmbool- Whether the current realm while the function runs is the realm of its caller instead of the realm of the function (
JsEngine.CurrentRealm, the realm of the objects created by the built-ins and the API): e.g. a function that implements an internal method of an exotic object (the traps of a proxy), which runs in the realm of the code that uses the object, or the functions of a host whose objects are created in the realm of the calling code.
Returns
CreateFunction<T1>(string, Action<T1>)
JsMarshalling.csCreates a function that calls action and returns undefined (see JsRealm.CreateFunction).
public JsFunction CreateFunction<T1>(string name, Action<T1> action)Type parameters
T1
Parameters
namestringactionAction<T1>
Returns
Exceptions
NotSupportedException- A type of the delegate is not supported by the conversions.
CreateFunction<TResult>(string, Func<TResult>)
JsMarshalling.csCreates a function that calls function: the arguments are converted with JsEngine.ToDotNet, and the result with JsRealm.FromDotNet. A conversion that fails throws a TypeError (or a RangeError) to the script; the other exceptions of the function are not JavaScript errors (throw a JsException to throw a JavaScript error).
public JsFunction CreateFunction<TResult>(string name, Func<TResult> function)Type parameters
TResult
Parameters
namestringfunctionFunc<TResult>
Returns
Exceptions
NotSupportedException- A type of the delegate is not supported by the conversions.
CreateFunction<T1, T2>(string, Action<T1, T2>)
JsMarshalling.csCreates a function that calls action and returns undefined (see JsRealm.CreateFunction).
public JsFunction CreateFunction<T1, T2>(string name, Action<T1, T2> action)Type parameters
T1T2
Parameters
namestringactionAction<T1, T2>
Returns
Exceptions
NotSupportedException- A type of the delegate is not supported by the conversions.
CreateFunction<T1, TResult>(string, Func<T1, TResult>)
JsMarshalling.csCreates a function that calls function: the arguments are converted with JsEngine.ToDotNet, and the result with JsRealm.FromDotNet. A conversion that fails throws a TypeError (or a RangeError) to the script; the other exceptions of the function are not JavaScript errors (throw a JsException to throw a JavaScript error).
public JsFunction CreateFunction<T1, TResult>(string name, Func<T1, TResult> function)Type parameters
T1TResult
Parameters
namestringfunctionFunc<T1, TResult>
Returns
Exceptions
NotSupportedException- A type of the delegate is not supported by the conversions.
CreateFunction<T1, T2, TResult>(string, Func<T1, T2, TResult>)
JsMarshalling.csCreates a function that calls function: the arguments are converted with JsEngine.ToDotNet, and the result with JsRealm.FromDotNet. A conversion that fails throws a TypeError (or a RangeError) to the script; the other exceptions of the function are not JavaScript errors (throw a JsException to throw a JavaScript error).
public JsFunction CreateFunction<T1, T2, TResult>(string name, Func<T1, T2, TResult> function)Type parameters
T1T2TResult
Parameters
namestringfunctionFunc<T1, T2, TResult>
Returns
Exceptions
NotSupportedException- A type of the delegate is not supported by the conversions.
CreateFunction<T1, T2, T3, TResult>(string, Func<T1, T2, T3, TResult>)
JsMarshalling.csCreates a function that calls function: the arguments are converted with JsEngine.ToDotNet, and the result with JsRealm.FromDotNet. A conversion that fails throws a TypeError (or a RangeError) to the script; the other exceptions of the function are not JavaScript errors (throw a JsException to throw a JavaScript error).
public JsFunction CreateFunction<T1, T2, T3, TResult>(string name, Func<T1, T2, T3, TResult> function)Type parameters
T1T2T3TResult
Parameters
namestringfunctionFunc<T1, T2, T3, TResult>
Returns
Exceptions
NotSupportedException- A type of the delegate is not supported by the conversions.
CreateJsonModule(string, string?, object?)
JsRealm.csCreates a JSON module (ParseJSONModule): a module whose default export is the parsed JSON value.
public JsSyntheticModule CreateJsonModule(string json, string? url = null, object? hostDefined = null)CreatePromise overloads
CreatePromise(Task)
JsEngine.Async.csCreates a promise of the realm that settles when the task completes: it is fulfilled with undefined, or rejected (see JsRealm.CreatePromise).
CreatePromise(Task<JsValue>)
JsEngine.Async.csCreates a promise of the realm that settles when the task completes (see JsRealm.CreatePromise). The value of the task must not be an object created out of the thread of the engine: use JsRealm.CreatePromise to create it when the promise settles.
CreatePromise<T>(Task<T>, Func<T, JsValue>)
JsEngine.Async.csCreates a promise of the realm that settles when the task completes. The task can complete on any thread: the engine settles the promise on its own thread, as work posted by JsEngine.Post, so the host runs the jobs (JsEngine.RunJobs, or JsEngine.RunUntilSettledAsync). The promise is:
- fulfilled with the result converted by
convertResult, which runs on the thread of the engine (it can create objects); - rejected with the value of a
JsExceptionthrown by the task or byconvertResult; - rejected with an
Errorwhose message is the message of any other exception, or of theOperationCanceledExceptionof a canceled task.
When the engine is disposed before the task completes, the promise stays pending.
CreateSyntheticModule(IEnumerable<string>, Action<JsSyntheticModule>, string?, object?)
JsRealm.csCreates a synthetic module whose exports are set by evaluate with JsSyntheticModule.SetExport when the module is evaluated.
public JsSyntheticModule CreateSyntheticModule(IEnumerable<string> exportNames, Action<JsSyntheticModule> evaluate, string? url = null, object? hostDefined = null)Parameters
exportNamesIEnumerable<string>evaluateAction<JsSyntheticModule>urlstring?hostDefinedobject?
Returns
CreateTextModule(string, string?, object?)
JsRealm.csCreates a text module (CreateTextModule, the import text proposal): a module whose default export is the text, imported with with { type: "text" }.
public JsSyntheticModule CreateTextModule(string text, string? url = null, object? hostDefined = null)Evaluate(string)
JsRealm.csEvaluates code in this realm as an indirect eval and returns its completion value.
Parameters
codestring
Returns
Exceptions
JsException- The code threw an exception (a SyntaxError for invalid code).
Execute overloads
Execute(JsPreparedScript, object?, bool)
JsRealm.csRuns a prepared script in this realm (ScriptEvaluation) and returns its completion value.
public JsValue Execute(JsPreparedScript script, object? hostDefined = null, bool mutedErrors = false)Parameters
scriptJsPreparedScript- The script.
hostDefinedobject?- The data of the host associated with the script ([[HostDefined]]).
mutedErrorsbool- Whether the errors of the script are muted (a cross-origin script fetched without CORS).
Returns
Exceptions
JsException- The script threw an exception.
Execute(string, string?)
JsRealm.csRuns a script in this realm (ScriptEvaluation) and returns its completion value.
Parameters
codestring- The source text of the script.
urlstring?- The URL (or file name) of the script, used in the stack traces and the error locations.
Returns
Exceptions
JsException- The script threw an exception (a SyntaxError for an invalid script).
FromDotNet overloads
FromDotNet(object?)
JsMarshalling.csConverts a .NET value to a JavaScript value, creating the objects in this realm:
- null is
null; aJsValueand aJsObjectare not converted; - a boolean, a string and a char are a boolean and a string; the numeric types are a number (a
Int64or aDecimalmay lose precision), aBigIntegeris a BigInt; - a
DateTimeOffsetand aDateTimeare a Date (aDateTimewhose kind is unspecified is a UTC date); - a
JsonElementand aJsonNodeare the value thatJSON.parsewould create; - a dictionary whose keys are strings (
IDictionary<TKey, TValue>,IReadOnlyDictionary<TKey, TValue>orIDictionary) is an ordinary object; - any other
IEnumerableis an array.
The values of the collections are converted recursively.
Parameters
valueobject?
Returns
Exceptions
NotSupportedException- The value, or a value of a collection, has a type that cannot be converted (e.g. a delegate or a class: use
JsHostObjectorJsRealm.CreateFunction). InvalidOperationException- The value contains a cycle, or no engine is entered on the thread.
FromDotNet<T>(T)
JsMarshalling.csConverts a .NET value of type T to a JavaScript value, as JsRealm.FromDotNet does (without boxing the primitive types).
public JsValue FromDotNet<T>(T value)Type parameters
T
Parameters
valueT
Returns
Exceptions
NotSupportedException- The value has a type that cannot be converted.
InvalidOperationException- The value contains a cycle, or no engine is entered on the thread.
ParseModule overloads
ParseModule(string, string?, object?)
JsRealm.csParses a module (ParseModule). The module is then loaded, linked and evaluated with the methods of JsModule.
public JsSourceTextModule ParseModule(string code, string? url = null, object? hostDefined = null)Parameters
codestring- The source text of the module.
urlstring?- The URL (or file name) of the module, used to resolve its imports and in the stack traces.
hostDefinedobject?- The data of the host associated with the module.
Returns
Exceptions
JsException- The module is not valid (a SyntaxError).
ParseModule(string, string?, object?, int, int)
JsRealm.csParses a module (ParseModule) whose source text is a part of a document (e.g. an inline module script of an HTML document).
public JsSourceTextModule ParseModule(string code, string? url, object? hostDefined, int lineOffset, int columnOffset)Parameters
codestring- The source text of the module.
urlstring?- The URL (or file name) of the module, used to resolve its imports and in the stack traces.
hostDefinedobject?- The data of the host associated with the module.
lineOffsetint- The number of lines before the code in its document.
columnOffsetint- The column of the code in the first line of its document (0-based).
Returns
Exceptions
JsException- The module is not valid (a SyntaxError, located at the error).
SetGlobalThis(JsObject)
JsRealm.csSets the this value of the global code ([[GlobalThisValue]] of the global environment), the host-defined this value of InitializeHostDefinedRealm (https://tc39.es/ecma262/#sec-initializehostdefinedrealm): e.g. the WindowProxy of a window, whose global object is the Window. It is the this of the scripts, of the sloppy functions called without a this value and of the indirect evals, and the value of the globalThis property. Call it before any code runs in the realm.
Parameters
thisValueJsObject- The object.