maui-aspire

.NET MAUI 与 .NET Aspire

与其他 Aspire 客户端的主要区别

MAUI 应用不会由 AppHost 编排，而是在设备或模拟器上运行，并通过网络连接。这会带来一系列变化：

• ❌ 不能使用 Aspire 服务发现 URI（https+http://apiservice）
• ❌ 不能在 AppHost 中通过 .WithReference() 添加
• ❌ 不能使用 AddServiceDefaults()（MAUI 不是 ASP.NET Core 主机）
• ✅ 必须使用网络可访问的真实端点
• ✅ 必须使用 MSAL.NET（公共客户端），而非 OIDC（机密客户端）

常见注意事项

1. ❌ 不要将 MAUI 添加到 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. ❌ 不要在 MAUI 中使用 Aspire 服务发现 URI

// ❌ 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 模拟器无法访问 localhost

Android 模拟器有自己的网络堆栈。localhost 指向模拟器本身，而不是主机。

// ❌ 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 模拟器不信任 .NET 开发证书

模拟器不会信任你的 HTTPS 开发证书。在本地开发期间：

// ⚠️ 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. ⚠️ 使用的是公共客户端身份验证，而非机密客户端

MAUI 使用 PublicClientApplication（MSAL.NET）。Entra Aspire 身份验证技能（entra-id-aspire-authentication）仅适用于 API/Blazor Server 端。对于 MAUI 端，请使用 maui-authentication 技能。

6. ⚠️ Aspire 要求使用 .NET 10+

确保 MAUI 项目也以 net10.0-* TFM 为目标，以匹配 Aspire 后端。

Blazor Hybrid 注意事项

在调用 Aspire 服务的 MAUI Blazor Hybrid 应用中，身份验证发生在 MAUI 层（MSAL.NET），而不是 Blazor WebView 中。不要在 MAUI 应用中使用 AddMicrosoftIdentityWebApp 或服务器端 OIDC 模式。

Aspire 服务默认配置不适用

MAUI 项目不应使用 AddServiceDefaults()，因为：

• MAUI 应用不是 ASP.NET Core 主机
• 移动端的 OpenTelemetry 有不同的要求
• 健康检查端点不适用于客户端应用

如需实现遥测关联，请使用 System.Diagnostics API 单独配置 OpenTelemetry。

开发工作流选择

场景	操作
调试 API 问题	使用 Aspire 仪表板：https://localhost:17178
调试 MAUI 和 API	在一个终端中运行 Aspire AppHost，在另一个终端中运行 MAUI
VS：同时调试	打开两个 VS 实例，每个项目使用一个
VS Code	使用两个终端，或使用 Aspire 扩展和 MAUI 扩展

平台网络配置速查

平台	localhost 是否可用？	是否信任 HTTPS 开发证书？	是否需要特殊配置？
iOS Simulator	✅ 是	✅ 是（macOS 钥匙串）	HTTP 的 ATS 例外
Android Emulator	❌ 使用 10.0.2.2	❌ 否	网络安全配置
Mac Catalyst	✅ 是	✅ 是	无
Windows	✅ 是	✅ 是	无

检查清单

• 未通过 AddProject 将 MAUI 项目添加到 AppHost
• API 基础 URL 使用真实端点，而非 https+http:// URI
• Android：使用 10.0.2.2，而非 localhost
• Android：仅在本地开发时绕过 SSL 或配置 HTTP
• 身份验证使用 MSAL.NET PublicClientApplication，而非机密客户端
• MAUI 和 Aspire 均以 net10.0-* 为目标
• MAUI 项目中未调用 AddServiceDefaults()