Class JsonRpc

Namespace: StreamJsonRpc

Assembly: StreamJsonRpc.dll

Manages a JSON-RPC connection with another entity over a Stream.

public class JsonRpc : IDisposableObservable, IDisposable, IJsonRpcFormatterCallbacks, IJsonRpcTracingCallbacks

Inheritance: object

JsonRpc

Implements: IDisposableObservable

IDisposable

IJsonRpcFormatterCallbacks

IJsonRpcTracingCallbacks

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

JsonRpc(IJsonRpcMessageHandler)

Initializes a new instance of the JsonRpc class.

public JsonRpc(IJsonRpcMessageHandler messageHandler)

Parameters

messageHandler IJsonRpcMessageHandler: The message handler to use to transmit and receive RPC messages.

Remarks

It is important to call StartListening() to begin receiving messages.

JsonRpc(IJsonRpcMessageHandler, object?)

Initializes a new instance of the JsonRpc class.

public JsonRpc(IJsonRpcMessageHandler messageHandler, object? target)

Parameters

messageHandler IJsonRpcMessageHandler: The message handler to use to transmit and receive RPC messages.
target object: An optional target object to invoke when incoming RPC requests arrive.

Remarks

It is important to call StartListening() to begin receiving messages.

JsonRpc(Stream)

Initializes a new instance of the JsonRpc class that uses HeaderDelimitedMessageHandler around messages serialized using the JsonMessageFormatter.

public JsonRpc(Stream stream)

Parameters

stream Stream: The full duplex stream used to transmit and receive messages.

Remarks

It is important to call StartListening() to begin receiving messages.

JsonRpc(Stream?, Stream?, object?)

Initializes a new instance of the JsonRpc class that uses HeaderDelimitedMessageHandler around messages serialized using the JsonMessageFormatter.

public JsonRpc(Stream? sendingStream, Stream? receivingStream, object? target = null)

Parameters

sendingStream Stream: The stream used to transmit messages. May be null.
receivingStream Stream: The stream used to receive messages. May be null.
target object: An optional target object to invoke when incoming RPC requests arrive.

Remarks

It is important to call StartListening() to begin receiving messages.

Properties

ActivityTracingStrategy

Gets or sets the strategy for propagating activity IDs over RPC.

public IActivityTracingStrategy? ActivityTracingStrategy { get; set; }

Property Value

IActivityTracingStrategy

AllowModificationWhileListening

Gets or sets a value indicating whether configuration of this instance can be changed after StartListening() or Attach(Stream, object?) has been called.

public bool AllowModificationWhileListening { get; set; }

Property Value

bool: The default is false.

Remarks

By default, all configuration such as target objects and target methods must be set before listening starts to avoid a race condition whereby we receive a method invocation message before we have wired up a handler for it and must reject the call. But in some advanced scenarios, it may be necessary to add target methods after listening has started (e.g. in response to an invocation that enables additional functionality), in which case setting this property to true is appropriate.

CancelLocallyInvokedMethodsWhenConnectionIsClosed

Gets or sets a value indicating whether to cancel all methods dispatched locally that accept a CancellationToken when the connection with the remote party is closed.

public bool CancelLocallyInvokedMethodsWhenConnectionIsClosed { get; set; }

Property Value

bool

CancellationStrategy

Gets or sets the cancellation strategy to use.

public ICancellationStrategy? CancellationStrategy { get; set; }

Property Value

ICancellationStrategy: The default value is the StreamJsonRpc.StandardCancellationStrategy which uses the "$/cancelRequest" notification.

Exceptions

InvalidOperationException: Thrown if StreamJsonRpc.JsonRpc.HasListeningStarted is true and AllowModificationWhileListening is false.

Completion

Gets a Task that completes when this instance is disposed or when listening has stopped whether by error, disposal or the stream closing.

public Task Completion { get; }

Property Value

Task

Remarks

The returned Task may transition to a faulted state for exceptions fatal to the protocol or this instance.

When local RPC target objects or methods have been added, those methods may still be running from prior RPC requests when this property completes. Track their completion with the DispatchCompletion property.

DispatchCompletion

Gets a Task that completes when no local target methods are executing from an RPC call.

public Task DispatchCompletion { get; }

Property Value

Task

Remarks

If the JSON-RPC connection is still active when retrieving this property's value, the returned Task will complete when no local dispatches are in progress, even if the connection is still active. Retrieving the property after a previously obtained Task has completed will result in a new, incomplete Task if incoming requests are currently in dispatch.

ExceptionOptions

Gets or sets the settings to use for serializing/deserializing exceptions.

public ExceptionSettings ExceptionOptions { get; set; }

Property Value

ExceptionSettings

ExceptionStrategy

Gets or sets a value indicating whether exceptions thrown by the RPC server should be fully serialized for the RPC client to then deserialize.

public ExceptionProcessing ExceptionStrategy { get; set; }

Property Value

ExceptionProcessing: The default value is CommonErrorData.

Remarks

This setting influences the implementations of error processing virtual methods on this class. When those methods are overridden by a derived type, this property may have different or no impact on behavior. This does not alter how LocalRpcException behaves when thrown, since that exception type supplies all the details of the error response directly.

IsDisposed

Gets a value indicating whether this instance has been disposed.

public bool IsDisposed { get; }

Property Value

bool: true if this instance has been disposed.

JoinableTaskFactory

Gets or sets the JoinableTaskFactory to participate in to mitigate deadlocks with the main thread.

public JoinableTaskFactory? JoinableTaskFactory { get; set; }

Property Value

JoinableTaskFactory: Defaults to null.

JoinableTaskTracker

Gets or sets the JsonRpc.JoinableTaskTokenTracker to use to correlate JoinableTask tokens. This property is only applicable when JoinableTaskFactory is null.

public JsonRpc.JoinableTaskTokenTracker JoinableTaskTracker { get; set; }

Property Value

JsonRpc.JoinableTaskTokenTracker: Defaults to an instance shared with all other JsonRpc instances that do not otherwise set this value explicitly.

Remarks

This property is ignored when JoinableTaskFactory is set to a non-null value.

This property should only be set explicitly when in an advanced scenario where one process has many JsonRpc instances that interact with multiple remote processes such that avoiding correlating JoinableTask tokens across JsonRpc instances is undesirable.

LoadableTypes

Gets the set of types that can be deserialized by name at runtime.

public ref LoadableTypeCollection LoadableTypes { get; }

Property Value

LoadableTypeCollection

Remarks

This set of types is used by the default implementation of LoadTypeTrimSafe(string, string?) to determine which types can be deserialized when their name is encountered in an RPC message. At present, it is only used for deserializing Exception-derived types.

The default collection includes Exception, InvalidOperationException and ArgumentException.

As a `ref return` property, this property may be set to a collection of loadable types intended for sharing across JsonRpc instances.

SynchronizationContext

Gets or sets the SynchronizationContext to use when invoking methods requested by the remote party.

public SynchronizationContext? SynchronizationContext { get; set; }

Property Value

SynchronizationContext: Defaults to null.

Remarks

When not specified, methods are invoked on the threadpool.

TraceSource

Gets or sets the TraceSource used to trace JSON-RPC messages and events.

public TraceSource TraceSource { get; set; }

Property Value

TraceSource: The value can never be null.

Exceptions

ArgumentNullException: Thrown by the setter if a null value is provided.

Methods

AddLocalRpcMethod(MethodInfo, object?, JsonRpcMethodAttribute?)

Adds a handler for an RPC method with a given name.

public void AddLocalRpcMethod(MethodInfo handler, object? target, JsonRpcMethodAttribute? methodRpcSettings)

Parameters

handler MethodInfo: The method or delegate to invoke when a matching RPC message arrives. This method may accept parameters from the incoming JSON-RPC message.
target object: An instance of the type that defines handler which should handle the invocation.
methodRpcSettings JsonRpcMethodAttribute: A description for how this method should be treated. It need not be an attribute that was actually applied to handler. An attribute will not be discovered via reflection on the handler, even if this value is null.

Exceptions

InvalidOperationException: Thrown if called after StartListening() is called and AllowModificationWhileListening is false.

AddLocalRpcMethod(string?, Delegate)

Adds a handler for an RPC method with a given name.

public void AddLocalRpcMethod(string? rpcMethodName, Delegate handler)

Parameters

rpcMethodName string: The name of the method as it is identified by the incoming JSON-RPC message. It need not match the name of the CLR method/delegate given here.
handler Delegate: The method or delegate to invoke when a matching RPC message arrives. This method may accept parameters from the incoming JSON-RPC message.

Exceptions

InvalidOperationException: Thrown if called after StartListening() is called and AllowModificationWhileListening is false.

AddLocalRpcMethod(string?, MethodInfo, object?)

Adds a handler for an RPC method with a given name.

public void AddLocalRpcMethod(string? rpcMethodName, MethodInfo handler, object? target)

Parameters

rpcMethodName string: The name of the method as it is identified by the incoming JSON-RPC message. It need not match the name of the CLR method/delegate given here.
handler MethodInfo: The method or delegate to invoke when a matching RPC message arrives. This method may accept parameters from the incoming JSON-RPC message.
target object: An instance of the type that defines handler which should handle the invocation.

Exceptions

InvalidOperationException: Thrown if called after StartListening() is called and AllowModificationWhileListening is false.

AddLocalRpcTarget(RpcTargetMetadata, object, JsonRpcTargetOptions?)

Adds the specified target as possible object to invoke when incoming messages are received.

public void AddLocalRpcTarget(RpcTargetMetadata exposingMembersOn, object target, JsonRpcTargetOptions? options)

Parameters

exposingMembersOn RpcTargetMetadata: The description of the RPC target.
target object: Target to invoke when incoming messages are received.
options JsonRpcTargetOptions: A set of customizations for how the target object is registered. If null, default options will be used.

Remarks

When multiple target objects are added, the first target with a method that matches a request is invoked.

Exceptions

InvalidOperationException: Thrown if called after StartListening() is called and AllowModificationWhileListening is false.

AddLocalRpcTarget(object)

Adds the specified target as possible object to invoke when incoming messages are received.

public void AddLocalRpcTarget(object target)

Parameters

target object: Target to invoke when incoming messages are received.

Remarks

When multiple target objects are added, the first target with a method that matches a request is invoked.

Exceptions

InvalidOperationException: Thrown if called after StartListening() is called and AllowModificationWhileListening is false.

AddLocalRpcTarget(object, JsonRpcTargetOptions?)

Adds the specified target as possible object to invoke when incoming messages are received.

public void AddLocalRpcTarget(object target, JsonRpcTargetOptions? options)

Parameters

target object: Target to invoke when incoming messages are received.
options JsonRpcTargetOptions: A set of customizations for how the target object is registered. If null, default options will be used.

Remarks

When multiple target objects are added, the first target with a method that matches a request is invoked.

Exceptions

InvalidOperationException: Thrown if called after StartListening() is called and AllowModificationWhileListening is false.

AddLocalRpcTarget(Type, object, JsonRpcTargetOptions?)

Adds the specified target as possible object to invoke when incoming messages are received.

public void AddLocalRpcTarget(Type exposingMembersOn, object target, JsonRpcTargetOptions? options)

Parameters

exposingMembersOn Type: The description of the RPC target.
target object: Target to invoke when incoming messages are received.
options JsonRpcTargetOptions: A set of customizations for how the target object is registered. If null, default options will be used.

Remarks

When multiple target objects are added, the first target with a method that matches a request is invoked.

Exceptions

InvalidOperationException: Thrown if called after StartListening() is called and AllowModificationWhileListening is false.

AddLocalRpcTarget<T>(T, JsonRpcTargetOptions?)

Adds the specified target as possible object to invoke when incoming messages are received.

public void AddLocalRpcTarget<T>(T target, JsonRpcTargetOptions? options) where T : notnull

Parameters

target T: Target to invoke when incoming messages are received.
options JsonRpcTargetOptions: A set of customizations for how the target object is registered. If null, default options will be used.

Type Parameters

T: The description of the RPC target.

Remarks

When multiple target objects are added, the first target with a method that matches a request is invoked.

Exceptions

InvalidOperationException: Thrown if called after StartListening() is called and AllowModificationWhileListening is false.

AddRemoteRpcTarget(JsonRpc)

Adds a remote rpc connection so calls can be forwarded to the remote target if local targets do not handle it.

public void AddRemoteRpcTarget(JsonRpc remoteTarget)

Parameters

remoteTarget JsonRpc: The json rpc connection to the remote target.

Attach(Stream?, Stream?, object?)

Initializes a new instance of the JsonRpc class that uses HeaderDelimitedMessageHandler around messages serialized using the JsonMessageFormatter, and immediately starts listening.

public static JsonRpc Attach(Stream? sendingStream, Stream? receivingStream, object? target = null)

Parameters

sendingStream Stream: The stream used to transmit messages. May be null.
receivingStream Stream: The stream used to receive messages. May be null.
target object: An optional target object to invoke when incoming RPC requests arrive.

Returns

JsonRpc: The initialized and listening JsonRpc object.

Attach(Stream, object?)

Initializes a new instance of the JsonRpc class that uses HeaderDelimitedMessageHandler around messages serialized using the JsonMessageFormatter, and immediately starts listening.

public static JsonRpc Attach(Stream stream, object? target = null)

Parameters

stream Stream: A bidirectional stream to send and receive RPC messages on.
target object: An optional target object to invoke when incoming RPC requests arrive.

Returns

JsonRpc: The initialized and listening JsonRpc object.

Attach(ReadOnlySpan<Type>, JsonRpcProxyOptions?)

Creates a JSON-RPC client proxy that conforms to the specified server interfaces.

public object Attach(ReadOnlySpan<Type> interfaceTypes, JsonRpcProxyOptions? options)

Parameters

interfaceTypes ReadOnlySpan<Type>: The interfaces that describes the functions available on the remote end.
options JsonRpcProxyOptions: A set of customizations for how the client proxy is wired up. If null, default options will be used.

Returns

object: An instance of the generated proxy.

Remarks

Calls to this method are intercepted by a source generator and replaced with a NativeAOT-compatible method call when the interceptor is enabled.

Attach(Type)

Creates a JSON-RPC client proxy that conforms to the specified server interface.

public object Attach(Type interfaceType)

Parameters

interfaceType Type: The interface that describes the functions available on the remote end.

Returns

object: An instance of the generated proxy.

Remarks

Calls to this method are intercepted by a source generator and replaced with a NativeAOT-compatible method call when the interceptor is enabled.

Attach(Type, JsonRpcProxyOptions?)

Creates a JSON-RPC client proxy that conforms to the specified server interface.

public object Attach(Type interfaceType, JsonRpcProxyOptions? options)

Parameters

interfaceType Type: The interface that describes the functions available on the remote end.
options JsonRpcProxyOptions: A set of customizations for how the client proxy is wired up. If null, default options will be used.

Returns

object: An instance of the generated proxy.

Remarks

Calls to this method are intercepted by a source generator and replaced with a NativeAOT-compatible method call when the interceptor is enabled.

Attach<T>()

Creates a JSON-RPC client proxy that conforms to the specified server interface.

public T Attach<T>() where T : class

Returns

T: An instance of the generated proxy.

Type Parameters

T: The interface that describes the functions available on the remote end.

Remarks

Calls to this method are intercepted by a source generator and replaced with a NativeAOT-compatible method call when the interceptor is enabled.

Attach<T>(IJsonRpcMessageHandler)

Creates a JSON-RPC client proxy that conforms to the specified server interface.

public static T Attach<T>(IJsonRpcMessageHandler handler) where T : class

Parameters

handler IJsonRpcMessageHandler: The message handler to use.

Returns

T: An instance of the generated proxy. In addition to implementing T, it also implements IDisposable and should be disposed of to close the connection.

Type Parameters

T: The interface that describes the functions available on the remote end.

Remarks

Calls to this method are intercepted by a source generator and replaced with a NativeAOT-compatible method call when the interceptor is enabled.

Attach<T>(IJsonRpcMessageHandler, JsonRpcProxyOptions?)

Creates a JSON-RPC client proxy that conforms to the specified server interface.

public static T Attach<T>(IJsonRpcMessageHandler handler, JsonRpcProxyOptions? options) where T : class

Parameters

handler IJsonRpcMessageHandler: The message handler to use.
options JsonRpcProxyOptions: A set of customizations for how the client proxy is wired up. If null, default options will be used.

Returns

T: An instance of the generated proxy. In addition to implementing T, it also implements IDisposable and should be disposed of to close the connection.

Type Parameters

T: The interface that describes the functions available on the remote end.

Remarks

Calls to this method are intercepted by a source generator and replaced with a NativeAOT-compatible method call when the interceptor is enabled.

Attach<T>(JsonRpcProxyOptions?)

Creates a JSON-RPC client proxy that conforms to the specified server interface.

public T Attach<T>(JsonRpcProxyOptions? options) where T : class

Parameters

options JsonRpcProxyOptions: A set of customizations for how the client proxy is wired up. If null, default options will be used.

Returns

T: An instance of the generated proxy.

Type Parameters

T: The interface that describes the functions available on the remote end.

Remarks

Calls to this method are intercepted by a source generator and replaced with a NativeAOT-compatible method call when the interceptor is enabled.

Attach<T>(Stream)

Creates a JSON-RPC client proxy that conforms to the specified server interface.

public static T Attach<T>(Stream stream) where T : class

Parameters

stream Stream: The bidirectional stream used to send and receive JSON-RPC messages.

Returns

T: An instance of the generated proxy. In addition to implementing T, it also implements IDisposable and should be disposed of to close the connection.

Type Parameters

T: The interface that describes the functions available on the remote end.

Remarks

Calls to this method are intercepted by a source generator and replaced with a NativeAOT-compatible method call when the interceptor is enabled.

Attach<T>(Stream?, Stream?)

Creates a JSON-RPC client proxy that conforms to the specified server interface.

public static T Attach<T>(Stream? sendingStream, Stream? receivingStream) where T : class

Parameters

sendingStream Stream: The stream used to transmit messages. May be null.
receivingStream Stream: The stream used to receive messages. May be null.

Returns

T: An instance of the generated proxy. In addition to implementing T, it also implements IDisposable and should be disposed of to close the connection.

Type Parameters

T: The interface that describes the functions available on the remote end.

Remarks

Calls to this method are intercepted by a source generator and replaced with a NativeAOT-compatible method call when the interceptor is enabled.

CreateErrorDetails(JsonRpcRequest, Exception)

Creates the JsonRpcError.ErrorDetail to be used as the value for the error property to be sent back to the client in response to an exception being thrown from an RPC method invoked locally.

protected virtual JsonRpcError.ErrorDetail CreateErrorDetails(JsonRpcRequest request, Exception exception)

Parameters

request JsonRpcRequest: The request that led to the invocation that ended up failing.
exception Exception: The exception thrown from the RPC method.

Returns

JsonRpcError.ErrorDetail: The error details to return to the client. Must not be null.

Remarks

This method may be overridden in a derived class to change the way error details are expressed.

See Also: CreateExceptionFromRpcError(JsonRpcRequest, JsonRpcError)

CreateExceptionFromRpcError(JsonRpcRequest, JsonRpcError)

Creates a RemoteRpcException (or derived type) that represents the data found in a JSON-RPC error response. This is called on the client side to produce the exception that will be thrown back to the RPC client.

protected virtual RemoteRpcException CreateExceptionFromRpcError(JsonRpcRequest request, JsonRpcError response)

Parameters

request JsonRpcRequest: The JSON-RPC request that produced this error.
response JsonRpcError: The JSON-RPC error response.

Returns

RemoteRpcException: An instance of RemoteRpcException.

See Also: CreateErrorDetails(JsonRpcRequest, Exception)

CreateNewRequestId()

Creates a unique RequestId for an outbound request.

protected virtual RequestId CreateNewRequestId()

Returns

RequestId: The unique RequestId.

DispatchRequestAsync(JsonRpcRequest, TargetMethod, CancellationToken)

Invokes the method on the local RPC target object and converts the response into a JSON-RPC result message.

protected virtual ValueTask<JsonRpcMessage> DispatchRequestAsync(JsonRpcRequest request, TargetMethod targetMethod, CancellationToken cancellationToken)

Parameters

request JsonRpcRequest: The incoming JSON-RPC request that resulted in the targetMethod being selected to receive the dispatch.
targetMethod TargetMethod: The method to be invoked and the arguments to pass to it.
cancellationToken CancellationToken: A cancellation token to pass to InvokeAsync(CancellationToken).

Returns

ValueTask<JsonRpcMessage>: The JSON-RPC response message to send back to the client. This is never expected to be null. If the protocol indicates no response message is expected by the client, it will be dropped rather than transmitted.

Remarks

Overrides of this method are expected to call this base method for core functionality. Overrides should call the base method before any yielding await in order to maintain consistent message ordering unless the goal of the override is specifically to alter ordering of incoming messages.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

Dispose(bool)

Disposes managed and native resources held by this instance.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool: true if being disposed; false if being finalized.

GetErrorDetailsDataType(JsonRpcError)

Determines the type that the Data object should be deserialized to for an incoming JsonRpcError message.

protected virtual Type? GetErrorDetailsDataType(JsonRpcError error)

Parameters

error JsonRpcError: The received error message.

Returns

Type: The type, or null if the type is unknown.

Remarks

The default implementation matches what CreateErrorDetails(JsonRpcRequest, Exception) does by assuming that the Data object should be deserialized as an instance of CommonErrorData. However derived types can override this method and use Code or other means to determine the appropriate type.

GetJsonRpcMethodAttribute(string, ReadOnlySpan<ParameterInfo>)

Gets the JsonRpcMethodAttribute for a previously discovered RPC method, if there is one.

public JsonRpcMethodAttribute? GetJsonRpcMethodAttribute(string methodName, ReadOnlySpan<ParameterInfo> parameters)

Parameters

methodName string: The name of the method for which the attribute is sought.
parameters ReadOnlySpan<ParameterInfo>: The list of parameters found on the method, as they may be given to TryGetTypedArguments(ReadOnlySpan<ParameterInfo>, Span<object?>). Note this list may omit some special parameters such as a trailing CancellationToken.

Returns

JsonRpcMethodAttribute

InvokeAsync(string, object?)

Invokes a given method on a JSON-RPC server.

public Task InvokeAsync(string targetName, object? argument)

Parameters

targetName string: Name of the method to invoke. Must not be null or empty.
argument object: A single method argument, must be serializable using the selected IJsonRpcMessageFormatter.

Returns

Task: A task that completes with the response from the JSON-RPC server.

Exceptions

OperationCanceledException: Thrown after cancellationToken is canceled. If the request has already been transmitted, the exception is only thrown after the server has received the cancellation notification and responded to it. If the server completes the request instead of cancelling, this exception will not be thrown. When the connection drops before receiving a response, this exception is thrown if cancellationToken has been canceled.
RemoteRpcException: A common base class for a variety of RPC exceptions that may be thrown. Some common derived types are listed individually.
RemoteInvocationException: Thrown when an error is returned from the server in consequence of executing the requested method.
RemoteMethodNotFoundException: Thrown when the server reports that no matching method was found to invoke.
ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) before the request or while the request is in progress, unless cancellationToken is already signaled.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

InvokeAsync(string, params object?[]?)

Invokes a given method on a JSON-RPC server.

public Task InvokeAsync(string targetName, params object?[]? arguments)

Parameters

targetName string: Name of the method to invoke. Must not be null or empty.
arguments object[]: Arguments to pass to the invoked method. They must be serializable using the selected IJsonRpcMessageFormatter. If null, no arguments are passed.

Returns

Task: A task that completes with the response from the JSON-RPC server.

Exceptions

OperationCanceledException: Thrown after cancellationToken is canceled. If the request has already been transmitted, the exception is only thrown after the server has received the cancellation notification and responded to it. If the server completes the request instead of cancelling, this exception will not be thrown. When the connection drops before receiving a response, this exception is thrown if cancellationToken has been canceled.
RemoteRpcException: A common base class for a variety of RPC exceptions that may be thrown. Some common derived types are listed individually.
RemoteInvocationException: Thrown when an error is returned from the server in consequence of executing the requested method.
RemoteMethodNotFoundException: Thrown when the server reports that no matching method was found to invoke.
ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) before the request or while the request is in progress, unless cancellationToken is already signaled.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

InvokeAsync<TResult>(string, object?)

Invokes a given method on a JSON-RPC server.

public Task<TResult> InvokeAsync<TResult>(string targetName, object? argument)

Parameters

targetName string: Name of the method to invoke. Must not be null or empty.
argument object: A single method argument, must be serializable using the selected IJsonRpcMessageFormatter.

Returns

Task<TResult>: A task that completes with the response from the JSON-RPC server.

Type Parameters

TResult: Type of the method result.

Exceptions

OperationCanceledException: Thrown after cancellationToken is canceled. If the request has already been transmitted, the exception is only thrown after the server has received the cancellation notification and responded to it. If the server completes the request instead of cancelling, this exception will not be thrown. When the connection drops before receiving a response, this exception is thrown if cancellationToken has been canceled.
RemoteRpcException: A common base class for a variety of RPC exceptions that may be thrown. Some common derived types are listed individually.
RemoteInvocationException: Thrown when an error is returned from the server in consequence of executing the requested method.
RemoteMethodNotFoundException: Thrown when the server reports that no matching method was found to invoke.
ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) before the request or while the request is in progress, unless cancellationToken is already signaled.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

InvokeAsync<TResult>(string, params object?[]?)

Invokes a given method on a JSON-RPC server.

public Task<TResult> InvokeAsync<TResult>(string targetName, params object?[]? arguments)

Parameters

targetName string: Name of the method to invoke. Must not be null or empty.
arguments object[]: Arguments to pass to the invoked method. They must be serializable using the selected IJsonRpcMessageFormatter. If null, no arguments are passed.

Returns

Task<TResult>: A task that completes with the response from the JSON-RPC server.

Type Parameters

TResult: Type of the method result.

Exceptions

OperationCanceledException: Thrown after cancellationToken is canceled. If the request has already been transmitted, the exception is only thrown after the server has received the cancellation notification and responded to it. If the server completes the request instead of cancelling, this exception will not be thrown. When the connection drops before receiving a response, this exception is thrown if cancellationToken has been canceled.
RemoteRpcException: A common base class for a variety of RPC exceptions that may be thrown. Some common derived types are listed individually.
RemoteInvocationException: Thrown when an error is returned from the server in consequence of executing the requested method.
RemoteMethodNotFoundException: Thrown when the server reports that no matching method was found to invoke.
ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) before the request or while the request is in progress, unless cancellationToken is already signaled.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

InvokeCoreAsync<TResult>(RequestId, string, IReadOnlyList<object?>?, IReadOnlyList<Type>?, IReadOnlyDictionary<string, Type>?, CancellationToken, bool)

Invokes a given method on a JSON-RPC server.

protected Task<TResult> InvokeCoreAsync<TResult>(RequestId id, string targetName, IReadOnlyList<object?>? arguments, IReadOnlyList<Type>? positionalArgumentDeclaredTypes, IReadOnlyDictionary<string, Type>? namedArgumentDeclaredTypes, CancellationToken cancellationToken, bool isParameterObject)

Parameters

id RequestId: An identifier established by the Client. If the default value is given, it is assumed to be a notification.
targetName string: Name of the method to invoke. Must not be null or empty.
arguments IReadOnlyList<object>: Arguments to pass to the invoked method. They must be serializable using the selected IJsonRpcMessageFormatter. If null, no arguments are passed.
positionalArgumentDeclaredTypes IReadOnlyList<Type>: A list of Type objects that describe how each element in arguments is expected by the server to be typed. If specified, this must have exactly the same length as arguments and contain no null elements. This value is ignored when isParameterObject is true.
namedArgumentDeclaredTypes IReadOnlyDictionary<string, Type>: A dictionary of Type objects that describe how each entry in the IReadOnlyDictionary<TKey, TValue> provided in the only element of arguments is expected by the server to be typed. If specified, this must have exactly the same set of keys as the dictionary contained in the first element of arguments, and contain no null values.
cancellationToken CancellationToken: The token whose cancellation should signal the server to stop processing this request.
isParameterObject bool: Value which indicates if parameter should be passed as an object.

Returns

Task<TResult>: A task that completes with the response from the JSON-RPC server.

Type Parameters

TResult: RPC method return type.

Exceptions

OperationCanceledException: Thrown after cancellationToken is canceled. If the request has already been transmitted, the exception is only thrown after the server has received the cancellation notification and responded to it. If the server completes the request instead of cancelling, this exception will not be thrown. When the connection drops before receiving a response, this exception is thrown if cancellationToken has been canceled.
RemoteRpcException: A common base class for a variety of RPC exceptions that may be thrown. Some common derived types are listed individually.
RemoteInvocationException: Thrown when an error is returned from the server in consequence of executing the requested method.
RemoteMethodNotFoundException: Thrown when the server reports that no matching method was found to invoke.
ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) before the request or while the request is in progress, unless cancellationToken is already signaled.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

InvokeCoreAsync<TResult>(RequestId, string, IReadOnlyList<object?>?, CancellationToken)

Invokes the specified RPC method.

protected Task<TResult> InvokeCoreAsync<TResult>(RequestId id, string targetName, IReadOnlyList<object?>? arguments, CancellationToken cancellationToken)

Parameters

id RequestId: An identifier established by the Client that MUST contain a String, Number, or NULL value if included. If it is not included it is assumed to be a notification.
targetName string: Name of the method to invoke. Must not be null or empty.
arguments IReadOnlyList<object>: Arguments to pass to the invoked method. They must be serializable using the selected IJsonRpcMessageFormatter. If null, no arguments are passed.
cancellationToken CancellationToken: The token whose cancellation should signal the server to stop processing this request.

Returns

Task<TResult>: A task that completes with the response from the JSON-RPC server.

Type Parameters

TResult: RPC method return type.

InvokeCoreAsync<TResult>(RequestId, string, IReadOnlyList<object?>?, CancellationToken, bool)

Invokes a given method on a JSON-RPC server.

protected Task<TResult> InvokeCoreAsync<TResult>(RequestId id, string targetName, IReadOnlyList<object?>? arguments, CancellationToken cancellationToken, bool isParameterObject)

Parameters

id RequestId: An identifier established by the Client. If the default value is given, it is assumed to be a notification.
targetName string: Name of the method to invoke. Must not be null or empty.
arguments IReadOnlyList<object>: Arguments to pass to the invoked method. They must be serializable using the selected IJsonRpcMessageFormatter. If null, no arguments are passed.
cancellationToken CancellationToken: The token whose cancellation should signal the server to stop processing this request.
isParameterObject bool: Value which indicates if parameter should be passed as an object.

Returns

Task<TResult>: A task that completes with the response from the JSON-RPC server.

Type Parameters

TResult: RPC method return type.

Exceptions

OperationCanceledException: Thrown after cancellationToken is canceled. If the request has already been transmitted, the exception is only thrown after the server has received the cancellation notification and responded to it. If the server completes the request instead of cancelling, this exception will not be thrown. When the connection drops before receiving a response, this exception is thrown if cancellationToken has been canceled.
RemoteRpcException: A common base class for a variety of RPC exceptions that may be thrown. Some common derived types are listed individually.
RemoteInvocationException: Thrown when an error is returned from the server in consequence of executing the requested method.
RemoteMethodNotFoundException: Thrown when the server reports that no matching method was found to invoke.
ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) before the request or while the request is in progress, unless cancellationToken is already signaled.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

InvokeCoreAsync<TResult>(long?, string, IReadOnlyList<object?>?, CancellationToken)

Invokes the specified RPC method.

[Obsolete("Use the InvokeCoreAsync(RequestId, ...) overload instead.")]
protected Task<TResult> InvokeCoreAsync<TResult>(long? id, string targetName, IReadOnlyList<object?>? arguments, CancellationToken cancellationToken)

Parameters

id long?: An identifier established by the Client that MUST contain a String, Number, or NULL value if included. If it is not included it is assumed to be a notification.
targetName string: Name of the method to invoke. Must not be null or empty.
arguments IReadOnlyList<object>: Arguments to pass to the invoked method. They must be serializable using the selected IJsonRpcMessageFormatter. If null, no arguments are passed.
cancellationToken CancellationToken: The token whose cancellation should signal the server to stop processing this request.

Returns

Task<TResult>: A task that completes with the response from the JSON-RPC server.

Type Parameters

TResult: RPC method return type.

InvokeCoreAsync<TResult>(long?, string, IReadOnlyList<object?>?, CancellationToken, bool)

Invokes a given method on a JSON-RPC server.

[Obsolete("Use the InvokeCoreAsync(RequestId, ...) overload instead.")]
protected Task<TResult> InvokeCoreAsync<TResult>(long? id, string targetName, IReadOnlyList<object?>? arguments, CancellationToken cancellationToken, bool isParameterObject)

Parameters

id long?: An identifier established by the Client. If the default value is given, it is assumed to be a notification.
targetName string: Name of the method to invoke. Must not be null or empty.
arguments IReadOnlyList<object>: Arguments to pass to the invoked method. They must be serializable using the selected IJsonRpcMessageFormatter. If null, no arguments are passed.
cancellationToken CancellationToken: The token whose cancellation should signal the server to stop processing this request.
isParameterObject bool: Value which indicates if parameter should be passed as an object.

Returns

Task<TResult>: A task that completes with the response from the JSON-RPC server.

Type Parameters

TResult: RPC method return type.

InvokeWithCancellationAsync(string, IReadOnlyList<object?>?, IReadOnlyList<Type>, CancellationToken)

Invokes a given method on a JSON-RPC server.

public Task InvokeWithCancellationAsync(string targetName, IReadOnlyList<object?>? arguments, IReadOnlyList<Type> argumentDeclaredTypes, CancellationToken cancellationToken)

Parameters

targetName string: Name of the method to invoke. Must not be null or empty.
arguments IReadOnlyList<object>: Arguments to pass to the invoked method. They must be serializable using the selected IJsonRpcMessageFormatter. If null, no arguments are passed.
argumentDeclaredTypes IReadOnlyList<Type>: A list of Type objects that describe how each element in arguments is expected by the server to be typed. If specified, this must have exactly the same length as arguments and contain no null elements. This value is ignored when isParameterObject is true.
cancellationToken CancellationToken: The token whose cancellation should signal the server to stop processing this request.

Returns

Task: A task that completes with the response from the JSON-RPC server.

Exceptions

OperationCanceledException: Thrown after cancellationToken is canceled. If the request has already been transmitted, the exception is only thrown after the server has received the cancellation notification and responded to it. If the server completes the request instead of cancelling, this exception will not be thrown. When the connection drops before receiving a response, this exception is thrown if cancellationToken has been canceled.
RemoteRpcException: A common base class for a variety of RPC exceptions that may be thrown. Some common derived types are listed individually.
RemoteInvocationException: Thrown when an error is returned from the server in consequence of executing the requested method.
RemoteMethodNotFoundException: Thrown when the server reports that no matching method was found to invoke.
ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) before the request or while the request is in progress, unless cancellationToken is already signaled.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

InvokeWithCancellationAsync(string, IReadOnlyList<object?>?, CancellationToken)

Invokes a given method on a JSON-RPC server.

public Task InvokeWithCancellationAsync(string targetName, IReadOnlyList<object?>? arguments = null, CancellationToken cancellationToken = default)

Parameters

targetName string: Name of the method to invoke. Must not be null or empty.
arguments IReadOnlyList<object>: Arguments to pass to the invoked method. They must be serializable using the selected IJsonRpcMessageFormatter. If null, no arguments are passed.
cancellationToken CancellationToken: The token whose cancellation should signal the server to stop processing this request.

Returns

Task: A task that completes with the response from the JSON-RPC server.

Exceptions

OperationCanceledException: Thrown after cancellationToken is canceled. If the request has already been transmitted, the exception is only thrown after the server has received the cancellation notification and responded to it. If the server completes the request instead of cancelling, this exception will not be thrown. When the connection drops before receiving a response, this exception is thrown if cancellationToken has been canceled.
RemoteRpcException: A common base class for a variety of RPC exceptions that may be thrown. Some common derived types are listed individually.
RemoteInvocationException: Thrown when an error is returned from the server in consequence of executing the requested method.
RemoteMethodNotFoundException: Thrown when the server reports that no matching method was found to invoke.
ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) before the request or while the request is in progress, unless cancellationToken is already signaled.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

InvokeWithCancellationAsync<TResult>(string, IReadOnlyList<object?>?, IReadOnlyList<Type>?, CancellationToken)

Invokes a given method on a JSON-RPC server.

public Task<TResult> InvokeWithCancellationAsync<TResult>(string targetName, IReadOnlyList<object?>? arguments, IReadOnlyList<Type>? argumentDeclaredTypes, CancellationToken cancellationToken)

Parameters

targetName string: Name of the method to invoke. Must not be null or empty.
arguments IReadOnlyList<object>: Arguments to pass to the invoked method. They must be serializable using the selected IJsonRpcMessageFormatter. If null, no arguments are passed.
argumentDeclaredTypes IReadOnlyList<Type>: A list of Type objects that describe how each element in arguments is expected by the server to be typed. If specified, this must have exactly the same length as arguments and contain no null elements. This value is ignored when isParameterObject is true.
cancellationToken CancellationToken: The token whose cancellation should signal the server to stop processing this request.

Returns

Task<TResult>: A task that completes when the server method executes and returns the result.

Type Parameters

TResult: Type of the method result.

Exceptions

OperationCanceledException: Thrown after cancellationToken is canceled. If the request has already been transmitted, the exception is only thrown after the server has received the cancellation notification and responded to it. If the server completes the request instead of cancelling, this exception will not be thrown. When the connection drops before receiving a response, this exception is thrown if cancellationToken has been canceled.
RemoteRpcException: A common base class for a variety of RPC exceptions that may be thrown. Some common derived types are listed individually.
RemoteInvocationException: Thrown when an error is returned from the server in consequence of executing the requested method.
RemoteMethodNotFoundException: Thrown when the server reports that no matching method was found to invoke.
ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) before the request or while the request is in progress, unless cancellationToken is already signaled.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

InvokeWithCancellationAsync<TResult>(string, IReadOnlyList<object?>?, CancellationToken)

Invokes a given method on a JSON-RPC server.

public Task<TResult> InvokeWithCancellationAsync<TResult>(string targetName, IReadOnlyList<object?>? arguments = null, CancellationToken cancellationToken = default)

Parameters

targetName string: Name of the method to invoke. Must not be null or empty.
arguments IReadOnlyList<object>: Arguments to pass to the invoked method. They must be serializable using the selected IJsonRpcMessageFormatter. If null, no arguments are passed.
cancellationToken CancellationToken: The token whose cancellation should signal the server to stop processing this request.

Returns

Task<TResult>: A task that completes when the server method executes and returns the result.

Type Parameters

TResult: Type of the method result.

Exceptions

OperationCanceledException: Thrown after cancellationToken is canceled. If the request has already been transmitted, the exception is only thrown after the server has received the cancellation notification and responded to it. If the server completes the request instead of cancelling, this exception will not be thrown. When the connection drops before receiving a response, this exception is thrown if cancellationToken has been canceled.
RemoteRpcException: A common base class for a variety of RPC exceptions that may be thrown. Some common derived types are listed individually.
RemoteInvocationException: Thrown when an error is returned from the server in consequence of executing the requested method.
RemoteMethodNotFoundException: Thrown when the server reports that no matching method was found to invoke.
ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) before the request or while the request is in progress, unless cancellationToken is already signaled.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

InvokeWithParameterObjectAsync(string, NamedArgs?, CancellationToken)

Invokes a given method on a JSON-RPC server.

public Task InvokeWithParameterObjectAsync(string targetName, NamedArgs? argument = null, CancellationToken cancellationToken = default)

Parameters

targetName string: Name of the method to invoke. Must not be null or empty.
argument NamedArgs: An object that captures the parameter names, types, and the arguments to be passed to the RPC method.
cancellationToken CancellationToken: The token whose cancellation should signal the server to stop processing this request.

Returns

Task: A task that completes with the response from the JSON-RPC server.

Exceptions

OperationCanceledException: Thrown after cancellationToken is canceled. If the request has already been transmitted, the exception is only thrown after the server has received the cancellation notification and responded to it. If the server completes the request instead of cancelling, this exception will not be thrown. When the connection drops before receiving a response, this exception is thrown if cancellationToken has been canceled.
RemoteRpcException: A common base class for a variety of RPC exceptions that may be thrown. Some common derived types are listed individually.
RemoteInvocationException: Thrown when an error is returned from the server in consequence of executing the requested method.
RemoteMethodNotFoundException: Thrown when the server reports that no matching method was found to invoke.
ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) before the request or while the request is in progress, unless cancellationToken is already signaled.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

InvokeWithParameterObjectAsync(string, IReadOnlyDictionary<string, object?>?, IReadOnlyDictionary<string, Type>?, CancellationToken)

Invokes a given method on a JSON-RPC server.

public Task InvokeWithParameterObjectAsync(string targetName, IReadOnlyDictionary<string, object?>? argument, IReadOnlyDictionary<string, Type>? argumentDeclaredTypes, CancellationToken cancellationToken)

Parameters

targetName string: Name of the method to invoke. Must not be null or empty.
argument IReadOnlyDictionary<string, object>: An object whose properties match the names of parameters on the target method. Must be serializable using the selected IJsonRpcMessageFormatter.
argumentDeclaredTypes IReadOnlyDictionary<string, Type>: A dictionary of Type objects that describe how each entry in the IReadOnlyDictionary<TKey, TValue> provided in argument is expected by the server to be typed. If specified, this must have exactly the same set of keys as argument and contain no null values.
cancellationToken CancellationToken: The token whose cancellation should signal the server to stop processing this request.

Returns

Task: A task that completes with the response from the JSON-RPC server.

Exceptions

OperationCanceledException: Thrown after cancellationToken is canceled. If the request has already been transmitted, the exception is only thrown after the server has received the cancellation notification and responded to it. If the server completes the request instead of cancelling, this exception will not be thrown. When the connection drops before receiving a response, this exception is thrown if cancellationToken has been canceled.
RemoteRpcException: A common base class for a variety of RPC exceptions that may be thrown. Some common derived types are listed individually.
RemoteInvocationException: Thrown when an error is returned from the server in consequence of executing the requested method.
RemoteMethodNotFoundException: Thrown when the server reports that no matching method was found to invoke.
ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) before the request or while the request is in progress, unless cancellationToken is already signaled.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

InvokeWithParameterObjectAsync(string, object?, IReadOnlyDictionary<string, Type>?, CancellationToken)

Invokes a given method on a JSON-RPC server.

public Task InvokeWithParameterObjectAsync(string targetName, object? argument, IReadOnlyDictionary<string, Type>? argumentDeclaredTypes, CancellationToken cancellationToken)

Parameters

targetName string: Name of the method to invoke. Must not be null or empty.
argument object: An object whose properties match the names of parameters on the target method. Must be serializable using the selected IJsonRpcMessageFormatter.
argumentDeclaredTypes IReadOnlyDictionary<string, Type>: A dictionary of Type objects that describe how each entry in the IReadOnlyDictionary<TKey, TValue> provided in argument is expected by the server to be typed. If specified, this must have exactly the same set of keys as argument and contain no null values.
cancellationToken CancellationToken: The token whose cancellation should signal the server to stop processing this request.

Returns

Task: A task that completes with the response from the JSON-RPC server.

Exceptions

OperationCanceledException: Thrown after cancellationToken is canceled. If the request has already been transmitted, the exception is only thrown after the server has received the cancellation notification and responded to it. If the server completes the request instead of cancelling, this exception will not be thrown. When the connection drops before receiving a response, this exception is thrown if cancellationToken has been canceled.
RemoteRpcException: A common base class for a variety of RPC exceptions that may be thrown. Some common derived types are listed individually.
RemoteInvocationException: Thrown when an error is returned from the server in consequence of executing the requested method.
RemoteMethodNotFoundException: Thrown when the server reports that no matching method was found to invoke.
ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) before the request or while the request is in progress, unless cancellationToken is already signaled.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

InvokeWithParameterObjectAsync(string, object?, CancellationToken)

Invokes a given method on a JSON-RPC server.

public Task InvokeWithParameterObjectAsync(string targetName, object? argument = null, CancellationToken cancellationToken = default)

Parameters

targetName string: Name of the method to invoke. Must not be null or empty.
argument object: An object whose properties match the names of parameters on the target method. Must be serializable using the selected IJsonRpcMessageFormatter.
cancellationToken CancellationToken: The token whose cancellation should signal the server to stop processing this request.

Returns

Task: A task that completes with the response from the JSON-RPC server.

Exceptions

OperationCanceledException: Thrown after cancellationToken is canceled. If the request has already been transmitted, the exception is only thrown after the server has received the cancellation notification and responded to it. If the server completes the request instead of cancelling, this exception will not be thrown. When the connection drops before receiving a response, this exception is thrown if cancellationToken has been canceled.
RemoteRpcException: A common base class for a variety of RPC exceptions that may be thrown. Some common derived types are listed individually.
RemoteInvocationException: Thrown when an error is returned from the server in consequence of executing the requested method.
RemoteMethodNotFoundException: Thrown when the server reports that no matching method was found to invoke.
ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) before the request or while the request is in progress, unless cancellationToken is already signaled.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

InvokeWithParameterObjectAsync<TResult>(string, NamedArgs?, CancellationToken)

Invokes a given method on a JSON-RPC server.

public Task<TResult> InvokeWithParameterObjectAsync<TResult>(string targetName, NamedArgs? argument = null, CancellationToken cancellationToken = default)

Parameters

targetName string: Name of the method to invoke. Must not be null or empty.
argument NamedArgs: An object that captures the parameter names, types, and the arguments to be passed to the RPC method.
cancellationToken CancellationToken: The token whose cancellation should signal the server to stop processing this request.

Returns

Task<TResult>: A task that completes with the response from the JSON-RPC server.

Type Parameters

TResult: Type of the method result.

Exceptions

OperationCanceledException: Thrown after cancellationToken is canceled. If the request has already been transmitted, the exception is only thrown after the server has received the cancellation notification and responded to it. If the server completes the request instead of cancelling, this exception will not be thrown. When the connection drops before receiving a response, this exception is thrown if cancellationToken has been canceled.
RemoteRpcException: A common base class for a variety of RPC exceptions that may be thrown. Some common derived types are listed individually.
RemoteInvocationException: Thrown when an error is returned from the server in consequence of executing the requested method.
RemoteMethodNotFoundException: Thrown when the server reports that no matching method was found to invoke.
ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) before the request or while the request is in progress, unless cancellationToken is already signaled.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

InvokeWithParameterObjectAsync<TResult>(string, IReadOnlyDictionary<string, object?>?, IReadOnlyDictionary<string, Type>?, CancellationToken)

Invokes a given method on a JSON-RPC server.

public Task<TResult> InvokeWithParameterObjectAsync<TResult>(string targetName, IReadOnlyDictionary<string, object?>? argument, IReadOnlyDictionary<string, Type>? argumentDeclaredTypes, CancellationToken cancellationToken)

Parameters

targetName string: Name of the method to invoke. Must not be null or empty.
argument IReadOnlyDictionary<string, object>: An object whose properties match the names of parameters on the target method. Must be serializable using the selected IJsonRpcMessageFormatter.
argumentDeclaredTypes IReadOnlyDictionary<string, Type>: A dictionary of Type objects that describe how each entry in the IReadOnlyDictionary<TKey, TValue> provided in argument is expected by the server to be typed. If specified, this must have exactly the same set of keys as argument and contain no null values.
cancellationToken CancellationToken: The token whose cancellation should signal the server to stop processing this request.

Returns

Task<TResult>: A task that completes with the response from the JSON-RPC server.

Type Parameters

TResult: Type of the method result.

Exceptions

OperationCanceledException: Thrown after cancellationToken is canceled. If the request has already been transmitted, the exception is only thrown after the server has received the cancellation notification and responded to it. If the server completes the request instead of cancelling, this exception will not be thrown. When the connection drops before receiving a response, this exception is thrown if cancellationToken has been canceled.
RemoteRpcException: A common base class for a variety of RPC exceptions that may be thrown. Some common derived types are listed individually.
RemoteInvocationException: Thrown when an error is returned from the server in consequence of executing the requested method.
RemoteMethodNotFoundException: Thrown when the server reports that no matching method was found to invoke.
ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) before the request or while the request is in progress, unless cancellationToken is already signaled.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

InvokeWithParameterObjectAsync<TResult>(string, object?, IReadOnlyDictionary<string, Type>?, CancellationToken)

Invokes a given method on a JSON-RPC server.

public Task<TResult> InvokeWithParameterObjectAsync<TResult>(string targetName, object? argument, IReadOnlyDictionary<string, Type>? argumentDeclaredTypes, CancellationToken cancellationToken)

Parameters

targetName string: Name of the method to invoke. Must not be null or empty.
argument object: An object whose properties match the names of parameters on the target method. Must be serializable using the selected IJsonRpcMessageFormatter.
argumentDeclaredTypes IReadOnlyDictionary<string, Type>: A dictionary of Type objects that describe how each entry in the IReadOnlyDictionary<TKey, TValue> provided in argument is expected by the server to be typed. If specified, this must have exactly the same set of keys as argument and contain no null values.
cancellationToken CancellationToken: The token whose cancellation should signal the server to stop processing this request.

Returns

Task<TResult>: A task that completes with the response from the JSON-RPC server.

Type Parameters

TResult: Type of the method result.

Exceptions

OperationCanceledException: Thrown after cancellationToken is canceled. If the request has already been transmitted, the exception is only thrown after the server has received the cancellation notification and responded to it. If the server completes the request instead of cancelling, this exception will not be thrown. When the connection drops before receiving a response, this exception is thrown if cancellationToken has been canceled.
RemoteRpcException: A common base class for a variety of RPC exceptions that may be thrown. Some common derived types are listed individually.
RemoteInvocationException: Thrown when an error is returned from the server in consequence of executing the requested method.
RemoteMethodNotFoundException: Thrown when the server reports that no matching method was found to invoke.
ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) before the request or while the request is in progress, unless cancellationToken is already signaled.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

InvokeWithParameterObjectAsync<TResult>(string, object?, CancellationToken)

Invokes a given method on a JSON-RPC server.

public Task<TResult> InvokeWithParameterObjectAsync<TResult>(string targetName, object? argument = null, CancellationToken cancellationToken = default)

Parameters

targetName string: Name of the method to invoke. Must not be null or empty.
argument object: An object whose properties match the names of parameters on the target method. Must be serializable using the selected IJsonRpcMessageFormatter.
cancellationToken CancellationToken: The token whose cancellation should signal the server to stop processing this request.

Returns

Task<TResult>: A task that completes with the response from the JSON-RPC server.

Type Parameters

TResult: Type of the method result.

Exceptions

OperationCanceledException: Thrown after cancellationToken is canceled. If the request has already been transmitted, the exception is only thrown after the server has received the cancellation notification and responded to it. If the server completes the request instead of cancelling, this exception will not be thrown. When the connection drops before receiving a response, this exception is thrown if cancellationToken has been canceled.
RemoteRpcException: A common base class for a variety of RPC exceptions that may be thrown. Some common derived types are listed individually.
RemoteInvocationException: Thrown when an error is returned from the server in consequence of executing the requested method.
RemoteMethodNotFoundException: Thrown when the server reports that no matching method was found to invoke.
ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) before the request or while the request is in progress, unless cancellationToken is already signaled.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

IsFatalException(Exception)

Indicates whether the connection should be closed when the server throws an exception.

protected virtual bool IsFatalException(Exception ex)

Parameters

ex Exception: The Exception thrown from server that is potentially fatal.

Returns

bool: A bool indicating if the streams should be closed.

Remarks

This method is invoked within the context of an exception filter or when a task fails to complete and simply returns false by default. If the process should crash on an exception, calling FailFast(string, Exception) will produce such behavior.

LoadType(string, string?)

Attempts to load a type based on its full name and possibly assembly name.

protected virtual Type? LoadType(string typeFullName, string? assemblyName)

Parameters

typeFullName string: The FullName of the type to be loaded.
assemblyName string: The assemble name that is expected to define the type, if available. This should be parseable by AssemblyName(string).

Returns

Type: The loaded Type, if one could be found; otherwise null.

Remarks

This method is used to load types that are strongly referenced by incoming messages during serialization. It is important to not load types that may pose a security threat based on the type and the trust level of the remote party.

The default implementation of this method loads any type named if it can be found based on its assembly name (if provided) or based on any assembly already loaded in the AppDomain otherwise.

Implementations should avoid throwing FileLoadException, TypeLoadException or other exceptions, preferring to return null instead.

LoadTypeTrimSafe(string, string?)

When overridden by a derived type, this attempts to load a type based on its full name and possibly assembly name.

protected virtual Type? LoadTypeTrimSafe(string typeFullName, string? assemblyName)

Parameters

typeFullName string: The FullName of the type to be loaded.
assemblyName string: The assemble name that is expected to define the type, if available. This should be parseable by AssemblyName(string).

Returns

Type: The loaded Type, if one could be found; otherwise null.

Remarks

The default implementation of this method matches types registered with the LoadableTypes collection.

Implementations should avoid throwing FileLoadException, TypeLoadException or other exceptions, preferring to return null instead.

NotifyAsync(string, object?)

Invokes a given method on a JSON-RPC server without waiting for its response.

public Task NotifyAsync(string targetName, object? argument)

Parameters

targetName string: Name of the method to invoke. Must not be null or empty.
argument object: Method argument, must be serializable using the selected IJsonRpcMessageFormatter.

Returns

Task: A task that completes when the notify request is sent to the channel to the server.

Remarks

Any error that happens on the server side is ignored.

Exceptions

ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) while the request is being transmitted.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

NotifyAsync(string, params object?[]?)

Invokes a given method on a JSON-RPC server without waiting for its response.

public Task NotifyAsync(string targetName, params object?[]? arguments)

Parameters

targetName string: Name of the method to invoke. Must not be null or empty.
arguments object[]: Arguments to pass to the invoked method. They must be serializable using the selected IJsonRpcMessageFormatter. If null, no arguments are passed.

Returns

Task: A task that completes when the notify request is sent to the channel to the server.

Remarks

Any error that happens on the server side is ignored.

Exceptions

ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) while the request is being transmitted.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

NotifyAsync(string, object?[]?, IReadOnlyList<Type>?)

Invokes a given method on a JSON-RPC server without waiting for its response.

public Task NotifyAsync(string targetName, object?[]? arguments, IReadOnlyList<Type>? argumentDeclaredTypes)

Parameters

targetName string: Name of the method to invoke. Must not be null or empty.
arguments object[]: Arguments to pass to the invoked method. They must be serializable using the selected IJsonRpcMessageFormatter. If null, no arguments are passed.
argumentDeclaredTypes IReadOnlyList<Type>: A list of Type objects that describe how each element in arguments is expected by the server to be typed. If specified, this must have exactly the same length as arguments and contain no null elements. This value is ignored when isParameterObject is true.

Returns

Task: A task that completes when the notify request is sent to the channel to the server.

Remarks

Any error that happens on the server side is ignored.

Exceptions

ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) while the request is being transmitted.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

NotifyWithParameterObjectAsync(string, NamedArgs?)

Invokes a given method on a JSON-RPC server without waiting for its response.

public Task NotifyWithParameterObjectAsync(string targetName, NamedArgs? argument = null)

Parameters

targetName string: Name of the method to invoke. Must not be null or empty.
argument NamedArgs: An object whose properties match the names of parameters on the target method. Must be serializable using the selected IJsonRpcMessageFormatter.

Returns

Task: A task that completes when the notification has been transmitted.

Remarks

Any error that happens on the server side is ignored.

Exceptions

ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) while the request is being transmitted.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

NotifyWithParameterObjectAsync(string, IReadOnlyDictionary<string, object?>?, IReadOnlyDictionary<string, Type>?)

Invokes a given method on a JSON-RPC server without waiting for its response.

public Task NotifyWithParameterObjectAsync(string targetName, IReadOnlyDictionary<string, object?>? namedArguments, IReadOnlyDictionary<string, Type>? argumentDeclaredTypes)

Parameters

targetName string: Name of the method to invoke. Must not be null or empty.
namedArguments IReadOnlyDictionary<string, object>: A dictionary of parameter names and arguments.
argumentDeclaredTypes IReadOnlyDictionary<string, Type>: A dictionary of Type objects that describe how each entry in the IReadOnlyDictionary<TKey, TValue> provided in the only element of arguments is expected by the server to be typed. If specified, this must have exactly the same set of keys as the dictionary contained in the first element of arguments, and contain no null values.

Returns

Task: A task that completes when the notification has been transmitted.

Remarks

Any error that happens on the server side is ignored.

Exceptions

ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) while the request is being transmitted.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

NotifyWithParameterObjectAsync(string, object?)

Invokes a given method on a JSON-RPC server without waiting for its response.

public Task NotifyWithParameterObjectAsync(string targetName, object? argument = null)

Parameters

targetName string: Name of the method to invoke. Must not be null or empty.
argument object: An object whose properties match the names of parameters on the target method. Must be serializable using the selected IJsonRpcMessageFormatter.

Returns

Task: A task that completes when the notification has been transmitted.

Remarks

Any error that happens on the server side is ignored.

Exceptions

ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) while the request is being transmitted.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

NotifyWithParameterObjectAsync(string, object?, IReadOnlyDictionary<string, Type>?)

Invokes a given method on a JSON-RPC server without waiting for its response.

public Task NotifyWithParameterObjectAsync(string targetName, object? argument, IReadOnlyDictionary<string, Type>? argumentDeclaredTypes)

Parameters

targetName string: Name of the method to invoke. Must not be null or empty.
argument object: An object whose properties match the names of parameters on the target method. Must be serializable using the selected IJsonRpcMessageFormatter.
argumentDeclaredTypes IReadOnlyDictionary<string, Type>: A dictionary of Type objects that describe how each entry in the IReadOnlyDictionary<TKey, TValue> provided in the only element of arguments is expected by the server to be typed. If specified, this must have exactly the same set of keys as the dictionary contained in the first element of arguments, and contain no null values.

Returns

Task: A task that completes when the notification has been transmitted.

Remarks

Any error that happens on the server side is ignored.

Exceptions

ArgumentNullException: If targetName is null.
ArgumentException: Thrown when targetName is empty.
ObjectDisposedException: If this instance of JsonRpc has already been disposed prior to this call.
ConnectionLostException: Thrown when the connection is terminated (by either side) while the request is being transmitted.
Exception: Any exception thrown by the IJsonRpcMessageFormatter (typically due to serialization failures). When using JsonMessageFormatter this should be Newtonsoft.Json.JsonSerializationException. When using MessagePackFormatter this should be MessagePack.MessagePackSerializationException.

OnRequestTransmissionAborted(JsonRpcRequest)

Raises the RequestTransmissionAborted event.

protected virtual void OnRequestTransmissionAborted(JsonRpcRequest request)

Parameters

request JsonRpcRequest: The request whose transmission could not be completed.

OnResponseReceived(JsonRpcMessage)

Raises the ResponseReceived event.

protected virtual void OnResponseReceived(JsonRpcMessage response)

Parameters

response JsonRpcMessage: The result or error that was received.

OnResponseSent(JsonRpcMessage)

Raises the ResponseSent event.

protected virtual void OnResponseSent(JsonRpcMessage response)

Parameters

response JsonRpcMessage: The result or error that was sent.

SendAsync(JsonRpcMessage, CancellationToken)

Sends the JSON-RPC message to IJsonRpcMessageHandler instance to be transmitted.

protected virtual ValueTask SendAsync(JsonRpcMessage message, CancellationToken cancellationToken)

Parameters

message JsonRpcMessage: The message to send.
cancellationToken CancellationToken: A token to cancel the send request.

Returns

ValueTask: A task that represents the asynchronous operation.

Remarks

StartListening()

Starts listening to incoming messages.

public void StartListening()

Events

Disconnected

Raised when the underlying stream is disconnected.

public event EventHandler<JsonRpcDisconnectedEventArgs>? Disconnected

Event Type

EventHandler<JsonRpcDisconnectedEventArgs>

Table of Contents

Class JsonRpc

Constructors

JsonRpc(IJsonRpcMessageHandler)

Parameters

Remarks

JsonRpc(IJsonRpcMessageHandler, object?)

Parameters

Remarks

JsonRpc(Stream)

Parameters

Remarks

JsonRpc(Stream?, Stream?, object?)

Parameters

Remarks

Properties

ActivityTracingStrategy

Property Value

AllowModificationWhileListening

Property Value

Remarks

CancelLocallyInvokedMethodsWhenConnectionIsClosed

Property Value

CancellationStrategy

Property Value

Exceptions

Completion

Property Value

Remarks

DispatchCompletion

Property Value

Remarks

ExceptionOptions

Property Value

ExceptionStrategy

Property Value

Remarks

IsDisposed

Property Value

JoinableTaskFactory

Property Value

JoinableTaskTracker

Property Value

Remarks

LoadableTypes

Property Value

Remarks

SynchronizationContext

Property Value

Remarks

TraceSource

Property Value

Exceptions

Methods

AddLocalRpcMethod(MethodInfo, object?, JsonRpcMethodAttribute?)

Parameters

Exceptions

AddLocalRpcMethod(string?, Delegate)

Parameters

Exceptions

AddLocalRpcMethod(string?, MethodInfo, object?)

Parameters

Exceptions

AddLocalRpcTarget(RpcTargetMetadata, object, JsonRpcTargetOptions?)

Parameters

Remarks

Exceptions

AddLocalRpcTarget(object)

Parameters

Remarks

Exceptions

AddLocalRpcTarget(object, JsonRpcTargetOptions?)

Parameters

Remarks

Exceptions

AddLocalRpcTarget(Type, object, JsonRpcTargetOptions?)

Parameters

Remarks

Exceptions

AddLocalRpcTarget<T>(T, JsonRpcTargetOptions?)