Интеграция .NET MAUI с Aspire

Aspire — это готовый к облаку стек для создания наблюдаемых, готовых к работе, распределенных приложений. Интеграция .NET MAUI с Aspire упрощает разработку при создании мобильных и классических приложений, которые подключаются к локальным веб-службам во время разработки.

Что такое Aspire?

Aspire предоставляет согласованный, с учетом мнения набор инструментов и шаблонов для создания и запуска распределенных приложений. Он предназначен для улучшения возможностей создания облачных приложений, предоставляя следующие возможности:

• Оркестрация: упрощённое регулирование множества служб и зависимостей
• Компоненты: предварительно созданные интеграции для общих служб и платформ
• Тулчейн: Панель разработчика для отслеживания и управления сервисами
• Обнаружение служб: автоматическая настройка для обмена данными между службами

Дополнительные сведения о Aspire см. в документации по Aspire.

Преимущества использования Aspire с .NET MAUI

Интеграция Aspire с приложениями .NET MAUI обеспечивает несколько ключевых преимуществ:

• Упрощенная конфигурация: устранение сложной конфигурации сети для конкретной платформы. Не нужно вручную обрабатывать 10.0.2.2 для Android или решать проблемы с проверкой сертификатов.
• Автоматическое обнаружение служб: приложение MAUI автоматически обнаруживает и подключается к локальным службам без жестко закодированных URL-адресов.
• Интеграция туннелей разработки: встроенная поддержка dev Tunnels в iOS и Android, что упрощает подключение мобильных эмуляторов и симуляторов к локальным службам.
• Согласованный интерфейс. Используйте одни и те же шаблоны и средства во всем стеке приложений.
• Наблюдаемые службы: отслеживайте службы с помощью панели мониторинга Aspire во время разработки.

Сравнение с традиционным подходом

Традиционно подключение приложения MAUI .NET к локальным веб-службам требует значительной настройки вручную. Вам нужно:

• Используйте разные URL-адреса для разных платформ (localhost, 10.0.2.2 и т. д.)
• Настройка параметров безопасности сети для Android
• Настройка Apple Transport Security (ATS) для iOS
• Обработка проверки сертификата для HTTPS
• Управляйте URL-адресами службы вручную в коде.

Дополнительные сведения о традиционном подходе см. в разделе "Подключение к локальным веб-службам".

Благодаря интеграции Aspire эти сложности обрабатываются автоматически, что позволяет сосредоточиться на создании приложения вместо настройки сетевого доступа.

Предпосылки

Чтобы использовать Aspire с .NET MAUI, вам потребуется:

• Пакет SDK для .NET 10 или более поздней версии
• Aspire 13 или более поздние
• Приложение .NET MAUI, предназначенное для .NET 10 или более поздней версии
• Одна или несколько веб-служб

Начало работы

Настройка интеграции Aspire с приложением .NET MAUI включает добавление двух ключевых проектов в решение:

1. Проект по умолчанию службы MAUI: предоставляет конфигурацию по умолчанию для приложения MAUI
2. App Host проект: Оркеструет службы вашего приложения и обрабатывает их обнаружение.

Создание проекта по умолчанию службы 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 и все проекты веб-службы:

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

Добавьте ссылку на хостинг-пакет Aspire для .NET MAUI.

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

Настройка узла приложения

В проекте Program.csузла приложений зарегистрируйте приложение MAUI и веб-службы:

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

В приложении MauiProgram.cs.NET MAUI настройте значения по умолчанию службы и добавьте 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приложений.

Создание клиента службы

Создайте типизированный клиент для использования веб-службы:

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 интеграция Aspire автоматически обрабатывает требования к сети для конкретной платформы. Вам больше не нужно:

• Настройка специального 10.0.2.2 адреса
• Настройка файлов конфигурации безопасности сети
• Включение чистотекстового трафика для локальной разработки

Интеграция использует туннели Dev Tunnels для обеспечения безопасного, надежного подключения между эмулятором Android и локальными службами.

Интеграция с Dev Tunnels

Dev Tunnels обеспечивает безопасный способ предоставления локальных веб-служб мобильным устройствам и эмуляторам. Интеграция Aspire автоматически:

• Создание и управление туннелями разработки для служб
• Настройка приложения 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() создает туннель Dev специально для трафика протокола OpenTelemetry (OTLP), что позволяет данным телеметрии из приложений iOS и Android достичь дашборда Aspire на вашей машине разработки. Это важно для мониторинга и отладки мобильных приложений с помощью панели мониторинга Aspire.

Дополнительные сведения о туннелях Dev см. в документации по туннелям dev.

Виндоус

В Windows подключение к локальной службе работает непосредственно через localhost, не требуя дополнительной настройки. Интеграция Aspire предоставляет согласованный API на всех платформах, но базовая реализация в Windows проста.

Запуск приложения

Чтобы запустить приложение MAUI с интеграцией Aspire, можно использовать один из следующих методов:

Visual Studio:

1. Настройте проект App Host в качестве стартового проекта
2. Запустите решение (F5 или Отладка > Начать отладку)

Командная строка:

1. Перейдите в каталог проекта узла приложений
2. Запустите dotnet run или dotnet run --project YourApp.AppHost.csproj, кроме того, вы можете использовать Aspire CLI и запустить aspire run.

VS Code:

1. Открытие папки проекта узла приложений
2. Запуск проекта с помощью отладчика .NET или терминала

При запуске хоста приложения:

• Откроется панель мониторинга Aspire, показывающая все зарегистрированные службы
• Приложение MAUI не запускается автоматически. Каждый целевой объект .NET MAUI можно запустить вручную с помощью панели мониторинга.

При запуске приложения через узел приложения:

• Все службы запускались автоматически
• Обнаружение служб настроено
• Панель мониторинга предоставляет мониторинг в режиме реального времени
• Журналы из всех служб доступны в одном месте

Мониторинг и отладка

Панель мониторинга Aspire предоставляет мощные средства для мониторинга и отладки приложения:

• Представление ресурсов: просмотр всех запущенных служб и их состояния
• Журналы: просмотр объединенных журналов из всех служб в одном месте
• Трассировки: распределенная трассировка между службами
• Метрики: мониторинг производительности и использования ресурсов

Устранение неполадок

В этом разделе рассматриваются распространенные проблемы, которые могут возникнуть при интеграции Aspire с приложениями .NET MAUI.

Отсутствующие метрики или трассировки из приложений iOS или Android

Если вы не видите данные телеметрии (метрики, трассировки или журналы) от ваших iOS или Android приложений на панели мониторинга Aspire, проверьте, что метод WithOtlpDevTunnel() добавлен в конфигурацию вашего устройства в узле хоста приложений.

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

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

Этот метод WithOtlpDevTunnel() создает туннель Dev Tunnel, предназначенный специально для трафика протокола OpenTelemetry (OTLP), который необходим для передачи данных телеметрии от мобильных устройств к вашей рабочей машине. Без этого приложения iOS и Android не смогут отправлять данные телеметрии на панель мониторинга Aspire.

Обнаружение служб не работает

Если приложение MAUI не может подключиться к веб-службам:

1. Убедитесь, что вы вызвали AddServiceDefaults() в приложении MAUI MauiProgram.cs
2. Убедитесь, что имя службы в конфигурации клиента HTTP соответствует имени, используемому в узле приложений.
3. Убедитесь, что вы используете схему https+http:// в URL-адресе службы
4. Для iOS и Android убедитесь, что вы правильно настроили туннели разработки на узле приложений

Проблемы с подключением к туннелям разработки

Если туннели разработки не работают для iOS или Android:

1. Убедитесь, что туннель разработки настроен с анонимным доступом: .WithAnonymousAccess()
2. Убедитесь, что конфигурация устройства содержит ссылку на Dev Tunnel: .WithReference(weatherApi, publicDevTunnel)
3. Убедитесь, что параметры брандмауэра или сетевой безопасности не блокируют подключения туннеля
4. Попробуйте перезапустить хост приложения, чтобы заново создать туннели.

Ведущий процесс приложения не запускается

Если хост приложения не удается запустить:

1. Убедитесь, что все пути проекта в хосте Program.cs верны и используют относительные пути.
2. Убедитесь, что все проекты, на которые ссылается ссылка, успешно создаются самостоятельно
3. Убедитесь, что пакет SDK для .NET 10 и Aspire установлены правильно.
4. Проверьте вывод консоли хоста приложения на предмет конкретных сообщений об ошибках.

Приложение MAUI не может найти службы по умолчанию

Если приложение MAUI сообщает об ошибках, связанных с отсутствующими службами по умолчанию:

1. Убедитесь, что вы добавили ссылку на проект по умолчанию службы MAUI в файле проекта приложения MAUI
2. Убедитесь, что проект по умолчанию службы успешно выполняет сборку проекта
3. Убедитесь, что вы вызываете AddServiceDefaults() перед настройкой HTTP-клиентов

Лучшие практики

При создании приложений .NET MAUI с интеграцией Aspire:

• Использование типизированных клиентов: создание строго типизированных HTTP-клиентов для каждой службы для повышения удобства обслуживания
• Обрабатывайте ошибки корректно: сетевые операции могут завершиться ошибкой. Реализуйте правильную обработку ошибок и логику повторных попыток выполнения.
• Панель управления Aspire: используйте панель управления Aspire для отладки и мониторинга во время разработки
• Тестирование на всех платформах: хотя интеграция обрабатывает различия платформ, всегда тестируйте на целевых платформах.
• Следуйте значениям по умолчанию службы: проект по умолчанию службы предоставляет рекомендуемые шаблоны для устойчивости и телеметрии

Пример приложения

Полный рабочий пример интеграции .NET MAUI с Aspire см. в примере AspireWithMaui в репозитории Aspire.

В примере показано следующее:

• Полная структура проекта
• Регистрация и обнаружение служб
• Учет специфики платформы
• Шаблоны обработки ошибок и устойчивости

Дополнительные ресурсы

• Документация Aspire
• Обнаружение служб в Aspire
• Оркестрация Aspire
• Подключение к локальным веб-службам (традиционный подход)

Интеграция .NET MAUI с Aspire доступна в .NET MAUI 10 и более поздних версий. Сведения о подключении к локальным веб-службам в более ранних версиях см. в разделе "Подключение к локальным веб-службам".