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
<PackageReference Include="Scarlet.Extensions.Hosting.DirectN" Version="1.1.0" />
<PackageVersion Include="Scarlet.Extensions.Hosting.DirectN" Version="1.1.0" />
<PackageReference Include="Scarlet.Extensions.Hosting.DirectN" />
paket add Scarlet.Extensions.Hosting.DirectN --version 1.1.0
#r "nuget: Scarlet.Extensions.Hosting.DirectN, 1.1.0"
#:package Scarlet.Extensions.Hosting.DirectN@1.1.0
#addin nuget:?package=Scarlet.Extensions.Hosting.DirectN&version=1.1.0
#tool nuget:?package=Scarlet.Extensions.Hosting.DirectN&version=1.1.0
Scarlet.Extensions.Hosting.DirectN
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
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.Exitcalled 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
Applicationper 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
- HostingMinimal: Top-level statements with
Host.CreateApplicationBuilder, a DirectN window created by a component, and aBackgroundServiceupdating it through Threading. - 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:
- Getting Started — Minimal setup guide
- Components — UI-thread objects with constructor injection
- Application Options — Shutdown mode, startup and exit, unhandled exceptions
- DirectN Lifetime — The host lifetime for windowed applications
- Threading — Switch between UI and background threads
- TrayIcon — System tray icon support
- Message Queue — The UI-thread queue and its guarantees
- Architecture & How It Works — Internal architecture and lifecycle
- API Reference — Complete API reference
- FAQ & Troubleshooting — Common questions and error solutions
- Migrating from Extensions.Hosting.Wpf — API mapping and a before/after example
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 | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0-windows7.0 is compatible. |
-
net10.0-windows7.0
- DirectNAot (>= 1.7.1)
- DirectNAot.Extensions (>= 1.7.1)
- Microsoft.Extensions.Hosting (>= 10.0.3)
- Scarlet.DirectN.Threading (>= 1.1.0)
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.