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

[jfversluis]

Description

This PR adds support for running .NET MAUI applications on Windows devices through the Aspire app host.

After discussion with the always wonderful Aspire team about #11942, making some changes in how the MAUI integration will work. This is the first of a series of PRs, this one is adding the Windows app integration first, plus some plumbing, the rest we can add after this for shorter review cycles.

Features

• Windows Device Resources: Add Windows platform targets to MAUI projects that run via dotnet run with the appropriate target framework
• Platform Validation: Automatically detects if the host OS supports Windows execution and marks resources as "Unsupported" when running on non-Windows hosts
• Target Framework Detection: Validates that MAUI projects include a Windows target framework (e.g., net10.0-windows10.0.19041.0) and fails fast with clear error messages if missing
• Multiple Devices: Support for adding multiple Windows device resources to the same MAUI project with unique names
• Explicit Start: Windows devices require explicit user action to start (not auto-started), allowing developers to control when the app launches

Public API

namespace Aspire.Hosting;

public static class MauiProjectExtensions
{
    /// <summary>
    /// Adds a .NET MAUI project to the application model.
    /// </summary>
    public static IResourceBuilder<MauiProjectResource> AddMauiProject(
        this IDistributedApplicationBuilder builder,
        string name,
        string projectPath);
}

public static class MauiWindowsExtensions
{
    /// <summary>
    /// Adds a Windows device resource to run the MAUI application on the Windows platform.
    /// </summary>
    public static IResourceBuilder<MauiWindowsPlatformResource> AddWindowsDevice(
        this IResourceBuilder<MauiProjectResource> builder,
        string? name = null);
}

Usage Example

var builder = DistributedApplication.CreateBuilder(args);

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

var maui = builder.AddMauiProject("mauiapp", "../MyMauiApp/MyMauiApp.csproj");
var windowsDevice = maui.AddWindowsDevice()
    .WithReference(weatherApi);

builder.Build().Run();

Architecture

The implementation is structured for extensibility with upcoming iOS, Android, and macOS platform support:

• Annotations/: Shared UnsupportedPlatformAnnotation for cross-platform unsupported state handling
• Lifecycle/: Shared UnsupportedPlatformEventSubscriber for setting resource states after orchestration
• Utilities/: Reusable ProjectFileReader for detecting target frameworks across all platforms

Testing

• 11 comprehensive unit tests covering resource creation, naming, TFM detection, and error scenarios

Contributes to #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

[Copilot]

Pull Request Overview

This PR introduces initial support for running .NET MAUI applications on Windows devices through the Aspire app host. The implementation adds a new Aspire.Hosting.Maui integration package that enables developers to manage MAUI apps alongside their other Aspire-orchestrated services, with Windows being the first supported platform. The PR establishes foundational architecture (utilities, annotations, lifecycle management) that will support additional platforms (iOS, Android, macOS) in future PRs.

Key Changes:

• New Aspire.Hosting.Maui package with Windows device integration
• Platform detection and validation infrastructure
• Comprehensive test coverage (11 unit tests)
• Sample playground demonstrating MAUI + Aspire integration

Reviewed Changes

Copilot reviewed 64 out of 72 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/Aspire.Hosting.Maui/MauiProjectResourceExtensions.cs	Adds AddMauiProject extension method to register MAUI projects in the app model
src/Aspire.Hosting.Maui/MauiWindowsExtensions.cs	Implements AddWindowsDevice extension with TFM validation and platform detection
src/Aspire.Hosting.Maui/MauiProjectResource.cs	Defines parent resource that contains platform-specific device collections
src/Aspire.Hosting.Maui/MauiWindowsPlatformResource.cs	Represents a Windows platform instance derived from ExecutableResource
src/Aspire.Hosting.Maui/Utilities/ProjectFileReader.cs	Utility for parsing project files to detect target frameworks
src/Aspire.Hosting.Maui/Annotations/UnsupportedPlatformAnnotation.cs	Annotation marking resources as unsupported on current host platform
src/Aspire.Hosting.Maui/Lifecycle/UnsupportedPlatformEventSubscriber.cs	Sets "Unsupported" state for resources with unsupported platform annotation
tests/Aspire.Hosting.Maui.Tests/MauiWindowsExtensionsTests.cs	11 comprehensive tests covering resource creation, naming, TFM detection, and error scenarios
playground/AspireWithMaui/*	Complete sample application demonstrating MAUI + Aspire integration with Weather API
eng/Build.props	Excludes MAUI client from standard build to avoid MAUI workload requirement
.github/CODEOWNERS	Adds @jfversluis as code owner for MAUI integration

[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://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 12284

Or

• Run remotely in PowerShell:

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

[davidfowl]

When you build a custom resource, you need implement all of the life cycle and behavior, is that what you want?

[mitchdenny]

Think of this as a root resource, the add AddWindows(...) call will be the real project resource.

[davidfowl]

This is gonna force install the maui workload on build by default?

[mitchdenny]

Step one. Quantify the impact.

I suspect it might not even work on the build agents.

[jfversluis]

Yes, see #12284 (comment) talked about it with Mitch who says: lets try it and see what it does for build times.

[davidfowl]

It's not just about build times, it's about disrupting everyone else working on aspire for one project 😄. The node and python samples go out of their way to skip if nothing is installed.

[joperezr]

I'm not so sure about this change. With SDK workloads, you want to be careful when you add dependencies to feeds that have unreleased versions of workloads or workload sets, as that can potentially put your machine in a torn state if a version is picked up and it depends on something else that is not part of the feed.

IMO we should probably consider reverting this particular feed, and instead see if there is a way to have the SDK team push only released versions into dotnet-public to prevent the above.

cc: @marcpopMSFT in case anything I said above is wrong.

[joperezr]

This will not always be true, as there are cases where the machine-wide version matches the version in global.json then the build won't create a local .dotnet folder. Instead, this script should be calling the dotnet.cmd or dotnet.sh scripts in the root of the repo which will resolve to the right place always.

cc: @jfversluis

[joperezr]

@jfversluis is the plan to also add a github workflow or something that is protecting this part of the script and ensuring it doesn't get broken? We should have some sort of protection by having a job that restores the workload and tries to build the maui playground project.