Aspire.Hosting.Maui 13.1.0-preview.1.25616.3

Prefix Reserved
.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher.
This is a prerelease version of Aspire.Hosting.Maui. 
dotnet add package Aspire.Hosting.Maui --version 13.1.0-preview.1.25616.3
                    


                    

                
NuGet\Install-Package Aspire.Hosting.Maui -Version 13.1.0-preview.1.25616.3
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Aspire.Hosting.Maui" Version="13.1.0-preview.1.25616.3" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="Aspire.Hosting.Maui" Version="13.1.0-preview.1.25616.3" />
                    


                            Directory.Packages.props
                        

                    

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


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add Aspire.Hosting.Maui --version 13.1.0-preview.1.25616.3
                    


                    

                
#r "nuget: Aspire.Hosting.Maui, 13.1.0-preview.1.25616.3"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package Aspire.Hosting.Maui@13.1.0-preview.1.25616.3
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=Aspire.Hosting.Maui&version=13.1.0-preview.1.25616.3&prerelease
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=Aspire.Hosting.Maui&version=13.1.0-preview.1.25616.3&prerelease
                    


                            Install as a Cake Tool

Aspire.Hosting.Maui

This library provides support for running .NET MAUI applications within an Aspire application model. It enables local development and debugging of MAUI apps alongside other services in your distributed application.

Getting Started

Adding a MAUI Application

Add a MAUI project to your Aspire app host:

var builder = DistributedApplication.CreateBuilder(args);

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

Adding Platform Targets

Add specific platform targets for your MAUI application:

// Windows
mauiApp.AddWindowsDevice();

// macOS Catalyst
mauiApp.AddMacCatalystDevice();

// iOS Simulator
mauiApp.AddiOSSimulator();

// iOS Device
mauiApp.AddiOSDevice();

// Android Device
mauiApp.AddAndroidDevice();

// Android Emulator
mauiApp.AddAndroidEmulator();

You can optionally specify custom names and device/simulator IDs:

mauiApp.AddWindowsDevice("my-windows-app");

// iOS with specific simulator UDID
mauiApp.AddiOSSimulator("iphone-15-sim", "E25BBE37-69BA-4720-B6FD-D54C97791E79");

// iOS with specific device UDID (requires device provisioning)
mauiApp.AddiOSDevice("my-iphone", "00008030-001234567890123A");

// Android with specific emulator
mauiApp.AddAndroidEmulator("pixel-7-emulator", "Pixel_7_API_33");

// Android with specific device serial
mauiApp.AddAndroidDevice("my-pixel", "abc12345");

Note on Device/Simulator ID Validation: The iOS methods include validation to help detect common mistakes:

  • AddiOSDevice() will fail at startup if you pass a GUID-format ID (which is typical for Simulator UDIDs)
  • AddiOSSimulator() will fail at startup if you pass a non-GUID format ID (which is typical for device UDIDs)

These validation errors appear in the dashboard when you try to start the resource, making it clear if you've accidentally swapped device and simulator IDs.

OpenTelemetry Connectivity for Mobile Platforms

Mobile devices, Android emulators, and iOS simulators cannot reach localhost where the Aspire dashboard's OTLP endpoint typically runs. This library provides a simple way to configure OpenTelemetry connectivity using dev tunnels.

Using Dev Tunnel

Automatically create and configure a dev tunnel for the dashboard's OTLP endpoint. This is needed when running a .NET MAUI app on:

  • Android emulator or device
  • iOS simulator or device

You should not need this when running on Windows or Mac Catalyst (they can access localhost directly).

// Android emulator with OTLP dev tunnel
mauiApp.AddAndroidEmulator()
    .WithOtlpDevTunnel();

// iOS simulator with OTLP dev tunnel
mauiApp.AddiOSSimulator()
    .WithOtlpDevTunnel();

// iOS device with OTLP dev tunnel
mauiApp.AddiOSDevice()
    .WithOtlpDevTunnel();

When WithOtlpDevTunnel() is not added, things will still work, however tracing, metrics and telemetry data will not be complete.

This method automatically:

  • Resolves the dashboard's OTLP endpoint from configuration
  • Creates a dev tunnel for it
  • Configures the MAUI platform to use the tunneled endpoint
  • Handles all service discovery and environment variable configuration

Requirements:

  • Aspire.Hosting.DevTunnels package must be referenced
  • Dev tunnel CLI must be installed (automatic prompt if missing)
  • User must be logged in to dev tunnel service (automatic prompt if needed)

Environment Variables Set

When you configure OTLP with dev tunnel, the following environment variables are automatically set:

  • OTEL_EXPORTER_OTLP_ENDPOINT: The dev tunnel URL for the OTLP endpoint
  • OTEL_EXPORTER_OTLP_PROTOCOL: Set to grpc (standard Aspire configuration)
  • OTEL_SERVICE_NAME: The resource name
  • OTEL_RESOURCE_ATTRIBUTES: Service instance ID

Example: Complete Aspire App with MAUI

var builder = DistributedApplication.CreateBuilder(args);

// Add backend services
var apiService = builder.AddProject<Projects.ApiService>("apiservice");

// Create a dev tunnel for the API service
var apiTunnel = builder.AddDevTunnel("api-tunnel")
    .WithAnonymousAccess()
    .WithReference(apiService.GetEndpoint("https"));

// Add MAUI app with multiple platform targets
var mauiApp = builder.AddMauiProject("mauiapp", "../MauiApp/MauiApp.csproj");

// Windows - can access localhost directly
mauiApp.AddWindowsDevice()
    .WithReference(apiService);

// Android Emulator - needs dev tunnels for both API and OTLP
mauiApp.AddAndroidEmulator()
    .WithOtlpDevTunnel() // For telemetry
    .WithReference(apiService, apiTunnel); // For API calls

// Android Device - same configuration
mauiApp.AddAndroidDevice()
    .WithOtlpDevTunnel()
    .WithReference(apiService, apiTunnel);

// iOS Simulator - needs dev tunnels for both API and OTLP
mauiApp.AddiOSSimulator()
    .WithOtlpDevTunnel() // For telemetry
    .WithReference(apiService, apiTunnel); // For API calls

// iOS Device - same configuration
mauiApp.AddiOSDevice()
    .WithOtlpDevTunnel()
    .WithReference(apiService, apiTunnel);

builder.Build().Run();

Platform-Specific Notes

iOS

Finding Simulator UDIDs:

# Using simctl
/Applications/Xcode.app/Contents/Developer/usr/bin/simctl list

# Or use Xcode: Window > Devices and Simulators

Device Requirements:

Android

Finding Emulator Names:

# List all available Android virtual devices
%ANDROID_HOME%\emulator\emulator.exe -list-avds

# Or use Android Studio: Tools > Device Manager

Finding Device Serials:

# List connected Android devices
adb devices

Requirements

  • .NET 10.0 or later
  • MAUI workload must be installed: dotnet workload install maui
  • Platform-specific SDKs:
    • Windows: Windows SDK 10.0.19041.0 or later
    • macOS: Xcode with command-line tools
    • Android: Android SDK via Visual Studio or Android Studio

Feedback & Issues

Please file issues at https://github.com/dotnet/aspire/issues

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.