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