Update XamlOptionalChanges spec to include new MSBuild properties

[evelynwu-msft]

PR Type

• Bugfix
• Feature
• Code style update (formatting, renaming)
• Refactoring (no functional changes, no API changes)
• Build related changes
• Documentation content changes
• Other (please describe):

Description

During API review of the XamlOptionalChanges spec, it was decided that MSBuild properties should be added to enable and control automatic generation of the API calls by XamlCompiler and that this should be the preferred method by which developers enable or disable optional changes. Additionally, it was decided that the behavior of DISABLE_XAML_GENERATED_MAIN should be modified so that it renames the generated main method instead of removing it entirely thereby allowing custom entry points to delegate to the default implementation if desired.

This PR updates the XamlOptionalChanges spec to reflect these decisions.

[sundaramramaswamy]

Since DISABLE_XAML_GENERATED_MAIN now renames rather than removes the generated entry point, would it help to show a short example of delegating to XamlGeneratedProgram.XamlGeneratedMain() here? The current sample calls Application.Start() directly, so the new rename behavior isn't demonstrated. #WontFix

[evelynwu-msft]

I don't think this is the right place to put that. Unfortunately there is no existing documentation for DISABLE_XAML_GENERATED_MAIN (the only places where it's currently mentioned are as part of samples on how to use unrelated features) so creating that document is part of my task to ensure that this new behavior is documented on MSDN.

[sundaramramaswamy]

Could you clarify the expected pattern when both approaches are combined? e.g. if a developer sets MSBuild properties and defines DISABLE_XAML_GENERATED_MAIN, does delegating to the renamed entry point pick up the MSBuild-generated calls automatically? A brief note on this would help avoid double-enabling surprises.

[evelynwu-msft]

Any optional-change calls produced by Approach 1 remain inside that renamed generated body.

This explicitly says that the API calls are still generated and remain in the renamed entry point. Does it not logically follow that, if a developer were to call the renamed entry point from their own main(), those generated API calls would be invoked in addition to whatever the developer is doing in their main()?

[ghost1372]

is there a particular reason the new API uses comma-separated values?

Most MSBuild list properties use semicolon-separated values (for example, NoWarn, DefineConstants, etc.), so when I tested the API today, I naturally used semicolons based on my MSBuild experience. That resulted in an error because the API expects commas.

I was just curious if there was a specific design reason for choosing commas instead of following the existing MSBuild convention.

[evelynwu-msft]

Unfortunately, WinAppSDK's RuntimeCompatibilityOptions feature only supports commas as the separator in the corresponding WindowsAppSDKDisabledChanges MSBuild property and so we chose to follow that same pattern with this property for consistency.

---

In reply to: 5001970239

[HotCakeX]

@evelynwu-msft Hi, if we define these properties in the .csproj file, does that ensure that only the selected variant is packaged with the app, rather than both variants?

If I choose the optimized variant, I would not want the default, unoptimized version to be included as well, since that would unnecessarily increase the app's package size.

[evelynwu-msft]

There is no change in binary size; these are simply run-time flags that control which branch to take in certain specific parts of the codebase.

---

In reply to: 5048963402