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

[jfversluis]

Description

This PR adds Mac Catalyst platform support to Aspire's MAUI hosting capabilities, mirroring the existing Windows platform implementation and following the same patterns for consistency and maintainability.

Follow up from #12284 and #11942

Features

• Mac Catalyst device registration - Add Mac Catalyst devices using AddMacCatalystDevice() or AddMacCatalystDevice(name) for multiple instances
• Platform Validation: Automatically detects if the host OS supports macOS execution and marks resources as "Unsupported" when running on non-macOS 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

New Files

• IMauiPlatformResource.cs - Marker interface for all MAUI platform-specific resources (Windows, Android (tbd), iOS (tbd), Mac Catalyst). This interface enables uniform handling across all MAUI platforms and simplifies future platform additions.
• MauiMacCatalystExtensions.cs - Extension methods for adding Mac Catalyst devices to MAUI projects via AddMacCatalystDevice().
• MauiMacCatalystPlatformResource.cs - Resource class representing a Mac Catalyst platform instance of a MAUI project.
• MauiMacCatalystExtensionsTests.cs - Comprehensive test suite covering Mac Catalyst resource registration, configuration, and error handling.

Modified Files

• MauiWindowsPlatformResource.cs - Implements IMauiPlatformResource interface for unified platform handling.
• UnsupportedPlatformEventSubscriber.cs - Updated to use IMauiPlatformResource interface check instead of explicit type checks, simplifying logic and supporting all current and future platforms.
• Playground example - Updated AspireWithMaui to demonstrate Mac Catalyst usage alongside Windows.

Public API

namespace Aspire.Hosting;

public static class MauiMacCatalystExtensions
{
    /// <summary>
    /// Adds a Mac Catalyst device resource to run the MAUI application on the macOS platform.
    /// </summary>
    public static IResourceBuilder<MauiMacCatalystPlatformResource> AddMacCatalystDevice(
        this IResourceBuilder<MauiProjectResource> builder);

    /// <summary>
    /// Adds a Mac Catalyst device resource to run the MAUI application on the macOS platform with a specific name.
    /// </summary>
    public static IResourceBuilder<MauiMacCatalystPlatformResource> AddMacCatalystDevice(
        this IResourceBuilder<MauiProjectResource> builder,
        string name);
}

Usage Example

var builder = DistributedApplication.CreateBuilder(args);

var weatherApi = builder.AddProject("webapi", @"../AspireWithMaui.WeatherApi/AspireWithMaui.WeatherApi.csproj");

var mauiapp = builder.AddMauiProject("mauiapp", @"../AspireWithMaui.MauiClient/AspireWithMaui.MauiClient.csproj");

// Add Windows device
mauiapp.AddWindowsDevice()
    .WithReference(weatherApi);

// Add Mac Catalyst device
mauiapp.AddMacCatalystDevice()
    .WithReference(weatherApi);

builder.Build().Run();

Architecture

This PR also introduces IMauiPlatformResource, a marker interface for unified handling of all MAUI platform resources:

• IMauiPlatformResource: Marker interface implemented by all platform-specific resources (Windows, Mac Catalyst, and future iOS/Android)
• UnsupportedPlatformEventSubscriber: Simplified to use interface-based checks instead of explicit type checks, making it easier to add new platforms
• Platform Consistency: Mac Catalyst implementation mirrors Windows pattern (ProjectResource base, inline configuration, TFM validation)

Testing

• 20 comprehensive unit tests covering Mac Catalyst resource creation, naming, TFM detection, configuration, and error scenarios
• All existing MAUI tests continue to pass

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

Or

• Run remotely in PowerShell:

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

[Copilot]

Pull Request Overview

This PR adds Mac Catalyst platform support to Aspire's MAUI hosting capabilities, following the same architectural patterns as the existing Windows implementation. The implementation introduces a marker interface IMauiPlatformResource for unified handling of all MAUI platform resources, adds Mac Catalyst device registration through AddMacCatalystDevice(), and includes platform validation with automatic detection of macOS host support and TFM validation.

Key Changes:

• Added Mac Catalyst platform support with automatic TFM detection and OS validation
• Introduced IMauiPlatformResource marker interface to unify platform-specific resource handling
• Extracted common platform configuration logic into MauiPlatformHelper to reduce code duplication

Reviewed Changes

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

Show a summary per file

File	Description
MauiMacCatalystExtensions.cs	Adds extension methods for registering Mac Catalyst devices with MAUI projects
MauiMacCatalystPlatformResource.cs	Defines the Mac Catalyst platform resource class implementing IMauiPlatformResource
IMauiPlatformResource.cs	Introduces marker interface for unified handling of all MAUI platform resources
MauiPlatformHelper.cs	Provides shared helper methods for platform resource configuration
UnsupportedPlatformEventSubscriber.cs	Updated to use IMauiPlatformResource interface instead of explicit type checks
MauiWindowsPlatformResource.cs	Updated to implement IMauiPlatformResource interface
MauiWindowsExtensions.cs	Refactored to use MauiPlatformHelper for common path operations
MauiProjectResource.cs	Updated documentation to mention AddMacCatalystDevice
MauiMacCatalystExtensionsTests.cs	Comprehensive test suite for Mac Catalyst functionality
AppHost.cs	Playground example demonstrating Mac Catalyst usage

[mitchdenny]

I think make this derive from IResource or maybe even IResourceWithParent.

[jfversluis]

Addressed in commit ce2c2ef

[mitchdenny]

You don't actually need to two this check (in fact the check is not quite right). You can just add the resource to the model and it will do a uniqueness check on the name. You cannot have two resources with the same name even if they differ by type. Change this for the Windows resource too - I didn't pick it up in review last time ;)

[jfversluis]

Addressed in commit 669549a

[mitchdenny]

Approving assuming you'll address the feedback above. I cannot test on a Mac unfortunately. I think there might be an issue with restore.cmd -restore-maui it would be good if you could test that on Windows on a clean repo just to make sure its working the way you expect?

[jfversluis]

Discussed workload changes offline, @joperezr will have a look at that. Will do the other changes in the next PR.