Meziantou.Framework

NodeJsHost Class

Namespace
Meziantou.Framework.NodeJs
Assembly
Meziantou.Framework.NodeJs.dll
Package
Meziantou.Framework.NodeJs 1.0.4
Source
NodeJsHost.cs
Available in package assets
net10.0net11.0

Hosts a Node.js process and runs JavaScript code in it.

public sealed class NodeJsHost : IAsyncDisposable

Remarks

The Node.js process runs out of process and communicates with the host using JSON messages over a private local socket. Arguments and results are serialized as JSON.

Calls can run concurrently. They run on the main thread of the process, or on worker threads when NodeJsHostOptions.WorkerThreads is set, so CPU-bound calls run in parallel. The Node.js process exits when the host is disposed, or when the connection with the .NET process is closed (e.g. when the .NET process exits) unless its event loop is blocked. Its standard input is closed, and its standard output and error are only passed to NodeJsHostOptions.StandardOutputReceived and NodeJsHostOptions.StandardErrorReceived.

Example

await using var node = await NodeJsHost.StartAsync();

// Evaluate code as the body of an async function
var sum = await node.EvaluateAsync("return 1 + 2;");
Assert.Equal(3, sum.GetInt32());

// Call a function exported by a module: a file, a package, or a built-in module
var text = await node.InvokeAsync("node:util", "format", ["%s has %d items", "cart", 3]);
Assert.Equal("cart has 3 items", text.GetString());
Implements

Properties

NameDescription
NodeVersionGets the version of Node.js, as reported by process.version (e.g. v24.15.0).
ProcessIdGets the identifier of the Node.js process.

NodeVersion

NodeJsHost.cs

Gets the version of Node.js, as reported by process.version (e.g. v24.15.0).

public string NodeVersion { get; }

Property value

string

ProcessId

NodeJsHost.cs

Gets the identifier of the Node.js process.

public int ProcessId { get; }

Property value

int

Remarks

The identifier remains available once the process exits or the host is disposed.

Methods

NameDescription
CreateInstanceAsync(string, string?, IReadOnlyList<JsonNode?>?, CancellationToken)Imports a module, creates an instance of one of its exported classes (new), and keeps the instance in the Node.js process.
CreateInstanceAsync(string, string?, object?[]?, JsonSerializerOptions?, CancellationToken)Imports a module, creates an instance of one of its exported classes (new), and keeps the instance in the Node.js process. Arguments are serialized using reflection.
DisposeAsync()Stops the Node.js process. Pending calls fail with ObjectDisposedException.
EvaluateAsync(string, IReadOnlyList<JsonNode?>?, CancellationToken)Evaluates JavaScript code as the body of an async function that receives arguments.
EvaluateAsync(string, CancellationToken)Evaluates JavaScript code as the body of an async function.
EvaluateAsync<T>(string, IReadOnlyList<JsonNode?>?, JsonTypeInfo<T>, CancellationToken)Evaluates JavaScript code as the body of an async function that receives arguments, and deserializes the result.
EvaluateAsync<T>(string, object?[]?, JsonSerializerOptions?, CancellationToken)Evaluates JavaScript code as the body of an async function that receives arguments, and deserializes the result. Arguments are serialized using reflection.
EvaluateAsync<T>(string, JsonSerializerOptions?, CancellationToken)Evaluates JavaScript code as the body of an async function and deserializes the result using reflection.
EvaluateAsync<T>(string, JsonTypeInfo<T>, CancellationToken)Evaluates JavaScript code as the body of an async function and deserializes the result.
EvaluateAsync<T>(string, CancellationToken)Evaluates JavaScript code as the body of an async function and deserializes the result using reflection.
EvaluateReferenceAsync(string, IReadOnlyList<JsonNode?>?, CancellationToken)Evaluates JavaScript code as the body of an async function that receives arguments, and keeps the result in the Node.js process.
EvaluateReferenceAsync(string, object?[]?, JsonSerializerOptions?, CancellationToken)Evaluates JavaScript code as the body of an async function that receives arguments, and keeps the result in the Node.js process. Arguments are serialized using reflection.
EvaluateReferenceAsync(string, CancellationToken)Evaluates JavaScript code as the body of an async function, and keeps the result in the Node.js process.
EvaluateVoidAsync(string, IReadOnlyList<JsonNode?>?, CancellationToken)Evaluates JavaScript code as the body of an async function that receives arguments, ignoring its result. The result does not need to be serializable.
EvaluateVoidAsync(string, object?[]?, JsonSerializerOptions?, CancellationToken)Evaluates JavaScript code as the body of an async function that receives arguments, ignoring its result. Arguments are serialized using reflection.
EvaluateVoidAsync(string, CancellationToken)Evaluates JavaScript code as the body of an async function, ignoring its result. The result does not need to be serializable.
InvokeAsync(string, string?, IReadOnlyList<JsonNode?>?, CancellationToken)Imports a module and calls one of its exports.
InvokeAsync<T>(string, string?, IReadOnlyList<JsonNode?>?, JsonTypeInfo<T>, CancellationToken)Imports a module, calls one of its exports, and deserializes the result.
InvokeAsync<T>(string, string?, object?[]?, JsonSerializerOptions?, CancellationToken)Imports a module, calls one of its exports, and deserializes the result. Arguments are serialized using reflection.
InvokeAsync<T>(string, string?, CancellationToken)Imports a module, calls one of its exports without arguments, and deserializes the result using reflection.
InvokeReferenceAsync(string, string?, IReadOnlyList<JsonNode?>?, CancellationToken)Imports a module, calls one of its exports, and keeps the result in the Node.js process.
InvokeReferenceAsync(string, string?, object?[]?, JsonSerializerOptions?, CancellationToken)Imports a module, calls one of its exports, and keeps the result in the Node.js process. Arguments are serialized using reflection.
InvokeVoidAsync(string, string?, IReadOnlyList<JsonNode?>?, CancellationToken)Imports a module and calls one of its exports, ignoring its result. The result does not need to be serializable.
InvokeVoidAsync(string, string?, object?[]?, JsonSerializerOptions?, CancellationToken)Imports a module and calls one of its exports, ignoring its result. Arguments are serialized using reflection.
StartAsync(NodeJsHostOptions?, CancellationToken)Starts a new Node.js process.

CreateInstanceAsync overloads

CreateInstanceAsync(string, string?, IReadOnlyList<JsonNode?>?, CancellationToken)

NodeJsHost.cs

Imports a module, creates an instance of one of its exported classes (new), and keeps the instance in the Node.js process.

public Task<JSReference> CreateInstanceAsync(string module, string? exportName, IReadOnlyList<JsonNode?>? arguments = null, CancellationToken cancellationToken = default)
Parameters
module string
The module specifier, as used by import(): an npm package name, a relative path starting with ./ or ../ and including the file extension, resolved from NodeJsHostOptions.WorkingDirectory, an absolute path, or a file: or node: URL. A module is loaded once, and kept for the lifetime of the process.
exportName string?
The name of the exported class or constructor function. When null, the default export is used.
arguments IReadOnlyList<JsonNode?>?
The arguments passed to the constructor. Use JSValue for values that JSON cannot represent, and JSReference to pass a value kept in the Node.js process.
cancellationToken CancellationToken
A token to stop waiting for the result. The JavaScript code keeps running.
Returns

Task<JSReference> A reference to the new instance. Dispose it when the instance is no longer needed.

Exceptions
NodeJsException
The export is not a constructor, the constructor throws, or the Node.js process exits.

CreateInstanceAsync(string, string?, object?[]?, JsonSerializerOptions?, CancellationToken)

NodeJsHost.cs

Imports a module, creates an instance of one of its exported classes (new), and keeps the instance in the Node.js process. Arguments are serialized using reflection.

[RequiresDynamicCode("JSON serialization and deserialization might require types that cannot be statically analyzed and might need runtime code generation. Use the overload that takes a JsonTypeInfo instead.")]
[RequiresUnreferencedCode("JSON serialization and deserialization might require types that cannot be statically analyzed. Use the overload that takes a JsonTypeInfo instead.")]
public Task<JSReference> CreateInstanceAsync(string module, string? exportName, object?[]? arguments, JsonSerializerOptions? options, CancellationToken cancellationToken = default)
Parameters
module string
The module specifier, as used by import(): an npm package name, a relative path starting with ./ or ../ and including the file extension, resolved from NodeJsHostOptions.WorkingDirectory, an absolute path, or a file: or node: URL. A module is loaded once, and kept for the lifetime of the process.
exportName string?
The name of the exported class or constructor function. When null, the default export is used.
arguments object?[]?
The arguments passed to the constructor. Use JSValue for values that JSON cannot represent, and JSReference to pass a value kept in the Node.js process.
options JsonSerializerOptions?
A token to stop waiting for the result. The JavaScript code keeps running.
cancellationToken CancellationToken
Returns

Task<JSReference> A reference to the new instance. Dispose it when the instance is no longer needed.

Exceptions
NodeJsException
The export is not a constructor, the constructor throws, or the Node.js process exits.

DisposeAsync()

NodeJsHost.cs

Stops the Node.js process. Pending calls fail with ObjectDisposedException.

net10.0

public ValueTask DisposeAsync()

net11.0

public ValueTask DisposeAsync()

Returns

ValueTask

EvaluateAsync overloads

EvaluateAsync(string, IReadOnlyList<JsonNode?>?, CancellationToken)

NodeJsHost.cs

Evaluates JavaScript code as the body of an async function that receives arguments.

public Task<JsonElement> EvaluateAsync(string code, IReadOnlyList<JsonNode?>? arguments, CancellationToken cancellationToken = default)
Parameters
code string
The body of the function. The arguments are available in the args array. Use return to return a value and await to wait for promises. require is available, and values stored on globalThis persist across calls.
arguments IReadOnlyList<JsonNode?>?
The arguments, available in the args array. Pass values as arguments instead of inserting them in the code, so they cannot change the code. Use JSValue for values that JSON cannot represent, and JSReference to pass a value kept in the Node.js process.
cancellationToken CancellationToken
A token to stop waiting for the result. The JavaScript code keeps running.
Returns

Task<JsonElement> The JSON representation of the returned value. BigInt values are exact JSON numbers (Node.js 21 or later).

Exceptions
NodeJsException
The JavaScript code throws, or the Node.js process exits.

EvaluateAsync(string, CancellationToken)

NodeJsHost.cs

Evaluates JavaScript code as the body of an async function.

public Task<JsonElement> EvaluateAsync(string code, CancellationToken cancellationToken = default)
Parameters
code string
The body of the function. Use return to return a value and await to wait for promises. require is available, and values stored on globalThis persist across calls.
cancellationToken CancellationToken
A token to stop waiting for the result. The JavaScript code keeps running.
Returns

Task<JsonElement> The JSON representation of the returned value. BigInt values are exact JSON numbers (Node.js 21 or later).

Exceptions
NodeJsException
The JavaScript code throws, or the Node.js process exits.

EvaluateAsync<T>(string, IReadOnlyList<JsonNode?>?, JsonTypeInfo<T>, CancellationToken)

NodeJsHost.cs

Evaluates JavaScript code as the body of an async function that receives arguments, and deserializes the result.

net10.0

public Task<T?> EvaluateAsync<T>(string code, IReadOnlyList<JsonNode?>? arguments, JsonTypeInfo<T> resultTypeInfo, CancellationToken cancellationToken = default)

net11.0

public Task<T?> EvaluateAsync<T>(string code, IReadOnlyList<JsonNode?>? arguments, JsonTypeInfo<T> resultTypeInfo, CancellationToken cancellationToken = default)
Type parameters
T
Parameters
code string
The body of the function. The arguments are available in the args array. Use return to return a value and await to wait for promises. require is available, and values stored on globalThis persist across calls.
arguments IReadOnlyList<JsonNode?>?
The arguments, available in the args array. Pass values as arguments instead of inserting them in the code, so they cannot change the code. Use JSValue for values that JSON cannot represent, and JSReference to pass a value kept in the Node.js process.
resultTypeInfo JsonTypeInfo<T>
A token to stop waiting for the result. The JavaScript code keeps running.
cancellationToken CancellationToken
Returns

Task<T?> The JSON representation of the returned value. BigInt values are exact JSON numbers (Node.js 21 or later).

Exceptions
JsonException
The result cannot be deserialized to T.

EvaluateAsync<T>(string, object?[]?, JsonSerializerOptions?, CancellationToken)

NodeJsHost.cs

Evaluates JavaScript code as the body of an async function that receives arguments, and deserializes the result. Arguments are serialized using reflection.

net10.0

[RequiresDynamicCode("JSON serialization and deserialization might require types that cannot be statically analyzed and might need runtime code generation. Use the overload that takes a JsonTypeInfo instead.")]
[RequiresUnreferencedCode("JSON serialization and deserialization might require types that cannot be statically analyzed. Use the overload that takes a JsonTypeInfo instead.")]
public Task<T?> EvaluateAsync<T>(string code, object?[]? arguments, JsonSerializerOptions? options = null, CancellationToken cancellationToken = default)

net11.0

[RequiresDynamicCode("JSON serialization and deserialization might require types that cannot be statically analyzed and might need runtime code generation. Use the overload that takes a JsonTypeInfo instead.")]
[RequiresUnreferencedCode("JSON serialization and deserialization might require types that cannot be statically analyzed. Use the overload that takes a JsonTypeInfo instead.")]
public Task<T?> EvaluateAsync<T>(string code, object?[]? arguments, JsonSerializerOptions? options = null, CancellationToken cancellationToken = default)
Type parameters
T
Parameters
code string
The body of the function. The arguments are available in the args array. Use return to return a value and await to wait for promises. require is available, and values stored on globalThis persist across calls.
arguments object?[]?
The arguments, available in the args array. Pass values as arguments instead of inserting them in the code, so they cannot change the code. Use JSValue for values that JSON cannot represent, and JSReference to pass a value kept in the Node.js process.
options JsonSerializerOptions?
A token to stop waiting for the result. The JavaScript code keeps running.
cancellationToken CancellationToken
Returns

Task<T?> The JSON representation of the returned value. BigInt values are exact JSON numbers (Node.js 21 or later).

Exceptions
JsonException
The result cannot be deserialized to T.

EvaluateAsync<T>(string, JsonSerializerOptions?, CancellationToken)

NodeJsHost.cs

Evaluates JavaScript code as the body of an async function and deserializes the result using reflection.

net10.0

[RequiresDynamicCode("JSON deserialization might require types that cannot be statically analyzed and might need runtime code generation. Use the overload that takes a JsonTypeInfo instead.")]
[RequiresUnreferencedCode("JSON deserialization might require types that cannot be statically analyzed. Use the overload that takes a JsonTypeInfo instead.")]
public Task<T?> EvaluateAsync<T>(string code, JsonSerializerOptions? options = null, CancellationToken cancellationToken = default)

net11.0

[RequiresDynamicCode("JSON deserialization might require types that cannot be statically analyzed and might need runtime code generation. Use the overload that takes a JsonTypeInfo instead.")]
[RequiresUnreferencedCode("JSON deserialization might require types that cannot be statically analyzed. Use the overload that takes a JsonTypeInfo instead.")]
public Task<T?> EvaluateAsync<T>(string code, JsonSerializerOptions? options = null, CancellationToken cancellationToken = default)
Type parameters
T
Parameters
code string
The body of the function. Use return to return a value and await to wait for promises. require is available, and values stored on globalThis persist across calls.
options JsonSerializerOptions?
A token to stop waiting for the result. The JavaScript code keeps running.
cancellationToken CancellationToken
Returns

Task<T?> The JSON representation of the returned value. BigInt values are exact JSON numbers (Node.js 21 or later).

Exceptions
JsonException
The result cannot be deserialized to T.

EvaluateAsync<T>(string, JsonTypeInfo<T>, CancellationToken)

NodeJsHost.cs

Evaluates JavaScript code as the body of an async function and deserializes the result.

net10.0

public Task<T?> EvaluateAsync<T>(string code, JsonTypeInfo<T> resultTypeInfo, CancellationToken cancellationToken = default)

net11.0

public Task<T?> EvaluateAsync<T>(string code, JsonTypeInfo<T> resultTypeInfo, CancellationToken cancellationToken = default)
Type parameters
T
Parameters
code string
The body of the function. Use return to return a value and await to wait for promises. require is available, and values stored on globalThis persist across calls.
resultTypeInfo JsonTypeInfo<T>
A token to stop waiting for the result. The JavaScript code keeps running.
cancellationToken CancellationToken
Returns

Task<T?> The JSON representation of the returned value. BigInt values are exact JSON numbers (Node.js 21 or later).

Exceptions
JsonException
The result cannot be deserialized to T.

EvaluateAsync<T>(string, CancellationToken)

NodeJsHost.cs

Evaluates JavaScript code as the body of an async function and deserializes the result using reflection.

[RequiresDynamicCode("JSON deserialization might require types that cannot be statically analyzed and might need runtime code generation. Use the overload that takes a JsonTypeInfo instead.")]
[RequiresUnreferencedCode("JSON deserialization might require types that cannot be statically analyzed. Use the overload that takes a JsonTypeInfo instead.")]
public Task<T?> EvaluateAsync<T>(string code, CancellationToken cancellationToken)
Type parameters
T
Parameters
code string
The body of the function. Use return to return a value and await to wait for promises. require is available, and values stored on globalThis persist across calls.
cancellationToken CancellationToken
A token to stop waiting for the result. The JavaScript code keeps running.
Returns

Task<T?> The JSON representation of the returned value. BigInt values are exact JSON numbers (Node.js 21 or later).

Exceptions
JsonException
The result cannot be deserialized to T.

EvaluateReferenceAsync overloads

EvaluateReferenceAsync(string, IReadOnlyList<JsonNode?>?, CancellationToken)

NodeJsHost.cs

Evaluates JavaScript code as the body of an async function that receives arguments, and keeps the result in the Node.js process.

public Task<JSReference> EvaluateReferenceAsync(string code, IReadOnlyList<JsonNode?>? arguments, CancellationToken cancellationToken = default)
Parameters
code string
The body of the function. The arguments are available in the args array. Use return to return a value and await to wait for promises. require is available, and values stored on globalThis persist across calls.
arguments IReadOnlyList<JsonNode?>?
The arguments, available in the args array. Pass values as arguments instead of inserting them in the code, so they cannot change the code. Use JSValue for values that JSON cannot represent, and JSReference to pass a value kept in the Node.js process.
cancellationToken CancellationToken
A token to stop waiting for the result. The JavaScript code keeps running.
Returns

Task<JSReference> A reference to the returned value. Dispose it when the value is no longer needed.

Exceptions
NodeJsException
The JavaScript code throws, or the Node.js process exits.

EvaluateReferenceAsync(string, object?[]?, JsonSerializerOptions?, CancellationToken)

NodeJsHost.cs

Evaluates JavaScript code as the body of an async function that receives arguments, and keeps the result in the Node.js process. Arguments are serialized using reflection.

[RequiresDynamicCode("JSON serialization and deserialization might require types that cannot be statically analyzed and might need runtime code generation. Use the overload that takes a JsonTypeInfo instead.")]
[RequiresUnreferencedCode("JSON serialization and deserialization might require types that cannot be statically analyzed. Use the overload that takes a JsonTypeInfo instead.")]
public Task<JSReference> EvaluateReferenceAsync(string code, object?[]? arguments, JsonSerializerOptions? options, CancellationToken cancellationToken = default)
Parameters
code string
The body of the function. The arguments are available in the args array. Use return to return a value and await to wait for promises. require is available, and values stored on globalThis persist across calls.
arguments object?[]?
The arguments, available in the args array. Pass values as arguments instead of inserting them in the code, so they cannot change the code. Use JSValue for values that JSON cannot represent, and JSReference to pass a value kept in the Node.js process.
options JsonSerializerOptions?
A token to stop waiting for the result. The JavaScript code keeps running.
cancellationToken CancellationToken
Returns

Task<JSReference> A reference to the returned value. Dispose it when the value is no longer needed.

Exceptions
NodeJsException
The JavaScript code throws, or the Node.js process exits.

EvaluateReferenceAsync(string, CancellationToken)

NodeJsHost.cs

Evaluates JavaScript code as the body of an async function, and keeps the result in the Node.js process.

public Task<JSReference> EvaluateReferenceAsync(string code, CancellationToken cancellationToken = default)
Parameters
code string
The body of the function. Use return to return a value and await to wait for promises. require is available, and values stored on globalThis persist across calls.
cancellationToken CancellationToken
A token to stop waiting for the result. The JavaScript code keeps running.
Returns

Task<JSReference> A reference to the returned value. Dispose it when the value is no longer needed.

Exceptions
NodeJsException
The JavaScript code throws, or the Node.js process exits.

EvaluateVoidAsync overloads

EvaluateVoidAsync(string, IReadOnlyList<JsonNode?>?, CancellationToken)

NodeJsHost.cs

Evaluates JavaScript code as the body of an async function that receives arguments, ignoring its result. The result does not need to be serializable.

public Task EvaluateVoidAsync(string code, IReadOnlyList<JsonNode?>? arguments, CancellationToken cancellationToken = default)
Parameters
code string
The body of the function. The arguments are available in the args array. Use return to return a value and await to wait for promises. require is available, and values stored on globalThis persist across calls.
arguments IReadOnlyList<JsonNode?>?
The arguments, available in the args array. Pass values as arguments instead of inserting them in the code, so they cannot change the code. Use JSValue for values that JSON cannot represent, and JSReference to pass a value kept in the Node.js process.
cancellationToken CancellationToken
A token to stop waiting for the result. The JavaScript code keeps running.
Returns

Task The JSON representation of the returned value. BigInt values are exact JSON numbers (Node.js 21 or later).

Exceptions
NodeJsException
The JavaScript code throws, or the Node.js process exits.

EvaluateVoidAsync(string, object?[]?, JsonSerializerOptions?, CancellationToken)

NodeJsHost.cs

Evaluates JavaScript code as the body of an async function that receives arguments, ignoring its result. Arguments are serialized using reflection.

[RequiresDynamicCode("JSON serialization and deserialization might require types that cannot be statically analyzed and might need runtime code generation. Use the overload that takes a JsonTypeInfo instead.")]
[RequiresUnreferencedCode("JSON serialization and deserialization might require types that cannot be statically analyzed. Use the overload that takes a JsonTypeInfo instead.")]
public Task EvaluateVoidAsync(string code, object?[]? arguments, JsonSerializerOptions? options, CancellationToken cancellationToken = default)
Parameters
code string
The body of the function. The arguments are available in the args array. Use return to return a value and await to wait for promises. require is available, and values stored on globalThis persist across calls.
arguments object?[]?
The arguments, available in the args array. Pass values as arguments instead of inserting them in the code, so they cannot change the code. Use JSValue for values that JSON cannot represent, and JSReference to pass a value kept in the Node.js process.
options JsonSerializerOptions?
A token to stop waiting for the result. The JavaScript code keeps running.
cancellationToken CancellationToken
Returns

Task The JSON representation of the returned value. BigInt values are exact JSON numbers (Node.js 21 or later).

Exceptions
NodeJsException
The JavaScript code throws, or the Node.js process exits.

EvaluateVoidAsync(string, CancellationToken)

NodeJsHost.cs

Evaluates JavaScript code as the body of an async function, ignoring its result. The result does not need to be serializable.

public Task EvaluateVoidAsync(string code, CancellationToken cancellationToken = default)
Parameters
code string
The body of the function. Use return to return a value and await to wait for promises. require is available, and values stored on globalThis persist across calls.
cancellationToken CancellationToken
A token to stop waiting for the result. The JavaScript code keeps running.
Returns

Task The JSON representation of the returned value. BigInt values are exact JSON numbers (Node.js 21 or later).

Exceptions
NodeJsException
The JavaScript code throws, or the Node.js process exits.

InvokeAsync overloads

InvokeAsync(string, string?, IReadOnlyList<JsonNode?>?, CancellationToken)

NodeJsHost.cs

Imports a module and calls one of its exports.

public Task<JsonElement> InvokeAsync(string module, string? exportName, IReadOnlyList<JsonNode?>? arguments = null, CancellationToken cancellationToken = default)
Parameters
module string
The module specifier, as used by import(): an npm package name, a relative path starting with ./ or ../ and including the file extension, resolved from NodeJsHostOptions.WorkingDirectory, an absolute path, or a file: or node: URL. A module is loaded once, and kept for the lifetime of the process.
exportName string?
The name of the export. When null, the default export is used. CommonJS exports are supported.
arguments IReadOnlyList<JsonNode?>?
The arguments passed to the function. Use JSValue for values that JSON cannot represent, and JSReference to pass a value kept in the Node.js process.
cancellationToken CancellationToken
A token to stop waiting for the result. The JavaScript code keeps running.
Returns

Task<JsonElement> The JSON representation of the value returned by the function (awaited if it is a promise), or the value of the export when it is not a function. BigInt values are exact JSON numbers (Node.js 21 or later).

Exceptions
NodeJsException
The JavaScript code throws, or the Node.js process exits.

InvokeAsync<T>(string, string?, IReadOnlyList<JsonNode?>?, JsonTypeInfo<T>, CancellationToken)

NodeJsHost.cs

Imports a module, calls one of its exports, and deserializes the result.

net10.0

public Task<T?> InvokeAsync<T>(string module, string? exportName, IReadOnlyList<JsonNode?>? arguments, JsonTypeInfo<T> resultTypeInfo, CancellationToken cancellationToken = default)

net11.0

public Task<T?> InvokeAsync<T>(string module, string? exportName, IReadOnlyList<JsonNode?>? arguments, JsonTypeInfo<T> resultTypeInfo, CancellationToken cancellationToken = default)
Type parameters
T
Parameters
module string
The module specifier, as used by import(): an npm package name, a relative path starting with ./ or ../ and including the file extension, resolved from NodeJsHostOptions.WorkingDirectory, an absolute path, or a file: or node: URL. A module is loaded once, and kept for the lifetime of the process.
exportName string?
The name of the export. When null, the default export is used. CommonJS exports are supported.
arguments IReadOnlyList<JsonNode?>?
The arguments passed to the function. Use JSValue for values that JSON cannot represent, and JSReference to pass a value kept in the Node.js process.
resultTypeInfo JsonTypeInfo<T>
A token to stop waiting for the result. The JavaScript code keeps running.
cancellationToken CancellationToken
Returns

Task<T?> The JSON representation of the value returned by the function (awaited if it is a promise), or the value of the export when it is not a function. BigInt values are exact JSON numbers (Node.js 21 or later).

Exceptions
JsonException
The result cannot be deserialized to T.

InvokeAsync<T>(string, string?, object?[]?, JsonSerializerOptions?, CancellationToken)

NodeJsHost.cs

Imports a module, calls one of its exports, and deserializes the result. Arguments are serialized using reflection.

net10.0

[RequiresDynamicCode("JSON serialization and deserialization might require types that cannot be statically analyzed and might need runtime code generation. Use the overload that takes a JsonTypeInfo instead.")]
[RequiresUnreferencedCode("JSON serialization and deserialization might require types that cannot be statically analyzed. Use the overload that takes a JsonTypeInfo instead.")]
public Task<T?> InvokeAsync<T>(string module, string? exportName, object?[]? arguments = null, JsonSerializerOptions? options = null, CancellationToken cancellationToken = default)

net11.0

[RequiresDynamicCode("JSON serialization and deserialization might require types that cannot be statically analyzed and might need runtime code generation. Use the overload that takes a JsonTypeInfo instead.")]
[RequiresUnreferencedCode("JSON serialization and deserialization might require types that cannot be statically analyzed. Use the overload that takes a JsonTypeInfo instead.")]
public Task<T?> InvokeAsync<T>(string module, string? exportName, object?[]? arguments = null, JsonSerializerOptions? options = null, CancellationToken cancellationToken = default)
Type parameters
T
Parameters
module string
The module specifier, as used by import(): an npm package name, a relative path starting with ./ or ../ and including the file extension, resolved from NodeJsHostOptions.WorkingDirectory, an absolute path, or a file: or node: URL. A module is loaded once, and kept for the lifetime of the process.
exportName string?
The name of the export. When null, the default export is used. CommonJS exports are supported.
arguments object?[]?
The arguments passed to the function. Use JSValue for values that JSON cannot represent, and JSReference to pass a value kept in the Node.js process.
options JsonSerializerOptions?
A token to stop waiting for the result. The JavaScript code keeps running.
cancellationToken CancellationToken
Returns

Task<T?> The JSON representation of the value returned by the function (awaited if it is a promise), or the value of the export when it is not a function. BigInt values are exact JSON numbers (Node.js 21 or later).

Exceptions
JsonException
The result cannot be deserialized to T.

InvokeAsync<T>(string, string?, CancellationToken)

NodeJsHost.cs

Imports a module, calls one of its exports without arguments, and deserializes the result using reflection.

[RequiresDynamicCode("JSON serialization and deserialization might require types that cannot be statically analyzed and might need runtime code generation. Use the overload that takes a JsonTypeInfo instead.")]
[RequiresUnreferencedCode("JSON serialization and deserialization might require types that cannot be statically analyzed. Use the overload that takes a JsonTypeInfo instead.")]
public Task<T?> InvokeAsync<T>(string module, string? exportName, CancellationToken cancellationToken)
Type parameters
T
Parameters
module string
The module specifier, as used by import(): an npm package name, a relative path starting with ./ or ../ and including the file extension, resolved from NodeJsHostOptions.WorkingDirectory, an absolute path, or a file: or node: URL. A module is loaded once, and kept for the lifetime of the process.
exportName string?
The name of the export. When null, the default export is used. CommonJS exports are supported.
cancellationToken CancellationToken
The arguments passed to the function. Use JSValue for values that JSON cannot represent, and JSReference to pass a value kept in the Node.js process.
Returns

Task<T?> The JSON representation of the value returned by the function (awaited if it is a promise), or the value of the export when it is not a function. BigInt values are exact JSON numbers (Node.js 21 or later).

Exceptions
JsonException
The result cannot be deserialized to T.

InvokeReferenceAsync overloads

InvokeReferenceAsync(string, string?, IReadOnlyList<JsonNode?>?, CancellationToken)

NodeJsHost.cs

Imports a module, calls one of its exports, and keeps the result in the Node.js process.

public Task<JSReference> InvokeReferenceAsync(string module, string? exportName, IReadOnlyList<JsonNode?>? arguments = null, CancellationToken cancellationToken = default)
Parameters
module string
The module specifier, as used by import(): an npm package name, a relative path starting with ./ or ../ and including the file extension, resolved from NodeJsHostOptions.WorkingDirectory, an absolute path, or a file: or node: URL. A module is loaded once, and kept for the lifetime of the process.
exportName string?
The name of the export. When null, the default export is used. CommonJS exports are supported.
arguments IReadOnlyList<JsonNode?>?
The arguments passed to the function. Use JSValue for values that JSON cannot represent, and JSReference to pass a value kept in the Node.js process.
cancellationToken CancellationToken
A token to stop waiting for the result. The JavaScript code keeps running.
Returns

Task<JSReference> A reference to the value returned by the function (awaited if it is a promise), or to the value of the export when it is not a function. Dispose it when the value is no longer needed.

Exceptions
NodeJsException
The JavaScript code throws, or the Node.js process exits.

InvokeReferenceAsync(string, string?, object?[]?, JsonSerializerOptions?, CancellationToken)

NodeJsHost.cs

Imports a module, calls one of its exports, and keeps the result in the Node.js process. Arguments are serialized using reflection.

[RequiresDynamicCode("JSON serialization and deserialization might require types that cannot be statically analyzed and might need runtime code generation. Use the overload that takes a JsonTypeInfo instead.")]
[RequiresUnreferencedCode("JSON serialization and deserialization might require types that cannot be statically analyzed. Use the overload that takes a JsonTypeInfo instead.")]
public Task<JSReference> InvokeReferenceAsync(string module, string? exportName, object?[]? arguments, JsonSerializerOptions? options, CancellationToken cancellationToken = default)
Parameters
module string
The module specifier, as used by import(): an npm package name, a relative path starting with ./ or ../ and including the file extension, resolved from NodeJsHostOptions.WorkingDirectory, an absolute path, or a file: or node: URL. A module is loaded once, and kept for the lifetime of the process.
exportName string?
The name of the export. When null, the default export is used. CommonJS exports are supported.
arguments object?[]?
The arguments passed to the function. Use JSValue for values that JSON cannot represent, and JSReference to pass a value kept in the Node.js process.
options JsonSerializerOptions?
A token to stop waiting for the result. The JavaScript code keeps running.
cancellationToken CancellationToken
Returns

Task<JSReference> A reference to the value returned by the function (awaited if it is a promise), or to the value of the export when it is not a function. Dispose it when the value is no longer needed.

Exceptions
NodeJsException
The JavaScript code throws, or the Node.js process exits.

InvokeVoidAsync overloads

InvokeVoidAsync(string, string?, IReadOnlyList<JsonNode?>?, CancellationToken)

NodeJsHost.cs

Imports a module and calls one of its exports, ignoring its result. The result does not need to be serializable.

public Task InvokeVoidAsync(string module, string? exportName, IReadOnlyList<JsonNode?>? arguments = null, CancellationToken cancellationToken = default)
Parameters
module string
The module specifier, as used by import(): an npm package name, a relative path starting with ./ or ../ and including the file extension, resolved from NodeJsHostOptions.WorkingDirectory, an absolute path, or a file: or node: URL. A module is loaded once, and kept for the lifetime of the process.
exportName string?
The name of the export. When null, the default export is used. CommonJS exports are supported.
arguments IReadOnlyList<JsonNode?>?
The arguments passed to the function. Use JSValue for values that JSON cannot represent, and JSReference to pass a value kept in the Node.js process.
cancellationToken CancellationToken
A token to stop waiting for the result. The JavaScript code keeps running.
Returns

Task The JSON representation of the value returned by the function (awaited if it is a promise), or the value of the export when it is not a function. BigInt values are exact JSON numbers (Node.js 21 or later).

Exceptions
NodeJsException
The JavaScript code throws, or the Node.js process exits.

InvokeVoidAsync(string, string?, object?[]?, JsonSerializerOptions?, CancellationToken)

NodeJsHost.cs

Imports a module and calls one of its exports, ignoring its result. Arguments are serialized using reflection.

[RequiresDynamicCode("JSON serialization and deserialization might require types that cannot be statically analyzed and might need runtime code generation. Use the overload that takes a JsonTypeInfo instead.")]
[RequiresUnreferencedCode("JSON serialization and deserialization might require types that cannot be statically analyzed. Use the overload that takes a JsonTypeInfo instead.")]
public Task InvokeVoidAsync(string module, string? exportName, object?[]? arguments, JsonSerializerOptions? options, CancellationToken cancellationToken = default)
Parameters
module string
The module specifier, as used by import(): an npm package name, a relative path starting with ./ or ../ and including the file extension, resolved from NodeJsHostOptions.WorkingDirectory, an absolute path, or a file: or node: URL. A module is loaded once, and kept for the lifetime of the process.
exportName string?
The name of the export. When null, the default export is used. CommonJS exports are supported.
arguments object?[]?
The arguments passed to the function. Use JSValue for values that JSON cannot represent, and JSReference to pass a value kept in the Node.js process.
options JsonSerializerOptions?
A token to stop waiting for the result. The JavaScript code keeps running.
cancellationToken CancellationToken
Returns

Task The JSON representation of the value returned by the function (awaited if it is a promise), or the value of the export when it is not a function. BigInt values are exact JSON numbers (Node.js 21 or later).

Exceptions
NodeJsException
The JavaScript code throws, or the Node.js process exits.

StartAsync(NodeJsHostOptions?, CancellationToken)

NodeJsHost.cs

Starts a new Node.js process.

net10.0

public static Task<NodeJsHost> StartAsync(NodeJsHostOptions? options = null, CancellationToken cancellationToken = default)

net11.0

public static Task<NodeJsHost> StartAsync(NodeJsHostOptions? options = null, CancellationToken cancellationToken = default)

Parameters

options NodeJsHostOptions?
The options. They are copied, so changing them once the process is started has no effect.
cancellationToken CancellationToken
A token to cancel the startup.

Returns

Task<NodeJsHost>

Exceptions

NodeJsException
The node executable cannot be found, or the process fails to start.
ArgumentOutOfRangeException
NodeJsHostOptions.MaxConcurrentCalls, NodeJsHostOptions.StartupTimeout, NodeJsHostOptions.UnresponsiveTimeout, or NodeJsHostOptions.WorkerThreads is zero or negative.