.NET MAUI integration

Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.

This article is the reference for the Aspire .NET MAUI integration. It documents the AppHost APIs you use to orchestrate .NET MAUI mobile and desktop applications in your AppHost project, and shows how to configure .NET MAUI apps to discover and connect to Aspire-managed services.

Prerequisites

To use the .NET MAUI integration with Aspire, you need:

.NET 10 SDK or later.
Aspire 13 or later.
A .NET MAUI app targeting .NET 10 or later.

Hosting integration

The .NET MAUI hosting integration is distributed via the 📦 Aspire.Hosting.Maui NuGet package. It enables you to orchestrate .NET MAUI applications in your AppHost project and register platform-specific device configurations.

Installation

To add the .NET MAUI hosting integration to your AppHost, install the 📦 Aspire.Hosting.Maui NuGet package:

aspire add maui

Learn more about aspire add in the command reference.

Or, choose a manual installation approach:

#:package Aspire.Hosting.Maui@*

<PackageReference Include="Aspire.Hosting.Maui" Version="*" />

Add .NET MAUI project

To orchestrate a .NET MAUI application in your AppHost, call AddMauiProject with the name and path to the .csproj file:

var builder = DistributedApplication.CreateBuilder(args);

var weatherApi = builder.AddProject<Projects.WeatherApi>("webapi");

var mauiapp = builder.AddMauiProject("mauiapp", "../YourMauiApp/YourMauiApp.csproj");

// Add platform-specific device configurations here...

builder.Build().Run();

Platform-specific device configurations

Each target platform requires a specific device configuration chained from the MAUI project resource:

Windows apps run directly on the host machine using localhost:

mauiapp.AddWindowsDevice()
    .WithReference(weatherApi);

Mac Catalyst apps also use localhost directly on macOS:

mauiapp.AddMacCatalystDevice()
    .WithReference(weatherApi);

iOS Simulator requires Dev Tunnels to connect to local services:

var publicDevTunnel = builder.AddDevTunnel("devtunnel-public")
    .WithAnonymousAccess()
    .WithReference(weatherApi.GetEndpoint("https"));

mauiapp.AddiOSSimulator()
    .WithOtlpDevTunnel()
    .WithReference(weatherApi, publicDevTunnel);

Android Emulator also requires Dev Tunnels for connectivity:

mauiapp.AddAndroidEmulator()
    .WithOtlpDevTunnel()
    .WithReference(weatherApi, publicDevTunnel);

On Windows and Mac Catalyst, local service connectivity works directly through localhost without requiring Dev Tunnels. iOS Simulator and Android Emulator require Dev Tunnels; the WithOtlpDevTunnel() method creates a Dev Tunnel specifically for OpenTelemetry Protocol (OTLP) traffic so telemetry from mobile targets reaches the Aspire dashboard.

Complete AppHost example

The following example shows all platform configurations together in a single AppHost:

var builder = DistributedApplication.CreateBuilder(args);

var weatherApi = builder.AddProject<Projects.WeatherApi>("webapi");

var publicDevTunnel = builder.AddDevTunnel("devtunnel-public")
    .WithAnonymousAccess()
    .WithReference(weatherApi.GetEndpoint("https"));

var mauiapp = builder.AddMauiProject("mauiapp", "../YourMauiApp/YourMauiApp.csproj");

mauiapp.AddWindowsDevice()
    .WithReference(weatherApi);

mauiapp.AddMacCatalystDevice()
    .WithReference(weatherApi);

mauiapp.AddiOSSimulator()
    .WithOtlpDevTunnel()
    .WithReference(weatherApi, publicDevTunnel);

mauiapp.AddAndroidEmulator()
    .WithOtlpDevTunnel()
    .WithReference(weatherApi, publicDevTunnel);

builder.Build().Run();

Configure the .NET MAUI app

To configure your .NET MAUI app to discover and connect to Aspire-managed services:

Create a MAUI Service Defaults project.
Reference it from your MAUI app.
Configure service defaults in your MAUI app.

Create a MAUI Service Defaults project

The MAUI Service Defaults project contains shared configuration for your MAUI app, including service discovery, resilience, and telemetry setup:

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

Add a reference to this project from your MAUI app:

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

Configure your MAUI app

In your MauiProgram.cs, add service defaults and configure HTTP clients:

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");
            });

        builder.AddServiceDefaults();

        builder.Services.AddHttpClient<WeatherApiClient>(client =>
        {
            client.BaseAddress = new Uri("https+http://webapi");
        });

        return builder.Build();
    }
}

Create a typed client

Create a strongly-typed HTTP client to consume your web service:

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);
}

Use the client in your app

Inject and use the client in your pages or view models:

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 is not null)
            {
                ResultLabel.Text = $"Retrieved {forecasts.Length} forecasts";
            }
        }
        catch (Exception ex)
        {
            ResultLabel.Text = $"Error: {ex.Message}";
        }
    }
}