用途
当 MAUI 应用在本地开发或测试期间需要消费由 .NET Aspire 编排的 API 或服务时,使用该技能。它聚焦于 MAUI 客户端与 Aspire AppHost 之间的连接配置,而不是后端 API 本身的实现。
工作流程
技能给出的流程包括:
- 检查解决方案是否同时存在 Aspire AppHost 与 MAUI 客户端项目。
- 当 MAUI 应用目标为 .NET 8 或更高版本,且解析后的端点配置在运行时确实对应用可用时,使用 Aspire 服务发现。
- 在 MauiProgram.cs 中注册服务发现与类型化 HttpClient 客户端。
- 仅在存在匹配的 Services__... 配置时,使用 https+http://apiservice 这类服务名。
- 为模拟器、仿真器、桌面与物理设备提供平台可达的回退基地址。
- 若绕过 Aspire 服务发现,需考虑模拟器/仿真器的网络寻址方式。
- 将认证、令牌处理器与后端 API 客户端保留在依赖注入(DI)中。
- 按需从 Android 模拟器、iOS 仿真器与物理设备进行验证。
服务发现模式
部署到模拟器、仿真器或物理设备的 MAUI 应用通常不是 Aspire AppHost 的子进程,因此 AppHost 无法自动向设备应用注入服务发现环境变量。服务名 URI 只有在端点配置通过配置、生成的设置或其他显式启动/部署步骤提供给 MAUI 应用时才有效。
当开发流程能够从 AppHost 启动 MAUI 项目时,先在 AppHost 中连接 API 引用,并把端点配置传递给应用,示例代码:
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();
对于多个客户端,可一次配置默认值:
builder.Services.ConfigureHttpClientDefaults(http =>
{
http.AddServiceDiscovery();
});
https+http 方案表示按服务发现方案规则优先使用 HTTPS、回退到 HTTP。当只有 HTTP 可用时,它可能静默降级为 HTTP,因此应仅用于可接受该行为的开发环境。对于承载令牌或业务数据的生产端点,应只使用 https://。
独立运行与设备回退
对于大多数移动设备与模拟器运行,需要提供显式环境配置:
| 运行时 | 回退指引 |
|---|---|
| Android 模拟器 | 不使用 Aspire 服务发现时,用 10.0.2.2 指向宿主机 API |
| iOS 仿真器 | localhost 通常解析到 Mac 宿主机 |
| 桌面目标 | localhost 解析到同一台机器 |
| 物理设备 | 使用局域网主机名/IP、开发隧道、反向代理或已部署端点 |
不要把仅适用于模拟器的地址硬编码进生产配置。
开发证书与明文
- 优先使用 HTTPS 与受信任的开发证书。
- 若本地开发需要 HTTP,添加仅限调试的明文例外。
- 优先安装/信任开发证书,或使用显式的仅调试 HTTP 回退,而不是绕过证书校验的代码。不要在生成的应用指引中展示 DangerousAcceptAnyServerCertificateValidator 片段。
- 记录应用在 AppHost 下启动与直接设备部署两种方式。
- 避免在生产代码中全局禁用证书验证。
认证
- 复用应用的认证服务与类型化 HttpClient 处理器来附加令牌。
- OAuth 重定向 URI 需按平台区分;Aspire 服务发现不替代原生认证回调设置。
- 对于本地认证服务,确保模拟器/仿真器的重定向与回调 URL 与身份提供方配置匹配。
验证清单
- MAUI 应用已注册服务发现或生成的服务默认值。
- 类型化客户端在 AppHost 下启动时使用 Aspire 服务名。
- 独立运行的回退地址具备平台感知,且不作为生产默认值。
- HTTPS/开发证书或仅调试明文行为有明确说明。
- 认证与 API 客户端通过 DI 连接,而非页面级代码。