Members on this page
BackgroundErrorStateChangedClientComponent(ClientOptions)BeginOperation(CancellationToken)DisposeAsync()DisposeAsyncCore()InitializeAsync(CancellationToken)OnInitializeAsync(CancellationToken)OnStartAsync(CancellationToken)OnStopAsync()ReportBackgroundError(BackgroundOperation, string, Exception)StartAsync(CancellationToken)StopAsync(CancellationToken)ContextLifecycleStateOptionsRuntimeCancellationToken
Meshline.Sdk
Meshline.Components
ClientComponent Class
Provides initialization, start/stop, operation tracking, and asynchronous disposal for SDK components.
public abstract class ClientComponent : System.IAsyncDisposable
Inheritance System.Object → ClientComponent
Derived
↳ AccountManager
↳ ChannelManager
↳ DeviceManager
↳ GroupManager
↳ MessageManager
↳ ProfileManager
↳ MeshlineClient
Implements System.IAsyncDisposable
Remarks
Initialize before invoking component operations. Starting begins background processing; stopping allows a later restart. Disposal cancels and drains tracked operations. Event handlers execute on the raising thread and UI consumers must marshal updates as needed.
Constructors
ClientComponent(ClientOptions) Constructor
Initializes a new instance of ClientComponent.
protected ClientComponent(Meshline.Models.Client.ClientOptions options);
Parameters
options ClientOptions
The network and account configuration for this component.
Exceptions
System.ArgumentNullException
The network context in options is null. The options argument is null.
System.ArgumentException
The configured account identifier is invalid.
System.NotSupportedException
The configured account identifier uses an unsupported account namespace.
Properties
ClientComponent.Context Property
The network reference and registry contract identifying this Meshline network.
public Meshline.Models.NetworkContext Context { get; }
Property Value
ClientComponent.LifecycleState Property
The component's current initialization and runtime state.
public Meshline.Components.ComponentState LifecycleState { get; }
Property Value
ClientComponent.Options Property
The network and account options supplied when this component was constructed.
public Meshline.Models.Client.ClientOptions Options { get; }
Property Value
ClientComponent.RuntimeCancellationToken Property
The current runtime token, canceled when background work stops or the component is disposed.
protected System.Threading.CancellationToken RuntimeCancellationToken { protected get; }
Property Value
System.Threading.CancellationToken
Methods
ClientComponent.BeginOperation(CancellationToken) Method
Tracks a foreground operation and links its cancellation token to component disposal.
protected System.IDisposable BeginOperation(ref System.Threading.CancellationToken cancellationToken);
Parameters
cancellationToken System.Threading.CancellationToken
The caller's token, replaced with a token linked to the component's lifetime.
Returns
System.IDisposable
A scope that releases the linked token source and operation registration when disposed.
Exceptions
System.OperationCanceledException
The cancellationToken is already canceled.
System.ObjectDisposedException
The component has been disposed, or disposal has begun while registering an operation.
Remarks
Dispose the returned scope when the operation finishes. This method replaces the supplied token with a linked token; it does not perform initialization checks for the derived component.
ClientComponent.DisposeAsync() Method
Cancels and drains active operations, stops background work, and releases component-owned resources.
public System.Threading.Tasks.ValueTask DisposeAsync();
Implements DisposeAsync()
Returns
System.Threading.Tasks.ValueTask
A value task that completes when owned resources and active work have been released.
Exceptions
Microsoft.Data.Sqlite.SqliteException
A component cleanup hook fails to access SQLite while persisting pending local observations.
Microsoft.EntityFrameworkCore.DbUpdateException
A component cleanup hook cannot save its pending local observations.
System.AggregateException
An exception thrown by a registered lifetime cancellation callback is aggregated during cancellation.
ClientComponent.DisposeAsyncCore() Method
Releases component-specific resources after background work and tracked operations have ended.
protected virtual System.Threading.Tasks.ValueTask DisposeAsyncCore();
Returns
System.Threading.Tasks.ValueTask
A value task that completes when resource cleanup finishes.
ClientComponent.InitializeAsync(CancellationToken) Method
Initializes component state once and transitions the component to the stopped state.
public System.Threading.Tasks.Task InitializeAsync(System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
cancellationToken System.Threading.CancellationToken
A token that can cancel the operation.
Returns
System.Threading.Tasks.Task
A task that completes when the operation finishes.
Exceptions
System.OperationCanceledException
The operation observes cancellation of cancellationToken. Disposal of the component or relay session can also cancel pending work.
System.ObjectDisposedException
This component, or a dependency initialized by its initialization hook, has been disposed.
System.InvalidOperationException
The component initialization hook rejects the database binding or an unmet dependency initialization requirement.
Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.
Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.
System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.
System.IO.InvalidDataException
A component initialization hook finds inconsistent persisted device state.
Remarks
This method does not create or migrate the database. Initialization failures propagate and leave initialization incomplete so the caller can correct the cause and retry.
ClientComponent.OnInitializeAsync(CancellationToken) Method
Initializes component-specific state before the lifecycle transitions to stopped.
protected virtual System.Threading.Tasks.Task OnInitializeAsync(System.Threading.CancellationToken cancellationToken);
Parameters
cancellationToken System.Threading.CancellationToken
A token that can cancel the operation.
Returns
System.Threading.Tasks.Task
A task that completes when the operation finishes.
ClientComponent.OnStartAsync(CancellationToken) Method
Starts component-specific background work for the current runtime.
protected virtual System.Threading.Tasks.Task OnStartAsync(System.Threading.CancellationToken cancellationToken);
Parameters
cancellationToken System.Threading.CancellationToken
A token that can cancel the operation.
Returns
System.Threading.Tasks.Task
A task that completes when the operation finishes.
ClientComponent.OnStopAsync() Method
Drains component-specific background work after the runtime token has been canceled.
protected virtual System.Threading.Tasks.Task OnStopAsync();
Returns
System.Threading.Tasks.Task
A task that completes when the operation finishes.
ClientComponent.ReportBackgroundError(BackgroundOperation, string, Exception) Method
Raises the background error event with the failed activity and its diagnostic exception.
protected void ReportBackgroundError(Meshline.Components.BackgroundOperation operation, string? resource, System.Exception error);
Parameters
operation BackgroundOperation
The background activity that failed.
resource System.String
The associated resource identifier, or null when none applies.
error System.Exception
The failure to report.
ClientComponent.StartAsync(CancellationToken) Method
Starts background work after initialization; repeated calls while running have no effect.
public virtual System.Threading.Tasks.Task StartAsync(System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
cancellationToken System.Threading.CancellationToken
A token that can cancel the operation.
Returns
System.Threading.Tasks.Task
A task that completes when the operation finishes.
Exceptions
System.OperationCanceledException
The operation is canceled through cancellationToken, a component or relay lifetime ends, or a relay request times out.
System.ObjectDisposedException
The component has been disposed, or disposal has begun while registering an operation.
System.InvalidOperationException
Initialization is incomplete, or a component startup hook lacks the required local device, route, or published authorization.
System.Net.Http.HttpRequestException
Relay discovery, authentication, or the HTTP request fails at the transport layer.
RelayException
The relay rejects the operation with a structured protocol error that is not handled by this method.
System.IO.InvalidDataException
Relay evidence or returned state is missing, inconsistent, or fails protocol validation.
System.Text.Json.JsonException
A stored or received protocol document cannot be serialized or deserialized.
System.Text.DecoderFallbackException
A relay response contains bytes that are not valid UTF-8.
Microsoft.Data.Sqlite.SqliteException
The SQLite database cannot be opened or a database command fails, for example because the schema is not migrated or the file is locked.
Microsoft.EntityFrameworkCore.DbUpdateException
Persisting local changes fails, including database constraint or optimistic-concurrency failures.
System.Security.Cryptography.CryptographicException
The local device key cannot be validated against its certificate, or cryptographic signing or verification fails.
System.UnauthorizedAccessException
A component startup hook cannot authorize the local device or an account synchronization message.
System.ArgumentException
A startup hook encounters invalid input while resuming a pending account operation.
System.ArgumentOutOfRangeException
A startup hook resumes an account operation whose validity interval or revision is outside the supported range.
System.NotSupportedException
A startup hook encounters an account namespace unsupported by this SDK.
System.AggregateException
A runtime cancellation callback throws while a failed startup is being cleaned up.
Remarks
The caller token controls startup. Once startup completes, background work uses the component runtime token and ends through stop or disposal. A client device must already have published authorization before its device component can start.
ClientComponent.StopAsync(CancellationToken) Method
Stops background work and subscriptions while leaving the component available to start again.
public virtual System.Threading.Tasks.Task StopAsync(System.Threading.CancellationToken cancellationToken=default(System.Threading.CancellationToken));
Parameters
cancellationToken System.Threading.CancellationToken
A token that can cancel waiting to begin stopping; active shutdown is drained without cancellation.
Returns
System.Threading.Tasks.Task
A task that completes when the operation finishes.
Exceptions
System.OperationCanceledException
The cancellationToken is canceled while waiting to enter the lifecycle transition.
System.ObjectDisposedException
This component, or a dependency stopped by its shutdown hook, has been disposed.
System.AggregateException
An exception thrown by a runtime cancellation callback is aggregated while stopping background work.
Remarks
The cancellation token controls waiting to enter the lifecycle operation. Once stopping begins, runtime shutdown is drained without that token. The application-owned relay pool remains available to other components.
Events
ClientComponent.BackgroundError Event
Occurs when background processing reports a failure; awaited operation failures propagate to their caller.
public event EventHandler<BackgroundErrorEventArgs>? BackgroundError;
Event Type
System.EventHandler<BackgroundErrorEventArgs>
ClientComponent.StateChanged Event
Occurs when the component lifecycle state changes.
public event EventHandler<ComponentStateChangedEventArgs>? StateChanged;