From bc84c9403493f093f7def80f44d4807d3655f0ef Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Mon, 17 Nov 2025 14:15:57 +0100 Subject: [PATCH 1/3] Add MAUI integration docs --- src/frontend/sidebar.topics.ts | 1 + .../docs/integrations/frameworks/maui.mdx | 397 ++++++++++++++++++ src/frontend/src/data/integration-docs.json | 4 + 3 files changed, 402 insertions(+) create mode 100644 src/frontend/src/content/docs/integrations/frameworks/maui.mdx diff --git a/src/frontend/sidebar.topics.ts b/src/frontend/sidebar.topics.ts index efd16a37..b5b6d5e4 100644 --- a/src/frontend/sidebar.topics.ts +++ b/src/frontend/sidebar.topics.ts @@ -864,6 +864,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { label: 'Deno apps', slug: 'integrations/frameworks/deno-apps' }, { label: 'Go apps', slug: 'integrations/frameworks/go-apps' }, { label: 'Java', slug: 'integrations/frameworks/java' }, + { label: '.NET MAUI', slug: 'integrations/frameworks/maui' }, { label: 'Orleans', slug: 'integrations/frameworks/orleans' }, { label: 'Python', slug: 'integrations/frameworks/python' }, { label: 'Rust', slug: 'integrations/frameworks/rust' }, diff --git a/src/frontend/src/content/docs/integrations/frameworks/maui.mdx b/src/frontend/src/content/docs/integrations/frameworks/maui.mdx new file mode 100644 index 00000000..2e252927 --- /dev/null +++ b/src/frontend/src/content/docs/integrations/frameworks/maui.mdx @@ -0,0 +1,397 @@ +--- +title: .NET MAUI integration +description: Learn how to integrate .NET MAUI mobile and desktop applications with Aspire for simplified service orchestration and discovery. +--- + +import { Aside, Code, Tabs, TabItem } from '@astrojs/starlight/components'; + + + +The .NET MAUI integration with Aspire simplifies the development experience when building mobile and desktop applications that connect to local web services during development. This integration enables you to orchestrate your .NET MAUI apps alongside your backend services using Aspire's powerful orchestration capabilities. + +## What is .NET MAUI? + +.NET Multi-platform App UI (.NET MAUI) is a cross-platform framework for creating native mobile and desktop apps with C# and XAML. With .NET MAUI, you can develop apps that run on Android, iOS, macOS, and Windows from a single shared codebase. + +## Benefits of using Aspire with .NET MAUI + +Integrating Aspire with your .NET MAUI applications provides several key benefits: + +- **Simplified configuration**: Eliminate complex platform-specific networking configuration. No need to manually handle `10.0.2.2` for Android or deal with certificate validation issues. +- **Automatic service discovery**: Your MAUI app automatically discovers and connects to local services without hardcoded URLs. +- **Development tunnels integration**: Built-in support for Dev Tunnels on iOS and Android, making it easy to connect mobile emulators and simulators to local services. +- **Consistent experience**: Use the same patterns and tools across your entire application stack. +- **Observable services**: Monitor your services through the Aspire dashboard during development. + +### Comparison with traditional approach + +Traditionally, connecting a .NET MAUI app to local web services requires significant manual configuration: + +- Use different URLs for different platforms (localhost, 10.0.2.2, etc.) +- Configure network security settings for Android +- Set up Apple Transport Security (ATS) for iOS +- Handle certificate validation for HTTPS +- Manually manage service URLs in your code + +With Aspire integration, these complexities are handled automatically, allowing you to focus on building your application instead of configuring network access. + +## Prerequisites + +To use Aspire with .NET MAUI, you need: + +- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) or later +- [Aspire 13](/get-started/) or later +- A .NET MAUI app targeting .NET 10 or later +- One or more web services to connect to + +## Hosting integration + +The MAUI hosting integration is distributed via the [Aspire.Hosting.Maui](https://www.nuget.org/packages/Aspire.Hosting.Maui) NuGet package and enables you to orchestrate .NET MAUI applications in your App Host project. + +### Register MAUI project + +To register a MAUI project in your App Host, install the `Aspire.Hosting.Maui` package and use the `AddMauiProject` extension method: + +```csharp +var builder = DistributedApplication.CreateBuilder(args); + +// Register your backend service +var weatherApi = builder.AddProject("webapi"); + +// Register your MAUI app +var mauiapp = builder.AddMauiProject("mauiapp", @"../YourMauiApp/YourMauiApp.csproj"); + +builder.Build().Run(); +``` + +### Platform-specific device configurations + +The MAUI integration supports multiple platforms. Each platform requires a specific device configuration: + +#### Windows + +Windows apps run directly on the host machine using localhost: + +```csharp +mauiapp.AddWindowsDevice() + .WithReference(weatherApi); +``` + +#### Mac Catalyst + +Mac Catalyst apps also use localhost directly on macOS: + +```csharp +mauiapp.AddMacCatalystDevice() + .WithReference(weatherApi); +``` + +#### iOS Simulator + +iOS Simulator requires Dev Tunnels to connect to local services: + +```csharp +// Create a public dev tunnel for mobile platforms +var publicDevTunnel = builder.AddDevTunnel("devtunnel-public") + .WithAnonymousAccess() + .WithReference(weatherApi.GetEndpoint("https")); + +// Add iOS simulator with Dev Tunnel +mauiapp.AddiOSSimulator() + .WithOtlpDevTunnel() // Required for OpenTelemetry data collection + .WithReference(weatherApi, publicDevTunnel); +``` + +#### Android Emulator + +Android Emulator also requires Dev Tunnels for connectivity: + +```csharp +mauiapp.AddAndroidEmulator() + .WithOtlpDevTunnel() // Required for OpenTelemetry data collection + .WithReference(weatherApi, publicDevTunnel); +``` + +### Complete App Host example + +Here's a complete example showing all platform configurations: + +```csharp +var builder = DistributedApplication.CreateBuilder(args); + +// Register your web service +var weatherApi = builder.AddProject("webapi"); + +// Create a public dev tunnel for iOS and Android +var publicDevTunnel = builder.AddDevTunnel("devtunnel-public") + .WithAnonymousAccess() + .WithReference(weatherApi.GetEndpoint("https")); + +// Register your MAUI app +var mauiapp = builder.AddMauiProject("mauiapp", @"../YourMauiApp/YourMauiApp.csproj"); + +// Add Windows device (uses localhost directly) +mauiapp.AddWindowsDevice() + .WithReference(weatherApi); + +// Add Mac Catalyst device (uses localhost directly) +mauiapp.AddMacCatalystDevice() + .WithReference(weatherApi); + +// Add iOS simulator with Dev Tunnel +mauiapp.AddiOSSimulator() + .WithOtlpDevTunnel() // Required for OpenTelemetry data collection + .WithReference(weatherApi, publicDevTunnel); + +// Add Android emulator with Dev Tunnel +mauiapp.AddAndroidEmulator() + .WithOtlpDevTunnel() // Required for OpenTelemetry data collection + .WithReference(weatherApi, publicDevTunnel); + +builder.Build().Run(); +``` + + + +## Client configuration + +To configure your .NET MAUI app to work with Aspire, you need to: + +1. Create a MAUI Service Defaults project +2. Reference it from your MAUI app +3. Configure service defaults in your MAUI app + +### Create a MAUI Service Defaults project + +The MAUI Service Defaults project contains shared configuration for your MAUI app: + +```bash +dotnet new maui-aspire-servicedefaults -n YourApp.MauiServiceDefaults +``` + +This project includes: +- Service discovery configuration +- Default resilience patterns +- Telemetry setup +- Platform-specific networking configuration + +Add a reference to this project from your MAUI app: + +```bash +dotnet add YourMauiApp.csproj reference YourApp.MauiServiceDefaults/YourApp.MauiServiceDefaults.csproj +``` + +### Configure your MAUI app + +In your `MauiProgram.cs`, add service defaults and configure HTTP clients: + +```csharp +using Microsoft.Extensions.Configuration; +using Microsoft.Extensions.Hosting; + +public static class MauiProgram +{ + public static MauiApp CreateMauiApp() + { + var builder = MauiApp.CreateBuilder(); + + builder + .UseMauiApp() + .ConfigureFonts(fonts => + { + fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular"); + fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold"); + }); + + // Add service defaults + builder.Services.AddServiceDefaults(); + + // Configure HTTP client with service discovery + builder.Services.AddHttpClient(client => + { + // Service name matches the name used in App Host + client.BaseAddress = new Uri("https+http://webapi"); + }); + + return builder.Build(); + } +} +``` + + + +### Create a typed client + +Create a strongly-typed HTTP client to consume your web service: + +```csharp +public class WeatherApiClient +{ + private readonly HttpClient _httpClient; + + public WeatherApiClient(HttpClient httpClient) + { + _httpClient = httpClient; + } + + public async Task GetWeatherForecastAsync( + CancellationToken cancellationToken = default) + { + return await _httpClient.GetFromJsonAsync( + "/weatherforecast", + cancellationToken); + } +} + +public record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary) +{ + public int TemperatureF => 32 + (int)(TemperatureC / 0.5556); +} +``` + +### Use the client in your app + +Inject and use the client in your pages or view models: + +```csharp +public partial class MainPage : ContentPage +{ + private readonly WeatherApiClient _weatherClient; + + public MainPage(WeatherApiClient weatherClient) + { + _weatherClient = weatherClient; + InitializeComponent(); + } + + private async void OnGetWeatherClicked(object sender, EventArgs e) + { + try + { + var forecasts = await _weatherClient.GetWeatherForecastAsync(); + + if (forecasts != null) + { + ResultLabel.Text = $"Retrieved {forecasts.Length} forecasts"; + } + } + catch (Exception ex) + { + ResultLabel.Text = $"Error: {ex.Message}"; + } + } +} +``` + +## Platform-specific considerations + +### Dev Tunnels for iOS and Android + +Dev Tunnels provide a secure way to expose your local web services to mobile devices and emulators. The Aspire integration automatically: + +- Creates and manages Dev Tunnels for your services +- Configures your MAUI app to use the tunnel URLs +- Handles authentication and connection management + +### OpenTelemetry data collection + +The `WithOtlpDevTunnel()` method creates a Dev Tunnel specifically for OpenTelemetry protocol (OTLP) traffic, allowing telemetry data from your iOS and Android apps to reach the Aspire dashboard. This is essential for monitoring and debugging your mobile apps through the Aspire dashboard. + +### Windows and Mac Catalyst + +On Windows and Mac Catalyst, local service connectivity works directly through localhost without requiring Dev Tunnels. The Aspire integration provides a consistent API across all platforms while handling platform-specific requirements automatically. + +## Running your application + +To run your MAUI app with Aspire integration: + + + + +1. Set the App Host project as the startup project +2. Run the solution (F5 or Debug > Start Debugging) + + + + +Navigate to the App Host project directory and run: + +```bash +dotnet run +``` + +Or use the Aspire CLI: + +```bash +aspire run +``` + + + + +1. Open the App Host project folder +2. Run the project using the .NET debugger or terminal + + + + +When the App Host starts: +- The Aspire dashboard will open, showing all registered services +- Your MAUI app will **not** launch automatically +- Start each .NET MAUI target manually through the dashboard + +The dashboard provides real-time monitoring, logs from all services, and distributed tracing across your entire application stack. + +## Troubleshooting + +### Service discovery not working + +If your MAUI app can't connect to your web services: + +1. Verify that you've called `AddServiceDefaults()` in your MAUI app's `MauiProgram.cs` +2. Ensure the service name in your HTTP client configuration matches the name used in the App Host +3. Check that you're using the `https+http://` scheme in your service URL +4. For iOS and Android, confirm that Dev Tunnels are configured correctly in the App Host + +### Missing telemetry from iOS/Android apps + +If you're not seeing telemetry data from your iOS or Android apps in the Aspire dashboard: + +1. Verify that you've added the `WithOtlpDevTunnel()` method to your device configurations +2. Ensure Dev Tunnels have anonymous access configured +3. Check that your firewall isn't blocking tunnel connections + +### Dev Tunnels connection issues + +If Dev Tunnels aren't working for iOS or Android: + +1. Ensure the Dev Tunnel is configured with anonymous access: `.WithAnonymousAccess()` +2. Verify that the device configuration includes the Dev Tunnel reference +3. Try restarting the App Host to recreate the tunnels + +## Best practices + +When building .NET MAUI apps with Aspire integration: + +- **Use typed clients**: Create strongly-typed HTTP clients for each service to improve maintainability +- **Handle errors gracefully**: Network operations can fail; implement proper error handling and retry logic +- **Leverage the dashboard**: Use the Aspire dashboard for debugging and monitoring during development +- **Test on all platforms**: While the integration handles platform differences, always test on your target platforms +- **Follow service defaults**: The service defaults project provides recommended patterns for resilience and telemetry + +## Sample application + +For a complete working example of .NET MAUI integration with Aspire, see the [AspireWithMaui sample](https://github.com/dotnet/aspire/tree/main/playground/AspireWithMaui) in the Aspire repository. + +## See also + +- [.NET MAUI documentation](https://learn.microsoft.com/dotnet/maui/) +- [.NET MAUI integration with Aspire on Microsoft Learn](https://learn.microsoft.com/dotnet/maui/data-cloud/aspire-integration) +- [Dev Tunnels documentation](https://learn.microsoft.com/aspnet/core/test/dev-tunnels) +- [Aspire service discovery](/reference/service-discovery/) diff --git a/src/frontend/src/data/integration-docs.json b/src/frontend/src/data/integration-docs.json index 12e69128..c2497832 100644 --- a/src/frontend/src/data/integration-docs.json +++ b/src/frontend/src/data/integration-docs.json @@ -275,6 +275,10 @@ "match": "CommunityToolkit.Aspire.Hosting.Java", "href": "/integrations/frameworks/java/" }, + { + "match": "Aspire.Hosting.Maui", + "href": "/integrations/frameworks/maui/" + }, { "match": "Aspire.Hosting.Python", "href": "/integrations/frameworks/python/" From 8b12077f660b6fc0e58d4da69e4e9182fda6fa1f Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Mon, 17 Nov 2025 14:24:23 +0100 Subject: [PATCH 2/3] Update src/frontend/src/content/docs/integrations/frameworks/maui.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- src/frontend/src/content/docs/integrations/frameworks/maui.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/frontend/src/content/docs/integrations/frameworks/maui.mdx b/src/frontend/src/content/docs/integrations/frameworks/maui.mdx index 2e252927..f1f68827 100644 --- a/src/frontend/src/content/docs/integrations/frameworks/maui.mdx +++ b/src/frontend/src/content/docs/integrations/frameworks/maui.mdx @@ -251,7 +251,7 @@ public class WeatherApiClient public record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary) { - public int TemperatureF => 32 + (int)(TemperatureC / 0.5556); + public int TemperatureF => 32 + (int)(TemperatureC * 1.8); } ``` From acb6488d3e270d92c7745338a53e0795a44dc67d Mon Sep 17 00:00:00 2001 From: David Pine Date: Mon, 17 Nov 2025 14:38:13 +0000 Subject: [PATCH 3/3] Enhance .NET MAUI integration documentation with improved content structure, added visuals, and clarified instructions for service configuration and troubleshooting. --- .../docs/integrations/frameworks/maui.mdx | 193 ++++++++++-------- 1 file changed, 107 insertions(+), 86 deletions(-) diff --git a/src/frontend/src/content/docs/integrations/frameworks/maui.mdx b/src/frontend/src/content/docs/integrations/frameworks/maui.mdx index f1f68827..1bf54d97 100644 --- a/src/frontend/src/content/docs/integrations/frameworks/maui.mdx +++ b/src/frontend/src/content/docs/integrations/frameworks/maui.mdx @@ -3,14 +3,29 @@ title: .NET MAUI integration description: Learn how to integrate .NET MAUI mobile and desktop applications with Aspire for simplified service orchestration and discovery. --- -import { Aside, Code, Tabs, TabItem } from '@astrojs/starlight/components'; +import { Image } from 'astro:assets'; +import { Aside, Badge, Code, Steps, Tabs, TabItem } from '@astrojs/starlight/components'; +import { Kbd } from 'starlight-kbd/components' +import mauiIcon from '@assets/icons/maui-icon.png'; + + + +.NET MAUI logo + +The .NET MAUI integration with Aspire simplifies the development experience when building mobile and desktop applications that connect to local web services during development. This integration enables you to orchestrate your .NET MAUI apps alongside your backend services using Aspire's powerful orchestration capabilities. -The .NET MAUI integration with Aspire simplifies the development experience when building mobile and desktop applications that connect to local web services during development. This integration enables you to orchestrate your .NET MAUI apps alongside your backend services using Aspire's powerful orchestration capabilities. - ## What is .NET MAUI? .NET Multi-platform App UI (.NET MAUI) is a cross-platform framework for creating native mobile and desktop apps with C# and XAML. With .NET MAUI, you can develop apps that run on Android, iOS, macOS, and Windows from a single shared codebase. @@ -29,11 +44,11 @@ Integrating Aspire with your .NET MAUI applications provides several key benefit Traditionally, connecting a .NET MAUI app to local web services requires significant manual configuration: -- Use different URLs for different platforms (localhost, 10.0.2.2, etc.) -- Configure network security settings for Android -- Set up Apple Transport Security (ATS) for iOS -- Handle certificate validation for HTTPS -- Manually manage service URLs in your code +- Use different URLs for different platforms (localhost, 10.0.2.2, etc.). +- Configure network security settings for Android. +- Set up Apple Transport Security (ATS) for iOS. +- Handle certificate validation for HTTPS. +- Manually manage service URLs in your code. With Aspire integration, these complexities are handled automatically, allowing you to focus on building your application instead of configuring network access. @@ -41,27 +56,29 @@ With Aspire integration, these complexities are handled automatically, allowing To use Aspire with .NET MAUI, you need: -- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) or later -- [Aspire 13](/get-started/) or later -- A .NET MAUI app targeting .NET 10 or later -- One or more web services to connect to +- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) or later. +- [Aspire 13](/get-started/) or later. +- A .NET MAUI app targeting .NET 10 or later. +- One or more web services to connect to. ## Hosting integration -The MAUI hosting integration is distributed via the [Aspire.Hosting.Maui](https://www.nuget.org/packages/Aspire.Hosting.Maui) NuGet package and enables you to orchestrate .NET MAUI applications in your App Host project. +The MAUI hosting integration is distributed via the [Aspire.Hosting.Maui](https://www.nuget.org/packages/Aspire.Hosting.Maui) NuGet package and enables you to orchestrate .NET MAUI applications in your AppHost project. ### Register MAUI project -To register a MAUI project in your App Host, install the `Aspire.Hosting.Maui` package and use the `AddMauiProject` extension method: +To register a MAUI project in your AppHost, install the `Aspire.Hosting.Maui` package and use the `AddMauiProject` extension method: -```csharp +```csharp title="C# โ€” AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); // Register your backend service var weatherApi = builder.AddProject("webapi"); // Register your MAUI app -var mauiapp = builder.AddMauiProject("mauiapp", @"../YourMauiApp/YourMauiApp.csproj"); +var mauiapp = builder.AddMauiProject("mauiapp", "../YourMauiApp/YourMauiApp.csproj"); + +// Add platform specific preferences here, chaining calls on your mauiapp. builder.Build().Run(); ``` @@ -70,29 +87,27 @@ builder.Build().Run(); The MAUI integration supports multiple platforms. Each platform requires a specific device configuration: -#### Windows - + + Windows apps run directly on the host machine using localhost: -```csharp +```csharp title="C# โ€” AppHost.cs" mauiapp.AddWindowsDevice() .WithReference(weatherApi); ``` - -#### Mac Catalyst - + + Mac Catalyst apps also use localhost directly on macOS: -```csharp +```csharp title="C# โ€” AppHost.cs" mauiapp.AddMacCatalystDevice() .WithReference(weatherApi); ``` - -#### iOS Simulator - + + iOS Simulator requires Dev Tunnels to connect to local services: -```csharp +```csharp title="C# โ€” AppHost.cs" // Create a public dev tunnel for mobile platforms var publicDevTunnel = builder.AddDevTunnel("devtunnel-public") .WithAnonymousAccess() @@ -103,22 +118,23 @@ mauiapp.AddiOSSimulator() .WithOtlpDevTunnel() // Required for OpenTelemetry data collection .WithReference(weatherApi, publicDevTunnel); ``` - -#### Android Emulator - + + Android Emulator also requires Dev Tunnels for connectivity: -```csharp +```csharp title="C# โ€” AppHost.cs" mauiapp.AddAndroidEmulator() .WithOtlpDevTunnel() // Required for OpenTelemetry data collection .WithReference(weatherApi, publicDevTunnel); ``` + + -### Complete App Host example +### Complete AppHost example Here's a complete example showing all platform configurations: -```csharp +```csharp title="C# โ€” AppHost.cs" var builder = DistributedApplication.CreateBuilder(args); // Register your web service @@ -154,34 +170,36 @@ builder.Build().Run(); ``` ## Client configuration To configure your .NET MAUI app to work with Aspire, you need to: -1. Create a MAUI Service Defaults project -2. Reference it from your MAUI app -3. Configure service defaults in your MAUI app + +1. Create a MAUI Service Defaults project. +2. Reference it from your MAUI app. +3. Configure service defaults in your MAUI app. + ### Create a MAUI Service Defaults project The MAUI Service Defaults project contains shared configuration for your MAUI app: -```bash +```bash title=".NET CLI โ€” New service defaults" dotnet new maui-aspire-servicedefaults -n YourApp.MauiServiceDefaults ``` This project includes: -- Service discovery configuration -- Default resilience patterns -- Telemetry setup -- Platform-specific networking configuration +- Service discovery configuration. +- Default resilience patterns. +- Telemetry setup. +- Platform-specific networking configuration. Add a reference to this project from your MAUI app: -```bash +```bash title=".NET CLI โ€” Add project reference" dotnet add YourMauiApp.csproj reference YourApp.MauiServiceDefaults/YourApp.MauiServiceDefaults.csproj ``` @@ -189,7 +207,7 @@ dotnet add YourMauiApp.csproj reference YourApp.MauiServiceDefaults/YourApp.Maui In your `MauiProgram.cs`, add service defaults and configure HTTP clients: -```csharp +```csharp title="C# โ€” MauiProgram.cs" using Microsoft.Extensions.Configuration; using Microsoft.Extensions.Hosting; @@ -213,7 +231,7 @@ public static class MauiProgram // Configure HTTP client with service discovery builder.Services.AddHttpClient(client => { - // Service name matches the name used in App Host + // Service name matches the name used in AppHost client.BaseAddress = new Uri("https+http://webapi"); }); @@ -223,14 +241,14 @@ public static class MauiProgram ``` ### Create a typed client Create a strongly-typed HTTP client to consume your web service: -```csharp +```csharp title="C# โ€” WeatherApiClient.cs" public class WeatherApiClient { private readonly HttpClient _httpClient; @@ -259,7 +277,7 @@ public record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary) Inject and use the client in your pages or view models: -```csharp +```csharp title="C# โ€” MainPage.cs" public partial class MainPage : ContentPage { private readonly WeatherApiClient _weatherClient; @@ -276,7 +294,7 @@ public partial class MainPage : ContentPage { var forecasts = await _weatherClient.GetWeatherForecastAsync(); - if (forecasts != null) + if (forecasts is not null) { ResultLabel.Text = $"Retrieved {forecasts.Length} forecasts"; } @@ -295,9 +313,9 @@ public partial class MainPage : ContentPage Dev Tunnels provide a secure way to expose your local web services to mobile devices and emulators. The Aspire integration automatically: -- Creates and manages Dev Tunnels for your services -- Configures your MAUI app to use the tunnel URLs -- Handles authentication and connection management +- Creates and manages Dev Tunnels for your services. +- Configures your MAUI app to use the tunnel URLs. +- Handles authentication and connection management. ### OpenTelemetry data collection @@ -311,40 +329,38 @@ On Windows and Mac Catalyst, local service connectivity works directly through l To run your MAUI app with Aspire integration: - + -1. Set the App Host project as the startup project -2. Run the solution (F5 or Debug > Start Debugging) + +1. Set the AppHost project as the startup project. +2. Run the solution ( or Debug > Start Debugging). + - - -Navigate to the App Host project directory and run: - -```bash -dotnet run -``` + -Or use the Aspire CLI: +Navigate to the AppHost project directory and run: -```bash +```bash title="Aspire CLI โ€” Run" aspire run ``` -1. Open the App Host project folder -2. Run the project using the .NET debugger or terminal + +1. Open the AppHost project folder. +2. Run the project using the .NET debugger or terminal. + -When the App Host starts: -- The Aspire dashboard will open, showing all registered services -- Your MAUI app will **not** launch automatically -- Start each .NET MAUI target manually through the dashboard +When the AppHost starts: +- The Aspire dashboard will open, showing all registered services. +- Your MAUI app will **not** launch automatically. +- Start each .NET MAUI target manually through the dashboard. The dashboard provides real-time monitoring, logs from all services, and distributed tracing across your entire application stack. @@ -354,36 +370,42 @@ The dashboard provides real-time monitoring, logs from all services, and distrib If your MAUI app can't connect to your web services: -1. Verify that you've called `AddServiceDefaults()` in your MAUI app's `MauiProgram.cs` -2. Ensure the service name in your HTTP client configuration matches the name used in the App Host -3. Check that you're using the `https+http://` scheme in your service URL -4. For iOS and Android, confirm that Dev Tunnels are configured correctly in the App Host + +1. Verify that you've called `AddServiceDefaults()` in your MAUI app's `MauiProgram.cs`. +2. Ensure the service name in your HTTP client configuration matches the name used in the AppHost. +3. Check that you're using the `https+http://` scheme in your service URL. +4. For iOS and Android, confirm that Dev Tunnels are configured correctly in the AppHost. + ### Missing telemetry from iOS/Android apps If you're not seeing telemetry data from your iOS or Android apps in the Aspire dashboard: -1. Verify that you've added the `WithOtlpDevTunnel()` method to your device configurations -2. Ensure Dev Tunnels have anonymous access configured -3. Check that your firewall isn't blocking tunnel connections + +1. Verify that you've added the `WithOtlpDevTunnel()` method to your device configurations. +2. Ensure Dev Tunnels have anonymous access configured. +3. Check that your firewall isn't blocking tunnel connections. + ### Dev Tunnels connection issues If Dev Tunnels aren't working for iOS or Android: -1. Ensure the Dev Tunnel is configured with anonymous access: `.WithAnonymousAccess()` -2. Verify that the device configuration includes the Dev Tunnel reference -3. Try restarting the App Host to recreate the tunnels + +1. Ensure the Dev Tunnel is configured with anonymous access: `.WithAnonymousAccess()`. +2. Verify that the device configuration includes the Dev Tunnel reference. +3. Try restarting the AppHost to recreate the tunnels. + ## Best practices When building .NET MAUI apps with Aspire integration: -- **Use typed clients**: Create strongly-typed HTTP clients for each service to improve maintainability -- **Handle errors gracefully**: Network operations can fail; implement proper error handling and retry logic -- **Leverage the dashboard**: Use the Aspire dashboard for debugging and monitoring during development -- **Test on all platforms**: While the integration handles platform differences, always test on your target platforms -- **Follow service defaults**: The service defaults project provides recommended patterns for resilience and telemetry +- **Use typed clients**: Create strongly-typed HTTP clients for each service to improve maintainability. +- **Handle errors gracefully**: Network operations can fail; implement proper error handling and retry logic. +- **Leverage the dashboard**: Use the Aspire dashboard for debugging and monitoring during development. +- **Test on all platforms**: While the integration handles platform differences, always test on your target platforms. +- **Follow service defaults**: The service defaults project provides recommended patterns for resilience and telemetry. ## Sample application @@ -394,4 +416,3 @@ For a complete working example of .NET MAUI integration with Aspire, see the [As - [.NET MAUI documentation](https://learn.microsoft.com/dotnet/maui/) - [.NET MAUI integration with Aspire on Microsoft Learn](https://learn.microsoft.com/dotnet/maui/data-cloud/aspire-integration) - [Dev Tunnels documentation](https://learn.microsoft.com/aspnet/core/test/dev-tunnels) -- [Aspire service discovery](/reference/service-discovery/)