Add CoreCLR on WebAssembly features documentation by radekdoulik · Pull Request #124455 · dotnet/runtime

radekdoulik · 2026-02-16T08:42:54Z

Add a features document for CoreCLR WASM browser support at docs/design/coreclr/browser-wasm-coreclr.md, structured similarly to the existing src/mono/wasm/features.md.

Covers:

Configuring browser features (execution model, SIMD, EH, BigInt, threading, HTTP, WebSocket, memory, GC, globalization, MSBuild properties)
JavaScript host API and interop
Project folder structure
Hosting the application (MIME types, CSP)
Resources consumed on the target device
Key differences from Mono WASM and known limitations
Developer tools (building, running, debugging, logging)

Add a features document for CoreCLR WASM browser support, structured similarly to the existing src/mono/wasm/features.md. Covers configuring browser features, JavaScript host API, project structure, hosting, resource consumption, differences from Mono WASM, and developer tools. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

dotnet-policy-service · 2026-02-16T08:47:47Z

Tagging subscribers to this area: @agocke, @dotnet/runtime-infrastructure
See info in area-owners.md if you want to be subscribed.

Copilot

Pull request overview

Adds an initial design/features document describing the current state and configuration surface of CoreCLR running in the browser via WebAssembly, intended to parallel existing Mono WASM documentation and point readers to relevant build/debug resources within the repo.

Changes:

Introduces docs/design/coreclr/browser-wasm-coreclr.md covering browser feature requirements, hosting concerns, tooling, and CoreCLR-vs-Mono differences.
Links to existing build/debug documentation (docs/workflow/building/coreclr/wasm.md) and loader API typings (src/native/corehost/browserhost/loader/dotnet.d.ts).
Documents runtime characteristics such as interpreter execution model, memory sizing, globalization/ICU, and known limitations.

docs/design/coreclr/browser-wasm-coreclr.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

Copilot · 2026-02-16T08:54:23Z

docs/design/coreclr/browser-wasm-coreclr.md

+
+### WebSocket
+
+Applications using the [WebSocketClient](https://learn.microsoft.com/dotnet/api/system.net.websockets.clientwebsocket) managed API require the browser to support the [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) API.


The doc refers to a "WebSocketClient" managed API, but the type at the linked URL is ClientWebSocket. Rename this to the correct API name to prevent confusion.

Suggested change

Applications using the [WebSocketClient](https://learn.microsoft.com/dotnet/api/system.net.websockets.clientwebsocket) managed API require the browser to support the [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) API.

Applications using the [ClientWebSocket](https://learn.microsoft.com/dotnet/api/system.net.websockets.clientwebsocket) managed API require the browser to support the [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) API.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.

Copilot · 2026-02-16T08:59:36Z

docs/design/coreclr/browser-wasm-coreclr.md

+
+### WebSocket
+
+Applications using the [WebSocketClient](https://learn.microsoft.com/dotnet/api/system.net.websockets.clientwebsocket) managed API require the browser to support the [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) API.


The class name should be ClientWebSocket, not WebSocketClient. The text refers to the System.Net.WebSockets.ClientWebSocket class but uses the wrong name in the prose.

Suggested change

Applications using the [WebSocketClient](https://learn.microsoft.com/dotnet/api/system.net.websockets.clientwebsocket) managed API require the browser to support the [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) API.

Applications using the [ClientWebSocket](https://learn.microsoft.com/dotnet/api/system.net.websockets.clientwebsocket) managed API require the browser to support the [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) API.

Copilot · 2026-02-16T08:59:37Z

docs/design/coreclr/browser-wasm-coreclr.md

+  <WasmEnvironmentVariable Include="COMPlus_LogEnable" Value="1" />
+  <WasmEnvironmentVariable Include="COMPlus_LogToConsole" Value="1" />
+  <WasmEnvironmentVariable Include="COMPlus_LogLevel" Value="10" />
+  <WasmEnvironmentVariable Include="COMPlus_LogFacility" Value="410" />


CoreCLR has migrated from the legacy COMPlus_ environment variable prefix to DOTNET_. These logging configuration examples should use the DOTNET_ prefix instead. For example, DOTNET_LogEnable instead of COMPlus_LogEnable, DOTNET_LogToConsole instead of COMPlus_LogToConsole, etc.

Suggested change

<WasmEnvironmentVariable Include="COMPlus_LogEnable" Value="1" />

<WasmEnvironmentVariable Include="COMPlus_LogToConsole" Value="1" />

<WasmEnvironmentVariable Include="COMPlus_LogLevel" Value="10" />

<WasmEnvironmentVariable Include="COMPlus_LogFacility" Value="410" />

<WasmEnvironmentVariable Include="DOTNET_LogEnable" Value="1" />

<WasmEnvironmentVariable Include="DOTNET_LogToConsole" Value="1" />

<WasmEnvironmentVariable Include="DOTNET_LogLevel" Value="10" />

<WasmEnvironmentVariable Include="DOTNET_LogFacility" Value="410" />

jkotas · 2026-02-16T19:57:25Z

docs/design/coreclr/browser-wasm-coreclr.md

+
+### CoreCLR runtime logging
+
+```xml


I do not expect that this is the one right setting for logging to use with wasm. You typically want to tailor it to what you are trying to diagnose.

https://github.com/dotnet/runtime/blob/main/docs/design/coreclr/botr/logging.md is our doc for logging. Perhaps this should be adeed there?

jkotas · 2026-02-16T19:59:27Z

docs/design/coreclr/browser-wasm-coreclr.md

+- **GC/Finalizer issues** — Finalizer integration with the browser event loop has known issues ([#123712](https://github.com/dotnet/runtime/issues/123712)).
+- **PAL limitations** — No process/signal/pipe support ([#122506](https://github.com/dotnet/runtime/issues/122506)).
+
+## Developer tools


This should be somewhere under docs\workflow . There is no "design" in how to build and debug.

jkotas · 2026-02-16T20:05:14Z

docs/design/coreclr/browser-wasm-coreclr.md

+|----------|---------|-------------|
+| `RuntimeFlavor` | `Mono` | Set to `CoreCLR` to use CoreCLR runtime |
+| `WasmEnableExceptionHandling` | `true` | Enable native WASM exception handling |
+| `WasmEnableSIMD` | `true` | Enable WASM SIMD instructions |


The earlier chapter says that WasmEnableSIMD must be enabled for CoreCLR. Why is this important?

jkotas · 2026-02-16T20:05:46Z

docs/design/coreclr/browser-wasm-coreclr.md

+| `RuntimeFlavor` | `Mono` | Set to `CoreCLR` to use CoreCLR runtime |
+| `WasmEnableExceptionHandling` | `true` | Enable native WASM exception handling |
+| `WasmEnableSIMD` | `true` | Enable WASM SIMD instructions |
+| `InvariantGlobalization` | `false` | Disable ICU for smaller binary size |


Similar here, duplicated with ICU above

jkotas · 2026-02-16T20:07:37Z

docs/design/coreclr/browser-wasm-coreclr.md

+| **Execution** | CoreCLR interpreter (+ RyuJIT AOT in progress) | Mono interpreter + JITerpreter + optional AOT |
+| **GC** | CoreCLR workstation GC | Mono SGen GC |
+| **Type system** | CoreCLR type system | Mono type system |
+| **Assembly loading** | `AssemblyLoadContext` | Mono native loader |


What does it mean that AssemblyLoadContext is used for assembly loading? I would expect it to be CoreCLR native loader.

jkotas · 2026-02-16T20:10:01Z

docs/design/coreclr/browser-wasm-coreclr.md

+| **Workload** | Not yet available | `wasm-tools` / `wasm-experimental` |
+| **Maturity** | Experimental | Production-supported |
+
+### Known limitations


It would be interesting to list the limitations that we expect to stay and that are relevant from user point of view. Work in progress, etc. is not interesting for a design doc.

Copilot AI review requested due to automatic review settings February 16, 2026 08:42

github-actions bot added the needs-area-label An area label is needed to ensure this gets routed to the appropriate area owners label Feb 16, 2026

dotnet-policy-service bot assigned radekdoulik Feb 16, 2026

Copilot started reviewing on behalf of radekdoulik February 16, 2026 08:43 View session

radekdoulik mentioned this pull request Feb 16, 2026

[browser] no sockets #124347

Merged

radekdoulik added the area-Infrastructure-coreclr label Feb 16, 2026

github-project-automation bot added this to Runtime Infra Feb 16, 2026

radekdoulik added arch-wasm WebAssembly architecture and removed needs-area-label An area label is needed to ensure this gets routed to the appropriate area owners labels Feb 16, 2026

radekdoulik added this to the Future milestone Feb 16, 2026

radekdoulik requested review from AaronRobinsonMSFT, jkotas, lewing, pavelsavara and steveisok February 16, 2026 08:48

Copilot AI reviewed Feb 16, 2026

View reviewed changes

radekdoulik requested review from Copilot, kg and maraf February 16, 2026 08:48

Copilot started reviewing on behalf of radekdoulik February 16, 2026 08:49 View session

Update docs/design/coreclr/browser-wasm-coreclr.md

4d99b37

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI reviewed Feb 16, 2026

View reviewed changes

Apply suggestions from code review

9676ff4

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings February 16, 2026 08:54

Copilot started reviewing on behalf of radekdoulik February 16, 2026 08:55 View session

Copilot AI reviewed Feb 16, 2026

View reviewed changes

jkotas reviewed Feb 16, 2026

View reviewed changes


		### WebSocket

		Applications using the [WebSocketClient](https://learn.microsoft.com/dotnet/api/system.net.websockets.clientwebsocket) managed API require the browser to support the [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) API.

	Applications using the [WebSocketClient](https://learn.microsoft.com/dotnet/api/system.net.websockets.clientwebsocket) managed API require the browser to support the [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) API.
	Applications using the [ClientWebSocket](https://learn.microsoft.com/dotnet/api/system.net.websockets.clientwebsocket) managed API require the browser to support the [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) API.

Comments

Conversation

radekdoulik commented Feb 16, 2026

Uh oh!

dotnet-policy-service bot commented Feb 16, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

jkotas Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

jkotas Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

jkotas Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

jkotas Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

jkotas Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

jkotas Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants