/maui-dependency-injection

name: maui-dependency-injection
description: >
  Guidance for configuring dependency injection in .NET MAUI apps — service
  registration in MauiProgram.cs, lifetime selection (Singleton / Transient / Scoped),
  constructor injection, Shell navigation auto-resolution, platform-specific
  registrations, and testability patterns.
  USE FOR: "dependency injection", "DI setup", "AddSingleton", "AddTransient",
  "AddScoped", "service registration", "constructor injection", "IServiceProvider",
  "MauiProgram DI", "register services", "BindingContext injection".
  DO NOT USE FOR: data binding (use maui-data-binding), Shell route configuration
  (use maui-shell-navigation), unit-test mocking frameworks (use standard xUnit
  and NSubstitute patterns).
license: MIT

Dependency Injection in .NET MAUI

.NET MAUI uses the same `Microsoft.Extensions.DependencyInjection` container as ASP.NET Core. All service registration happens in `MauiProgram.CreateMauiApp()` on `builder.Services`. The container is built once at startup and is immutable thereafter.

When to Use

• Registering services, ViewModels, and Pages in `MauiProgram.cs`
• Choosing between `AddSingleton`, `AddTransient`, and `AddScoped`
• Wiring constructor injection for Pages and ViewModels
• Leveraging Shell navigation to auto-resolve DI-registered Pages
• Registering platform-specific service implementations with `#if` directives
• Designing interfaces for testable service layers

When Not to Use

• XAML data-binding syntax or compiled bindings — use the **maui-data-binding** skill
• Shell route registration and query parameters — use the **maui-shell-navigation** skill
• Mocking frameworks or test runners — use standard .NET testing tools (xUnit, NUnit, MSTest) and mocking libraries (NSubstitute, Moq)

Inputs

• A .NET MAUI project with a `MauiProgram.cs` file
• Knowledge of which services, ViewModels, and Pages need registration
• Target platforms (Android, iOS, Mac Catalyst, Windows) for conditional registrations

Rules That Change the Answer

| Situation | Do this | Why | |---|---|---| | Registering a Page or ViewModel | Prefer `AddTransient` | A fresh instance per navigation avoids stale state, and a Singleton page cannot be re-added to the visual tree after it is removed. Singleton is defensible for a genuinely single-instance page (e.g. a root tab you want to keep warm) | | Registering shared/expensive state | `AddSingleton` | One instance app-wide (settings, DB connection, `HttpClient` handler) | | Tempted to use `AddScoped` | Use `AddTransient` (or `AddSingleton` if sharing is intended) | MAUI has **no** built-in request scope like ASP.NET Core's HTTP pipeline. MAUI does create one `IServiceScope` per window, so a Scoped service lives as long as that window — and resolved from the root provider it behaves like a Singleton. Neither gives you per-navigation freshness | | Navigating to a DI-registered page | Register the page **and** its ViewModel, then `Routing.RegisterRoute` | `Shell.Current.GoToAsync` resolves the page through DI and injects its constructor dependencies | | Platform-specific implementation | `#if` per platform **with every platform covered** | A missing platform branch leaves the service unregistered and throws at resolution time |

**Do not** introduce DI into a project that isn't using it, swap a working service lifetime, or add an interface purely for symmetry — only when the user asked or it fixes a real defect.

**Answer narrowly, but completely.** When you recommend a lifetime change, show the registration code, and give the realistic alternatives rather than a single verdict — for a unit-of-work or `DbContext` question that means `AddTransient`, an explicit `IServiceScopeFactory.CreateScope()`, **and** the factory pattern (`AddDbContextFactory`), with a note on when each fits. A one-line prescription is usually a worse answer than a short menu with trade-offs.

// Explicit scope when you genuinely need unit-of-work semantics
using var scope = scopeFactory.CreateScope();
var db = scope.ServiceProvider.GetRequiredService<MyDbContext>();

Workflow

1. Identify all services, ViewModels, and Pages that need to participate in dependency injection. 2. Choose the correct lifetime for each type — `AddSingleton` for shared services, `AddTransient` for Pages and ViewModels. 3. Register all types in `MauiProgram.CreateMauiApp()` on `builder.Services`, grouping by category (services, HTTP, ViewModels, Pages). 4. Register Pages as Shell routes in `AppShell.xaml.cs` so Shell navigation auto-resolves the full dependency graph. 5. Wire each Page to its ViewModel via constructor injection, assigning the ViewModel as `BindingContext`. 6. Add platform-specific registrations with `#if` directives, ensuring every target platform is covered or has a fallback. 7. Verify resolution works by running the app and confirming no `null` dependencies or missing-registration exceptions at runtime.

---

Lifetime Selection

| Lifetime | When to Use | Typical Types | |---|---|---| | `AddSingleton<T>()` | Shared state, expensive to create, app-wide config | `HttpClient` factory, settings service, database connection | | `AddTransient<T>()` | Lightweight, stateless, or needs a fresh instance per use | Pages, ViewModels, per-call API wrappers | | `AddScoped<T>()` | Per-window lifetime, or a manually created `IServiceScope` | Scoped unit-of-work (rare in MAUI) |

**Key rule:** Register Pages and ViewModels as **Transient** by default. Register shared services as **Singleton**.

> ⚠️ **Avoid `AddScoped` unless you manually manage `IServiceScope`.** MAUI has no built-in request scope like ASP.NET Core. MAUI creates one `IServiceScope` per window, so a Scoped service lives as long as that window; resolved from the root provider it silently behaves as a Singleton. Neither gives per-navigation freshness.

---

Registration Pattern in MauiProgram.cs

public static MauiApp CreateMauiApp()
{
    var