Class ServiceJsonRpcDescriptor

Namespace

Microsoft.ServiceHub.Framework

Assembly

Microsoft.ServiceHub.Framework.dll

An RPC descriptor for services that support JSON-RPC.

public class ServiceJsonRpcDescriptor : ServiceRpcDescriptor, IEquatable<ServiceJsonRpcDescriptor>

Inheritance

object

ServiceRpcDescriptor

ServiceJsonRpcDescriptor

Implements

IEquatable<ServiceJsonRpcDescriptor>

Derived

DelegatingServiceJsonRpcDescriptor

ServiceJsonRpcDescriptor<T>

Inherited Members

ServiceRpcDescriptor.Moniker

ServiceRpcDescriptor.TraceSource

ServiceRpcDescriptor.MultiplexingStream

ServiceRpcDescriptor.JoinableTaskFactory

ServiceRpcDescriptor.ClientInterface

ServiceRpcDescriptor.ConstructRpc<T>(object, IDuplexPipe)

ServiceRpcDescriptor.ConstructRpc<T>(IDuplexPipe)

ServiceRpcDescriptor.ConstructRpc(object, IDuplexPipe)

ServiceRpcDescriptor.WithTraceSource(TraceSource)

ServiceRpcDescriptor.WithJoinableTaskFactory(JoinableTaskFactory)

ServiceRpcDescriptor.WithServiceMoniker(ServiceMoniker)

object.Equals(object, object)

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

ServiceJsonRpcDescriptor(ServiceJsonRpcDescriptor)

Initializes a new instance of the ServiceJsonRpcDescriptor class and initializes all fields based on a template instance.

protected ServiceJsonRpcDescriptor(ServiceJsonRpcDescriptor copyFrom)

Parameters

copyFrom ServiceJsonRpcDescriptor

The instance to copy all fields from.

ServiceJsonRpcDescriptor(ServiceMoniker, Formatters, MessageDelimiters)

Initializes a new instance of the ServiceJsonRpcDescriptor class with no support for opening additional streams except by relying on the underlying service broker to provide one.

public ServiceJsonRpcDescriptor(ServiceMoniker serviceMoniker, ServiceJsonRpcDescriptor.Formatters formatter, ServiceJsonRpcDescriptor.MessageDelimiters messageDelimiter)

Parameters

serviceMoniker ServiceMoniker

The service moniker.

formatter ServiceJsonRpcDescriptor.Formatters

The formatter to use for the JSON-RPC message.

messageDelimiter ServiceJsonRpcDescriptor.MessageDelimiters

The message delimiter scheme to use.

ServiceJsonRpcDescriptor(ServiceMoniker, Type?, Formatters, MessageDelimiters)

Initializes a new instance of the ServiceJsonRpcDescriptor class with no support for opening additional streams except by relying on the underlying service broker to provide one.

public ServiceJsonRpcDescriptor(ServiceMoniker serviceMoniker, Type? clientInterface, ServiceJsonRpcDescriptor.Formatters formatter, ServiceJsonRpcDescriptor.MessageDelimiters messageDelimiter)

Parameters

serviceMoniker ServiceMoniker

The service moniker.

clientInterface Type

The interface type that the client's "callback" RPC target is expected to implement. May be null if the service does not invoke methods on the client.

formatter ServiceJsonRpcDescriptor.Formatters

The formatter to use for the JSON-RPC message.

messageDelimiter ServiceJsonRpcDescriptor.MessageDelimiters

The message delimiter scheme to use.

ServiceJsonRpcDescriptor(ServiceMoniker, Type?, Formatters, MessageDelimiters, Options?)

Initializes a new instance of the ServiceJsonRpcDescriptor class with support for opening additional streams with MultiplexingStreamOptions.

public ServiceJsonRpcDescriptor(ServiceMoniker serviceMoniker, Type? clientInterface, ServiceJsonRpcDescriptor.Formatters formatter, ServiceJsonRpcDescriptor.MessageDelimiters messageDelimiter, MultiplexingStream.Options? multiplexingStreamOptions)

Parameters

serviceMoniker ServiceMoniker

The service moniker.

clientInterface Type

The interface type that the client's "callback" RPC target is expected to implement. May be null if the service does not invoke methods on the client.

formatter ServiceJsonRpcDescriptor.Formatters

The formatter to use for the JSON-RPC message.

messageDelimiter ServiceJsonRpcDescriptor.MessageDelimiters

The message delimiter scheme to use.

multiplexingStreamOptions MultiplexingStream.Options

The options that a Nerdbank.Streams.MultiplexingStream may be created with. A null value will prevent a Nerdbank.Streams.MultiplexingStream from being created for the RPC connection.

Properties

AcceptProxyWithExtraInterfaces

Gets a value indicating whether a source-generated local proxy that implements extra interfaces may be used.

public bool AcceptProxyWithExtraInterfaces { get; }

Property Value

bool

AdditionalServiceInterfaces

Gets the set of interfaces that will be added to a generated proxy in addition to the one specified as the type argument to ConstructRpcClient<T>() or GetProxyAsync<T>(ServiceRpcDescriptor, ServiceActivationOptions, CancellationToken).

public ImmutableArray<Type>? AdditionalServiceInterfaces { get; }

Property Value

ImmutableArray<Type>?

The default value is null.

Remarks

A null value may signal an implementation of GetProxyAsync<T>(ServiceRpcDescriptor, ServiceActivationOptions, CancellationToken) to supply some default set of optional interfaces based on service registration. Such implementations should honor any non-null value from this property (including an empty array) by not adding any additional interfaces beyond those specified.

DisplayName

Gets the display name to use for the JsonRpc instance.

public string DisplayName { get; }

Property Value

string

The default value is the full name of this descriptor's type.

ExceptionStrategy

Gets the way exceptions are communicated from the service to the client. This is set on the ExceptionStrategy property when the JsonRpc instance is created.

public ExceptionProcessing ExceptionStrategy { get; }

Property Value

ExceptionProcessing

The default value is CommonErrorData.

Formatter

Gets the formatting used by the service.

public ServiceJsonRpcDescriptor.Formatters Formatter { get; }

Property Value

ServiceJsonRpcDescriptor.Formatters

MessageDelimiter

Gets the mechanism by which message boundaries may be discerned. Some expected values are found in ServiceJsonRpcDescriptor.MessageDelimiters.

public ServiceJsonRpcDescriptor.MessageDelimiters MessageDelimiter { get; }

Property Value

ServiceJsonRpcDescriptor.MessageDelimiters

MultiplexingStreamOptions

Gets the options to use when creating a new Nerdbank.Streams.MultiplexingStream as a prerequisite to establishing an RPC connection.

public MultiplexingStream.Options? MultiplexingStreamOptions { get; }

Property Value

MultiplexingStream.Options

Remarks

Any non-null value from this property is always frozen.

Protocol

Gets a non-localized name of the protocol supported by this instance.

public override string Protocol { get; }

Property Value

string

Methods

Clone()

Creates a copy of this instance with all the same properties.

protected override ServiceRpcDescriptor Clone()

Returns

ServiceRpcDescriptor

The copy.

Remarks

Derived types should override this method to create a new instance of their own type, using the ServiceRpcDescriptor(ServiceRpcDescriptor) copy constructor, then copy all their unique properties from this instance to the new one before returning the new one.

ConstructLocalProxy<T>(T?)

Wraps some target object with a proxy that gives the caller the similar semantics to calling an actual RPC object using JsonRpc.

public override T? ConstructLocalProxy<T>(T? target) where T : class

Parameters

target T

The object to which all calls to the proxy should be forwarded.

Returns

T

The proxy, or null if target is null.

Type Parameters

T

The interface that the returned proxy must implement.

Remarks

The proxy will forward all calls made to the T interface to the target object. Exceptions thrown from the target will be caught by the proxy and a RemoteInvocationException will be thrown instead with some of the original exception details preserved (but not as an InnerException) in order to emulate what an RPC connection would be like. This proxy implements T. The proxy also implements IDisposable and will forward a call to Dispose() to the target object if the target object implements IDisposable.

ConstructRpcConnection(IDuplexPipe)

Establishes an RPC connection over an IDuplexPipe.

public override ServiceRpcDescriptor.RpcConnection ConstructRpcConnection(IDuplexPipe pipe)

Parameters

pipe IDuplexPipe

The pipe used to send and receive RPC messages.

Returns

ServiceRpcDescriptor.RpcConnection

An object representing the lifetime of the connection.

Remarks

Callers are expected to call ConstructRpcClient<T>() and/or AddLocalRpcTarget(object) on the result value before invoking StartListening() to begin the RPC session.

CreateConnection(JsonRpc)

Initializes a new instance of a ServiceJsonRpcDescriptor.JsonRpcConnection or derived type.

protected virtual ServiceJsonRpcDescriptor.JsonRpcConnection CreateConnection(JsonRpc jsonRpc)

Parameters

jsonRpc JsonRpc

The JsonRpc object that will have to be passed to JsonRpcConnection(JsonRpc).

Returns

ServiceJsonRpcDescriptor.JsonRpcConnection

The new instance of ServiceJsonRpcDescriptor.JsonRpcConnection.

CreateFormatter()

Initializes a new instance of IJsonRpcMessageFormatter for use in a new server or client.

protected virtual IJsonRpcMessageFormatter CreateFormatter()

Returns

IJsonRpcMessageFormatter

The new message formatter.

CreateHandler(IDuplexPipe, IJsonRpcMessageFormatter)

Initializes a new instance of IJsonRpcMessageHandler for use in a new server or client.

protected virtual IJsonRpcMessageHandler CreateHandler(IDuplexPipe pipe, IJsonRpcMessageFormatter formatter)

Parameters

pipe IDuplexPipe

The pipe the handler should use to send and receive messages.

formatter IJsonRpcMessageFormatter

The IJsonRpcMessageFormatter the handler should use to encode messages.

Returns

IJsonRpcMessageHandler

The new message handler.

CreateJsonRpc(IJsonRpcMessageHandler)

Initializes a new instance of JsonRpc for use in a new server or client.

protected virtual JsonRpc CreateJsonRpc(IJsonRpcMessageHandler handler)

Parameters

handler IJsonRpcMessageHandler

The message handler that the JsonRpc instance should use.

Returns

JsonRpc

The new JsonRpc.

Equals(ServiceJsonRpcDescriptor?)

public bool Equals(ServiceJsonRpcDescriptor? other)

Parameters

other ServiceJsonRpcDescriptor

Returns

bool

Equals(object?)

public override bool Equals(object? obj)

Parameters

obj object

Returns

bool

GetHashCode()

public override int GetHashCode()

Returns

int

WithAcceptProxyWithExtraInterfaces(bool)

Returns an instance of ServiceJsonRpcDescriptor that resembles this one, but with the AcceptProxyWithExtraInterfaces property set to a new value.

public ServiceJsonRpcDescriptor WithAcceptProxyWithExtraInterfaces(bool value)

Parameters

value bool

The new value for the AcceptProxyWithExtraInterfaces property.

Returns

ServiceJsonRpcDescriptor

A clone of this instance, with the property changed. Or this same instance if the property already matches.

WithAdditionalServiceInterfaces(ImmutableArray<Type>?)

Returns an instance of ServiceJsonRpcDescriptor that resembles this one, but with the AdditionalServiceInterfaces property set to a new value.

public ServiceJsonRpcDescriptor WithAdditionalServiceInterfaces(ImmutableArray<Type>? value)

Parameters

value ImmutableArray<Type>?

The new value for the AdditionalServiceInterfaces property.

Returns

ServiceJsonRpcDescriptor

A clone of this instance, with the property changed. Or this same instance if the property already matches.

WithDisplayName(string)

Returns an instance of ServiceJsonRpcDescriptor that resembles this one, but with the DisplayName property set to a new value.

public ServiceJsonRpcDescriptor WithDisplayName(string displayName)

Parameters

displayName string

The new value for the DisplayName property.

Returns

ServiceJsonRpcDescriptor

A clone of this instance, with the property changed. Or this same instance if the property already matches.

WithExceptionStrategy(ExceptionProcessing)

Returns an instance of ServiceJsonRpcDescriptor that resembles this one, but with the ExceptionStrategy property set to a new value.

public ServiceJsonRpcDescriptor WithExceptionStrategy(ExceptionProcessing exceptionStrategy)

Parameters

exceptionStrategy ExceptionProcessing

The new value for the ExceptionStrategy property.

Returns

ServiceJsonRpcDescriptor

A clone of this instance, with the property changed. Or this same instance if the property already matches.

WithMultiplexingStream(MultiplexingStream?)

Returns an instance of ServiceRpcDescriptor that resembles this one, but with the MultiplexingStream property set to the specified value and Nerdbank.Streams.MultiplexingStream.Options set to null.

public override ServiceRpcDescriptor WithMultiplexingStream(MultiplexingStream? multiplexingStream)

Parameters

multiplexingStream MultiplexingStream

The Nerdbank.Streams.MultiplexingStream that may be used by constructed clients or servers.

Returns

ServiceRpcDescriptor

A clone of this instance, with the property changed. Or this same instance if the property already matches.

WithMultiplexingStream(Options?)

Returns an instance of ServiceJsonRpcDescriptor that resembles this one, but with the MultiplexingStreamOptions property set to a frozen copy of the specified value. If a Nerdbank.Streams.MultiplexingStream has been set, it is cleared.

public ServiceRpcDescriptor WithMultiplexingStream(MultiplexingStream.Options? multiplexingStreamOptions)

Parameters

multiplexingStreamOptions MultiplexingStream.Options

Options to use when setting up a new Nerdbank.Streams.MultiplexingStream that should be set up on a pipe before initializing RPC; null to not set up or use any.

Returns

ServiceRpcDescriptor

A clone of this instance, with the property changed. Or this same instance if the property already matches.