SuperAPI AI 工具集

maui-aspire-client

编程与开发

查看项目

更新于 10-16 10:54

技能介绍

用途

当 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 连接,而非页面级代码。