Class BrokeredServiceContainer

Namespace

Nerdbank.JsonRpc.BrokeredServices

Assembly

Nerdbank.JsonRpc.dll

A programmatic, host-extensible container for per-client service activation.

public class BrokeredServiceContainer : IBrokeredServiceContainer, IDisposable

Inheritance

object

BrokeredServiceContainer

Implements

IBrokeredServiceContainer

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

BrokeredServiceContainerExtensions.Proffer<T>(IBrokeredServiceContainer, IJsonRpcDescriptor<T>, Func<CancellationToken, ValueTask<T?>>)

BrokeredServiceContainerExtensions.Proffer<T>(IBrokeredServiceContainer, IJsonRpcDescriptor<T>, Func<ValueTask<T?>>)

BrokeredServiceContainerExtensions.Proffer<T>(IBrokeredServiceContainer, IJsonRpcDescriptor<T>, Func<T?>)

Properties

JoinableTaskFactory

Gets the host's joinable task factory for shared service loading and RPC connections.

public JoinableTaskFactory? JoinableTaskFactory { get; init; }

Property Value

JoinableTaskFactory

Logger

Gets the container logger.

public ILogger<BrokeredServiceContainer> Logger { get; init; }

Property Value

ILogger<BrokeredServiceContainer>

LoggerFactory

Gets the factory for connection, local proxy and deferred activation loggers.

public ILoggerFactory LoggerFactory { get; init; }

Property Value

ILoggerFactory

Methods

ApplyDescriptorSettings(IJsonRpcDescriptor, bool)

Allows a host to customize immutable descriptor settings by role.

protected virtual IJsonRpcDescriptor ApplyDescriptorSettings(IJsonRpcDescriptor descriptor, bool clientRole)

Parameters

descriptor IJsonRpcDescriptor

The contract descriptor.

clientRole bool

Whether the descriptor is for the client.

Returns

IJsonRpcDescriptor

The descriptor to use.

CreateRpcContext(ServiceMoniker, bool)

Supplies runtime connection infrastructure, including typed logging.

protected virtual ServiceRpcContext CreateRpcContext(ServiceMoniker moniker, bool clientRole)

Parameters

moniker ServiceMoniker

The requested service.

clientRole bool

Whether the connection is for the client.

Returns

ServiceRpcContext

Per-connection infrastructure.

Dispose()

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

public void Dispose()

GetDependencyBroker(IServiceBroker, ServiceActivationOptions)

Allows the host to scope the dependency broker supplied to a factory.

protected virtual IServiceBroker GetDependencyBroker(IServiceBroker broker, ServiceActivationOptions options)

Parameters

broker IServiceBroker

The requesting broker.

options ServiceActivationOptions

The activation context.

Returns

IServiceBroker

The dependency broker.

GetRegisteredServices()

Gets a snapshot of currently registered identities for host diagnostics.

public IReadOnlyList<ServiceMoniker> GetRegisteredServices()

Returns

IReadOnlyList<ServiceMoniker>

The registered service identities.

GetServiceBroker(ServiceAudience)

Creates a broker view with independent availability tracking.

public IServiceBroker GetServiceBroker(ServiceAudience audience = ServiceAudience.Local)

Parameters

audience ServiceAudience

Flags every exposed service must have. None imposes no requirements, but never exposes services with no location audience.

Returns

IServiceBroker

The broker view.

Remarks

Use Local for an RPC relay, optionally combined with PublicSdk. Process-only services cannot be acquired as pipes.

NotifyAvailabilityChanged(ServiceMoniker)

Notifies interested brokers that a lazily discovered service may have changed.

protected void NotifyAvailabilityChanged(ServiceMoniker moniker)

Parameters

moniker ServiceMoniker

The affected service identity.

OnMissingServiceRegistrationAsync(ServiceMoniker, CancellationToken)

Allows a host to complete pending catalog registration before a missing service is rejected.

protected virtual ValueTask OnMissingServiceRegistrationAsync(ServiceMoniker moniker, CancellationToken cancellationToken)

Parameters

moniker ServiceMoniker

The requested service that is not currently registered.

cancellationToken CancellationToken

Cancels this request's wait for registrations.

Returns

ValueTask

A task that completes when registrations relevant to this request are available.

Remarks

The default implementation does nothing. Overrides may await pending catalog sources and call Register(ServiceRegistration). This method runs outside the container lock, at most once per lookup, and may run concurrently for multiple requests. The catalog is checked again after completion; neither completion nor missing results are cached. Already registered services, including those excluded by audience policy, do not invoke this method. Hosts are responsible for sharing catalog loading and isolating its lifetime from individual request cancellation.

OnRequestHandled(ServiceMoniker, Exception?, bool)

Observes a completed request, including unavailable and failed activations.

protected virtual void OnRequestHandled(ServiceMoniker moniker, Exception? exception, bool available)

Parameters

moniker ServiceMoniker

The requested service.

exception Exception

The failure, or null.

available bool

Whether an implementation was returned.

Remarks

For callback-enabled RPC, channel acquisition precedes activation completion. Later activation failures are logged separately.

Proffer<T>(IJsonRpcDescriptor<T>, BrokeredServiceFactory<T>)

Publishes an implementation until its proffer lease is disposed.

public virtual IDisposable Proffer<T>(IJsonRpcDescriptor<T> descriptor, BrokeredServiceFactory<T> factory) where T : class

Parameters

descriptor IJsonRpcDescriptor<T>

The descriptor for an already registered service.

factory BrokeredServiceFactory<T>

The per-client activation factory.

Returns

IDisposable

A lease that removes availability without destroying existing clients.

Type Parameters

T

The primary service contract.

Exceptions

InvalidOperationException

The moniker is not registered or is already proffered.

Register(ServiceRegistration)

Registers a service identity and optional on-demand loader without loading its implementation.

public virtual void Register(ServiceRegistration registration)

Parameters

registration ServiceRegistration

The service metadata.

Remarks

May be called concurrently with acquisitions and other catalog operations. Duplicate registrations are rejected.

TryGetServiceOfferingAsync(ServiceMoniker, CancellationToken)

Discovers externally supplied offerings using host-specific discovery.

protected virtual ValueTask<BrokeredServiceContainer.ServiceOffering?> TryGetServiceOfferingAsync(ServiceMoniker moniker, CancellationToken cancellationToken)

Parameters

moniker ServiceMoniker

The requested service.

cancellationToken CancellationToken

Cancels lookup.

Returns

ValueTask<BrokeredServiceContainer.ServiceOffering>

The host implementation for an already registered service, or null.

Unregister(ServiceMoniker)

Removes a registration and its current proffer without destroying existing activations.

public virtual bool Unregister(ServiceMoniker moniker)

Parameters

moniker ServiceMoniker

The identity to remove.

Returns

bool

Whether the service was registered.

Remarks

May be called on a live container. Pending lookups cannot use the removed registration to discover a replacement, and existing activations remain client-owned.