Update performance documentation with latest recommendations

[Copilot]

Updates performance guidance per issue #3105: recommend CollectionView over ListView, clarify Shell expectations, add async best practices, and document IDisposable/DI pitfalls.

ListView → CollectionView

• Replaced "Optimize ListView performance" with "Use CollectionView instead of ListView"
• Added warning about placing either control inside ScrollView/StackLayout (breaks virtualization)

Shell apps clarification

• Added note that Shell is not a universal performance fix—it improves startup by deferring page creation, not other performance issues

Async programming

• Added fire-and-forget anti-pattern guidance: always await async methods
• Removed Task.Delay recommendation (not a common perf concern)
• Added link to async/await best practices documentation

CollectionView data handling

• Warning about CollectionView throwing on off-thread ItemsSource updates
• ObservableCollection<T> guidance: prefer List<T> for static data; batch updates and reassign ItemsSource for large datasets

IDisposable and dependency injection

• New subsection warning against registering IDisposable types as transient services (container won't dispose them)
• Recommend scoped/singleton services or factory pattern for disposable types

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Performance document should be updated with latest recommendations</issue_title>
<issue_description>### Type of issue

Out of Date Information

Description

1. ListView section should tell users to just use CollectionView and we should call out not using it inside a "StackLayout"
2. Review these recommendations around image handling

• https://learn.microsoft.com/en-us/dotnet/maui/deployment/performance?view=net-maui-9.0#optimize-image-resources

3. Should we put this on the doc? https://learn.microsoft.com/en-us/dotnet/maui/deployment/performance?view=net-maui-9.0#create-shell-apps or possibly add additional context? We don't want to necessarly trigger people to think that converting to shell will magically fix performance issues
4. Task suggestions https://learn.microsoft.com/en-us/dotnet/maui/deployment/performance?view=net-maui-9.0#fundamentals

• Should we mention Task.Run? Should this section just refer out to other async/await documentation?
• We should probably add a section about making sure to await everything and never just call an async method
• Review this suggestion "Use the Task.Delay method to produce a Task object that finishes after the specified time. This is useful for scenarios such as polling for data, and delaying handling user input for a predetermined time. For more information, see Task.Delay."

5. update this documentation to refer to CollectionView and indicate recommendations about not using an ObservableCollection. We should also discourage users from depending on the auto marshalling behavior of CV
6. Include documentation around IDisposable and how it shouldn't be used on transient services. https://learn.microsoft.com/en-us/dotnet/maui/deployment/performance?view=net-maui-9.0#release-idisposable-resources https://learn.microsoft.com/en-us/dotnet/core/extensions/dependency-injection-guidelines#recommendations

Page URL

https://learn.microsoft.com/en-us/dotnet/maui/deployment/performance?view=net-maui-9.0

Content source URL

https://github.com/dotnet/docs-maui/blob/main/docs/deployment/performance.md

Document Version Independent Id

5845bd05-2151-862c-9b29-1d76664a9f0d

Platform Id

ed86303e-6644-339a-3af0-abd3ffb65a76

Article author

@davidbritch

Metadata

• ID: 5845bd05-2151-862c-9b29-1d76664a9f0d
• PlatformId: ed86303e-6644-339a-3af0-abd3ffb65a76
• Service: dotnet-mobile
• Sub-service: dotnet-maui

Related Issues</issue_description>

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

• Fixes Performance document should be updated with latest recommendations #2874

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

---

Internal previews

📄 File	🔗 Preview link
docs/deployment/performance.md	docs/deployment/performance

[learn-build-service-prod]

Learn Build status updates of commit 93cabf9:

✅ 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 4c55a5a:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/deployment/performance.md	✅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 7d7cec3:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/deployment/performance.md	✅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 7d7cec3:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/deployment/performance.md	✅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 e885c13:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/deployment/performance.md	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.

[Copilot]

Pull request overview

This PR updates the performance documentation with current best practices for .NET MAUI development. It addresses issue #3105 by modernizing guidance around list controls, Shell navigation, async programming, and dependency injection patterns.

Changes:

• Replaces ListView performance guidance with CollectionView recommendations
• Clarifies Shell's role in improving startup time rather than general performance
• Adds async/await best practices, including fire-and-forget anti-patterns and CollectionView threading behavior
• Documents IDisposable pitfalls with transient service registration in dependency injection

[Copilot]

The StackLayout mentioned in this warning is ambiguous. .NET MAUI has both StackLayout and VerticalStackLayout/HorizontalStackLayout. Consider clarifying which layout types are affected, or use the more general term "stack layouts" to cover all variants.