Class PluginServer
Namespace: DotBoxD.Plugins
Assembly: DotBoxD.Plugins.dll
In-process server-extension convenience surface: register a batch kernel under a service contract, then obtain a typed proxy that invokes it request/response. Plugin-facing remote facades usually expose the same capability from the domain surface they extend.
public sealed class PluginServer : IDisposableInheritance
Section titled “Inheritance”Implements
Section titled “Implements”Inherited Members
Section titled “Inherited Members”object.Equals(object?), object.Equals(object?, object?), object.GetHashCode(), object.GetType(), object.ReferenceEquals(object?, object?), object.ToString()
Extension Methods
Section titled “Extension Methods”PluginServerJsonExtensions.InstallJsonAsync(PluginServer, string, SandboxPolicy?, CancellationToken)
Properties
Section titled “Properties”Events
Section titled “ Events”public PluginEventAdapterRegistry Events { get; }Property Value
Section titled “Property Value”public HookRegistry Hooks { get; }Property Value
Section titled “Property Value”Kernels
Section titled “ Kernels”public KernelRegistry Kernels { get; }Property Value
Section titled “Property Value”Subscriptions
Section titled “ Subscriptions”public SubscriptionRegistry Subscriptions { get; }Property Value
Section titled “Property Value”Methods
Section titled “Methods”BindContext<T>(string, Action<T>?)
Section titled “ BindContext<T>(string, Action<T>?)”public LiveContext<T> BindContext<T>(string name, Action<T>? initialize = null) where T : classParameters
Section titled “Parameters”name string
initialize Action<T>?
Returns
Section titled “Returns”LiveContext<T>
Type Parameters
Section titled “Type Parameters”T
BindValue<T>(string, T)
Section titled “ BindValue<T>(string, T)”public LiveValue<T> BindValue<T>(string name, T initialValue)Parameters
Section titled “Parameters”name string
initialValue T
Returns
Section titled “Returns”LiveValue<T>
Type Parameters
Section titled “Type Parameters”T
Create(IPluginMessageSink?, Action<SandboxHostBuilder>?, SandboxPolicy?, ExecutionMode, Action<SubscriptionDeliveryFault>?)
Section titled “ Create(IPluginMessageSink?, Action<SandboxHostBuilder>?, SandboxPolicy?, ExecutionMode, Action<SubscriptionDeliveryFault>?)”public static PluginServer Create(IPluginMessageSink? messages, Action<SandboxHostBuilder>? configureHost, SandboxPolicy? defaultPolicy, ExecutionMode executionMode, Action<SubscriptionDeliveryFault>? onSubscriptionFault)Parameters
Section titled “Parameters”messages IPluginMessageSink?
configureHost Action<SandboxHostBuilder>?
defaultPolicy SandboxPolicy?
executionMode ExecutionMode
onSubscriptionFault Action<SubscriptionDeliveryFault>?
Returns
Section titled “Returns”Create(IPluginMessageSink?, Action<SandboxHostBuilder>?, SandboxPolicy?, ExecutionMode, Action<SubscriptionDeliveryFault>?, Action<ResultHookFault>?)
Section titled “ Create(IPluginMessageSink?, Action<SandboxHostBuilder>?, SandboxPolicy?, ExecutionMode, Action<SubscriptionDeliveryFault>?, Action<ResultHookFault>?)”public static PluginServer Create(IPluginMessageSink? messages = null, Action<SandboxHostBuilder>? configureHost = null, SandboxPolicy? defaultPolicy = null, ExecutionMode executionMode = ExecutionMode.Auto, Action<SubscriptionDeliveryFault>? onSubscriptionFault = null, Action<ResultHookFault>? onResultHookFault = null)Parameters
Section titled “Parameters”messages IPluginMessageSink?
configureHost Action<SandboxHostBuilder>?
defaultPolicy SandboxPolicy?
executionMode ExecutionMode
onSubscriptionFault Action<SubscriptionDeliveryFault>?
onResultHookFault Action<ResultHookFault>?
Returns
Section titled “Returns”CreateSession()
Section titled “ CreateSession()”Creates a new ownership session. Every kernel installed through the session is tagged with it as the owner, so no other session can replace or mutate it; disposing the session revokes and unregisters the kernels it owns. Use one session per untrusted connection.
public PluginSession CreateSession()Returns
Section titled “Returns”Dispose()
Section titled “ Dispose()”Releases the owned DotBoxD.Hosting.Execution.SandboxHost (compiled executable cache, generated load
contexts, hotness state, and other host-owned execution resources) so a host that retires a
plugin server (per tenant, world, test, or reload) can deterministically reclaim them through
the public plugin API. After disposal the lifecycle entrypoints
(DotBoxD.Plugins.PluginServer.InstallAsync(DotBoxD.Plugins.PluginPackage,DotBoxD.Kernels.SandboxPolicy,System.Threading.CancellationToken), DotBoxD.Plugins.PluginServer.Uninstall(System.String)) throw System.ObjectDisposedException.
Disposal is idempotent.
public void Dispose()GetRequiredCapabilities(PluginPackage)
Section titled “ GetRequiredCapabilities(PluginPackage)”Analyzes a package against this server’s registered host bindings and returns the concrete capabilities its verified module requires. Use this to build a least-privilege install policy from host-trusted binding metadata instead of trusting the package manifest.
public IReadOnlyList<string> GetRequiredCapabilities(PluginPackage package)Parameters
Section titled “Parameters”package PluginPackage
Returns
Section titled “Returns”InstallAsync(PluginPackage, SandboxPolicy?, CancellationToken)
Section titled “ InstallAsync(PluginPackage, SandboxPolicy?, CancellationToken)”public ValueTask<InstalledKernel> InstallAsync(PluginPackage package, SandboxPolicy? policy = null, CancellationToken cancellationToken = default)Parameters
Section titled “Parameters”package PluginPackage
policy SandboxPolicy?
cancellationToken CancellationToken
Returns
Section titled “Returns”InstallPoolAsync(PluginPackage, int, SandboxPolicy?, CancellationToken)
Section titled “ InstallPoolAsync(PluginPackage, int, SandboxPolicy?, CancellationToken)”public ValueTask<InstalledKernelPool> InstallPoolAsync(PluginPackage package, int degreeOfParallelism, SandboxPolicy? policy = null, CancellationToken cancellationToken = default)Parameters
Section titled “Parameters”package PluginPackage
degreeOfParallelism int
policy SandboxPolicy?
cancellationToken CancellationToken
Returns
Section titled “Returns”ValueTask<InstalledKernelPool>
InstallServerExtensionAsync(PluginPackage, SandboxPolicy?, CancellationToken)
Section titled “ InstallServerExtensionAsync(PluginPackage, SandboxPolicy?, CancellationToken)”Installs a server extension package: a kernel invoked request/response (via
DotBoxD.Plugins.Kernel.InstalledKernel.InvokeServerExtensionAsync(System.Collections.Generic.IReadOnlyList{DotBoxD.Kernels.Sandbox.SandboxValue},System.Threading.CancellationToken)) rather than wired to an event. It is
validated by DotBoxD.Plugins.Runtime.Rpc.RpcKernelPackageValidator because the manifest uses the existing
rpcEntrypoint field and has no event subscription/contract.
public ValueTask<InstalledKernel> InstallServerExtensionAsync(PluginPackage package, SandboxPolicy? policy = null, CancellationToken cancellationToken = default)Parameters
Section titled “Parameters”package PluginPackage
policy SandboxPolicy?
cancellationToken CancellationToken
Returns
Section titled “Returns”RegisterEventAdapter<TEvent>(IPluginEventAdapter<TEvent>)
Section titled “ RegisterEventAdapter<TEvent>(IPluginEventAdapter<TEvent>)”public PluginServer RegisterEventAdapter<TEvent>(IPluginEventAdapter<TEvent> adapter)Parameters
Section titled “Parameters”adapter IPluginEventAdapter<TEvent>
Returns
Section titled “Returns”Type Parameters
Section titled “Type Parameters”TEvent
RegisterServerExtensionAsync<TService, TKernel>(SandboxPolicy?, CancellationToken)
Section titled “ RegisterServerExtensionAsync<TService, TKernel>(SandboxPolicy?, CancellationToken)”Resolves TKernel’s generated verified-IR package, installs it as a server
extension, and binds the TService contract to it for
DotBoxD.Plugins.PluginServer.ServerExtension.
public ValueTask<string> RegisterServerExtensionAsync<TService, TKernel>(SandboxPolicy? policy = null, CancellationToken cancellationToken = default) where TService : class where TKernel : classParameters
Section titled “Parameters”policy SandboxPolicy?
cancellationToken CancellationToken
Returns
Section titled “Returns”Type Parameters
Section titled “Type Parameters”TService
TKernel
ServerExtension<TService>()
Section titled “ ServerExtension<TService>()”Returns a typed proxy implementing TService whose calls run the bound batch
kernel request/response (arguments and results are marshaled to and from the sandbox). Throws if no
extension was registered for the contract.
public TService ServerExtension<TService>() where TService : classReturns
Section titled “Returns”TService
Type Parameters
Section titled “Type Parameters”TService
Uninstall(string)
Section titled “ Uninstall(string)”public bool Uninstall(string pluginId)Parameters
Section titled “Parameters”pluginId string
Returns
Section titled “Returns”UninstallPool(InstalledKernelPool)
Section titled “ UninstallPool(InstalledKernelPool)”public bool UninstallPool(InstalledKernelPool pool)Parameters
Section titled “Parameters”pool InstalledKernelPool
Returns
Section titled “Returns”WireHook(InstalledKernel, WireOptions?)
Section titled “ WireHook(InstalledKernel, WireOptions?)”Wires an installed kernel into the hook pipeline for the event it subscribes to,
selecting the terminal (Use / UseProjecting / UseResult / UseProjectingResult)
from the kernel’s trusted, recomputed classification. Replaces the per-event / per-terminal routing every
host used to hand-write. The event is resolved by name from the registered adapters, so the host stays
agnostic of plugin ids and event types. Throws when the subscribed event has no registered adapter.
public WireResult WireHook(InstalledKernel kernel, WireOptions? options = null)Parameters
Section titled “Parameters”kernel InstalledKernel
options WireOptions?
Returns
Section titled “Returns”Remarks
Section titled “Remarks”Opt-in convenience over public API: customize the routing decision via
DotBoxD.Plugins.WireOptions.ClassifyOverride, build a custom by-name router on
DotBoxD.Plugins.Runtime.PluginEventAdapterRegistry.TryResolveErased(System.String,DotBoxD.Plugins.Runtime.IErasedPluginEventAdapter@), or hand-write the equivalent directly with
typed server.Hooks.On<TEvent>().Use(kernel) plus your own event-name → type dispatch.
WireSubscription(InstalledKernel, WireOptions?)
Section titled “ WireSubscription(InstalledKernel, WireOptions?)”Wires an installed kernel into the subscription (fire-and-forget) pipeline for the
event it subscribes to. A plain terminal is routed through DotBoxD.Plugins.WireOptions.IndexRegistry first
(when supplied, DotBoxD.Plugins.WireOptions.UseIndex is set, and verified IR maps to indexed fields),
falling back to the broad pipeline; a projecting terminal pushes to the plugin’s native delegate. Result
terminals are rejected — subscriptions have no result channel.
public WireResult WireSubscription(InstalledKernel kernel, WireOptions? options = null)Parameters
Section titled “Parameters”kernel InstalledKernel
options WireOptions?
Returns
Section titled “Returns”Remarks
Section titled “Remarks”Opt-in convenience; see DotBoxD.Plugins.PluginServer.WireHook(DotBoxD.Plugins.Kernel.InstalledKernel,DotBoxD.Plugins.WireOptions) for the customization seams and the
hand-written equivalent (server.Subscriptions.On<TEvent>().Use(kernel)).