Meziantou.FrameworkJSCallback Class
A .NET delegate passed as an argument of a call, which JavaScript code receives as an async function.
public sealed class JSCallbackRemarks
Calling the function sends its arguments to the .NET process, invokes the delegate, and resolves the returned promise with the result of the delegate. The arguments are converted to JSON as the results of calls are, and the delegate receives their JSON representation. The result of the delegate is converted as the arguments of calls are, so it can contain JSValue, JSReference, and JSCallback values. When the delegate throws, the promise is rejected with an Error whose name is the name of the type of the exception, and whose message is its message.
The delegate runs on the thread pool, and can be called concurrently and after the call that passed it completes, for instance when the JavaScript code keeps the function as an event handler. The process keeps the delegate as long as the JavaScript function is not garbage collected, or until the process exits or the host is disposed. The CancellationToken of the delegate is canceled when the host is disposed, the process exits, or the worker thread that called it exits.
A JSCallback converts implicitly to a JsonNode, so it can be used as an argument, or nested in a JsonObject or a JsonArray argument. It is not bound to a process, so it can be used in the calls of several hosts. Within a call, the same instance is the same JavaScript function.
Example
await using var node = await NodeJsHost.StartAsync();
// A .NET delegate that JavaScript code calls as an async function, e.g. to report progress
var progress = new ConcurrentQueue<int>();
var onProgress = JSCallback.Create(args => progress.Enqueue(args[0].GetInt32()));
// An asynchronous delegate: the promise resolves with its result
var getPrice = JSCallback.Create(async (args, cancellationToken) =>
{
await Task.Delay(10, cancellationToken);
return args[0].GetString() is "apple" ? 3 : 5;
});
var total = await node.EvaluateAsync("""
const [items, onProgress, getPrice] = args;
let total = 0;
for (let i = 0; i < items.length; i++) {
total += await getPrice(items[i]);
await onProgress(i + 1);
}
return total;
""", [new JsonArray("apple", "pear"), onProgress, getPrice]);
Assert.Equal(8, total.GetInt32());
Assert.Equal(new[] { 1, 2 }, progress.ToArray());Methods
| Name | Description |
|---|---|
| Create(Action<IReadOnlyList<JsonElement>>) | Creates a function that invokes a delegate. The function returns undefined. |
| Create(Func<IReadOnlyList<JsonElement>, JsonNode?>) | Creates a function that invokes a delegate and returns its result. |
| Create(Func<IReadOnlyList<JsonElement>, CancellationToken, Task<JsonNode?>>) | Creates a function that invokes an asynchronous delegate and returns its result. |
| Create(Func<IReadOnlyList<JsonElement>, CancellationToken, Task>) | Creates a function that invokes an asynchronous delegate. The function returns undefined. |
| ToJsonNode() | Converts the callback to a JsonNode, to use it as an argument or in a JsonObject or JsonArray argument. |
Create overloads
Create(Action<IReadOnlyList<JsonElement>>)
JSCallback.csCreates a function that invokes a delegate. The function returns undefined.
public static JSCallback Create(Action<IReadOnlyList<JsonElement>> callback)Parameters
callbackAction<IReadOnlyList<JsonElement>>- The delegate. It receives the JSON representation of the arguments of the function.
Returns
Create(Func<IReadOnlyList<JsonElement>, JsonNode?>)
JSCallback.csCreates a function that invokes a delegate and returns its result.
public static JSCallback Create(Func<IReadOnlyList<JsonElement>, JsonNode?> callback)Parameters
callbackFunc<IReadOnlyList<JsonElement>, JsonNode?>- The delegate. It receives the JSON representation of the arguments of the function.
Returns
Create(Func<IReadOnlyList<JsonElement>, CancellationToken, Task<JsonNode?>>)
JSCallback.csCreates a function that invokes an asynchronous delegate and returns its result.
public static JSCallback Create(Func<IReadOnlyList<JsonElement>, CancellationToken, Task<JsonNode?>> callback)Parameters
callbackFunc<IReadOnlyList<JsonElement>, CancellationToken, Task<JsonNode?>>- The delegate. It receives the JSON representation of the arguments of the function, and a token canceled when the host is terminated.
Returns
Create(Func<IReadOnlyList<JsonElement>, CancellationToken, Task>)
JSCallback.csCreates a function that invokes an asynchronous delegate. The function returns undefined.
public static JSCallback Create(Func<IReadOnlyList<JsonElement>, CancellationToken, Task> callback)Parameters
callbackFunc<IReadOnlyList<JsonElement>, CancellationToken, Task>- The delegate. It receives the JSON representation of the arguments of the function, and a token canceled when the host is terminated.
Returns
ToJsonNode()
JSCallback.csConverts the callback to a JsonNode, to use it as an argument or in a JsonObject or JsonArray argument.
public JsonNode ToJsonNode()Returns
Operators
| Name | Description |
|---|---|
| implicit operator JsonNode?(JSCallback?) | Converts the callback to a JsonNode, to use it as an argument or in a JsonObject or JsonArray argument. |
implicit operator JsonNode?(JSCallback?)
JSCallback.csConverts the callback to a JsonNode, to use it as an argument or in a JsonObject or JsonArray argument.
public static implicit operator JsonNode?(JSCallback? value)