Skip to content

Commit 3424da1

Browse files
Copilotjfversluis
Copilot
and
jfversluis
committed
Add comprehensive .NET MAUI Aspire integration documentation
Co-authored-by: jfversluis <939291+jfversluis@users.noreply.github.com>
1 parent 3cd88ed commit 3424da1

File tree

3 files changed

+349
-0
lines changed

3 files changed

+349
-0
lines changed

‎docs/TOC.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1236,6 +1236,8 @@
12361236
items:
12371237
- name: Consume a REST-based web service
12381238
href: data-cloud/rest.md
1239+
- name: .NET MAUI integration with .NET Aspire
1240+
href: data-cloud/aspire-integration.md
12391241
- name: Connect to local web services
12401242
href: data-cloud/local-web-services.md
12411243
- name: Deployment & testing

‎docs/data-cloud/aspire-integration.md‎

Lines changed: 344 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,344 @@
1+
---
2+
title: ".NET MAUI integration with .NET Aspire"
3+
description: "Learn how to use .NET Aspire to simplify connecting your .NET MAUI app to local web services during development."
4+
ms.date: 10/31/2024
5+
---
6+
7+
# .NET MAUI integration with .NET Aspire
8+
9+
::: moniker range=">=net-maui-10.0"
10+
11+
> [!IMPORTANT]
12+
> This feature is currently in preview. Integration with Visual Studio 2026 is coming but not completely available yet.
13+
14+
.NET Aspire is an opinionated, cloud-ready stack for building observable, production-ready, distributed applications. The .NET MAUI integration with .NET Aspire simplifies the development experience when building mobile and desktop applications that connect to local web services during development.
15+
16+
## What is .NET Aspire?
17+
18+
.NET Aspire provides a consistent, opinionated set of tools and patterns for building and running distributed applications. It's designed to improve the experience of building cloud-native applications by providing:
19+
20+
- **Orchestration**: Simplified management of multiple services and dependencies
21+
- **Components**: Pre-built integrations for common services and platforms
22+
- **Tooling**: Developer dashboard for monitoring and managing services
23+
- **Service discovery**: Automatic configuration for service-to-service communication
24+
25+
For more information about .NET Aspire, see [.NET Aspire documentation](/dotnet/aspire/).
26+
27+
## Benefits of using Aspire with .NET MAUI
28+
29+
Integrating .NET Aspire with your .NET MAUI applications provides several key benefits:
30+
31+
- **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.
32+
- **Automatic service discovery**: Your MAUI app automatically discovers and connects to local services without hardcoded URLs.
33+
- **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.
34+
- **Consistent experience**: Use the same patterns and tools across your entire application stack.
35+
- **Observable services**: Monitor your services through the Aspire dashboard during development.
36+
37+
### Comparison with traditional approach
38+
39+
Traditionally, connecting a .NET MAUI app to local web services requires significant manual configuration. You need to:
40+
41+
- Use different URLs for different platforms (localhost, 10.0.2.2, etc.)
42+
- Configure network security settings for Android
43+
- Set up Apple Transport Security (ATS) for iOS
44+
- Handle certificate validation for HTTPS
45+
- Manually manage service URLs in your code
46+
47+
For more information about the traditional approach, see [Connect to local web services](local-web-services.md).
48+
49+
With .NET Aspire integration, these complexities are handled automatically, allowing you to focus on building your application instead of configuring network access.
50+
51+
## Prerequisites
52+
53+
To use .NET Aspire with .NET MAUI, you need:
54+
55+
- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) or later
56+
- [.NET Aspire workload](/dotnet/aspire/fundamentals/setup-tooling)
57+
- A .NET MAUI app targeting .NET 10 or later
58+
- One or more ASP.NET Core web services
59+
60+
To install the .NET Aspire workload, run:
61+
62+
```dotnetcli
63+
dotnet workload install aspire
64+
```
65+
66+
## Getting started
67+
68+
Setting up .NET Aspire integration with your .NET MAUI application involves adding two key projects to your solution:
69+
70+
1. **MAUI Service Defaults project**: Provides default configuration for your MAUI app
71+
2. **App Host project**: Orchestrates your application services and handles service discovery
72+
73+
### Create a MAUI Service Defaults project
74+
75+
The MAUI Service Defaults project contains shared configuration that your MAUI application will use to connect to services. Create this project in your solution directory:
76+
77+
```dotnetcli
78+
dotnet new maui-aspire-servicedefaults -n YourApp.MauiServiceDefaults
79+
```
80+
81+
This project includes:
82+
83+
- Service discovery configuration
84+
- Default resilience patterns
85+
- Telemetry setup
86+
- Platform-specific networking configuration
87+
88+
Add a reference to this project from your .NET MAUI app project:
89+
90+
```dotnetcli
91+
dotnet add YourMauiApp.csproj reference YourApp.MauiServiceDefaults/YourApp.MauiServiceDefaults.csproj
92+
```
93+
94+
### Create an App Host project
95+
96+
The App Host project orchestrates all your application services, including your MAUI app and any backend services. Create this project in your solution directory:
97+
98+
```dotnetcli
99+
dotnet new aspire-apphost -n YourApp.AppHost
100+
```
101+
102+
Add references to your MAUI app and any web service projects:
103+
104+
```dotnetcli
105+
dotnet add YourApp.AppHost.csproj reference YourMauiApp/YourMauiApp.csproj
106+
dotnet add YourApp.AppHost.csproj reference YourWebService/YourWebService.csproj
107+
```
108+
109+
### Configure the App Host
110+
111+
In your App Host project's `Program.cs`, register your MAUI app and web services:
112+
113+
```csharp
114+
var builder = DistributedApplication.CreateBuilder(args);
115+
116+
// Register your web service
117+
var apiService = builder.AddProject<Projects.YourWebService>("apiservice");
118+
119+
// Register your MAUI app with a reference to the API service
120+
builder.AddProject<Projects.YourMauiApp>("mauiapp")
121+
.WithReference(apiService);
122+
123+
builder.Build().Run();
124+
```
125+
126+
> [!NOTE]
127+
> Screenshot suggestion: Show the Visual Studio Solution Explorer with the project structure including the MAUI app, Service Defaults, App Host, and Web Service projects.
128+
129+
### Configure your MAUI app
130+
131+
In your .NET MAUI app's `MauiProgram.cs`, configure service defaults and add HTTP clients:
132+
133+
```csharp
134+
using Microsoft.Extensions.Configuration;
135+
using Microsoft.Extensions.Hosting;
136+
137+
public static class MauiProgram
138+
{
139+
public static MauiApp CreateMauiApp()
140+
{
141+
var builder = MauiApp.CreateBuilder();
142+
143+
builder
144+
.UseMauiApp<App>()
145+
.ConfigureFonts(fonts =>
146+
{
147+
fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
148+
fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
149+
});
150+
151+
// Add service defaults
152+
builder.Services.AddServiceDefaults();
153+
154+
// Configure HTTP client with service discovery
155+
builder.Services.AddHttpClient<WeatherApiClient>(client =>
156+
{
157+
// Service name matches the name used in App Host
158+
client.BaseAddress = new Uri("https+http://apiservice");
159+
});
160+
161+
return builder.Build();
162+
}
163+
}
164+
```
165+
166+
The `https+http://` scheme is special syntax that enables both HTTPS and HTTP protocols, with preference for HTTPS. The service name (`apiservice` in this example) must match the name you used when registering the service in your App Host's `Program.cs`.
167+
168+
### Create a service client
169+
170+
Create a typed client to consume your web service:
171+
172+
```csharp
173+
public class WeatherApiClient
174+
{
175+
private readonly HttpClient _httpClient;
176+
177+
public WeatherApiClient(HttpClient httpClient)
178+
{
179+
_httpClient = httpClient;
180+
}
181+
182+
public async Task<WeatherForecast[]?> GetWeatherForecastAsync(CancellationToken cancellationToken = default)
183+
{
184+
return await _httpClient.GetFromJsonAsync<WeatherForecast[]>(
185+
"/weatherforecast",
186+
cancellationToken);
187+
}
188+
}
189+
190+
public record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
191+
{
192+
public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
193+
}
194+
```
195+
196+
### Use the client in your app
197+
198+
Inject and use the client in your pages or view models:
199+
200+
```csharp
201+
public partial class MainPage : ContentPage
202+
{
203+
private readonly WeatherApiClient _weatherClient;
204+
205+
public MainPage(WeatherApiClient weatherClient)
206+
{
207+
_weatherClient = weatherClient;
208+
InitializeComponent();
209+
}
210+
211+
private async void OnGetWeatherClicked(object sender, EventArgs e)
212+
{
213+
try
214+
{
215+
var forecasts = await _weatherClient.GetWeatherForecastAsync();
216+
217+
if (forecasts != null)
218+
{
219+
// Display the weather data
220+
ResultLabel.Text = $"Retrieved {forecasts.Length} forecasts";
221+
}
222+
}
223+
catch (Exception ex)
224+
{
225+
ResultLabel.Text = $"Error: {ex.Message}";
226+
}
227+
}
228+
}
229+
```
230+
231+
## Platform-specific considerations
232+
233+
### iOS and Mac Catalyst
234+
235+
On iOS and Mac Catalyst, the Aspire integration works seamlessly when running the app through the App Host. The service discovery configuration automatically provides the correct URLs for connecting to local services.
236+
237+
When using the iOS Simulator or running on a physical device, Dev Tunnels are automatically configured to enable connectivity to services running on your development machine.
238+
239+
> [!NOTE]
240+
> Screenshot suggestion: Show the Aspire dashboard with a MAUI iOS app connected to a web service, displaying the active connections and logs.
241+
242+
### Android
243+
244+
On Android, the Aspire integration handles the platform-specific networking requirements automatically. You no longer need to:
245+
246+
- Configure the special `10.0.2.2` address
247+
- Set up network security configuration files
248+
- Enable clear-text traffic for local development
249+
250+
The integration uses Dev Tunnels to provide secure, reliable connectivity between the Android emulator and your local services.
251+
252+
> [!NOTE]
253+
> Screenshot suggestion: Show the Android emulator running a MAUI app successfully connecting to a local service through the Aspire integration.
254+
255+
#### Dev Tunnels integration
256+
257+
Dev Tunnels provide a secure way to expose your local web services to mobile devices and emulators. The Aspire integration automatically:
258+
259+
- Creates and manages Dev Tunnels for your services
260+
- Configures your MAUI app to use the tunnel URLs
261+
- Handles authentication and connection management
262+
263+
This eliminates the need for complex network configuration and makes it easy to test your app on physical devices.
264+
265+
For more information about Dev Tunnels, see [Dev tunnels documentation](/aspnet/core/test/dev-tunnels).
266+
267+
### Windows
268+
269+
On Windows, local service connectivity works directly through localhost without requiring additional configuration. The Aspire integration provides a consistent API across all platforms, but the underlying implementation on Windows is straightforward.
270+
271+
## Running your application
272+
273+
To run your MAUI app with Aspire integration:
274+
275+
1. Set the App Host project as the startup project in Visual Studio or your preferred IDE
276+
2. Run the solution (F5 or Debug > Start Debugging)
277+
3. The Aspire dashboard will open, showing all registered services
278+
4. Your MAUI app will launch and automatically connect to the configured services
279+
280+
> [!NOTE]
281+
> Screenshot suggestion: Show the Aspire dashboard with multiple services running (MAUI app, web service, database if applicable) with their status indicators and resource usage.
282+
283+
When you run your application through the App Host:
284+
285+
- All services start automatically
286+
- Service discovery is configured
287+
- The dashboard provides real-time monitoring
288+
- Logs from all services are available in one place
289+
290+
### Selecting your platform target
291+
292+
When running through the App Host, you can select which platform to target:
293+
294+
1. In Visual Studio, use the target framework dropdown to select your desired platform (Android, iOS, Windows, etc.)
295+
2. The App Host will launch your MAUI app on the selected platform
296+
3. Service connectivity works automatically on all platforms
297+
298+
## Monitoring and debugging
299+
300+
The Aspire dashboard provides powerful tools for monitoring and debugging your application:
301+
302+
- **Resource view**: See all running services and their status
303+
- **Logs**: View combined logs from all services in one place
304+
- **Traces**: Distributed tracing across services
305+
- **Metrics**: Monitor performance and resource usage
306+
307+
> [!NOTE]
308+
> Screenshot suggestion: Show the Aspire dashboard's traces view, displaying a request flowing from the MAUI app through to a backend service.
309+
310+
## Best practices
311+
312+
When building .NET MAUI apps with Aspire integration:
313+
314+
- **Use typed clients**: Create strongly-typed HTTP clients for each service to improve maintainability
315+
- **Handle errors gracefully**: Network operations can fail; implement proper error handling and retry logic
316+
- **Leverage the dashboard**: Use the Aspire dashboard for debugging and monitoring during development
317+
- **Test on all platforms**: While the integration handles platform differences, always test on your target platforms
318+
- **Follow service defaults**: The service defaults project provides recommended patterns for resilience and telemetry
319+
320+
## Sample application
321+
322+
For a complete working example of .NET MAUI integration with .NET Aspire, see the [AspireWithMaui sample](https://github.com/dotnet/aspire/tree/main/playground/AspireWithMaui) in the .NET Aspire repository.
323+
324+
The sample demonstrates:
325+
326+
- Complete project structure
327+
- Service registration and discovery
328+
- Platform-specific considerations
329+
- Error handling and resilience patterns
330+
331+
## Additional resources
332+
333+
- [.NET Aspire documentation](/dotnet/aspire/)
334+
- [Service discovery in .NET Aspire](/dotnet/aspire/service-discovery/overview)
335+
- [.NET Aspire orchestration](/dotnet/aspire/fundamentals/app-host-overview)
336+
- [Connect to local web services (traditional approach)](local-web-services.md)
337+
338+
::: moniker-end
339+
340+
::: moniker range="<net-maui-10.0"
341+
342+
.NET MAUI integration with .NET Aspire is available in .NET MAUI 10 and later. For information about connecting to local web services in earlier versions, see [Connect to local web services](local-web-services.md).
343+
344+
::: moniker-end

‎docs/data-cloud/local-web-services.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,9 @@ ms.date: 10/07/2024
1010

1111
Many mobile and desktop apps consume web services. During the software development phase, it's common to deploy a web service locally and consume it from an app running in the Android emulator or iOS simulator. This avoids having to deploy the web service to a hosted endpoint, and enables a straightforward debugging experience because both the app and web service are running locally.
1212

13+
> [!TIP]
14+
> If you're using .NET 10 or later, consider using [.NET Aspire integration](aspire-integration.md) to simplify connecting to local web services. Aspire automatically handles platform-specific networking configuration, service discovery, and development tunnels, eliminating much of the manual configuration described in this article.
15+
1316
.NET Multi-platform App UI (.NET MAUI) apps that run on Windows or MacCatalyst can consume ASP.NET Core web services that are running locally over HTTP or HTTPS without any additional work, provided that you've [trusted your development certificate](#trust-your-development-certificate). However, additional work is required when the app is running in the Android emulator or iOS simulator, and the process is different depending on whether the web service is running over HTTP or HTTPS.
1417

1518
## Local machine address

0 commit comments

Comments
 (0)