Repository navigation
11. API Reference π
Complete reference for all public APIs in the Scarlet.Extensions.Hosting.DirectN packages (version 1.1).
All registration methods throw ArgumentNullException for null arguments and return the same instance for chaining.
Namespace Scarlet.Extensions.Hosting.DirectN. These work with every builder: builder.Services of Host.CreateApplicationBuilder, and inside IHostBuilder.ConfigureServices.
public static IServiceCollection AddDirectN(this IServiceCollection services)Runs a DirectN application on a dedicated UI thread inside the host. The UI thread starts after every hosted service has started, and the host stops when the application exits (and vice versa). Calling it again only adds configuration.
public static IServiceCollection AddDirectN(
this IServiceCollection services,
Action<DirectNOptions> configureOptions)Same as AddDirectN(), and configures the DirectNOptions.
public static IServiceCollection AddDirectNComponent<
[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] TComponent>(
this IServiceCollection services)
where TComponent : class, IDirectNComponentAdds a component, created with its dependencies from the container on the UI thread (ActivatorUtilities.CreateInstance), initialized before the message loop starts and disposed there after it ends. The container never disposes it.
public static IServiceCollection AddDirectNComponent<TComponent>(
this IServiceCollection services,
Func<IServiceProvider, TComponent> createComponent)
where TComponent : class, IDirectNComponentAdds a component created by createComponent on the UI thread.
public static IServiceCollection AddDirectNLifetime(this IServiceCollection services)Uses DirectNLifetime as the host lifetime instead of the default ConsoleLifetime. Optional: with any lifetime, AddDirectN already stops the host when the application exits.
public static IServiceCollection AddDirectNLifetime(
this IServiceCollection services,
Action<DirectNLifetimeOptions> configureOptions)Same, and configures the DirectNLifetimeOptions.
public static IHostBuilder UseDirectNLifetime(this IHostBuilder hostBuilder)
public static IHostBuilder UseDirectNLifetime(this IHostBuilder hostBuilder, Action<DirectNLifetimeOptions> configureOptions)IHostBuilder shortcuts for AddDirectNLifetime.
public interface IDirectNThread
{
Thread MainThread { get; }
DirectNDispatcher Dispatcher { get; }
SynchronizationContext SynchronizationContext { get; }
IDirectNContext Context { get; }
void HandleApplicationExit();
event EventHandler<DirectNUnhandledExceptionEventArgs>? UnhandledException;
}| Member | Description |
|---|---|
MainThread |
The UI thread. It exists, unstarted, before the host starts |
Dispatcher |
Post, TryPost and InvokeAsync to the UI thread. Usable before the UI thread starts; also registered as DirectNDispatcher (see Message Queue). New in 1.1: classes implementing IDirectNThread must add it |
SynchronizationContext |
Runs work on the UI thread. Post works at any time and never throws; Send returns or throws, never hangs on a closed queue (see Message Queue) |
Context |
The application state |
HandleApplicationExit() |
Stops the host, which exits the application. Any thread. Before the application has started (e.g. from OnStartup), the host stops once it has. Ignored when startup failed or the host is being disposed |
UnhandledException |
Raised on the UI thread when posted work throws; set Handled to keep running |
public interface IDirectNContext
{
bool IsRunning { get; }
Application? Application { get; }
}Application is DirectN's DirectN.Extensions.Utilities.Application, created by the host on the UI thread, for advanced use. The host owns its lifetime.
public interface IDirectNComponent
{
void InitializeComponent();
}Called on the UI thread before the message loop starts. Implement IDisposable for cleanup on the UI thread.
| Property | Type | Default |
|---|---|---|
ShutdownMode |
ShutdownMode |
OnLastWindowClose |
OnStartup |
Action<IServiceProvider, IDirectNContext>? |
null |
OnExit |
Action<IServiceProvider, IDirectNContext>? |
null |
ShowFatalErrorDialog |
bool |
false |
OnLastWindowClose, OnExplicitShutdown. See Application Options.
public class DirectNLifetime : IHostLifetime, IDisposable
{
public DirectNLifetime(IOptions<DirectNLifetimeOptions> options, IHostEnvironment environment,
IHostApplicationLifetime applicationLifetime, IOptions<HostOptions> hostOptions);
public DirectNLifetime(IOptions<DirectNLifetimeOptions> options, IHostEnvironment environment,
IHostApplicationLifetime applicationLifetime, IOptions<HostOptions> hostOptions, ILoggerFactory loggerFactory);
}| Property | Type | Default |
|---|---|---|
SuppressStatusMessages |
bool |
false |
Namespace Scarlet.Extensions.Hosting.DirectN.TrayIcon.
public interface ITrayIcon : IDirectNComponent, IDisposable
{
}public static IServiceCollection AddDirectNTrayIcon<
[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] TTrayIcon>(
this IServiceCollection services)
where TTrayIcon : class, ITrayIcon
public static IServiceCollection AddDirectNTrayIcon<TTrayIcon>(
this IServiceCollection services,
Func<IServiceProvider, TTrayIcon> createTrayIcon)
where TTrayIcon : class, ITrayIconAdds the tray icon as a component.
public sealed class TrayNotifyIcon : IDisposable
{
public TrayIconImage? Icon { get; set; }
public string? Text { get; set; } // max 127 characters
public bool Visible { get; set; }
public TrayMenu? ContextMenu { get; set; }
public bool ShowContextMenuOnLeftClick { get; set; }
public object? Tag { get; set; }
public void ShowContextMenu();
public void ShowBalloonTip(string title, string text, TrayToolTipIcon icon = TrayToolTipIcon.None);
public void Dispose();
public event EventHandler? Click, DoubleClick;
public event EventHandler<TrayMouseEventArgs>? MouseClick, MouseDoubleClick, MouseDown, MouseUp, MouseMove;
public event EventHandler? BalloonTipShown, BalloonTipClicked, BalloonTipClosed;
}UI thread only (except Dispose). Text longer than 127 characters throws ArgumentOutOfRangeException; ShowBalloonTip requires a non-empty text of at most 255 characters and a title of at most 63.
public sealed class TrayMenu
{
public IList<TrayMenuItem> Items { get; }
public event EventHandler? Opening;
}public class TrayMenuItem
{
public TrayMenuItem(string text, EventHandler? click = null);
public string Text { get; set; }
public bool Enabled { get; set; } // default true
public bool Checked { get; set; }
public bool IsDefault { get; set; }
public object? Tag { get; set; }
public bool IsSeparator { get; }
public IList<TrayMenuItem> Items { get; }
public event EventHandler? Click;
public static TrayMenuItem Separator();
public void PerformClick();
}public sealed class TrayIconImage : IDisposable
{
public static TrayIconImage FromApplicationIcon();
public static TrayIconImage FromResource(int resourceId);
public static TrayIconImage FromFile(string path);
public static TrayIconImage FromStream(Stream ico);
public static TrayIconImage FromHandle(nint handle, bool ownsHandle);
public nint GetHandle(int size);
}-
TrayMouseEventArgs:Button,Clicks,X,Y(screen coordinates, physical pixels) -
TrayMouseButtons:None,Left,Right,Middle -
TrayToolTipIcon:None,Info,Warning,Error
public static class ApplicationInfo
{
public static string ProductVersion { get; }
public static string ProductName { get; }
}Namespace Scarlet.Extensions.Hosting.DirectN.Threading.
public static IServiceCollection AddThreadSwitching(this IServiceCollection services)Registers a JoinableTaskContext whose main thread is the DirectN UI thread, and its JoinableTaskFactory. Requires AddDirectN().
The same public API as Microsoft.VisualStudio.Threading 17.12 for JoinableTaskContext, JoinableTaskContextNode, JoinableTaskFactory, JoinableTask, JoinableTask<T>, JoinableTaskCollection, JoinableTaskCreationOptions, JoinableTaskContextException, AsyncLazy<T> and AwaitExtensions. See Threading.
Namespace Scarlet.DirectN.Threading.
public sealed class DirectNMessageQueue : DirectNDispatcher
{
public static DirectNMessageQueue? Current { get; }
public static DirectNMessageQueue GetOrCreateForCurrentThread();
public static void RethrowAsUnhandled(Exception exception);
public int ManagedThreadId { get; }
public Thread Thread { get; }
public DirectNSynchronizationContext SynchronizationContext { get; }
public bool IsClosed { get; }
public int DroppedCount { get; }
public event EventHandler<DirectNUnhandledExceptionEventArgs>? UnhandledException;
public override bool CheckAccess();
public void Post(SendOrPostCallback callback, object? state);
public bool TryPost(SendOrPostCallback callback, object? state);
public bool TryPost(SendOrPostCallback callback, object? state, Action<object?>? onAbandoned);
public void Close();
}public abstract class DirectNDispatcher
{
public abstract bool CheckAccess();
public void VerifyAccess();
public void Post(Action callback);
public bool TryPost(Action callback);
public Task InvokeAsync(Action callback, CancellationToken cancellationToken = default);
public Task<T> InvokeAsync<T>(Func<T> callback, CancellationToken cancellationToken = default);
public Task InvokeAsync(Func<Task> callback, CancellationToken cancellationToken = default);
public Task<T> InvokeAsync<T>(Func<Task<T>> callback, CancellationToken cancellationToken = default);
protected abstract bool TryEnqueue(SendOrPostCallback callback, object? state, Action<object?> onAbandoned);
}Schedules work on a UI thread. InvokeAsync always queues (never inline), completes with the callback's result or exception, and faults with InvalidOperationException when the work is rejected or dropped before running; cancellation only prevents the callback from starting. See Message Queue.
To implement it, TryEnqueue must be thread-safe and always queue; preserve the caller's ExecutionContext and run the callback under the UI thread's SynchronizationContext; for accepted work (true), eventually call exactly one of callback and onAbandoned; return false, not throw, when the work is rejected.
public sealed class DirectNSynchronizationContext : SynchronizationContext
{
public DirectNMessageQueue Queue { get; }
}public sealed class DirectNUnhandledExceptionEventArgs : EventArgs
{
public DirectNUnhandledExceptionEventArgs(Exception exception);
public Exception Exception { get; }
public bool Handled { get; set; }
}See Message Queue for the guarantees.
Scarlet.Extensions.Hosting.DirectN
Getting Started
Core Features
Extensions
Reference