/maui-aspire

name: maui-aspire
description: >
  Guide for .NET MAUI apps consuming .NET Aspire-hosted backend services.
  Covers AppHost configuration, service discovery for mobile clients,
  HttpClient DI setup, Entra ID authentication with MSAL.NET for calling
  protected APIs, development workflow (Aspire dashboard + MAUI debugging),
  Blazor Hybrid considerations, and platform-specific networking for
  Android emulators and iOS simulators.
  USE FOR: "MAUI with Aspire", "Aspire service discovery", "AppHost MAUI",
  "Aspire backend", "MAUI Aspire networking", "mobile Aspire", "Aspire dashboard MAUI".
  DO NOT USE FOR: standalone REST API calls without Aspire (use maui-rest-api),
  authentication without Aspire (use maui-authentication), or Aspire-only projects without MAUI.

.NET MAUI with .NET Aspire

Key Differences from Other Aspire Clients

MAUI apps are NOT orchestrated by the AppHost — they run on devices/simulators and connect over the network. This changes everything:

• ❌ Cannot use Aspire service discovery URIs (`https+http://apiservice`)
• ❌ Cannot be added with `.WithReference()` in the AppHost
• ❌ Cannot use `AddServiceDefaults()` (not an ASP.NET Core host)
• ✅ Must use real network-reachable endpoints
• ✅ Must use MSAL.NET (public client) — not OIDC (confidential client)

Common Gotchas

1. ❌ Don't add MAUI to the AppHost

// ❌ MAUI doesn't implement IServiceMetadata — this will fail
builder.AddProject<Projects.MyMauiApp>("mauiapp");

// ✅ Only add backend services to the AppHost
var apiService = builder.AddProject<Projects.MyApp_ApiService>("apiservice");

2. ❌ Don't use Aspire service discovery URIs in MAUI

// ❌ This only resolves inside the Aspire AppHost orchestration
client.BaseAddress = new Uri("https+http://apiservice");

// ✅ Use real endpoints
client.BaseAddress = new Uri("https://localhost:7001");

3. ⚠️ Android emulator can't reach localhost

The Android emulator has its own network stack. `localhost` points to the emulator itself, not the host machine.

// ❌ Fails silently on Android emulator
client.BaseAddress = new Uri("https://localhost:7001");

// ✅ Use 10.0.2.2 for host loopback on Android emulator
#if ANDROID && DEBUG
    client.BaseAddress = new Uri("https://10.0.2.2:7001");
#else
    client.BaseAddress = new Uri("https://localhost:7001");
#endif

4. ⚠️ Android emulator doesn't trust .NET dev certificates

The emulator won't trust your HTTPS dev cert. During local development:

// ⚠️ Development only — never ship this
#if ANDROID && DEBUG
builder.Services.AddHttpClient<IWeatherApiClient, WeatherApiClient>(client =>
{
    client.BaseAddress = new Uri("https://10.0.2.2:7001");
})
.ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler
{
    ServerCertificateCustomValidationCallback = (_, _, _, _) => true
});
#endif

5. ⚠️ Auth is public client, not confidential

MAUI uses `PublicClientApplication` (MSAL.NET). The Entra Aspire auth skill (`entra-id-aspire-authentication`) is for the API/Blazor Server side only. For the MAUI side, use the `maui-authentication` skill.

6. ⚠️ Aspire requires .NET 10+

Ensure your MAUI project also targets `net10.0-*` TFMs to match the Aspire backend.

Blazor Hybrid Caveat

In MAUI Blazor Hybrid apps calling Aspire services, authentication happens at the **MAUI layer** (MSAL.NET), not in the Blazor WebView. Don't use `AddMicrosoftIdentityWebApp` or server-side OIDC patterns in the MAUI app.

Aspire Service Defaults Don't Apply

MAUI projects should **not** use `AddServiceDefaults()` because:

• MAUI apps are not ASP.NET Core hosts
• OpenTelemetry for mobile has different requirements
• Health check endpoints don't apply to client apps

For telemetry correlation, configure OpenTelemetry separately using `System.Diagnostics` APIs.

Development Workflow Decision

| Scenario | What to do | |----------|-----------| | Debugging API issues | Use the Aspire dashboard at `https://localhost:17178` | | Debugging MAUI + API | Run Aspire AppHost in one terminal, MAUI in another | | VS: simultaneous debug | Open two VS instances — one per project | | VS Code | Two terminals, or Aspire extension + MAUI extension |

Platform Networking Quick Reference

| Platform | localhost works? | HTTPS dev cert trusted? | Special config needed? | |----------|-----------------|------------------------|----------------------| | iOS Simulator | ✅ Yes | ✅ Yes (macOS keychain) | ATS exception for HTTP | | Android Emulator | ❌ Use `10.0.2.2` | ❌ No | Network security config | | Mac Catalyst | ✅ Yes | ✅ Yes | None | | Windows | ✅ Yes | ✅ Yes | None |

Checklist

• [ ] MAUI project is NOT added to AppHost with `AddProject`
• [ ] API base URL uses real endpoints, not `https+http://` URIs
• [ ] Android: uses `10.0.2.2` instead of `localhost`
• [ ] Android: SSL bypass or HTTP config for local dev only
• [ ] Auth uses MSAL.NET `PublicClientApplication`, not confidential client
• [ ] MAUI and Aspire both target `net10.0-*`
• [ ] `AddServiceDefaults()` is NOT called in the MAUI project