Interface IJsonRpcClient

Namespace

Nerdbank.JsonRpc

Assembly

Nerdbank.JsonRpc.dll

Provides the client operations used by generated JSON-RPC proxy implementations.

public interface IJsonRpcClient

Remarks

This interface is public so source-generated code in consuming assemblies can reference it. Most application code should use JsonRpc or JsonRpcBatch directly. External implementations are not supported. Members may be added to this interface in future releases.

Properties

Serializer

Gets the serializer used to encode arguments and decode results.

JsonRpcSerializer Serializer { get; }

Property Value

JsonRpcSerializer

Methods

CreateArguments(bool, int, CancellationToken)

Creates a serializer-neutral builder for named or positional arguments.

JsonRpcArgumentsBuilder CreateArguments(bool named, int count, CancellationToken cancellationToken = default)

Parameters

named bool

Whether to use named arguments.

count int

The exact number of arguments to write.

cancellationToken CancellationToken

A token used when serializing all arguments.

Returns

JsonRpcArgumentsBuilder

An argument builder using this client's serializer.

NotifyAsync(string, JsonRpcValue, CancellationToken)

Sends a notification with arguments already serialized using the channel's selected encoding.

ValueTask NotifyAsync(string method, JsonRpcValue arguments, CancellationToken cancellationToken)

Parameters

method string

The name of the remote method to invoke.

arguments JsonRpcValue

The pre-serialized arguments payload.

cancellationToken CancellationToken

A token whose cancellation is observed before the notification is posted.

Returns

ValueTask

A task that completes when the notification has been accepted by the outbound channel.

Remarks

Consume the returned awaitable once. To share it, await it repeatedly, or compose it with other Tasks, call AsTask() or Preserve() once and retain the returned awaitable instead of the original. It may be backed by a pooled source that is recycled after consumption.

RequestAsync(string, JsonRpcValue, CancellationToken)

Sends a request with arguments already serialized using the channel's selected encoding.

ValueTask RequestAsync(string method, JsonRpcValue arguments, CancellationToken cancellationToken)

Parameters

method string

The name of the remote method to invoke.

arguments JsonRpcValue

The pre-serialized arguments payload.

cancellationToken CancellationToken

A token whose cancellation should be propagated to the remote endpoint.

Returns

ValueTask

A task that completes when the remote endpoint sends its response.

Remarks

Consume the returned awaitable once. To share it, await it repeatedly, or compose it with other Tasks, call AsTask() or Preserve() once and retain the returned awaitable instead of the original. It may be backed by a pooled source that is recycled after consumption. A remote RequestCancelled response throws OperationCanceledException. Cancellation exceptions include cancellationToken only if it is canceled. Unrequested remote cancellation has a message explaining that the remote party canceled processing without caller-requested cancellation. The original remote error is retained as a JsonRpcException inner exception; other remote errors throw JsonRpcException.

RequestAsync<TResult>(string, JsonRpcValue, ITypeShape<TResult>, CancellationToken)

Sends a request with arguments already serialized using the channel's selected encoding.

ValueTask<TResult> RequestAsync<TResult>(string method, JsonRpcValue arguments, ITypeShape<TResult> resultShape, CancellationToken cancellationToken)

Parameters

method string

The name of the remote method to invoke.

arguments JsonRpcValue

The pre-serialized arguments payload.

resultShape ITypeShape<TResult>

The type shape describing TResult.

cancellationToken CancellationToken

A token whose cancellation should be propagated to the remote endpoint.

Returns

ValueTask<TResult>

A task that completes with the result returned by the remote endpoint.

Type Parameters

TResult

The expected result type.

Remarks

Consume the returned awaitable once. To share it, await it repeatedly, or compose it with other Tasks, call AsTask() or Preserve() once and retain the returned awaitable instead of the original. It may be backed by a pooled source that is recycled after consumption. A remote RequestCancelled response throws OperationCanceledException. Cancellation exceptions include cancellationToken only if it is canceled. Unrequested remote cancellation has a message explaining that the remote party canceled processing without caller-requested cancellation. The original remote error is retained as a JsonRpcException inner exception; other remote errors throw JsonRpcException.