.NET MAUI 与 Aspire 的集成

重要

此功能目前处于预览状态。某些功能仍在实施中，并且尚未完全提供与 Visual Studio 2026 的集成。

Aspire 是一个有意见的、云就绪的堆栈，用于生成可观察的、生产就绪的分布式应用程序。 .NET MAUI 与 Aspire 的集成简化了开发体验，在开发过程中生成连接到本地 Web 服务的移动和桌面应用程序。

什么是 Aspire？

Aspire 提供了一组一致的、有意见的工具和模式，用于生成和运行分布式应用程序。它旨在通过提供以下功能来改进生成云原生应用程序的体验：

编排：简化多个服务和依赖关系的管理
组件：通用服务和平台的预构建集成
工具：用于监视和管理服务的开发人员仪表板
服务发现：服务到服务通信的自动配置

有关 Aspire 的详细信息，请参阅 Aspire 文档。

将 Aspire 与 .NET MAUI 配合使用的好处

将 Aspire 与 .NET MAUI 应用程序集成可提供几个关键优势：

简化的配置：消除复杂的特定于平台的网络配置。无需手动处理 10.0.2.2 Android 或处理证书验证问题。
自动服务发现：MAUI 应用会自动发现并连接到本地服务，而无需硬编码 URL。
开发隧道集成：对 iOS 和 Android 上的开发隧道的内置支持，使移动模拟器和模拟器可以轻松连接到本地服务。
一致的体验：在整个应用程序堆栈中使用相同的模式和工具。
可观察的服务：在开发过程中通过 Aspire 仪表板监视服务。

与传统方法的比较

传统上，将 .NET MAUI 应用连接到本地 Web 服务需要大量的手动配置。你需要：

将不同的 URL 用于不同的平台（localhost、10.0.2.2 等）
为 Android 配置网络安全设置
为 iOS 设置 Apple Transport Security （ATS）
处理 HTTPS 的证书验证
在代码中手动管理服务网址

有关传统方法的详细信息，请参阅 “连接到本地 Web 服务”。

通过 Aspire 集成，这些复杂性会自动处理，使你能够专注于构建应用程序，而不是配置网络访问。

先决条件

若要将 Aspire 与 .NET MAUI 配合使用，需要：

.NET 10 SDK 或更高版本
Aspire 13 或更高版本
面向 .NET 10 或更高版本的 .NET MAUI 应用
一个或多个 Web 服务

入门指南

将 Aspire 与 .NET MAUI 应用程序集成涉及将两个关键项目添加到您的解决方案中：

MAUI 服务默认值项目：为 MAUI 应用提供默认配置
应用主机项目：协调应用程序服务并处理服务发现

创建 MAUI 服务默认值项目

MAUI 服务默认值项目包含 MAUI 应用程序用于连接到服务的共享配置。在解决方案目录中创建此项目：

dotnet new maui-aspire-servicedefaults -n YourApp.MauiServiceDefaults

将项目添加到解决方案：

dotnet sln add YourApp.MauiServiceDefaults/YourApp.MauiServiceDefaults.csproj

此项目包括：

服务发现配置
默认复原模式
遥测设置
特定于平台的网络配置

在 .NET MAUI 应用项目中添加对该项目的引用：

dotnet add YourMauiApp.csproj reference YourApp.MauiServiceDefaults/YourApp.MauiServiceDefaults.csproj

创建应用主机项目

应用主机项目协调所有应用程序服务，包括 MAUI 应用和任何后端服务。在解决方案目录中创建此项目：

dotnet new aspire-apphost -n YourApp.AppHost

将项目添加到解决方案：

dotnet sln add YourApp.AppHost/YourApp.AppHost.csproj

将引用添加到您的 MAUI 应用程序和任何 Web 服务项目中：

dotnet add YourApp.AppHost.csproj reference YourMauiApp/YourMauiApp.csproj
dotnet add YourApp.AppHost.csproj reference YourWebService/YourWebService.csproj

添加对 .NET MAUI 的 Aspire 托管套餐的引用：

dotnet add package Aspire.Hosting.Maui --version 13.0.0-preview.1.25560.3 --project .\YourApp.AppHost\YourApp.AppHost.csproj

注释

现在，需要使用 Aspire.Hosting.Maui 包的预览版。

配置应用主机

在您的应用主机项目的 Program.cs 中，注册 MAUI 应用程序和 Web 服务：

var builder = DistributedApplication.CreateBuilder(args);

// Register your web service
var weatherApi = builder.AddProject("webapi", @"../YourWebService/YourWebService.csproj");

// Create a public dev tunnel for iOS and Android
var publicDevTunnel = builder.AddDevTunnel("devtunnel-public")
    .WithAnonymousAccess()
    .WithReference(weatherApi.GetEndpoint("https"));

// Register your MAUI app
var mauiapp = builder.AddMauiProject("mauiapp", @"../YourMauiApp/YourMauiApp.csproj");

// Add Windows device (uses localhost directly)
mauiapp.AddWindowsDevice()
    .WithReference(weatherApi);

// Add Mac Catalyst device (uses localhost directly)
mauiapp.AddMacCatalystDevice()
    .WithReference(weatherApi);

// Add iOS simulator with Dev Tunnel
mauiapp.AddiOSSimulator()
    .WithOtlpDevTunnel() // Required for OpenTelemetry data collection
    .WithReference(weatherApi, publicDevTunnel);

// Add Android emulator with Dev Tunnel
mauiapp.AddAndroidEmulator()
    .WithOtlpDevTunnel() // Required for OpenTelemetry data collection
    .WithReference(weatherApi, publicDevTunnel);

builder.Build().Run();

注释

可以为同一 MAUI 项目添加多个 Windows、Mac Catalyst、iOS 或 Android 仿真器或设备。每个设备配置都可以面向不同的平台，允许你从同一应用主机同时在多个目标上部署和测试应用。例如，可以添加 iOS 模拟器和物理 iOS 设备，或具有不同配置的多个 Android 仿真器。

配置 MAUI 应用

在 .NET MAUI 应用中 MauiProgram.cs，配置服务默认值并添加 HTTP 客户端：

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();

        builder
            .UseMauiApp<App>()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
            });

        // Add service defaults
        builder.AddServiceDefaults();

        // Configure HTTP client with service discovery
        builder.Services.AddHttpClient<WeatherApiClient>(client =>
        {
            // Service name matches the name used in App Host
            client.BaseAddress = new Uri("https+http://webapi");
        });

        return builder.Build();
    }
}

方案 https+http:// 是启用 HTTPS 和 HTTP 协议的特殊语法，优先使用 HTTPS。服务名称（webapi 在此示例中）必须与在应用主机 Program.cs中注册服务时使用的名称匹配。

创建服务客户端

创建类型化客户端以使用 Web 服务：

public class WeatherApiClient
{
    private readonly HttpClient _httpClient;

    public WeatherApiClient(HttpClient httpClient)
    {
        _httpClient = httpClient;
    }

    public async Task<WeatherForecast[]?> GetWeatherForecastAsync(CancellationToken cancellationToken = default)
    {
        return await _httpClient.GetFromJsonAsync<WeatherForecast[]>(
            "/weatherforecast",
            cancellationToken);
    }
}

public record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC * 1.8);
}

在应用中使用客户端

在页面或视图模型中注入并使用客户端：

public partial class MainPage : ContentPage
{
    private readonly WeatherApiClient _weatherClient;

    public MainPage(WeatherApiClient weatherClient)
    {
        _weatherClient = weatherClient;
        InitializeComponent();
    }

    private async void OnGetWeatherClicked(object sender, EventArgs e)
    {
        try
        {
            var forecasts = await _weatherClient.GetWeatherForecastAsync();

            if (forecasts != null)
            {
                // Display the weather data
                ResultLabel.Text = $"Retrieved {forecasts.Length} forecasts";
            }
        }
        catch (Exception ex)
        {
            ResultLabel.Text = $"Error: {ex.Message}";
        }
    }
}

特定于平台的注意事项

iOS 和 Mac Catalyst

在 iOS 和 Mac Catalyst 上，Aspire 集成在通过应用主机运行应用时无缝工作。服务发现配置自动提供正确的 URL 以连接到本地服务。

使用 iOS 模拟器或在物理设备上运行时，开发隧道会自动配置为启用与开发计算机上运行的服务的连接。

Android

在 Android 上，Aspire 集成会自动处理特定于平台的网络要求。不再需要：

配置特殊 10.0.2.2 地址
设置网络安全配置文件
启用用于本地开发的明文流量

集成使用 Dev Tunnels 在 Android 模拟器和本地服务之间提供安全可靠的连接。

Dev Tunnels 集成

开发隧道提供了一种安全的方法，用于向移动设备和模拟器公开本地 Web 服务。 Aspire 集成自动：

为您的服务创建和管理开发隧道 (Dev Tunnels)
将 MAUI 应用配置为使用隧道 URL
处理身份验证和连接管理

这样就无需复杂的网络配置，并可以轻松地在物理设备上测试应用。

OpenTelemetry 数据收集

在应用主机中配置 iOS 和 Android 设备时，请使用 WithOtlpDevTunnel() 此方法从以下平台启用 OpenTelemetry 数据收集：

mauiapp.AddiOSSimulator()
    .WithOtlpDevTunnel() // Required for OpenTelemetry data collection
    .WithReference(weatherApi, publicDevTunnel);

mauiapp.AddAndroidEmulator()
    .WithOtlpDevTunnel() // Required for OpenTelemetry data collection
    .WithReference(weatherApi, publicDevTunnel);

该方法 WithOtlpDevTunnel() 专门为 OpenTelemetry 协议（OTLP）流量创建开发隧道，允许 iOS 和 Android 应用中的遥测数据访问开发计算机上的 Aspire 仪表板。这对于通过 Aspire 仪表板监视和调试移动应用至关重要。

有关开发隧道的详细信息，请参阅开发隧道文档。

Windows操作系统

在 Windows 上，本地服务连接直接通过 localhost 工作，而无需其他配置。 Aspire 集成在所有平台上提供一致的 API，但 Windows 上的基础实现非常简单。

运行应用程序

若要使用 Aspire 集成运行 MAUI 应用，可以使用以下方法之一：

Visual Studio：

将应用主机项目设置为启动项目
运行解决方案（F5 或调试 > 开始调试）

命令行：

导航到应用主机项目目录
运行dotnet run 或者 dotnet run --project YourApp.AppHost.csproj，或者您也可以使用 Aspire CLI 并运行aspire run。

VS Code：

打开“应用主机”项目文件夹
使用 .NET 调试器或终端运行项目

应用主机启动时：

Aspire 仪表板将打开，显示所有已注册的服务
MAUI 应用不会自动启动。可以通过仪表板手动启动每个 .NET MAUI 目标。

通过应用主机运行应用程序时：

所有服务自动启动
服务发现已完成配置
仪表板提供实时监视
所有服务的日志可在一个位置使用

监视和调试

Aspire 仪表板提供强大的工具来监视和调试应用程序：

资源视图：查看所有正在运行的服务及其状态
日志：在一个位置查看所有服务的组合日志
跟踪：跨服务分布式跟踪
指标：监视性能和资源使用情况

Troubleshooting

本部分介绍将 Aspire 与 .NET MAUI 应用程序集成时可能会遇到的常见问题。

iOS/Android 应用中缺少指标或跟踪

如果在 Aspire 控制台中看不到 iOS 或 Android 应用的遥测数据（指标、跟踪或日志），请确认是否已将 WithOtlpDevTunnel() 方法添加到 App Host 的设备配置中：

mauiapp.AddiOSSimulator()
    .WithOtlpDevTunnel() // Required for OpenTelemetry data collection
    .WithReference(weatherApi, publicDevTunnel);

mauiapp.AddAndroidEmulator()
    .WithOtlpDevTunnel() // Required for OpenTelemetry data collection
    .WithReference(weatherApi, publicDevTunnel);

该方法 WithOtlpDevTunnel() 专门创建一个用于 OpenTelemetry 协议（OTLP）流量的开发隧道，以便移动设备的遥测数据可以传输到您的开发计算机。如果没有此功能，iOS 和 Android 应用将无法将其遥测数据发送到 Aspire 仪表板。

服务发现不起作用

如果 MAUI 应用无法连接到 Web 服务：

验证是否已在 MAUI 应用中调用AddServiceDefaults()MauiProgram.cs
确保 HTTP 客户端配置中的服务名称与应用主机中使用的名称匹配
请检查你在你的服务 URL 中使用的架构。
对于 iOS 和 Android，请确认已在应用主机中正确配置了开发隧道

开发隧道（Dev Tunnels）连接问题

如果 Dev Tunnels 无法在 iOS 或 Android 上运行：

确保开发隧道配置了匿名访问： .WithAnonymousAccess()
验证设备配置是否包含 Dev Tunnel 引用： .WithReference(weatherApi, publicDevTunnel)
检查防火墙或网络安全设置是否未阻止隧道连接
尝试重启应用主机以重新创建隧道

应用主机不会启动

如果应用主机无法启动：

确保应用主机 Program.cs 中的所有项目路径都正确，并使用相对路径
验证所有引用的项目是否都自行成功生成
检查是否已正确安装 .NET 10 SDK 和 Aspire
查看应用主机控制台输出以获取特定错误消息

MAUI 应用找不到服务默认值

如果 MAUI 应用报告有关缺少服务默认值的错误：

验证是否已在 MAUI 应用的项目文件中添加了对 MAUI 服务默认值项目的引用
确保服务默认值项目生成成功
在配置 HTTP 客户端之前，请检查你是否正在调用AddServiceDefaults()

最佳做法

使用 Aspire 集成生成 .NET MAUI 应用时：

使用类型化客户端：为每个服务创建强类型 HTTP 客户端以提高可维护性
优雅地处理错误：网络操作可能失败，需实现正确的错误处理和重试逻辑
利用仪表盘：在开发过程中使用 Aspire 仪表盘进行调试和监控
在所有平台上进行测试：虽然集成处理平台差异，但始终在目标平台上进行测试
遵循服务默认值：服务默认值项目为复原和遥测提供建议的模式

示例应用程序

有关 .NET MAUI 与 Aspire 集成的完整工作示例，请参阅 Aspire 存储库中的 AspireWithMaui 示例。

此示例演示：

完成项目结构
服务注册和发现
特定于平台的注意事项
错误处理和复原模式

其他资源

.NET MAUI 与 Aspire 的集成在 .NET MAUI 10 及更高版本中提供。有关在早期版本中连接到本地 Web 服务的信息，请参阅 “连接到本地 Web 服务”。

反馈

此页面是否有帮助？

Last updated on 2025-11-11