Scarlet.Extensions.Hosting.DirectN 1.1.0

Prefix Reserved
dotnet add package Scarlet.Extensions.Hosting.DirectN --version 1.1.0
                    
NuGet\Install-Package Scarlet.Extensions.Hosting.DirectN -Version 1.1.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Scarlet.Extensions.Hosting.DirectN" Version="1.1.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Scarlet.Extensions.Hosting.DirectN" Version="1.1.0" />
                    
Directory.Packages.props
<PackageReference Include="Scarlet.Extensions.Hosting.DirectN" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Scarlet.Extensions.Hosting.DirectN --version 1.1.0
                    
#r "nuget: Scarlet.Extensions.Hosting.DirectN, 1.1.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Scarlet.Extensions.Hosting.DirectN@1.1.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Scarlet.Extensions.Hosting.DirectN&version=1.1.0
                    
Install as a Cake Addin
#tool nuget:?package=Scarlet.Extensions.Hosting.DirectN&version=1.1.0
                    
Install as a Cake Tool

Scarlet.Extensions.Hosting.DirectN

Nuget Nuget GitHub codecov

Unofficial implementation of Microsoft.Extensions.Hosting for DirectN (Win32 / Direct2D) desktop applications, and the successor of Extensions.Hosting.Wpf for apps moving off WPF. It runs the DirectN UI thread inside the Generic Host and is Native AOT compatible end to end: every package is IsAotCompatible, and CI publishes the samples, the scenario app and the tests with PublishAot. The main package registers DirectNDispatcher for awaitable UI operations (InvokeAsync). Extension packages provide thread switching between the UI thread and the thread pool (JoinableTaskFactory, AsyncLazy<T>) and a tray icon.

Changelog | Wiki

NuGet Packages

Name Description Latest version
Scarlet.Extensions.Hosting.DirectN The main library, with Microsoft.Extensions.Hosting for DirectN support. NuGet
Scarlet.Extensions.Hosting.DirectN.TrayIcon An extension enabling tray icon support, with WinForms NotifyIcon behavior and a native Win32 menu. NuGet
Scarlet.Extensions.Hosting.DirectN.Threading An extension enabling thread switching between the UI thread and ThreadPool threads via an AOT-compatible extract of Microsoft.VisualStudio.Threading (JoinableTaskFactory, AsyncLazy<T>). NuGet
Scarlet.DirectN.Threading The UI-thread message queue and SynchronizationContext under the host. Installed with the main library. NuGet

Quick Start

1. Create Program.cs

Use Host.CreateApplicationBuilder from Microsoft.Extensions.Hosting. Everything is registered on builder.Services before calling Build(), so the same calls work with any IHostApplicationBuilder and inside IHostBuilder.ConfigureServices. There is no application class to write: the host creates DirectN's Application.

using Microsoft.Extensions.Hosting;
using Scarlet.Extensions.Hosting.DirectN;

var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddDirectN();
builder.Services.AddDirectNLifetime();
builder.Services.AddDirectNComponent<MainWindowComponent>();

using var host = builder.Build();
host.Run();

2. Create the UI in a component

Components are created with their dependencies from the container, initialized on the UI thread before the message loop starts, and disposed there (in reverse order) after it ends. The container never disposes them.

using DirectN.Extensions.Utilities;
using Scarlet.Extensions.Hosting.DirectN;

public sealed class MainWindowComponent : IDirectNComponent
{
    public void InitializeComponent()
    {
        var window = new Window("My app");
        window.ResizeClient(800, 600);
        window.Center();
        window.Show();
    }
}

AddDirectN takes options for what WPF's App class used to do:

builder.Services.AddDirectN(options =>
{
    options.ShutdownMode = ShutdownMode.OnExplicitShutdown;          // tray apps; default OnLastWindowClose
    options.OnStartup = (services, context) => { /* UI thread, before the message loop */ };
    options.OnExit = (services, context) => { /* UI thread, after the message loop */ };
});

The DirectN UI thread is created and started once every hosted service has started, the way ASP.NET Core starts serving requests. If any hosted service fails to start, the UI is never created; failures while creating it (in OnStartup or a component) fail host startup instead of crashing the process. Another hosted service that needs the UI thread can post to IDirectNThread.SynchronizationContext or use JoinableTaskFactory.SwitchToMainThreadAsync at any time: work posted before the UI thread exists runs once it has started. Just don't wait for it inside StartAsync (awaiting the switch there, or JoinableTaskFactory.Run): the UI thread only starts after every StartAsync has returned, so startup would hang. Do such work from BackgroundService.ExecuteAsync or IHostApplicationLifetime.ApplicationStarted instead.

Started last, the UI is also stopped first: before any hosted service's StopAsync, the host waits until the UI thread has fully ended (remaining windows closed, OnExit, components disposed), up to HostOptions.ShutdownTimeout. Application cleanup can therefore still use other hosted services and every registered service. When the application exits on its own (last window closed, Application.Exit(), IDirectNThread.HandleApplicationExit()), the host stops. Confirmed Windows session ends (log off, shut down, restart) and Restart Manager shutdown requests are handled too: application cleanup and the hosted services get a bounded opportunity (HostOptions.ShutdownTimeout) to finish before the process is terminated.

Known limitations:

  • Waiting for the UI thread is bounded by HostOptions.ShutdownTimeout, once. Application code that blocks longer (in initialization or cleanup) may still run after the host has started disposing services.
  • Environment.Exit called on the UI thread blocks it for good: the other hosted services are still stopped, but the application's cleanup (OnExit, components) doesn't run.
  • One DirectN host per process: DirectN allows one Application per thread and none after its process-wide exit.

AddDirectNLifetime() is optional. With any host lifetime, AddDirectN stops the host when the DirectN application exits. DirectNLifetime replaces the default ConsoleLifetime with one suited to a windowed application: no Ctrl+C handling or console shutdown hints, status messages (turn them off with AddDirectNLifetime(options => options.SuppressStatusMessages = true)), and a graceful host shutdown when the process exits.

3. Update .csproj

<PropertyGroup>
  <OutputType>WinExe</OutputType>
  <TargetFramework>net10.0-windows</TargetFramework>
  <PublishAot>true</PublishAot>
  <ApplicationManifest>app.manifest</ApplicationManifest>
</PropertyGroup>

The manifest should declare PerMonitorV2 DPI awareness and Common Controls 6 (visual styles, required by task dialogs); see the sample's manifest.

For the full guide including components, application options, thread switching, tray icons, and more, see the Wiki.

Samples

  1. HostingMinimal: Top-level statements with Host.CreateApplicationBuilder, a DirectN window created by a component, and a BackgroundService updating it through Threading.
  2. HostingTrayIcon: A windowless tray application (ShutdownMode.OnExplicitShutdown) using the TrayIcon feature: native menu, balloon tips, and Exit stopping the host.

Both publish with PublishAot.

Documentation

Full documentation is available in the Wiki:

License

MIT. Scarlet.Extensions.Hosting.DirectN.Threading contains code from microsoft/vs-threading (MIT) and the tray icon ports behavior from dotnet/winforms (MIT); see LICENSE-3RD-PARTY.txt and UPSTREAM.md.

Product Compatible and additional computed target framework versions.
.NET net10.0-windows7.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on Scarlet.Extensions.Hosting.DirectN:

Package Downloads
Scarlet.Extensions.Hosting.DirectN.Threading

Thread switching for Scarlet.Extensions.Hosting.DirectN: JoinableTaskFactory and AsyncLazy bound to the DirectN UI thread. Contains a trimmed, Native AOT compatible extract of Microsoft.VisualStudio.Threading (MIT); not affiliated with Microsoft.

Scarlet.Extensions.Hosting.DirectN.TrayIcon

Notification area (tray) icon for Scarlet.Extensions.Hosting.DirectN: a Native AOT compatible TrayNotifyIcon with WinForms behavior and a native Win32 context menu, hosted on the DirectN UI thread.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.1.0 134 11/5/2026
1.0.0 138 11/3/2026