Class JsonRpcBatch

Namespace

Nerdbank.JsonRpc

Assembly

Nerdbank.JsonRpc.dll

Builds and sends one JSON-RPC batch payload.

public class JsonRpcBatch : IJsonRpcClient, IDisposable

Inheritance

object

JsonRpcBatch

Implements

IJsonRpcClient

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

A batch is one-shot. Requests and notifications added before SendAsync(CancellationToken) are transmitted in one protocol payload. All requests are sent together, and their returned tasks complete after the peer returns the batch response.

Properties

Serializer

Gets the serializer used to encode arguments and decode results.

public JsonRpcSerializer Serializer { get; }

Property Value

JsonRpcSerializer

Methods

Attach(Type, JsonRpcProxyOptions?)

Attaches a generated client proxy for an RPC contract interface to this batch.

public object Attach(Type interfaceType, JsonRpcProxyOptions? options = null)

Parameters

interfaceType Type

The RPC contract interface to proxy.

options JsonRpcProxyOptions

Options controlling argument encoding for this proxy.

Returns

object

A generated proxy instance that implements interfaceType.

Attach<T>(JsonRpcProxyOptions?)

Attaches a generated client proxy for an RPC contract interface to this batch.

public T Attach<T>(JsonRpcProxyOptions? options = null)

Parameters

options JsonRpcProxyOptions

Options controlling argument encoding for this proxy.

Returns

T

A generated proxy instance that implements T.

Type Parameters

T

The RPC contract interface to proxy.

CancelAllAsync()

Queues cancellation notifications for all pending requests sent by this batch.

public ValueTask CancelAllAsync()

Returns

ValueTask

A task that completes when cancellation notifications have been accepted by the outbound channel.

Remarks

If this batch has not been sent yet, pending request tasks are canceled locally and those requests will be omitted from SendAsync(CancellationToken). After this batch has been sent, this method sends one JSON-RPC batch containing a $/cancelRequest notification for each request that has not already completed or been canceled.

Exceptions

ObjectDisposedException

Thrown if this batch has been disposed.

CreateArguments(bool, int, CancellationToken)

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

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

Dispose()

Releases this batch builder.

public void Dispose()

Remarks

Disposing an unsent batch cancels pending request tasks and prevents subsequent additions, sending, or cancellation. Disposing a batch after it has been sent does not cancel requests that are already in flight.

NotifyAsync(string, JsonRpcValue, CancellationToken)

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

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

Exceptions

ObjectDisposedException

Thrown if this batch has been disposed.

NotifyAsync<TArg>(string, in TArg, ITypeShape<TArg>, CancellationToken)

Adds a notification to this batch.

public ValueTask NotifyAsync<TArg>(string method, in TArg arguments, ITypeShape<TArg> argShape, CancellationToken cancellationToken)

Parameters

method string

The remote method name.

arguments TArg

The notification arguments.

argShape ITypeShape<TArg>

The argument type shape.

cancellationToken CancellationToken

A token whose cancellation controls whether this notification is sent.

Returns

ValueTask

A task that completes when the notification has been added to the batch.

Type Parameters

TArg

The argument type.

Exceptions

ObjectDisposedException

Thrown if this batch has been disposed.

NotifyAsync<TArg>(string, in TArg, CancellationToken)

Adds a notification to this batch.

public ValueTask NotifyAsync<TArg>(string method, in TArg arguments, CancellationToken cancellationToken) where TArg : IShapeable<TArg>

Parameters

method string

The remote method name.

arguments TArg

The notification arguments.

cancellationToken CancellationToken

A token whose cancellation controls whether this notification is sent.

Returns

ValueTask

A task that completes when the notification has been added to the batch.

Type Parameters

TArg

The argument type.

Exceptions

ObjectDisposedException

Thrown if this batch has been disposed.

RequestAsync(string, JsonRpcValue, CancellationToken)

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

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

Exceptions

ObjectDisposedException

Thrown if this batch has been disposed.

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

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

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

Exceptions

ObjectDisposedException

Thrown if this batch has been disposed.

RequestAsync<TArg>(string, in TArg, ITypeShape<TArg>, CancellationToken)

Adds a request without a result to this batch.

public ValueTask RequestAsync<TArg>(string method, in TArg arguments, ITypeShape<TArg> argShape, CancellationToken cancellationToken)

Parameters

method string

The remote method name.

arguments TArg

The request arguments.

argShape ITypeShape<TArg>

The argument type shape.

cancellationToken CancellationToken

A token whose cancellation controls whether this request is sent.

Returns

ValueTask

A task that completes when the batch response is received.

Type Parameters

TArg

The argument type.

Exceptions

ObjectDisposedException

Thrown if this batch has been disposed.

RequestAsync<TArg>(string, in TArg, CancellationToken)

Adds a request without a result to this batch.

public ValueTask RequestAsync<TArg>(string method, in TArg arguments, CancellationToken cancellationToken) where TArg : IShapeable<TArg>

Parameters

method string

The remote method name.

arguments TArg

The request arguments.

cancellationToken CancellationToken

A token whose cancellation controls whether this request is sent.

Returns

ValueTask

A task that completes when the batch response is received.

Type Parameters

TArg

The argument type.

Exceptions

ObjectDisposedException

Thrown if this batch has been disposed.

RequestAsync<TArg, TResult>(string, in TArg, ITypeShape<TArg>, ITypeShape<TResult>, CancellationToken)

Adds a request with a typed result to this batch.

public ValueTask<TResult> RequestAsync<TArg, TResult>(string method, in TArg arguments, ITypeShape<TArg> argShape, ITypeShape<TResult> resultShape, CancellationToken cancellationToken)

Parameters

method string

The remote method name.

arguments TArg

The request arguments.

argShape ITypeShape<TArg>

The argument type shape.

resultShape ITypeShape<TResult>

The result type shape.

cancellationToken CancellationToken

A token whose cancellation controls whether this request is sent.

Returns

ValueTask<TResult>

A task that completes with the result when the batch response is received.

Type Parameters

TArg

The argument type.

TResult

The result type.

Exceptions

ObjectDisposedException

Thrown if this batch has been disposed.

RequestAsync<TArg, TResult>(string, in TArg, CancellationToken)

Adds a request with a typed result to this batch.

public ValueTask<TResult> RequestAsync<TArg, TResult>(string method, in TArg arguments, CancellationToken cancellationToken) where TArg : IShapeable<TArg> where TResult : IShapeable<TResult>

Parameters

method string

The remote method name.

arguments TArg

The request arguments.

cancellationToken CancellationToken

A token whose cancellation controls whether this request is sent.

Returns

ValueTask<TResult>

A task that completes with the result when the batch response is received.

Type Parameters

TArg

The argument type.

TResult

The result type.

Exceptions

ObjectDisposedException

Thrown if this batch has been disposed.

RequestAsync<TArg, TResult, TResultProvider>(string, in TArg, CancellationToken)

Adds a request with a typed result to this batch.

public ValueTask<TResult> RequestAsync<TArg, TResult, TResultProvider>(string method, in TArg arguments, CancellationToken cancellationToken) where TArg : IShapeable<TArg> where TResultProvider : IShapeable<TResult>

Parameters

method string

The remote method name.

arguments TArg

The request arguments.

cancellationToken CancellationToken

A token whose cancellation controls whether this request is sent.

Returns

ValueTask<TResult>

A task that completes with the result when the batch response is received.

Type Parameters

TArg

The argument type.

TResult

The result type.

TResultProvider

The result shape provider type.

Exceptions

ObjectDisposedException

Thrown if this batch has been disposed.

SendAsync(CancellationToken)

Seals this batch and queues all non-canceled entries as one JSON-RPC protocol payload.

public ValueTask SendAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A token whose cancellation is observed until the batch has been enqueued for transmission. After the batch has been enqueued, cancel individual requests by canceling the token supplied to each request, or call CancelAllAsync() to enqueue one batch of cancellation notifications for every pending request in this batch.

Returns

ValueTask

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

Exceptions

ObjectDisposedException

Thrown if this batch has been disposed.