Dependency Injection & the Generic Host

The reasons are the same as for any other .NET workload, and the official overview lists them for a hard-coded dependency: replacing it forces edits in every consumer, its own dependencies must be configured by the consumer, and it cannot be replaced by a test double. The three ingredients of the fix are small:

This is the dependency inversion principle in practice: the high-level view model depends on an abstraction owned by the core library, and the low-level SQLite code depends on the same abstraction, so the dependency arrow points toward the core. For a layered solution such as Bookshelf (Bookshelf.Core, Bookshelf.Data, Bookshelf.Desktop, Bookshelf.Tests) the container is the only place that knows every project; see Project Structure & Build for the project references.

The official overview also warns that desktop apps "control their own lifetime", so WPF and Windows Forms must integrate the host lifetime with the application’s lifetime events. The rest of this page is that integration.

You can use new ServiceCollection().BuildServiceProvider() without a host; the MVVM Toolkit documentation and the WinUI tutorial do exactly that. The host adds the infrastructure most applications end up writing anyway. The Generic Host page lists what Host.CreateApplicationBuilder configures by default:

Two builder styles exist. Host.CreateApplicationBuilder (IHostApplicationBuilder, introduced in .NET 6) is a linear, property-based style (builder.Services, builder.Configuration, builder.Logging) and is the style the current templates and the WPF how-to use. Host.CreateDefaultBuilder (IHostBuilder) is the older callback style (ConfigureServices, ConfigureAppConfiguration); both provide the same defaults, and the documentation recommends the first for new projects. Older Bookshelf snippets and many blog posts use CreateDefaultBuilder; the two are interchangeable for everything on this page.

Which environment name is "current"? It comes from the DOTNET_ENVIRONMENT variable, which Visual Studio sets from a launch profile (the environmentVariables entry of Properties/launchSettings.json). A deployed desktop app has no such variable, so it runs as Production, the DI validation above is off, and the user secrets are not loaded. That asymmetry is the reason the testing section below validates the container explicitly.

The official how-to (Use the .NET Generic Host in a WPF app, dated March 2026) has four steps: remove StartupUri, build and start the host in the Startup handler, stop and dispose it in the Exit handler, and register the main window so that it can take services in its constructor. The pieces below are that sample adapted to Bookshelf.

The registrations live in two extension methods. AddBookshelfCore holds everything that all three UI stacks share (options, the data layer, the messenger and the hosted services); AddBookshelfDesktop calls it and adds the WPF-specific services, windows and view models. The same methods build the production container and a test container, and the WinUI and Windows Forms variants further down call AddBookshelfCore with their own UI registrations.

Source: Dependency injection overview, Options pattern and Options pattern guidance for .NET library authors (Add{Service} naming, and a namespace of your own rather than Microsoft.Extensions.DependencyInjection). The two-method layout, WindowScopeManager and IDialogService are Bookshelf patterns; neither WPF nor the toolkit defines them. AddBookshelfData is the data-layer registration shown on Local Data, Settings & Files.

ICatalogSyncClient is a small Bookshelf contract in Bookshelf.Core; CatalogSyncClient stands for the app’s own implementation (an HTTP client for a remote catalogue, for example), which this page does not show:

Source: Dependency injection overview ("Scope scenarios")

Host.CreateApplicationBuilder loads appsettings.json from the content root if the file is there (the how-to’s CopyToOutputDirectory rule puts it there). The options pattern turns a section of configuration into a strongly typed class and gives you validation.

Source: Options pattern in .NET (a section bound to an options class) and Logging in .NET (the Logging section)

Source: Options pattern in .NET (binding, ValidateDataAnnotations, ValidateOnStart) and Logging in .NET (the Logging section). The data-folder choice is a Bookshelf decision.

The options class must be non-abstract with a public parameterless constructor and public read-write properties to bind (fields are not bound). The registration in AddBookshelfCore binds the section and calls ValidateOnStart, so an invalid value (a PageSize of 0, a file name without .db) stops StartAsync with an OptionsValidationException before the first window shows. ValidateDataAnnotations lives in the Microsoft.Extensions.Options.DataAnnotations NuGet package, which the options page names explicitly; add it to the project if the build cannot find the method.

The host registers ILogger<T> and ILoggerFactory. Anything built by the container can ask for ILogger<MyType>, and the category is the full type name. The defaults print to the Console provider (invisible in a WinExe), the Debug provider (shows in the Visual Studio Output window), EventSource, and the Windows Event Log.

Source: Logging in .NET (message templates, LoggerMessage source generation) and .NET Generic Host (IHostedService)

The logging page recommends compile-time source generation ([LoggerMessage]) over the LogInformation extension methods for better performance and stronger typing, and recommends message templates with named placeholders (not string interpolation, which analyzer CA2254 flags). Placeholders are positional: the names are only labels.

Configure levels in the Logging section of appsettings.json (shown above) or in code through builder.Logging (ClearProviders, AddFilter, SetMinimumLevel, AddSimpleConsole). Levels run Trace (0), Debug, Information, Warning, Error, Critical and None (6). If nothing is configured the default is Information. A provider section such as Logging:Debug:LogLevel overrides Logging:LogLevel, and a more specific category beats a general one.

Practical points for desktop apps:

IHostedService has two lifecycle methods, StartAsync(CancellationToken) and StopAsync(CancellationToken). The host calls them when it starts and stops. BackgroundService is an abstract class that implements the interface and asks you to override ExecuteAsync(CancellationToken), which runs for the lifetime of the host and receives a token that fires on shutdown. A hosted service can use logging, configuration and DI like any other service.

The Bookshelf sync service refreshes the local catalogue every SyncInterval. It needs a scoped service (ICatalogSyncClient, the Bookshelf contract registered as scoped in AddBookshelfCore), so it follows the documented rule for scoped work in hosted services: do not inject the scoped service; inject IServiceScopeFactory, create a scope per iteration and resolve inside it.

Source: Worker Services in .NET (BackgroundService, IHostedService) and Dependency injection overview ("Scope scenarios"). The PeriodicTimer loop and the message are Bookshelf choices.

Notes:

Bookshelf stores books in SQLite through EF Core. The EF Core documentation explains the key constraints:

ASP.NET Core’s AddDbContext registers the context with a scoped lifetime, which maps to one request. A desktop app has no request scope: AddDbContext plus constructor injection into a singleton repository would keep one context for the whole session, accumulate every tracked entity, and break as soon as two operations overlap. The EF Core page describes AddDbContextFactory for "application types …​ that use dependency injection but do not create a service scope that aligns with the desired DbContext lifetime" (it names Blazor, but the same logic applies to WPF), and states that contexts created by the factory "are not managed by the application’s service provider and therefore must be disposed by the application".

Source: DbContext lifetime, configuration, and initialization ("Use a DbContext factory", "Avoiding DbContext threading issues"). The entity, context and repository bodies are Bookshelf code: the EF Core page shows AddDbContextFactory and CreateDbContext but no repository.

Why this works with the lifetimes above:

Do not register the context with AddDbContext in a WPF app unless you also create a scope per unit of work. The connection string here is a local SQLite file and contains no credential; a database that needs one belongs behind an authenticated service, not in appsettings.json.

The MVVM Toolkit does not ship a container. Its Ioc page says so: the toolkit "doesn’t provide built-in APIs" for dependency injection because Microsoft.Extensions.DependencyInjection already exists. What it does provide is the CommunityToolkit.Mvvm.DependencyInjection.Ioc class, a thread-safe holder for one IServiceProvider:

The Ioc conceptual page (last updated in 2022 according to its metadata, with a UWP example) walks through the same idea with a hand-written App.Services property and App.Current.Services.GetService<T>(), and the WinUI tutorial on Microsoft Learn (step 3, "Add dependency injection") uses the same shape. Neither shows Ioc.Default; the class documentation does.

The two can be combined: let the host build the provider, then publish it to Ioc.Default for the few places that cannot use constructor injection.

Source: Ioc class and Ioc (MVVM Toolkit). Combining Ioc.Default with a host-built provider is a Bookshelf pattern; the official pages show it with a provider built directly from a ServiceCollection.

When to use which approach:

An official note: the Ioc documentation does not state what ConfigureServices does when it is called twice. It is commonly said to throw an InvalidOperationException; the page cited here does not confirm it, so tests that configure the static instance should do so once in a fixture.

WinUI 3 apps start from a different Application class (Microsoft.UI.Xaml.Application) and activate through OnLaunched. No Microsoft Learn page was found that shows the Generic Host in a WinUI 3 app; the WinUI MVVM Toolkit tutorial builds a plain ServiceCollection in the App constructor. The snippet below combines that tutorial’s shape with the host from the WPF how-to. It is a pattern derived from the official pieces, not an official sample.

Source: Data binding with WinUI and MVVM Toolkit, step 3: add dependency injection for the App and OnLaunched structure; the host calls follow Use the .NET Generic Host in a WPF app. The combination is a pattern, not an official WinUI sample.

Differences to keep in mind:

Windows Forms has an official how-to as well (Use the .NET Generic Host in a Windows Forms app, March 2026). Because Main owns the message loop, the host is configured directly in Program.cs, and the form is passed to Application.Run:

Source: Use the .NET Generic Host in a Windows Forms app. AddBookshelfCore is the shared Bookshelf registration method; the official sample registers its own services inline.

Notes: the official sample registers the form as transient and calls the synchronous host.Start(). For Visual Basic with the Application Framework it uses the Startup and Shutdown events in ApplicationEvents.vb and an OnCreateMainForm override; removing the startup form setting avoids a designer-generated override that bypasses DI. Constructor injection into forms has a designer implication: Visual Studio’s designer needs to be able to create a form it is displaying, and a form whose only constructor has parameters is a frequent source of designer errors. Many teams keep a parameterless constructor for the designer next to the injected one; the how-to does not mention this, so check your designer version.

Production runs as Production, where scope and dependency validation are off. A composition mistake (a missing registration, a scoped service injected into a singleton) then shows up when the user first opens the affected window. Make a test do the validation instead, using the same extension method as the app:

Source: Dependency injection overview ("Scope validation") and .NET Generic Host (ServiceProviderOptions.ValidateOnBuild). Resolving WPF windows in a test needs an STA thread, so the test above stops at the view model; see Testing View Models & UI.

The guidelines add: pass validateScopes: true to BuildServiceProvider to turn a captive dependency into an InvalidOperationException ("Cannot consume scoped service …​"). ValidateOnBuild additionally checks at build time that every registered service can be constructed. Both options are on the ServiceProviderOptions class that the Generic Host page links. Neither can see a service that is only requested at run time through GetRequiredService, such as the ICatalogSyncClient that LibrarySyncService resolves inside its own scope: if that registration were missing, the container would still build, and the failure would appear on the first sync. That is why the test resolves it explicitly.