Maui Aspire

.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("mauiapp");

// ✅ Only add backend services to the AppHost
var apiService = builder.AddProject("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(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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: davidortinau
• Source: davidortinau/maui-skills
• License: MIT

Install and usage instructions live in the source repository linked above.