Class RemoteServiceBroker

Namespace

Microsoft.ServiceHub.Framework

Assembly

Microsoft.ServiceHub.Framework.dll

Exposes a remote IRemoteServiceBroker service as a local IServiceBroker.

public class RemoteServiceBroker : IServiceBroker, IDisposable, IAsyncDisposable

Inheritance

object

RemoteServiceBroker

Implements

IServiceBroker

IDisposable

IAsyncDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ServiceBrokerExtensions.GetPipeAsync(IServiceBroker, ServiceMoniker, CancellationToken)

ServiceBrokerExtensions.GetProxyAsync<T>(IServiceBroker, ServiceJsonRpcDescriptor<T>, CancellationToken)

ServiceBrokerExtensions.GetProxyAsync<T>(IServiceBroker, ServiceRpcDescriptor, CancellationToken)

Properties

Completion

Gets a Task that completes when this instance is disposed or the underlying Stream it was created with (if applicable) is closed.

public Task Completion { get; }

Property Value

Task

TraceSource

Gets or sets the TraceSource this instance will use for trace messages.

public TraceSource TraceSource { get; set; }

Property Value

TraceSource

Never null.

Methods

ConnectToMultiplexingServerAsync(IRemoteServiceBroker, MultiplexingStream, CancellationToken)

Initializes a new instance of the RemoteServiceBroker class.

public static Task<RemoteServiceBroker> ConnectToMultiplexingServerAsync(IRemoteServiceBroker serviceBroker, MultiplexingStream multiplexingStream, CancellationToken cancellationToken = default)

Parameters

serviceBroker IRemoteServiceBroker

An existing proxy established to acquire remote services. This object is considered "owned" by the returned RemoteServiceBroker and will be disposed when the returned value is disposed, or disposed before this method throws.

multiplexingStream MultiplexingStream

A multiplexing stream that underlies the serviceBroker proxy.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<RemoteServiceBroker>

An IServiceBroker that provides access to remote services.

Remarks

The RemoteServiceBroker is used as the wire protocol.

ConnectToMultiplexingServerAsync(Stream, Options?, TraceSource?, CancellationToken)

Initializes a new instance of the RemoteServiceBroker class that connects to an IRemoteServiceBroker on the default channel after establishing a Nerdbank.Streams.MultiplexingStream on the given Stream.

public static Task<RemoteServiceBroker> ConnectToMultiplexingServerAsync(Stream duplexStream, MultiplexingStream.Options? options, TraceSource? traceSource, CancellationToken cancellationToken = default)

Parameters

duplexStream Stream

A full duplex stream on which to create a multiplexing stream. This multiplexing stream is expected to offer a default channel (Empty name) with a IRemoteServiceBroker service. This object is considered "owned" by the returned RemoteServiceBroker and will be disposed when the returned value is disposed, or disposed before this method throws.

options MultiplexingStream.Options

Options to pass along to the created Nerdbank.Streams.MultiplexingStream on creation.

traceSource TraceSource

An optional means of logging activity.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<RemoteServiceBroker>

An IServiceBroker that provides access to remote services.

ConnectToMultiplexingServerAsync(Stream, Options?, CancellationToken)

Initializes a new instance of the RemoteServiceBroker class that connects to an IRemoteServiceBroker on the default channel after establishing a Nerdbank.Streams.MultiplexingStream on the given Stream.

public static Task<RemoteServiceBroker> ConnectToMultiplexingServerAsync(Stream duplexStream, MultiplexingStream.Options? options, CancellationToken cancellationToken = default)

Parameters

duplexStream Stream

A full duplex stream on which to create a multiplexing stream. This multiplexing stream is expected to offer a default channel (Empty name) with a IRemoteServiceBroker service. This object is considered "owned" by the returned RemoteServiceBroker and will be disposed when the returned value is disposed, or disposed before this method throws.

options MultiplexingStream.Options

Options to pass along to the created Nerdbank.Streams.MultiplexingStream on creation.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<RemoteServiceBroker>

An IServiceBroker that provides access to remote services.

ConnectToMultiplexingServerAsync(Stream, CancellationToken)

Initializes a new instance of the RemoteServiceBroker class that connects to an IRemoteServiceBroker on the default channel after establishing a Nerdbank.Streams.MultiplexingStream on the given Stream.

public static Task<RemoteServiceBroker> ConnectToMultiplexingServerAsync(Stream duplexStream, CancellationToken cancellationToken = default)

Parameters

duplexStream Stream

A full duplex stream on which to create a multiplexing stream. This multiplexing stream is expected to offer a default channel (Empty name) with a IRemoteServiceBroker service. This object is considered "owned" by the returned RemoteServiceBroker and will be disposed when the returned value is disposed, or disposed before this method throws.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<RemoteServiceBroker>

An IServiceBroker that provides access to remote services.

ConnectToServerAsync(IRemoteServiceBroker, CancellationToken)

Initializes a new instance of the RemoteServiceBroker class.

public static Task<RemoteServiceBroker> ConnectToServerAsync(IRemoteServiceBroker serviceBroker, CancellationToken cancellationToken = default)

Parameters

serviceBroker IRemoteServiceBroker

An existing proxy established to acquire remote services. This object is considered "owned" by the returned RemoteServiceBroker and will be disposed when the returned value is disposed, or disposed before this method throws.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<RemoteServiceBroker>

An IServiceBroker that provides access to remote services.

Remarks

The RemoteServiceBroker is used as the wire protocol.

ConnectToServerAsync(IDuplexPipe, TraceSource?, CancellationToken)

Initializes a new instance of the RemoteServiceBroker class.

public static Task<RemoteServiceBroker> ConnectToServerAsync(IDuplexPipe pipe, TraceSource? traceSource, CancellationToken cancellationToken = default)

Parameters

pipe IDuplexPipe

A duplex pipe over which to exchange JSON-RPC messages with an IRemoteServiceBroker service. This object is considered "owned" by the returned RemoteServiceBroker and will be completed when the returned value is disposed, or completed before this method throws.

traceSource TraceSource

An optional means of logging activity.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<RemoteServiceBroker>

An IServiceBroker that provides access to remote services.

Remarks

The RemoteServiceBroker is used as the wire protocol.

ConnectToServerAsync(IDuplexPipe, CancellationToken)

Initializes a new instance of the RemoteServiceBroker class.

public static Task<RemoteServiceBroker> ConnectToServerAsync(IDuplexPipe pipe, CancellationToken cancellationToken = default)

Parameters

pipe IDuplexPipe

A duplex pipe over which to exchange JSON-RPC messages with an IRemoteServiceBroker service. This object is considered "owned" by the returned RemoteServiceBroker and will be completed when the returned value is disposed, or completed before this method throws.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<RemoteServiceBroker>

An IServiceBroker that provides access to remote services.

Remarks

The RemoteServiceBroker is used as the wire protocol.

ConnectToServerAsync(string, TraceSource?, CancellationToken)

Initializes a new instance of the RemoteServiceBroker class.

public static Task<RemoteServiceBroker> ConnectToServerAsync(string pipeName, TraceSource? traceSource, CancellationToken cancellationToken = default)

Parameters

pipeName string

The name of a pipe over which to exchange JSON-RPC messages with an IRemoteServiceBroker service.

traceSource TraceSource

An optional means of logging activity.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<RemoteServiceBroker>

An IServiceBroker that provides access to remote services.

Remarks

The RemoteServiceBroker is used as the wire protocol.

ConnectToServerAsync(string, CancellationToken)

Initializes a new instance of the RemoteServiceBroker class.

public static Task<RemoteServiceBroker> ConnectToServerAsync(string pipeName, CancellationToken cancellationToken = default)

Parameters

pipeName string

The name of a pipe over which to exchange JSON-RPC messages with an IRemoteServiceBroker service.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<RemoteServiceBroker>

An IServiceBroker that provides access to remote services.

Remarks

The RemoteServiceBroker is used as the wire protocol.

Dispose()

[Obsolete("Use DisposeAsync instead.")]
public void Dispose()

Dispose(bool)

Disposes of managed and/or unmanaged resources.

[Obsolete("Override DisposeAsync instead.")]
protected virtual void Dispose(bool disposing)

Parameters

disposing bool

true to dispose of managed resources as well as unmanaged resources; false to release only unmanaged resources.

DisposeAsync()

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

public virtual ValueTask DisposeAsync()

Returns

ValueTask

GetPipeAsync(ServiceMoniker, ServiceActivationOptions, CancellationToken)

Requests access to some service through an IDuplexPipe.

public ValueTask<IDuplexPipe?> GetPipeAsync(ServiceMoniker serviceMoniker, ServiceActivationOptions options = default, CancellationToken cancellationToken = default)

Parameters

serviceMoniker ServiceMoniker

The moniker for the service.

options ServiceActivationOptions

Additional options that alter how the service may be activated or provide additional data to the service constructor.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<IDuplexPipe>

The duplex pipe that may be used to communicate with the service; or null if no matching service could be found. This should be disposed when no longer required.

Exceptions

ServiceCompositionException

Thrown when a service discovery or activation error occurs, or when the only service activation option is local service host activation since this overload does not accept a ServiceRpcDescriptor parameter.

GetProxyAsync<T>(ServiceRpcDescriptor, ServiceActivationOptions, CancellationToken)

Requests access to some service through a client proxy.

public ValueTask<T?> GetProxyAsync<T>(ServiceRpcDescriptor serviceDescriptor, ServiceActivationOptions options = default, CancellationToken cancellationToken = default) where T : class

Parameters

serviceDescriptor ServiceRpcDescriptor

An descriptor of the service.

options ServiceActivationOptions

Additional options that alter how the service may be activated or provide additional data to the service constructor.

cancellationToken CancellationToken

A cancellation token.

Returns

ValueTask<T>

The client proxy that may be used to communicate with the service; or null if no matching service could be found. This should be disposed when no longer required if the instance returned implements IDisposable.

Type Parameters

T

The type of client proxy to create.

Exceptions

ServiceCompositionException

Thrown when a service discovery or activation error occurs.

OfferLocalServiceHostAsync(CancellationToken)

Offers the local environment as a host for services proffered by the remote service broker when they can be activated locally.

public Task OfferLocalServiceHostAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A cancellation token.

Returns

Task

A task that completes after the service broker has acknowledged the local service host.

OnAvailabilityChanged(object?, BrokeredServicesChangedEventArgs)

Raises the AvailabilityChanged event.

protected virtual void OnAvailabilityChanged(object? sender, BrokeredServicesChangedEventArgs args)

Parameters

sender object

This parameter is ignored. The event will be raised with "this" as the sender.

args BrokeredServicesChangedEventArgs

Details regarding what changes have occurred.

SetAuthorizationService(IAuthorizationService?)

Sets the authorization service to use to obtain the default value for ClientCredentials for all service requests that do not explicitly provide it.

public void SetAuthorizationService(IAuthorizationService? authorizationService)

Parameters

authorizationService IAuthorizationService

The authorization service. May be null to clear a previously set value.

Remarks

This method is free threaded, but not thread-safe. It should not be called concurrently with itself.

SetAuthorizationService(IAuthorizationService?, JoinableTaskFactory?)

Sets the authorization service to use to obtain the default value for ClientCredentials for all service requests that do not explicitly provide it.

[Obsolete("Use the overload that does not accept a JoinableTaskFactory instead. This overload will be removed in a future release.", true)]
public void SetAuthorizationService(IAuthorizationService? authorizationService, JoinableTaskFactory? joinableTaskFactory)

Parameters

authorizationService IAuthorizationService

The authorization service. May be null to clear a previously set value.

joinableTaskFactory JoinableTaskFactory

A means to avoid deadlocks if the authorization service requires the main thread. May be null.

Remarks

This method is free threaded, but not thread-safe. It should not be called concurrently with itself.

Events

AvailabilityChanged

Occurs when a service previously queried for since the last AvailabilityChanged event may have changed availability.

public event EventHandler<BrokeredServicesChangedEventArgs>? AvailabilityChanged

Event Type

EventHandler<BrokeredServicesChangedEventArgs>

Remarks

Not all service availability changes result in raising this event. Only those changes that impact services queried for on this IServiceBroker instance will result in an event being raised. Changes already broadcast in a prior event are not included in a subsequent event. The data included in this event may be a superset of the minimum described here.