Add comprehensive .NET MAUI Aspire integration documentation for .NET 10

[Copilot]

Comprehensive .NET MAUI Aspire integration documentation for .NET 10:

• Create new documentation file: /home/runner/work/docs-maui/docs-maui/docs/data-cloud/aspire-integration.md
  • Add frontmatter with title, description, and ms.date
  • Write overview section explaining what Aspire is and integration benefits
  • Add section comparing traditional approach (reference local-web-services.md)
  • Document prerequisites and requirements
  • Create getting started section with project setup
    • Explain MAUI service defaults project (dotnet new maui-aspire-servicedefaults)
    • Explain app host project setup
    • Document web service integration
  • Add platform-specific considerations (iOS, Android with Dev Tunnels)
  • Include preview status notice and Visual Studio 2026 note
  • Add code examples based on AspireWithMaui sample
  • Add suggested screenshot placeholders
  • Cross-reference Aspire documentation
  • Add troubleshooting section with common issues
  • Add note about multiple device deployments
  • Fix service name consistency (webapi throughout)
  • Add Aspire 13 requirement
  • Clarify preview status with incomplete features note
  • Add multiple run methods (Visual Studio, command line, VS Code)
• Update /home/runner/work/docs-maui/docs-maui/docs/data-cloud/local-web-services.md
  • Add TIP callout with reference to new aspire-integration.md page
• Update /home/runner/work/docs-maui/docs-maui/docs/TOC.yml
  • Add entry for Aspire integration under "Data & cloud services > Web services" section
• Validate markdown formatting with markdownlint (0 errors)
• Review all changes for accuracy and completeness
• Replace all instances of ".NET Aspire" with "Aspire" per review feedback
• Address review comments:
  • Made web services not specific to ASP.NET Core
  • Removed workload installation section
  • Changed "Aspire workload" to "Aspire"
  • Updated Getting Started wording
  • Fixed AppHost code example to match actual sample
  • Added WithOtlpDevTunnel() documentation for OpenTelemetry
  • Added note about multiple device deployments
  • Added comprehensive troubleshooting section
  • Fixed service name mismatch (apiservice → webapi)
  • Added Aspire 13 version requirement
  • Enhanced preview status note with incomplete features
  • Added alternative run methods (dotnet run, VS Code)

Documentation Created:

• New comprehensive guide covering .NET MAUI + Aspire integration
• Benefits: simplified configuration, automatic service discovery, Dev Tunnels support
• Complete setup instructions with code examples
• Platform-specific guidance for iOS, Android, Mac Catalyst, and Windows
• Screenshots suggestions for key workflows
• Moniker ranges for .NET 10+ with fallback for earlier versions
• Cross-references to Aspire docs and traditional approach
• Detailed OpenTelemetry integration guidance
• Troubleshooting section covering common issues including missing telemetry, service discovery, Dev Tunnels, App Host startup, and service defaults
• Note explaining ability to deploy to multiple devices simultaneously
• Consistent service naming throughout examples
• Clear Aspire 13 version requirement
• Comprehensive preview status disclaimer
• Multiple methods to run the application (Visual Studio with F5, command line with dotnet run, and VS Code)

Files Modified:

1. docs/data-cloud/aspire-integration.md - Comprehensive documentation with accurate examples and troubleshooting
2. docs/data-cloud/local-web-services.md - TIP callout references "Aspire integration"
3. docs/TOC.yml - Entry shows ".NET MAUI integration with Aspire"

• Fixes Create comprehensive documentation for the .NET MAUI Aspire integration #3071

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Create comprehensive documentation for the .NET MAUI Aspire integration</issue_title>
<issue_description>For .NET 10 we're adding an integration with Aspire. I want to add a comprehensive doc, one page for now, on how to get started.

Start by describing what it is and what people can do with it. What are the benefits or using Aspire with .NET MAUI? You can reference this page: https://learn.microsoft.com/en-us/dotnet/maui/data-cloud/local-web-services?view=net-maui-9.0 because this should become a lot easier for people. In fact, add a reference back from that page to this new docs page as well, but don't change anything else.

From there, describe how people can get started setting this up for their project. People need to add a MAUI service defaults project (dotnet new maui-aspire-servicedefaults) and the app host project and potentially anything for the web services they try to connect. Reference the Aspire docs where applicable.

Suggest good places for screenshots and describe what those should show.

Make sure to note that the functionality is in preview. Integration in Visual Studio 2026 is coming but not completely available yet.

Have a look at the sample code for that here: https://github.com/dotnet/aspire/tree/main/playground/AspireWithMaui this has the public API to be used. Also look at dotnet/aspire#12402 and lets make sure to include iOS and Android in this and make special note of the Dev Tunnels integration there.

Remember to update the TOC and put it in a place where it makes sense.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Create comprehensive documentation for the .NET MAUI Aspire integration #3071

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

---

Internal previews

📄 File	🔗 Preview link
docs/data-cloud/aspire-integration.md	docs/data-cloud/aspire-integration
docs/data-cloud/local-web-services.md	docs/data-cloud/local-web-services

[learn-build-service-prod]

Learn Build status updates of commit 3cd88ed:

✅ Validation status: passed

For more details, please refer to the build report.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

Learn Build status updates of commit 3424da1:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/data-cloud/aspire-integration.md	✅Succeeded	View (>=net-maui-8.0)
docs/data-cloud/local-web-services.md	✅Succeeded	View (>=net-maui-8.0)
docs/TOC.yml	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.

[jfversluis]

@copilot Lets name it just Aspire not .NET Aspire in text, please replace every instance

[Copilot]

@copilot Lets name it just Aspire not .NET Aspire in text, please replace every instance

Replaced all instances of ".NET Aspire" with "Aspire" throughout the documentation in commit 31d2609.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

Learn Build status updates of commit 31d2609:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/data-cloud/aspire-integration.md	✅Succeeded	View (>=net-maui-8.0)
docs/data-cloud/local-web-services.md	✅Succeeded	View (>=net-maui-8.0)
docs/TOC.yml	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

Learn Build status updates of commit 31d2609:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/data-cloud/aspire-integration.md	✅Succeeded	View (>=net-maui-8.0)
docs/data-cloud/local-web-services.md	✅Succeeded	View (>=net-maui-8.0)
docs/TOC.yml	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.

[jfversluis]

@copilot address comments

[Copilot]

@copilot make sure to note in the requirements that Aspire 13 is needed and find a appropriate place to add a note box that this functionality currently in preview and that some features still need to...

Updated the prerequisites to specify "Aspire 13 or later" and enhanced the IMPORTANT note at the top to clarify that the feature is in preview with some features still being implemented. Commit 969a4a1.

[learn-build-service-prod]

Learn Build status updates of commit 969a4a1:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/data-cloud/aspire-integration.md	✅Succeeded	View (>=net-maui-8.0)
docs/data-cloud/local-web-services.md	✅Succeeded	View (>=net-maui-8.0)
docs/TOC.yml	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[jfversluis]

@copilot I see a couple of references that mention to start the AppHost with F5 and using Visual Studio. Make sure to also mention aspire run or dotnet run or VS Code. I think we already did. that in the beginning of the document. Make sure to update all instructions for this.

[Copilot]

@copilot I see a couple of references that mention to start the AppHost with F5 and using Visual Studio. Make sure to also mention aspire run or dotnet run or VS Code. I think we already did. that...

Updated the "Running your application" section to include three methods:

• Visual Studio (F5/Debug)
• Command line (dotnet run)
• VS Code (debugger or terminal)

Also updated the "Selecting your platform target" section to explain how each method handles platform selection. Commit 7af69e8.

[learn-build-service-prod]

Learn Build status updates of commit 7af69e8:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/data-cloud/aspire-integration.md	✅Succeeded	View (>=net-maui-8.0)
docs/data-cloud/local-web-services.md	✅Succeeded	View (>=net-maui-8.0)
docs/TOC.yml	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

Learn Build status updates of commit 7af69e8:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/data-cloud/aspire-integration.md	✅Succeeded	View (>=net-maui-8.0)
docs/data-cloud/local-web-services.md	✅Succeeded	View (>=net-maui-8.0)
docs/TOC.yml	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

Learn Build status updates of commit 3249072:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
docs/data-cloud/aspire-integration.md	⚠️Warning	View (>=net-maui-8.0)	Details
docs/data-cloud/local-web-services.md	✅Succeeded	View (>=net-maui-8.0)
docs/data-cloud/media/aspire-integration/maui-aspire-app-resources-dashboard.png	✅Succeeded	View (>=net-maui-8.0)
docs/data-cloud/media/aspire-integration/maui-aspire-http-trace.png	✅Succeeded	View (>=net-maui-8.0)
docs/data-cloud/media/aspire-integration/maui-aspire-project-structure.png	✅Succeeded	View (>=net-maui-8.0)
docs/data-cloud/media/aspire-integration/maui-aspire-windows-android.png	✅Succeeded	View (>=net-maui-8.0)
docs/TOC.yml	✅Succeeded	View (>=net-maui-8.0)

docs/data-cloud/aspire-integration.md

• Line 353, Column 1: [Warning: file-not-found - See documentation] Invalid file link: 'media/aspire-integration/maui-aspire-http-trace.pngmedia/aspire-integration/maui-aspire-http-trace.png'.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

[learn-build-service-prod]

Learn Build status updates of commit 895fa2e:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
docs/data-cloud/aspire-integration.md	⚠️Warning	View (>=net-maui-8.0)	Details
docs/data-cloud/local-web-services.md	✅Succeeded	View (>=net-maui-8.0)
docs/data-cloud/media/aspire-integration/maui-aspire-app-resources-dashboard.png	✅Succeeded	View (>=net-maui-8.0)
docs/data-cloud/media/aspire-integration/maui-aspire-http-trace.png	✅Succeeded	View (>=net-maui-8.0)
docs/data-cloud/media/aspire-integration/maui-aspire-project-structure.png	✅Succeeded	View (>=net-maui-8.0)
docs/data-cloud/media/aspire-integration/maui-aspire-windows-android.png	✅Succeeded	View (>=net-maui-8.0)
docs/TOC.yml	✅Succeeded	View (>=net-maui-8.0)

docs/data-cloud/aspire-integration.md

• Line 313, Column 101: [Warning: file-not-found - See documentation] Invalid file link: 'dotnet/aspire/cli/overview'.
• Line 343, Column 1: [Warning: file-not-found - See documentation] Invalid file link: 'media/aspire-integration/maui-aspire-http-trace.pngmedia/aspire-integration/maui-aspire-http-trace.png'.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

Learn Build status updates of commit 4cc2ef8:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
docs/data-cloud/aspire-integration.md	⚠️Warning	View (>=net-maui-8.0)	Details
docs/data-cloud/local-web-services.md	✅Succeeded	View (>=net-maui-8.0)
docs/data-cloud/media/aspire-integration/maui-aspire-app-resources-dashboard.png	✅Succeeded	View (>=net-maui-8.0)
docs/data-cloud/media/aspire-integration/maui-aspire-http-trace.png	✅Succeeded	View (>=net-maui-8.0)
docs/data-cloud/media/aspire-integration/maui-aspire-project-structure.png	✅Succeeded	View (>=net-maui-8.0)
docs/data-cloud/media/aspire-integration/maui-aspire-windows-android.png	✅Succeeded	View (>=net-maui-8.0)
docs/TOC.yml	✅Succeeded	View (>=net-maui-8.0)

docs/data-cloud/aspire-integration.md

• Line 313, Column 101: [Warning: file-not-found - See documentation] Invalid file link: 'dotnet/aspire/cli/overview'.
• Line 343, Column 1: [Warning: file-not-found - See documentation] Invalid file link: 'media/aspire-integration/maui-aspire-http-trace.pngmedia/aspire-integration/maui-aspire-http-trace.png'.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

Learn Build status updates of commit 5bf0c36:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/data-cloud/aspire-integration.md	✅Succeeded	View (>=net-maui-8.0)
docs/data-cloud/local-web-services.md	✅Succeeded	View (>=net-maui-8.0)
docs/data-cloud/media/aspire-integration/maui-aspire-app-resources-dashboard.png	✅Succeeded	View (>=net-maui-8.0)
docs/data-cloud/media/aspire-integration/maui-aspire-http-trace.png	✅Succeeded	View (>=net-maui-8.0)
docs/data-cloud/media/aspire-integration/maui-aspire-project-structure.png	✅Succeeded	View (>=net-maui-8.0)
docs/data-cloud/media/aspire-integration/maui-aspire-windows-android.png	✅Succeeded	View (>=net-maui-8.0)
docs/TOC.yml	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.