Table of Contents

Class ServiceJsonRpcPolyTypeDescriptor

Namespace
Microsoft.ServiceHub.Framework
Assembly
Microsoft.ServiceHub.Framework.dll

An RPC descriptor for services that support JSON-RPC via StreamJsonRpc using a PolyType-based formatter.

public class ServiceJsonRpcPolyTypeDescriptor : ServiceRpcDescriptor, IEquatable<ServiceJsonRpcPolyTypeDescriptor>
Inheritance
ServiceJsonRpcPolyTypeDescriptor
Implements
Derived
Inherited Members

Constructors

ServiceJsonRpcPolyTypeDescriptor(ServiceJsonRpcPolyTypeDescriptor)

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

protected ServiceJsonRpcPolyTypeDescriptor(ServiceJsonRpcPolyTypeDescriptor copyFrom)

Parameters

copyFrom ServiceJsonRpcPolyTypeDescriptor

The instance to copy all fields from.

ServiceJsonRpcPolyTypeDescriptor(ServiceMoniker, Formatters, MessageDelimiters, ITypeShapeProvider)

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

public ServiceJsonRpcPolyTypeDescriptor(ServiceMoniker serviceMoniker, ServiceJsonRpcPolyTypeDescriptor.Formatters formatter, ServiceJsonRpcPolyTypeDescriptor.MessageDelimiters messageDelimiter, ITypeShapeProvider typeShapeProvider)

Parameters

serviceMoniker ServiceMoniker

The service moniker.

formatter ServiceJsonRpcPolyTypeDescriptor.Formatters

The formatter to use for the JSON-RPC message.

messageDelimiter ServiceJsonRpcPolyTypeDescriptor.MessageDelimiters

The message delimiter scheme to use.

typeShapeProvider ITypeShapeProvider

The source of type shapes for all parameter and return types used in the RPC contract.

ServiceJsonRpcPolyTypeDescriptor(ServiceMoniker, Type?, Formatters, MessageDelimiters, Options?, ITypeShapeProvider)

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

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

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 ServiceJsonRpcPolyTypeDescriptor.Formatters

The formatter to use for the JSON-RPC message.

messageDelimiter ServiceJsonRpcPolyTypeDescriptor.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.

typeShapeProvider ITypeShapeProvider

The source of type shapes for all parameter and return types used in the RPC contract.

ServiceJsonRpcPolyTypeDescriptor(ServiceMoniker, Type?, Formatters, MessageDelimiters, ITypeShapeProvider)

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

public ServiceJsonRpcPolyTypeDescriptor(ServiceMoniker serviceMoniker, Type? clientInterface, ServiceJsonRpcPolyTypeDescriptor.Formatters formatter, ServiceJsonRpcPolyTypeDescriptor.MessageDelimiters messageDelimiter, ITypeShapeProvider typeShapeProvider)

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 ServiceJsonRpcPolyTypeDescriptor.Formatters

The formatter to use for the JSON-RPC message.

messageDelimiter ServiceJsonRpcPolyTypeDescriptor.MessageDelimiters

The message delimiter scheme to use.

typeShapeProvider ITypeShapeProvider

The source of type shapes for all parameter and return types used in the RPC contract.

Properties

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 ServiceJsonRpcPolyTypeDescriptor.Formatters Formatter { get; }

Property Value

ServiceJsonRpcPolyTypeDescriptor.Formatters

MessageDelimiter

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

public ServiceJsonRpcPolyTypeDescriptor.MessageDelimiters MessageDelimiter { get; }

Property Value

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

RpcTargetMetadata

Gets a collection of RpcTargetMetadata for use when calling AddLocalRpcTarget(object).

public ImmutableArray<RpcTargetMetadata> RpcTargetMetadata { get; }

Property Value

ImmutableArray<RpcTargetMetadata>

Remarks

The RPC target object passed to AddLocalRpcTarget(object) is expected to be assignable to the type designated by the TargetType property of all elements of this collection.

TypeShapeProvider

Gets the PolyType.ITypeShapeProvider to use for serializing and deserializing parameter and return types.

public ITypeShapeProvider TypeShapeProvider { get; }

Property Value

ITypeShapeProvider

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 and any interfaces specified in the AdditionalServiceInterfaces property. 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 ServiceJsonRpcPolyTypeDescriptor.JsonRpcConnection or derived type.

protected virtual ServiceJsonRpcPolyTypeDescriptor.JsonRpcConnection CreateConnection(JsonRpc jsonRpc)

Parameters

jsonRpc JsonRpc

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

Returns

ServiceJsonRpcPolyTypeDescriptor.JsonRpcConnection

The new instance of ServiceJsonRpcPolyTypeDescriptor.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(ServiceJsonRpcPolyTypeDescriptor?) 

public bool Equals(ServiceJsonRpcPolyTypeDescriptor? other)

Parameters

other ServiceJsonRpcPolyTypeDescriptor

Returns

bool

Equals(object?) 

public override bool Equals(object? obj)

Parameters

obj object

Returns

bool

GetHashCode() 

public override int GetHashCode()

Returns

int

WithAdditionalServiceInterfaces(ImmutableArray<Type>?)

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

public ServiceJsonRpcPolyTypeDescriptor WithAdditionalServiceInterfaces(ImmutableArray<Type>? value)

Parameters

value ImmutableArray<Type>?

The new value for the AdditionalServiceInterfaces property.

Returns

ServiceJsonRpcPolyTypeDescriptor

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 ServiceJsonRpcPolyTypeDescriptor WithDisplayName(string displayName)

Parameters

displayName string

The new value for the DisplayName property.

Returns

ServiceJsonRpcPolyTypeDescriptor

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

WithExceptionStrategy(ExceptionProcessing)

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

public ServiceJsonRpcPolyTypeDescriptor WithExceptionStrategy(ExceptionProcessing exceptionStrategy)

Parameters

exceptionStrategy ExceptionProcessing

The new value for the ExceptionStrategy property.

Returns

ServiceJsonRpcPolyTypeDescriptor

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.

[Obsolete("Use the WithMultiplexingStream(MultiplexingStream.Options) overload as may be defined in a derived type instead.")]
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 ServiceJsonRpcPolyTypeDescriptor 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.

WithRpcTargetMetadata(params ImmutableArray<RpcTargetMetadata>)

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

public ServiceJsonRpcPolyTypeDescriptor WithRpcTargetMetadata(params ImmutableArray<RpcTargetMetadata> value)

Parameters

value ImmutableArray<RpcTargetMetadata>

The new value for the RpcTargetMetadata property.

Returns

ServiceJsonRpcPolyTypeDescriptor

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

WithTypeShapeProvider(ITypeShapeProvider)

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

public ServiceJsonRpcPolyTypeDescriptor WithTypeShapeProvider(ITypeShapeProvider value)

Parameters

value ITypeShapeProvider

The new value for the TypeShapeProvider property.

Returns

ServiceJsonRpcPolyTypeDescriptor

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

Edit this page