maui-aspire-client

MAUI Aspire Client

Use this skill when a MAUI app consumes APIs or services orchestrated by .NET Aspire during local development or testing.

Workflow

1. Inspect whether the solution has an Aspire AppHost and a MAUI client project.
2. 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.
3. Register service discovery and typed HttpClient clients in MauiProgram.cs.
4. Use service names such as https+http://apiservice only when the matching Services__... configuration is present.
5. Provide platform-reachable fallback base addresses for emulator, simulator, desktop, and physical-device launches.
6. Account for emulator/simulator networking if bypassing Aspire service discovery.
7. Keep auth, token handlers, and backend API clients in DI.
8. 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:

var api = builder.AddProject<Projects.ApiService>("apiservice");
builder.AddProject<Projects.MauiClient>("mauiclient")
       .WithReference(api);

builder.Services.AddServiceDiscovery();

builder.Services.AddHttpClient<WeatherApiClient>(client =>
{
    // Development only: use "https://" for production endpoints.
    client.BaseAddress = new Uri("https+http://apiservice");
})
.AddServiceDiscovery();

For many clients, configure defaults once: