Skip to content

11. API Reference πŸ“š

Artyom M. edited this page Nov 5, 2026 · 4 revisions

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.


Scarlet.Extensions.Hosting.DirectN (Core)

ServiceCollectionExtensions

Namespace Scarlet.Extensions.Hosting.DirectN. These work with every builder: builder.Services of Host.CreateApplicationBuilder, and inside IHostBuilder.ConfigureServices.

AddDirectN()

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.

AddDirectN(configureOptions)

public static IServiceCollection AddDirectN(
    this IServiceCollection services,
    Action<DirectNOptions> configureOptions)

Same as AddDirectN(), and configures the DirectNOptions.

AddDirectNComponent<TComponent>()

public static IServiceCollection AddDirectNComponent<
    [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] TComponent>(
    this IServiceCollection services)
    where TComponent : class, IDirectNComponent

Adds 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.

AddDirectNComponent<TComponent>(factory)

public static IServiceCollection AddDirectNComponent<TComponent>(
    this IServiceCollection services,
    Func<IServiceProvider, TComponent> createComponent)
    where TComponent : class, IDirectNComponent

Adds a component created by createComponent on the UI thread.

AddDirectNLifetime()

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.

AddDirectNLifetime(configureOptions)

public static IServiceCollection AddDirectNLifetime(
    this IServiceCollection services,
    Action<DirectNLifetimeOptions> configureOptions)

Same, and configures the DirectNLifetimeOptions.

HostBuilderExtensions

public static IHostBuilder UseDirectNLifetime(this IHostBuilder hostBuilder)
public static IHostBuilder UseDirectNLifetime(this IHostBuilder hostBuilder, Action<DirectNLifetimeOptions> configureOptions)

IHostBuilder shortcuts for AddDirectNLifetime.

Core Interfaces

IDirectNThread

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

IDirectNContext

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.

IDirectNComponent

public interface IDirectNComponent
{
    void InitializeComponent();
}

Called on the UI thread before the message loop starts. Implement IDisposable for cleanup on the UI thread.

Options

DirectNOptions

Property Type Default
ShutdownMode ShutdownMode OnLastWindowClose
OnStartup Action<IServiceProvider, IDirectNContext>? null
OnExit Action<IServiceProvider, IDirectNContext>? null
ShowFatalErrorDialog bool false

ShutdownMode

OnLastWindowClose, OnExplicitShutdown. See Application Options.

GenericHost

DirectNLifetime

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);
}

DirectNLifetimeOptions

Property Type Default
SuppressStatusMessages bool false

Scarlet.Extensions.Hosting.DirectN.TrayIcon

Namespace Scarlet.Extensions.Hosting.DirectN.TrayIcon.

ITrayIcon

public interface ITrayIcon : IDirectNComponent, IDisposable
{
}

ServiceCollectionExtensions

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, ITrayIcon

Adds the tray icon as a component.

TrayNotifyIcon

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.

TrayMenu

public sealed class TrayMenu
{
    public IList<TrayMenuItem> Items { get; }
    public event EventHandler? Opening;
}

TrayMenuItem

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();
}

TrayIconImage

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, TrayMouseButtons, TrayToolTipIcon

  • TrayMouseEventArgs: Button, Clicks, X, Y (screen coordinates, physical pixels)
  • TrayMouseButtons: None, Left, Right, Middle
  • TrayToolTipIcon: None, Info, Warning, Error

ApplicationInfo

public static class ApplicationInfo
{
    public static string ProductVersion { get; }
    public static string ProductName { get; }
}

Scarlet.Extensions.Hosting.DirectN.Threading

Namespace Scarlet.Extensions.Hosting.DirectN.Threading.

ServiceCollectionExtensions

public static IServiceCollection AddThreadSwitching(this IServiceCollection services)

Registers a JoinableTaskContext whose main thread is the DirectN UI thread, and its JoinableTaskFactory. Requires AddDirectN().

JoinableTaskFactory, AsyncLazy<T> and the rest

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.


Scarlet.DirectN.Threading

Namespace Scarlet.DirectN.Threading.

DirectNMessageQueue

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();
}

DirectNDispatcher

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.

DirectNSynchronizationContext

public sealed class DirectNSynchronizationContext : SynchronizationContext
{
    public DirectNMessageQueue Queue { get; }
}

DirectNUnhandledExceptionEventArgs

public sealed class DirectNUnhandledExceptionEventArgs : EventArgs
{
    public DirectNUnhandledExceptionEventArgs(Exception exception);
    public Exception Exception { get; }
    public bool Handled { get; set; }
}

See Message Queue for the guarantees.

Clone this wiki locally