Meziantou.Framework

NodeJsHostPool Class

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

Runs JavaScript code on a fixed number of Node.js processes, so CPU-bound code can run in parallel.

public sealed class NodeJsHostPool : IAsyncDisposable

Remarks

Each call is sent to the host with the fewest calls in progress, including canceled calls whose JavaScript code has not completed. When NodeJsHostOptions.MaxConcurrentCalls is set, calls wait in the pool until a host can run them, so a host busy with a long call does not delay the following calls. Hosts do not share state: values stored on globalThis are only visible to calls running on the same host. Use NodeJsHostPool.RunAsync to run several calls on the same host.

When a Node.js process exits, its host is replaced by a new one the next time a host is selected. Set NodeJsHostOptions.UnresponsiveTimeout to also replace a process whose event loop is blocked by a canceled call. With NodeJsHostOptions.WorkerThreads, each process runs the calls on several worker threads, and only the worker thread blocked by a canceled call is restarted.

Example

string[] documents = ["# Title", "Some *text*"];

await using var pool = await NodeJsHostPool.StartAsync(Environment.ProcessorCount);

// Each call runs on the host with the fewest calls in progress, so the calls run in parallel
var results = await Task.WhenAll(documents.Select(document => pool.EvaluateAsync("return args[0].length;", [document])));

Assert.Equal([7, 11], results.Select(result => result.GetInt32()));
Implements

Properties

NameDescription
SizeGets the number of Node.js processes in the pool.

Size

NodeJsHostPool.cs

Gets the number of Node.js processes in the pool.

public int Size { get; }

Property value

int

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 all the Node.js processes. 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.
RunAsync(Func<NodeJsHost, Task>, CancellationToken)Runs a function with one host of the pool. Use it to run several calls on the same Node.js process.
RunAsync<T>(Func<NodeJsHost, Task<T>>, CancellationToken)Runs a function with one host of the pool. Use it to run several calls on the same Node.js process.
StartAsync(int, NodeJsHostOptions?, CancellationToken)Starts a pool of Node.js processes.

CreateInstanceAsync overloads

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

NodeJsHostPool.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.
Remarks

The reference is bound to the host that ran the call. When the arguments contain a JSReference, the call runs on the host that keeps the referenced value.

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

NodeJsHostPool.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.
Remarks

The reference is bound to the host that ran the call. When the arguments contain a JSReference, the call runs on the host that keeps the referenced value.

DisposeAsync()

NodeJsHostPool.cs

Stops all the Node.js processes. Pending calls fail with ObjectDisposedException.

net10.0

public ValueTask DisposeAsync()

net11.0

public ValueTask DisposeAsync()

Returns

ValueTask

EvaluateAsync overloads

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

NodeJsHostPool.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.
Remarks

When the arguments contain a JSReference, the call runs on the host that keeps the referenced value.

EvaluateAsync(string, CancellationToken)

NodeJsHostPool.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)

NodeJsHostPool.cs

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

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.
Remarks

When the arguments contain a JSReference, the call runs on the host that keeps the referenced value.

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

NodeJsHostPool.cs

Evaluates JavaScript code as the body of an async function that receives arguments, and deserializes the 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<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.
Remarks

When the arguments contain a JSReference, the call runs on the host that keeps the referenced value.

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

NodeJsHostPool.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, 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)

NodeJsHostPool.cs

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

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)

NodeJsHostPool.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)

NodeJsHostPool.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.
Remarks

The reference is bound to the host that ran the call. When the arguments contain a JSReference, the call runs on the host that keeps the referenced value.

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

NodeJsHostPool.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.
Remarks

The reference is bound to the host that ran the call. When the arguments contain a JSReference, the call runs on the host that keeps the referenced value.

EvaluateReferenceAsync(string, CancellationToken)

NodeJsHostPool.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.
Remarks

The reference is bound to the host that ran the call. Calls of the pool whose arguments contain it run on that host.

EvaluateVoidAsync overloads

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

NodeJsHostPool.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.
Remarks

When the arguments contain a JSReference, the call runs on the host that keeps the referenced value.

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

NodeJsHostPool.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.
Remarks

When the arguments contain a JSReference, the call runs on the host that keeps the referenced value.

EvaluateVoidAsync(string, CancellationToken)

NodeJsHostPool.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)

NodeJsHostPool.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.
Remarks

When the arguments contain a JSReference, the call runs on the host that keeps the referenced value.

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

NodeJsHostPool.cs

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

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.
Remarks

When the arguments contain a JSReference, the call runs on the host that keeps the referenced value.

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

NodeJsHostPool.cs

Imports a module, calls one of its exports, and deserializes the 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<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.
Remarks

When the arguments contain a JSReference, the call runs on the host that keeps the referenced value.

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

NodeJsHostPool.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)

NodeJsHostPool.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.
Remarks

The reference is bound to the host that ran the call. Calls of the pool whose arguments contain it run on that host.

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

NodeJsHostPool.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.
Remarks

The reference is bound to the host that ran the call. Calls of the pool whose arguments contain it run on that host.

InvokeVoidAsync overloads

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

NodeJsHostPool.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.
Remarks

When the arguments contain a JSReference, the call runs on the host that keeps the referenced value.

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

NodeJsHostPool.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.
Remarks

When the arguments contain a JSReference, the call runs on the host that keeps the referenced value.

RunAsync overloads

RunAsync(Func<NodeJsHost, Task>, CancellationToken)

NodeJsHostPool.cs

Runs a function with one host of the pool. Use it to run several calls on the same Node.js process.

public Task RunAsync(Func<NodeJsHost, Task> action, CancellationToken cancellationToken = default)
Parameters
action Func<NodeJsHost, Task>
The function to run. The host must not be used after the returned task completes.
cancellationToken CancellationToken
A token to stop waiting for a host to be available.
Returns

Task

RunAsync<T>(Func<NodeJsHost, Task<T>>, CancellationToken)

NodeJsHostPool.cs

Runs a function with one host of the pool. Use it to run several calls on the same Node.js process.

net10.0

public Task<T> RunAsync<T>(Func<NodeJsHost, Task<T>> action, CancellationToken cancellationToken = default)

net11.0

public Task<T> RunAsync<T>(Func<NodeJsHost, Task<T>> action, CancellationToken cancellationToken = default)
Type parameters
T
Parameters
action Func<NodeJsHost, Task<T>>
The function to run. The host must not be used after the returned task completes.
cancellationToken CancellationToken
A token to stop waiting for a host to be available.
Returns

Task<T>

Remarks

Calls made on the pool by the function, instead of on the host, do not wait for NodeJsHostOptions.MaxConcurrentCalls: the function already counts as a call, and waiting would never end when all the calls of the pool are such functions.

StartAsync(int, NodeJsHostOptions?, CancellationToken)

NodeJsHostPool.cs

Starts a pool of Node.js processes.

net10.0

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

net11.0

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

Parameters

size int
The number of Node.js processes. Environment.ProcessorCount is a good default for CPU-bound code.
options NodeJsHostOptions?
The options used to start each process. They are copied, so changing them once the pool is started has no effect, including on the processes that replace the ones that exit.
cancellationToken CancellationToken
A token to cancel the startup.

Returns

Task<NodeJsHostPool>

Exceptions

NodeJsException
A Node.js process fails to start.
ArgumentOutOfRangeException
size, NodeJsHostOptions.MaxConcurrentCalls, NodeJsHostOptions.StartupTimeout, NodeJsHostOptions.UnresponsiveTimeout, or NodeJsHostOptions.WorkerThreads is zero or negative.