| name | maui-aspire-client |
| description | Connect MAUI apps to Aspire-hosted APIs. USE FOR: `AddServiceDiscovery`, typed `HttpClient`, `https+http://apiservice`, missing AppHost config on devices, Android emulator `10.0.2.2`, iOS simulator `localhost`, physical-device LAN/dev-tunnel fallbacks, dev certs, Bearer handlers, debug-only cleartext. DO NOT USE FOR: offline caching, OAuth callbacks, or server-side Aspire. |
MAUI Aspire Client
Use this skill when a MAUI app consumes APIs or services orchestrated by .NET
Aspire during local development or testing.
Workflow
- Inspect whether the solution has an Aspire AppHost and a MAUI client project.
- Use Aspire service discovery when the MAUI app targets .NET 8 or later and
the resolved endpoint configuration is actually available to the app at
runtime.
- Register service discovery and typed
HttpClient clients in MauiProgram.cs.
- Use service names such as
https+http://apiservice only when the matching
Services__... configuration is present.
- Provide platform-reachable fallback base addresses for emulator, simulator,
desktop, and physical-device launches.
- Account for emulator/simulator networking if bypassing Aspire service
discovery.
- Keep auth, token handlers, and backend API clients in DI.
- Validate from Android emulator, iOS simulator, and physical devices as
applicable.
Service Discovery Pattern
MAUI apps deployed to emulators, simulators, or physical devices are usually not
child processes of the Aspire AppHost, so the AppHost cannot automatically
inject service discovery environment variables into the device app. Service-name
URIs work only when endpoint configuration is supplied to the MAUI app through
configuration, generated settings, or another explicit launch/deploy step.
When your dev flow can launch the MAUI project from the AppHost, wire the API
reference there first and pass endpoint configuration to the app:
