[wasm] Add missing properties to PropertiesThatTriggerRelinking for WASM and WASI

[Copilot]

This PR addresses the missing properties in PropertiesThatTriggerRelinking for WASM and WASI builds as identified in the issue discussion.

Problem

Several important properties that affect the native build output were not marked as triggering relinking, which could lead to inconsistent builds when these properties change. This means developers might change configuration properties but not see their changes take effect because the native components weren't rebuilt.

Solution

Added the following properties to PropertiesThatTriggerRelinking:

WASM-only (browser.proj):

• EmccInitialHeapSize - Controls memory layout together with EmccMaximumHeapSize. Heap size configuration applies only for browser scenarios, same as ExceptionHandling.

Both WASM and WASI:

• WasmEnableThreads - Affects memory layout (e.g., usage of SharedArrayBuffer in browser or DISABLE_THREADS switches in runtime)
• RunAOTCompilation - Native objects and linked outputs are no longer valid for new values and must be rebuilt
• PublishTrimmed - The set of assemblies and code passed to the native linker changes significantly

Changes

• Updated src/mono/browser/browser.proj to include all 4 properties in the generated wasm-props.json
• Updated src/mono/wasi/wasi.proj to include the 3 shared properties in the generated wasm-props.json
• Enhanced test coverage by adding WasmEnableThreads to the existing test framework in WasmNativeDefaultsTests.cs

Behavior

When any of these properties differs from the runtime pack default value, the build system will:

1. Detect the change via _ChangedPropertiesThatTriggerRelinking comparison
2. Set _WasmBuildNativeRequired=true
3. Force WasmBuildNative=true to trigger native relinking
4. Rebuild native components with the new configuration

This ensures developers get proper native rebuilds when changing these important configuration properties that affect memory layout, threading model, AOT compilation, or IL trimming.

Fixes #105135.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[ilonatommy]

@copilot, we have to document the changes.

Candidates for placing documentation:

• https://learn.microsoft.com/en-us/aspnet/core/blazor/performance/webassembly-runtime-performance#runtime-relinking (PR to https://github.com/dotnet/AspNetCore.Docs)
• src/mono/browser/README.md for browser

## Properties That Trigger Relinking

### What is Relinking?

Relinking is the process of rebuilding the native WebAssembly runtime (`dotnet.native.js`, `dotnet.native.wasm`, etc.) with updated or trimmed content, often resulting in a smaller or more optimized output. This is necessary when certain configuration properties or source changes require regeneration of the native artifacts.

### Properties That Trigger Relinking in `browser.proj`

The following MSBuild properties and build flags will trigger a relinking (full rebuild of native artifacts) during the browser/wasm build process:

- **RunAOTCompilation**  
  - `/p:RunAOTCompilation=true`  
  - Enables Ahead-of-Time (AOT) compilation. Changing this from false to true (or vice versa) requires relinking to produce the correct output.

- **WasmBuildNative**  
  - `/p:WasmBuildNative=true`  
  - Forces a fresh build of the native runtime components.

- **WasmRelinkNative**  
  - `/p:WasmRelinkNative=true`  
  - Explicitly requests relinking, even if not otherwise required by other property changes.

- **WasmBuildArgs**  
  - Any change to arguments passed via `/p:WasmBuildArgs=...` (such as enabling/disabling additional features or options) will trigger a relink.

- **Configuration/Target Architecture**  
  - Changing `/p:Configuration=Debug|Release` or `/p:RuntimeIdentifier=browser-wasm`, etc., can require relinking for correct native output.

- **Source Changes**  
  - Any modification to native code (C/C++/Emscripten sources) in `src/mono/browser` or dependent directories will naturally trigger a relink.

#### Notes

- Relinking ensures that the produced WebAssembly binaries reflect the current set of build options and runtime features.
- For incremental developer workflows, minimizing unnecessary relinks speeds up build times.
- The relink process is managed by MSBuild targets in `browser.proj`—refer to that file for the most up-to-date logic.

For questions or advanced scenarios, see the [WebAssembly build instructions](../../../docs/workflow/building/libraries/webassembly-instructions.md) or reach out to the .NET runtime maintainers.

• src/mono/wasi/README.md for WAS

## Properties That Trigger Relinking

### What is Relinking?

Relinking in WASI builds refers to regenerating the native WASI runtime artifacts (such as `dotnet.native.wasi`, supporting JS, etc.) to reflect changes in configuration, features, or source. This process is essential for producing correct, optimized binaries for WASI environments.

### Properties That Trigger Relinking in `wasi.proj`

The following MSBuild properties and build flags will trigger a relinking during the WASI build process:

- **RunAOTCompilation**  
  - `/p:RunAOTCompilation=true`  
  - Enables AOT compilation for WASI. Changing this property requires relinking for correct WASI output.

- **WasiBuildNative**  
  - `/p:WasiBuildNative=true`  
  - Forces a rebuild of all native WASI binaries, regardless of detected changes.

- **WasiRelinkNative**  
  - `/p:WasiRelinkNative=true`  
  - Explicitly requests relinking of native WASI artifacts.

- **WasiBuildArgs**  
  - Any change to `/p:WasiBuildArgs=...` (custom build flags or feature toggles) can trigger a relink.

- **Configuration/Target Architecture**  
  - Changing `/p:Configuration=Debug|Release` or `/p:RuntimeIdentifier=wasi-wasm`, etc., may require relinking.

- **Source Changes**  
  - Modifying native sources in `src/mono/wasi` or related directories will always trigger a relink.

#### Notes

- Correct relinking ensures WASI binaries are up-to-date and accurately reflect the intended configuration.
- Avoid unnecessary relinking for faster incremental builds.
- The relink logic is defined in `wasi.proj` and supporting MSBuild files.

For more detailed WASI build and configuration guidance, see the [WASI build documentation](../../../docs/workflow/building/libraries/webassembly-instructions.md) or consult with the .NET runtime community.

[Copilot]

@copilot, we have to document the changes.

Candidates for placing documentation:
...

Added comprehensive documentation for properties that trigger relinking in both src/mono/browser/README.md and src/mono/wasi/README.md. The documentation includes:

• Clear explanation of what relinking is and why it's needed
• Complete list of MSBuild properties that trigger relinking for each platform
• Usage examples with /p:PropertyName=value syntax
• Notes about build performance and incremental workflows

This covers the newly added properties (EmccInitialHeapSize, WasmEnableThreads, RunAOTCompilation, PublishTrimmed) as well as the existing properties for better developer understanding.

Commit: 8540857

[Copilot]

Pull Request Overview

This PR adds missing properties to PropertiesThatTriggerRelinking for WASM and WASI builds to ensure native components are properly rebuilt when configuration changes occur. The changes ensure that when developers modify important build properties like threading, AOT compilation, or trimming settings, the native runtime artifacts are correctly regenerated.

Key changes:

• Added 4 new properties to WASM builds: EmccInitialHeapSize, WasmEnableThreads, RunAOTCompilation, PublishTrimmed
• Added 3 new properties to WASI builds: WasmEnableThreads, RunAOTCompilation, PublishTrimmed
• Enhanced test coverage and added comprehensive documentation for relinking behavior

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/mono/browser/browser.proj	Added 4 properties to PropertiesThatTriggerRelinking JSON for WASM builds
src/mono/wasi/wasi.proj	Added 3 properties to PropertiesThatTriggerRelinking JSON for WASI builds
src/mono/wasm/Wasm.Build.Tests/WasmNativeDefaultsTests.cs	Added WasmEnableThreads to test coverage with explanatory comments
src/mono/browser/README.md	Added comprehensive documentation section explaining relinking properties and behavior
src/mono/wasi/README.md	Added comprehensive documentation section explaining relinking properties and behavior for WASI

[dotnet-policy-service]

Tagging subscribers to 'arch-wasm': @lewing
See info in area-owners.md if you want to be subscribed.

[ilonatommy]

All feedback applied.

[pavelsavara]

Should we trigger re-link on all things that influence trimmer features ?
Like WasmEnableStreamingResponse. This has to re-build for AOT.
Maybe this is only about incremental build again.

We already have EnableDiagnostics because that also has native component.

[ilonatommy]

Should we trigger re-link on all things that influence trimmer features ? Like WasmEnableStreamingResponse. This has to re-build for AOT. Maybe this is only about incremental build again.

WasmEnableStreamingResponse controls runtime (managed) feature, it looks like changing it does not affect native code. I do not see how changing WasmEnableStreamingResponse influences AOT.