Meziantou.FrameworkJSReference Class
A reference to a value kept in the Node.js process, such as an object that cannot be serialized as JSON.
public sealed class JSReference : IAsyncDisposable, IDisposableRemarks
The value is kept until the reference is disposed or the Node.js process exits. A reference can only be used with the process that created it. With NodeJsHostOptions.WorkerThreads, the value is kept by the worker thread that created it, and the calls that use the reference run on this worker thread; the value is lost when the worker thread exits or is terminated.
A JSReference converts implicitly to a JsonNode, so it can be used as an argument, or nested in a JsonObject or a JsonArray argument. The function receives the referenced value.
Example
await using var node = await NodeJsHost.StartAsync();
// A Hash object cannot be serialized as JSON, so it stays in the Node.js process
await using var hash = await node.InvokeReferenceAsync("node:crypto", "createHash", ["sha256"]);
await hash.InvokeVoidAsync("update", ["hello"]);
// A function receives the referenced value
await node.EvaluateVoidAsync("args[0].update(' world');", [hash]);
var digest = await hash.InvokeAsync("digest", ["hex"]);
Assert.Equal("b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9", digest.GetString());- Implements
Properties
| Name | Description |
|---|---|
| Host | Gets the host of the Node.js process that keeps the value. |
Host
JSReference.csGets the host of the Node.js process that keeps the value.
public NodeJsHost Host { get; }Property value
Methods
| Name | Description |
|---|---|
| CreateInstanceAsync(string?, IReadOnlyList<JsonNode?>?, CancellationToken) | Creates an instance (new) of the referenced class, or of a class that is a member of the referenced value, and keeps the instance in the Node.js process. |
| CreateInstanceAsync(string?, object?[]?, JsonSerializerOptions?, CancellationToken) | Creates an instance (new) of the referenced class, or of a class that is a member of the referenced value, and keeps the instance in the Node.js process. Arguments are serialized using reflection. |
| Dispose() | Releases the value, so Node.js can collect it. The release message is sent in the background. |
| DisposeAsync() | Releases the value, so Node.js can collect it. |
| GetValueAsync(CancellationToken) | Gets the JSON representation of the referenced value (awaited if it is a promise). |
| GetValueAsync<T>(JsonSerializerOptions?, CancellationToken) | Gets the referenced value, deserialized from its JSON representation using reflection. |
| GetValueAsync<T>(JsonTypeInfo<T>, CancellationToken) | Gets the referenced value, deserialized from its JSON representation. |
| GetValueAsync<T>(CancellationToken) | Gets the referenced value, deserialized from its JSON representation using reflection. |
| InvokeAsync(string?, IReadOnlyList<JsonNode?>?, CancellationToken) | Calls a method of the referenced value, or the referenced function. |
| InvokeAsync<T>(string?, IReadOnlyList<JsonNode?>?, JsonTypeInfo<T>, CancellationToken) | Calls a method of the referenced value, or the referenced function, and deserializes the result. |
| InvokeAsync<T>(string?, object?[]?, JsonSerializerOptions?, CancellationToken) | Calls a method of the referenced value, or the referenced function, and deserializes the result. Arguments are serialized using reflection. |
| InvokeAsync<T>(string?, CancellationToken) | Calls a method of the referenced value without arguments, or the referenced function, and deserializes the result using reflection. |
| InvokeReferenceAsync(string?, IReadOnlyList<JsonNode?>?, CancellationToken) | Calls a method of the referenced value, or the referenced function, and returns a reference to its result. |
| InvokeReferenceAsync(string?, object?[]?, JsonSerializerOptions?, CancellationToken) | Calls a method of the referenced value, or the referenced function, and returns a reference to its result. Arguments are serialized using reflection. |
| InvokeVoidAsync(string?, IReadOnlyList<JsonNode?>?, CancellationToken) | Calls a method of the referenced value, or the referenced function, and ignores its result. |
| InvokeVoidAsync(string?, object?[]?, JsonSerializerOptions?, CancellationToken) | Calls a method of the referenced value, or the referenced function, and ignores its result. Arguments are serialized using reflection. |
| ToJsonNode() | Converts the reference to a JsonNode, to use it as an argument or in a JsonObject or JsonArray argument. |
| ToString() | Returns a string that represents the current object. |
CreateInstanceAsync overloads
CreateInstanceAsync(string?, IReadOnlyList<JsonNode?>?, CancellationToken)
JSReference.csCreates an instance (new) of the referenced class, or of a class that is a member of the referenced value, and keeps the instance in the Node.js process.
public Task<JSReference> CreateInstanceAsync(string? memberName, IReadOnlyList<JsonNode?>? arguments = null, CancellationToken cancellationToken = default)Parameters
memberNamestring?- The name of the member of the referenced value that is a class or a constructor function. When
null, the referenced value is the class. argumentsIReadOnlyList<JsonNode?>?- The arguments passed to the constructor.
cancellationTokenCancellationToken- 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 value is not a constructor, the constructor throws, or the Node.js process exits.
CreateInstanceAsync(string?, object?[]?, JsonSerializerOptions?, CancellationToken)
JSReference.csCreates an instance (new) of the referenced class, or of a class that is a member of the referenced value, 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? memberName, object?[]? arguments, JsonSerializerOptions? options, CancellationToken cancellationToken = default)Parameters
memberNamestring?- The name of the member of the referenced value that is a class or a constructor function. When
null, the referenced value is the class. argumentsobject?[]?- The arguments passed to the constructor.
optionsJsonSerializerOptions?- A token to stop waiting for the result. The JavaScript code keeps running.
cancellationTokenCancellationToken
Returns
Task<JSReference> A reference to the new instance. Dispose it when the instance is no longer needed.
Exceptions
NodeJsException- The value is not a constructor, the constructor throws, or the Node.js process exits.
Dispose()
JSReference.csReleases the value, so Node.js can collect it. The release message is sent in the background.
public void Dispose()DisposeAsync()
JSReference.csGetValueAsync overloads
GetValueAsync(CancellationToken)
JSReference.csGets the JSON representation of the referenced value (awaited if it is a promise).
public Task<JsonElement> GetValueAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationToken- A token to stop waiting for the result.
Returns
Exceptions
NodeJsException- The value cannot be serialized, or the Node.js process exits.
GetValueAsync<T>(JsonSerializerOptions?, CancellationToken)
JSReference.csGets the referenced value, deserialized from its JSON representation 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?> GetValueAsync<T>(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?> GetValueAsync<T>(JsonSerializerOptions? options = null, CancellationToken cancellationToken = default)Type parameters
T
Parameters
optionsJsonSerializerOptions?- A token to stop waiting for the result.
cancellationTokenCancellationToken
Returns
Exceptions
JsonException- The result cannot be deserialized to
T.
GetValueAsync<T>(JsonTypeInfo<T>, CancellationToken)
JSReference.csGets the referenced value, deserialized from its JSON representation.
net10.0
public Task<T?> GetValueAsync<T>(JsonTypeInfo<T> resultTypeInfo, CancellationToken cancellationToken = default)net11.0
public Task<T?> GetValueAsync<T>(JsonTypeInfo<T> resultTypeInfo, CancellationToken cancellationToken = default)Type parameters
T
Parameters
resultTypeInfoJsonTypeInfo<T>- A token to stop waiting for the result.
cancellationTokenCancellationToken
Returns
Exceptions
JsonException- The result cannot be deserialized to
T.
GetValueAsync<T>(CancellationToken)
JSReference.csGets the referenced value, deserialized from its JSON representation 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?> GetValueAsync<T>(CancellationToken cancellationToken)Type parameters
T
Parameters
cancellationTokenCancellationToken- A token to stop waiting for the result.
Returns
Exceptions
JsonException- The result cannot be deserialized to
T.
InvokeAsync overloads
InvokeAsync(string?, IReadOnlyList<JsonNode?>?, CancellationToken)
JSReference.csCalls a method of the referenced value, or the referenced function.
public Task<JsonElement> InvokeAsync(string? methodName, IReadOnlyList<JsonNode?>? arguments = null, CancellationToken cancellationToken = default)Parameters
methodNamestring?- The name of the method, called with the referenced value as
this. When the member is not a function, its value is returned. Whennull, the referenced value is called, so it must be a function. argumentsIReadOnlyList<JsonNode?>?- The arguments passed to the function.
cancellationTokenCancellationToken- 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).
Exceptions
NodeJsException- The JavaScript code throws, or the Node.js process exits.
InvokeAsync<T>(string?, IReadOnlyList<JsonNode?>?, JsonTypeInfo<T>, CancellationToken)
JSReference.csCalls a method of the referenced value, or the referenced function, and deserializes the result.
net10.0
public Task<T?> InvokeAsync<T>(string? methodName, IReadOnlyList<JsonNode?>? arguments, JsonTypeInfo<T> resultTypeInfo, CancellationToken cancellationToken = default)net11.0
public Task<T?> InvokeAsync<T>(string? methodName, IReadOnlyList<JsonNode?>? arguments, JsonTypeInfo<T> resultTypeInfo, CancellationToken cancellationToken = default)Type parameters
T
Parameters
methodNamestring?- The name of the method, called with the referenced value as
this. When the member is not a function, its value is returned. Whennull, the referenced value is called, so it must be a function. argumentsIReadOnlyList<JsonNode?>?- The arguments passed to the function.
resultTypeInfoJsonTypeInfo<T>- A token to stop waiting for the result. The JavaScript code keeps running.
cancellationTokenCancellationToken
Returns
Task<T?> The JSON representation of the value returned by the function (awaited if it is a promise).
Exceptions
JsonException- The result cannot be deserialized to
T.
InvokeAsync<T>(string?, object?[]?, JsonSerializerOptions?, CancellationToken)
JSReference.csCalls a method of the referenced value, or the referenced function, 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? methodName, 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? methodName, object?[]? arguments = null, JsonSerializerOptions? options = null, CancellationToken cancellationToken = default)Type parameters
T
Parameters
methodNamestring?- The name of the method, called with the referenced value as
this. When the member is not a function, its value is returned. Whennull, the referenced value is called, so it must be a function. argumentsobject?[]?- The arguments passed to the function.
optionsJsonSerializerOptions?- A token to stop waiting for the result. The JavaScript code keeps running.
cancellationTokenCancellationToken
Returns
Task<T?> The JSON representation of the value returned by the function (awaited if it is a promise).
Exceptions
JsonException- The result cannot be deserialized to
T.
InvokeAsync<T>(string?, CancellationToken)
JSReference.csCalls a method of the referenced value without arguments, or the referenced function, 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? methodName, CancellationToken cancellationToken)Type parameters
T
Parameters
methodNamestring?- The name of the method, called with the referenced value as
this. When the member is not a function, its value is returned. Whennull, the referenced value is called, so it must be a function. cancellationTokenCancellationToken- The arguments passed to the function.
Returns
Task<T?> The JSON representation of the value returned by the function (awaited if it is a promise).
Exceptions
JsonException- The result cannot be deserialized to
T.
InvokeReferenceAsync overloads
InvokeReferenceAsync(string?, IReadOnlyList<JsonNode?>?, CancellationToken)
JSReference.csCalls a method of the referenced value, or the referenced function, and returns a reference to its result.
public Task<JSReference> InvokeReferenceAsync(string? methodName, IReadOnlyList<JsonNode?>? arguments = null, CancellationToken cancellationToken = default)Parameters
methodNamestring?- The name of the method, called with the referenced value as
this. When the member is not a function, its value is returned. Whennull, the referenced value is called, so it must be a function. argumentsIReadOnlyList<JsonNode?>?- The arguments passed to the function.
cancellationTokenCancellationToken- 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). Dispose it when the value is no longer needed.
Exceptions
NodeJsException- The JavaScript code throws, or the Node.js process exits.
InvokeReferenceAsync(string?, object?[]?, JsonSerializerOptions?, CancellationToken)
JSReference.csCalls a method of the referenced value, or the referenced function, and returns a reference to 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<JSReference> InvokeReferenceAsync(string? methodName, object?[]? arguments, JsonSerializerOptions? options, CancellationToken cancellationToken = default)Parameters
methodNamestring?- The name of the method, called with the referenced value as
this. When the member is not a function, its value is returned. Whennull, the referenced value is called, so it must be a function. argumentsobject?[]?- The arguments passed to the function.
optionsJsonSerializerOptions?- A token to stop waiting for the result. The JavaScript code keeps running.
cancellationTokenCancellationToken
Returns
Task<JSReference> A reference to the value returned by the function (awaited if it is a promise). 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?, IReadOnlyList<JsonNode?>?, CancellationToken)
JSReference.csCalls a method of the referenced value, or the referenced function, and ignores its result.
public Task InvokeVoidAsync(string? methodName, IReadOnlyList<JsonNode?>? arguments = null, CancellationToken cancellationToken = default)Parameters
methodNamestring?- The name of the method, called with the referenced value as
this. When the member is not a function, its value is returned. Whennull, the referenced value is called, so it must be a function. argumentsIReadOnlyList<JsonNode?>?- The arguments passed to the function.
cancellationTokenCancellationToken- 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).
Exceptions
NodeJsException- The JavaScript code throws, or the Node.js process exits.
InvokeVoidAsync(string?, object?[]?, JsonSerializerOptions?, CancellationToken)
JSReference.csCalls a method of the referenced value, or the referenced function, and ignores 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? methodName, object?[]? arguments, JsonSerializerOptions? options, CancellationToken cancellationToken = default)Parameters
methodNamestring?- The name of the method, called with the referenced value as
this. When the member is not a function, its value is returned. Whennull, the referenced value is called, so it must be a function. argumentsobject?[]?- The arguments passed to the function.
optionsJsonSerializerOptions?- A token to stop waiting for the result. The JavaScript code keeps running.
cancellationTokenCancellationToken
Returns
Task The JSON representation of the value returned by the function (awaited if it is a promise).
Exceptions
NodeJsException- The JavaScript code throws, or the Node.js process exits.
ToJsonNode()
JSReference.csConverts the reference to a JsonNode, to use it as an argument or in a JsonObject or JsonArray argument.
public JsonNode ToJsonNode()Returns
ToString()
JSReference.csOperators
| Name | Description |
|---|---|
| implicit operator JsonNode?(JSReference?) | Converts the reference to a JsonNode, to use it as an argument or in a JsonObject or JsonArray argument. |
implicit operator JsonNode?(JSReference?)
JSReference.csConverts the reference to a JsonNode, to use it as an argument or in a JsonObject or JsonArray argument.
public static implicit operator JsonNode?(JSReference? value)