[docs] Clarify EnableOnDemandResources and EmbedOnDemandResources properties - #26310
Merged
rolfbjarne merged 2 commits intoJul 28, 2026
Merged
Conversation
…perties Expand the documentation for the two on-demand-resources (ODR) build properties, since the difference between them caused customer confusion in issue #26218: * EnableOnDemandResources: explain that it's what turns ODR on, and show how to tag a resource with ResourceTags metadata (using Update rather than Include for already-globbed resources, and mentioning the MauiAsset equivalent). * EmbedOnDemandResources: clarify that it does NOT enable ODR, and only controls where asset packs are placed when packaging an IPA for distribution. The two entries now cross-reference each other.
Contributor
There was a problem hiding this comment.
Pull request overview
Clarifies the documentation for iOS/macOS on-demand resources (ODR) MSBuild properties to reduce user confusion, particularly around which property enables ODR vs how ODR asset packs are packaged for distribution.
Changes:
- Expanded
EmbedOnDemandResourcesdocs to explain it affects packaging layout, not whether ODR is enabled. - Expanded
EnableOnDemandResourcesdocs with an example showing how to tag resources usingResourceTagsmetadata (and guidance onUpdatevsInclude). - Added cross-references between the two properties.
dalexsoto
previously approved these changes
Jul 27, 2026
Address PR review feedback: for AppStore distribution the asset packs are always placed outside the .app bundle regardless of EmbedOnDemandResources; the property only changes the packaging layout for AdHoc distribution.
rolfbjarne
enabled auto-merge (squash)
July 28, 2026 09:51
dalexsoto
approved these changes
Jul 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Expand the documentation for the two on-demand-resources (ODR) build
properties. The difference between them caused customer confusion in
issue #26218, where a user thought on-demand resources were disabled by
default (they aren't on iOS) and that the "Embed on-demand resources in the
app bundle" option was what turned the feature on (it doesn't).
EnableOnDemandResources: explain that this is what turns ODR on, and showhow to tag a resource with
ResourceTagsmetadata — usingUpdateratherthan
Includefor resources that are already part of the project's defaultresources, and mentioning the
MauiAssetequivalent for .NET MAUI projects.EmbedOnDemandResources: clarify that it does NOT enable ODR, and onlycontrols where asset packs are placed when packaging an IPA for
distribution.
The two entries now cross-reference each other.
This is a documentation-only change; it does not change any build behavior and
does not by itself fix #26218 (which was a user project-metadata problem).
🤖 Pull request created by Copilot