Class ServiceProxyContext

Namespace

Nerdbank.JsonRpc.BrokeredServices

Assembly

Nerdbank.JsonRpc.dll

Supplies a leased service target and local invocation boundary policy.

public abstract class ServiceProxyContext : IDisposable, IAsyncDisposable

Inheritance

object

ServiceProxyContext

Implements

IDisposable

IAsyncDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Properties

EventTarget

Gets the current target for event attachment.

protected abstract object? EventTarget { get; }

Property Value

object

IsDisposed

Gets a value indicating whether the proxy is disposed.

public abstract bool IsDisposed { get; }

Property Value

bool

Logger

Gets the logger used to observe notification and cleanup failures.

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

Property Value

ILogger<ServiceProxyContext>

RpcOptions

Gets the exception disclosure policy for direct calls.

public JsonRpcOptions RpcOptions { get; init; }

Property Value

JsonRpcOptions

Remarks

Local failures retain their original inner exception when details are enabled; no typed exception payload is serialized or reconstructed.

Methods

Borrow(object, ILogger<ServiceProxyContext>?, JsonRpcOptions?)

Creates a callback boundary without taking ownership of the caller's target.

public static ServiceProxyContext Borrow(object target, ILogger<ServiceProxyContext>? logger = null, JsonRpcOptions? rpcOptions = null)

Parameters

target object

The caller-owned callback target.

logger ILogger<ServiceProxyContext>

The callback logger.

rpcOptions JsonRpcOptions

The exception disclosure policy.

Returns

ServiceProxyContext

The disposable boundary. Disposing it does not dispose the supplied target.

DetachEvents()

Detaches all event subscriptions before releasing a target.

protected void DetachEvents()

Dispose()

Disposes this context and relinquishes its owning reference.

public abstract void Dispose()

DisposeAsync()

Disposes this context and awaits owned resource cleanup.

public abstract ValueTask DisposeAsync()

Returns

ValueTask

A task tracking cleanup.

IsInterfaceEnabled(Type)

Tests whether a generated optional interface is currently available.

public virtual bool IsInterfaceEnabled(Type interfaceType)

Parameters

interfaceType Type

The optional interface.

Returns

bool

Whether the context currently supports it.

MoveEvents(object?)

Moves event attachments to a replacement generation.

protected void MoveEvents(object? target)

Parameters

target object

The replacement target, or null while unavailable.

ObserveNotification(ValueTask)

Observes a generated fire-and-forget invocation.

public void ObserveNotification(ValueTask operation)

Parameters

operation ValueTask

The invocation to observe.

Own(object, IDisposable?, bool, ILogger<ServiceProxyContext>?, JsonRpcOptions?)

Owns a local target for a newly acquired proxy.

public static ServiceProxyContext Own(object target, IDisposable? owner = null, bool translateExceptions = true, ILogger<ServiceProxyContext>? logger = null, JsonRpcOptions? rpcOptions = null)

Parameters

target object

The local service object.

owner IDisposable

The object to dispose instead of the target, if supplied.

translateExceptions bool

Whether service exceptions cross a local RPC boundary.

logger ILogger<ServiceProxyContext>

The direct-call logger.

rpcOptions JsonRpcOptions

The exception disclosure policy.

Returns

ServiceProxyContext

The context, which owns the target until disposed.

RejectArgumentOnlyResult<T>(T?, ServiceProxyLease)

Enforces the request-argument-only rule for call-scoped contracts and progress receivers on direct calls.

public T? RejectArgumentOnlyResult<T>(T? target, ServiceProxyLease lease) where T : class

Parameters

target T

The returned value.

lease ServiceProxyLease

The active invocation.

Returns

T

Null when the result is null; non-null call-scoped results always fail.

Type Parameters

T

The call-scoped contract.

RentAsync(CancellationToken)

Acquires a target for the duration of an invocation.

public abstract ValueTask<ServiceProxyLease> RentAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Cancels acquisition.

Returns

ValueTask<ServiceProxyLease>

A lease that must be disposed exactly once.

ReportCallbackException(Exception)

Observes a callback failure without throwing into service code.

public void ReportCallbackException(Exception exception)

Parameters

exception Exception

The callback failure.

Retain(IDuplexPipe?, ServiceProxyLease)

Retains a generation until both returned pipe ends are completed.

public IDuplexPipe? Retain(IDuplexPipe? pipe, ServiceProxyLease lease)

Parameters

pipe IDuplexPipe

The returned pipe.

lease ServiceProxyLease

The active invocation.

Returns

IDuplexPipe

The caller-owned pipe boundary.

Retain(PipeReader?, ServiceProxyLease)

Retains a generation until a returned reader is completed.

public PipeReader? Retain(PipeReader? reader, ServiceProxyLease lease)

Parameters

reader PipeReader

The returned reader.

lease ServiceProxyLease

The active invocation.

Returns

PipeReader

The caller-owned reader boundary.

Retain(PipeWriter?, ServiceProxyLease)

Retains a generation until a returned writer is completed.

public PipeWriter? Retain(PipeWriter? writer, ServiceProxyLease lease)

Parameters

writer PipeWriter

The returned writer.

lease ServiceProxyLease

The active invocation.

Returns

PipeWriter

The caller-owned writer boundary.

Retain(Stream?, ServiceProxyLease)

Retains a generation until a returned stream is disposed.

public Stream? Retain(Stream? stream, ServiceProxyLease lease)

Parameters

stream Stream

The returned stream.

lease ServiceProxyLease

The active invocation.

Returns

Stream

The caller-owned stream boundary.

RetainProxy<T>(T?, ServiceProxyLease)

Creates a generated direct proxy for a returned marshalable object.

public T? RetainProxy<T>(T? target, ServiceProxyLease lease) where T : class

Parameters

target T

The returned object.

lease ServiceProxyLease

The active invocation.

Returns

T

A caller-owned object boundary retaining its parent generation.

Type Parameters

T

The returned source-generated contract.

RetainSubscription(IDisposable?, ServiceProxyLease, Func<object, CancellationToken, ValueTask<IDisposable?>>?)

Retains a service generation while a returned subscription is active.

public virtual IDisposable? RetainSubscription(IDisposable? subscription, ServiceProxyLease lease, Func<object, CancellationToken, ValueTask<IDisposable?>>? resubscribe = null)

Parameters

subscription IDisposable

The service's subscription.

lease ServiceProxyLease

The active invocation lease.

resubscribe Func<object, CancellationToken, ValueTask<IDisposable>>

The generated operation for restoring observer subscriptions after replacement.

Returns

IDisposable

A subscription that releases its generation exactly once.

Retain<T>(IObserver<T>?, ServiceProxyLease)

Retains a generation for a returned observer without taking ownership of its target.

public IObserver<T>? Retain<T>(IObserver<T>? observer, ServiceProxyLease lease)

Parameters

observer IObserver<T>

The returned observer.

lease ServiceProxyLease

The active invocation.

Returns

IObserver<T>

The observer boundary, or the caller's original observer when round-tripping.

Type Parameters

T

The observed value.

TranslateException(Exception)

Translates a local target exception without serializing arguments or results.

public virtual Exception TranslateException(Exception exception)

Parameters

exception Exception

The target failure.

Returns

Exception

The exception to report to the caller.

UpdateEvent<THandler>(string, THandler?, Action<object, THandler>, Action<object, THandler>, bool, Func<THandler, THandler>?)

Updates an event attachment owned by this proxy.

public void UpdateEvent<THandler>(string key, THandler? handler, Action<object, THandler> attach, Action<object, THandler> detach, bool add, Func<THandler, THandler>? wrap = null) where THandler : Delegate

Parameters

key string

The generated event identity.

handler THandler

The client handler.

attach Action<object, THandler>

The generated typed add operation.

detach Action<object, THandler>

The generated typed remove operation.

add bool

Whether to add rather than remove.

wrap Func<THandler, THandler>

The generated callback boundary, if needed.

Type Parameters

THandler

The event delegate.

WrapProxy<T>(T?)

Creates a borrowed generated callback boundary, preserving round trips of service-owned objects.

public T? WrapProxy<T>(T? target) where T : class

Parameters

target T

The caller-owned target.

Returns

T

The borrowed proxy, or the original service object when returning across its own boundary.

Type Parameters

T

The source-generated callback interface.

WrapProxy<T>(T?, out IDisposable?)

Creates a callback boundary whose lifetime can be limited to one invocation.

public T? WrapProxy<T>(T? target, out IDisposable? boundary) where T : class

Parameters

target T

The caller-owned target.

boundary IDisposable

The boundary to dispose when the call or returned enumeration ends; never the caller's target.

Returns

T

The generated callback proxy.

Type Parameters

T

The source-generated callback interface.

Wrap<T>(IObserver<T>?)

Isolates observer callbacks from local service code without serialization.

public IObserver<T>? Wrap<T>(IObserver<T>? observer)

Parameters

observer IObserver<T>

The caller's observer.

Returns

IObserver<T>

A direct callback boundary.

Type Parameters

T

The observed value.

Wrap<T>(IObserver<T>?, out IDisposable?)

Creates an observer callback boundary that can be revoked if activation or invocation fails.

public IObserver<T>? Wrap<T>(IObserver<T>? observer, out IDisposable? boundary)

Parameters

observer IObserver<T>

The caller's observer.

boundary IDisposable

The borrowed boundary, never the caller's observer.

Returns

IObserver<T>

The service's observer argument.

Type Parameters

T

The observed value.

Wrap<T>(IProgress<T>?)

Isolates progress callbacks from local service code without serialization.

public IProgress<T>? Wrap<T>(IProgress<T>? progress)

Parameters

progress IProgress<T>

The caller's progress receiver.

Returns

IProgress<T>

A direct callback boundary.

Type Parameters

T

The progress value.

Wrap<T>(IProgress<T>?, out IDisposable?)

Creates a progress callback boundary that lasts for one invocation or enumeration.

public IProgress<T>? Wrap<T>(IProgress<T>? progress, out IDisposable? boundary)

Parameters

progress IProgress<T>

The caller's receiver.

boundary IDisposable

The boundary to dispose when the invocation ends.

Returns

IProgress<T>

The service's progress argument.

Type Parameters

T

The progress value.