[browser][coreCLR] Loading WebCIL 1.0 by pavelsavara · Pull Request #124268 · dotnet/runtime

pavelsavara · 2026-02-11T12:37:35Z

Enable WebCIL support for CoreCLR on Browser/WASM

Fixes #120248

WebCIL format v1.0 with 16-byte section alignment and IMAGE_SECTION_HEADER format

Bumps WebCIL version from 0.0 to 1.0.

The WebcilConverter now emits section data at 16-byte-aligned offsets, ensuring RVA static fields backing ReadOnlySpan<T> over types up to Vector128<T> retain their natural alignment.
The section headers are full IMAGE_SECTION_HEADER that makes the code of reading much simpler.

CoreCLR PEDecoder: native WebCIL parsing

New src/coreclr/inc/webcil.h defines WebcilHeader and WebcilSectionHeader C structs with static_assert size checks. PEDecoder gains:

FLAG_WEBCIL flag; HasWebcilHeaders() validates magic, version, section count/bounds/ordering and synthesizes IMAGE_SECTION_HEADER[] from WebCIL sections so RvaToSection()/RvaToOffset() work uniformly.
HasHeaders() / CheckHeaders() as unified entry points that dispatch to WebCIL or NT paths.
WebCIL-aware HasDirectoryEntry(), GetDirectoryEntryData() (handles COMHEADER and DEBUG entries via WebcilHeader fields with explicit range validation against section data).
CheckCorHeader() and CheckILOnly() WebCIL branches (WebCIL images are always IL-only by definition).
GetPEKindAndMachine() reports peILonly / IMAGE_FILE_MACHINE_I386 for WebCIL.
GetNumberOfRvaAndSizes() moved from public to private API; GetNumberOfSections() / FindFirstSection() delegate to synthesized headers for WebCIL.
Preconditions across the file generalized from CheckNTHeaders() to CheckHeaders() / HasHeaders().

PEImage / PEAssembly integration

PEImage exposes HasHeaders() forwarding to PEDecoder::HasHeaders(). PEAssembly uses HasHeaders() instead of HasNTHeaders() for metadata access.

Browser host loader: WebCIL module instantiation

New instantiateWebCILModule() in host assets:
- instantiates the .wasm wrapper as a WebAssembly module
- calls getWebcilSize/getWebcilPayload exports to extract the raw WebCIL
- copies the payload into 16-byte aligned memory, registers it under the .dll virtual path.
New getWasmMemory / getWasmTable
Enabling WebCIL by default for CoreCLR-on-WASM via WasmEnableWebcil.

DAC support gap

All WebCIL code paths in PEDecoder are gated behind #ifdef TARGET_BROWSER, which is mutually exclusive with DACCESS_COMPILE.
Should we drop #ifdef TARGET_BROWSER ? Or build target specific DAC binaries ?
Follow up in #124467

(func $getWebcilPayload (;1;) (export "getWebcilPayload") (param $d (;0;) i32) (param $n (;1;) i32)
    local.get $d
    i32.const 0
    local.get $n
    memory.init 1
)

dotnet-policy-service · 2026-02-11T12:38:25Z

Tagging subscribers to this area: @agocke, @jeffschwMSFT, @elinor-fung
See info in area-owners.md if you want to be subscribed.

Copilot

Pull request overview

This PR adds support for loading WebCIL version 1.0 assemblies in CoreCLR on browser/WASM targets. WebCIL is an alternative container format for ECMA-335 assemblies that strips PE headers and packages assemblies as WebAssembly modules with a .wasm extension, helping avoid issues with firewalls/antivirus software that block .dll files.

Changes:

Added WebCILImageLayout C++ class that extends PEImageLayout to handle WebCIL format, parsing WebCIL headers and mapping RVAs to file offsets
Implemented instantiateWebCILModule in TypeScript that instantiates WebCIL .wasm modules and extracts assembly payloads into aligned memory
Enabled WebCIL support for CoreCLR by removing WasmEnableWebcil=false restrictions and updating test configurations

Reviewed changes

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

Show a summary per file

File	Description
src/native/libs/Common/JavaScript/types/public-api.ts	Added "webcil1" asset behavior type
src/native/libs/Common/JavaScript/types/exchange.ts	Added instantiateWebCILModule to BrowserHost exports
src/native/libs/Common/JavaScript/cross-module/index.ts	Updated export table to include instantiateWebCILModule
src/native/corehost/browserhost/loader/dotnet.d.ts	Added "webcil1" type definition
src/native/corehost/browserhost/loader/assets.ts	Added WebCIL detection and loading logic, mapping .wasm to .dll paths
src/native/corehost/browserhost/host/index.ts	Exported instantiateWebCILModule function
src/native/corehost/browserhost/host/host.ts	Updated assembly path mapping to replace .wasm with .dll
src/native/corehost/browserhost/host/assets.ts	Implemented instantiateWebCILModule to extract WebCIL payload and register assemblies
src/mono/wasm/Wasm.Build.Tests/Common/BuildEnvironment.cs	Removed CoreCLR restriction for WebCIL in tests
src/mono/browser/build/WasmApp.InTree.props	Removed WasmEnableWebcil=false for CoreCLR, updated TODO comment
src/coreclr/vm/webcildecoder.cpp	New file implementing WebCILImageLayout class for parsing and validating WebCIL format
src/coreclr/vm/peimagelayout.h	Added WebCIL header structures and WebCILImageLayout class declaration
src/coreclr/vm/peimagelayout.cpp	Added WebCIL format detection in LoadFlat
src/coreclr/vm/peassembly.cpp	Excluded 32-bit NT headers check for TARGET_BROWSER, added braces for consistency
src/coreclr/vm/coreassemblyspec.cpp	Added braces around single-statement if bodies
src/coreclr/vm/CMakeLists.txt	Added webcildecoder.cpp to browser build
src/coreclr/inc/pedecoder.h	Made specific PEDecoder methods virtual for browser target to enable WebCILImageLayout overrides
eng/testing/tests.browser.targets	Removed WasmEnableWebcil=false for CoreCLR, updated TODO comment

src/coreclr/vm/webcildecoder.cpp

davidwrighton · 2026-02-11T15:38:15Z

Please have @elinor-fung look at this

src/coreclr/vm/peimagelayout.h

src/coreclr/vm/webcildecoder.cpp

Copilot

Pull request overview

Copilot reviewed 18 out of 19 changed files in this pull request and generated 7 comments.

eng/testing/tests.browser.targets

src/coreclr/vm/webcildecoder.cpp

src/native/corehost/browserhost/host/assets.ts

src/native/corehost/browserhost/loader/assets.ts

src/mono/browser/build/WasmApp.InTree.props

Copilot

Pull request overview

Copilot reviewed 18 out of 19 changed files in this pull request and generated 4 comments.

src/coreclr/vm/webcildecoder.cpp

src/native/corehost/browserhost/host/assets.ts

src/coreclr/vm/webcildecoder.cpp

Copilot

Pull request overview

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

src/coreclr/utilcode/pedecoder.cpp

Copilot

Pull request overview

Copilot reviewed 45 out of 46 changed files in this pull request and generated 4 comments.

src/tasks/Microsoft.NET.WebAssembly.Webcil/WebcilWasmWrapper.cs

src/native/corehost/browserhost/loader/assets.ts

src/tasks/Microsoft.NET.WebAssembly.Webcil/WebcilReader.cs

src/mono/wasm/Wasm.Build.Tests/Common/BuildEnvironment.cs

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

Copilot

Pull request overview

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

src/tasks/Microsoft.NET.WebAssembly.Webcil/WebcilConverter.cs

src/tasks/Microsoft.NET.WebAssembly.Webcil/WebcilWasmWrapper.cs

Copilot

Pull request overview

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

src/coreclr/utilcode/pedecoder.cpp

adamperlin · 2026-02-18T18:52:58Z

src/native/corehost/browserhost/host/host.ts


-    const assemblyPaths = loaderConfig.resources!.assembly.map(asset => asset.virtualPath);
-    const coreAssemblyPaths = loaderConfig.resources!.coreAssembly.map(asset => asset.virtualPath);
+    const assemblyPaths = loaderConfig.resources!.assembly.map(asset => asset.virtualPath.replace(/\.wasm$/, ".dll"));


Assemblies need to end in .dll for compatibility reasons?

I think there are many places in the codebase that assume .DLL or .EXE

runtime/src/coreclr/binder/utils.cpp

Lines 182 to 183 in f6777ec

const SString sDll(SString::Literal, W(".dll"));

const SString sExe(SString::Literal, W(".exe"));

runtime/src/coreclr/hosts/corerun/corerun.cpp

Lines 136 to 137 in f6777ec

W(".dll"),

W(".exe"),

Is it worth adding another extension ?

That I'm not sure about. If there are a lot of places that make this assumption then it might not be so clean to add another extension. @jkotas do you have any thoughts on this?

Right now we do not support loading Webcil .wasm files from Virtual File System (VFS), they are all in-memory only.

Hmm I'm not super familiar with VFS. Can you explain a little more about what the loading workflow looks like right now? Say I've built the runtime + browser host, then I compile a hello-world.dll assembly with crossgen into hello-world.wasm, and I want to load it and run it. What would that look like?

That's a lecture request 🤣

For browserhost running in browser, this is heavily async code that downloads all necessary assets and installs them.

runtime/src/native/corehost/browserhost/loader/run.ts

Line 25 in f6777ec

export async function createRuntime(downloadOnly: boolean): Promise<any> {

You can't use WASM memory or the VFS until emscripten POSIX emulator is up and running.

After we have POSIX "process" and CoreLib in memory, we can start the CoreCLR VM.

After we have the rest of assemblies, we can start the application (managed Main).

For corerun running in NodeJS, this is much simpler, but similar. It uses real file system of the host to load DLLs. I didn't implement WebCIL loader for corerun. It doesn't implement many other features.

@jkotas do you have any thoughts on this?
Right now we do not support loading Webcil .wasm files from Virtual File System (VFS), they are all in-memory only.

Do we simulate file paths in browser? For example, is Assembly.Location non-empty in browser?

If the assembly file path is user visible, it makes sense to keep using .dll as the suffix.
If the assembly file path is just an internal detail, it does not harm to use .dll as the suffix.

Copilot

Pull request overview

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

src/native/corehost/browserhost/loader/assets.ts

pavelsavara · 2026-02-18T20:47:19Z

What would the RiuJIT team workflow look like for R2R.wasm ?
Loading .wasm module is JavaScript action, It can't be done from C/C++ of the corerun.
There is little src\coreclr\hosts\corerun\wasm\libCorerun.js which could host such code.
How would it be triggered ? Would the VM call pinvoke_override for it ? Or external_assembly_probe ?
Because we can't let the VM just load it from the disk as data (as corerun does for IL only DLL files).

adamperlin · 2026-02-18T21:30:20Z

What would the RiuJIT team workflow look like for R2R.wasm ? Loading .wasm module is JavaScript action, It can't be done from C/C++ of the corerun. There is little src\coreclr\hosts\corerun\wasm\libCorerun.js which could host such code. How would it be triggered ? Would the VM call pinvoke_override for it ? Or external_assembly_probe ? Because we can't let the VM just load it from the disk as data (as corerun does for IL only DLL files).

I don't know if we're entirely sure of this yet. I think right now, our priority is whatever workflow is easiest to implement so that we can test codegen as soon as possible. What has your testing workflow been @pavelsavara? I'd be curious about @kg's perspective here as well.

pavelsavara · 2026-02-19T08:39:58Z

What has your testing workflow been @pavelsavara?

I'm used to test with full WASM SDK +http server + browser. The WASM SDK is MSBuild scripts that we ship. It prepares all necessary assets into a form that could be hosted on HTTP server. It also creates manifest - configuration for the browserhost loader, with list of all assets to download. For developers outside of my team, this seems too much.

So, I'm thinking, what's the current R2R inner dev loop for your team, when you test R2R for windows or iOS ?
The VM requesting R2R image would be similar to that, just not dlopen.
What is the call stack for loading R2R image on windows ?
How can I try ? What command lines you use to build and run it ?

I suggest that I could implement loading of R2R.wasm into corerun in next PR, if corerun is the way ...
I will need a sample of R2R.wasm file and a sample app that wants to load it.

# Conflicts: # src/native/corehost/browserhost/loader/assets.ts # src/native/libs/System.Native.Browser/native/index.ts

Copilot

Pull request overview

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

Copilot · 2026-02-19T15:55:27Z

src/tasks/Microsoft.NET.WebAssembly.Webcil/WebcilWasmWrapper.cs

        byte[] ulebSectionSize = ULEB128Encode(dataSectionSize);

        if (putativeULEBDataSectionSize.Length != ulebSectionSize.Length)
            throw new InvalidOperationException  ("adding padding would cause data section's encoded length to chane"); // TODO: fixme: there's upto one extra byte to encode the section length - take away a padding byte.


Typo in error message: "chane" should be "change".

adamperlin · 2026-02-19T23:40:59Z

What has your testing workflow been @pavelsavara?

So, I'm thinking, what's the current R2R inner dev loop for your team, when you test R2R for windows or iOS ? The VM requesting R2R image would be similar to that, just not dlopen. What is the call stack for loading R2R image on windows ? How can I try ? What command lines you use to build and run it ?

I suggest that I could implement loading of R2R.wasm into corerun in next PR, if corerun is the way ... I will need a sample of R2R.wasm file and a sample app that wants to load it.

I haven't done any testing of R2R so far for windows or ios and so I don't have as much context there. However, it sounds like automated tests are generally executed with corerun so that may also point to corerun being what we want to use here. I believe on windows you can execute an R2R image output from crossgen directly with dotnet or with a locally built corerun, if the image has an entrypoint!

If we implement support in corerun, would we then be able to do something like, node /my/build/corerun.js my-r2r-app.wasm? That's assuming the app has an entry point already. That would be a very nice and simple dev loop! Do you have any pointers on what a sample app might look like here? I am truly thinking of simple, self-contained test assemblies for executing basic generated code, i.e.,

// No external dependencies besides corlib
class WasmTest 
{
  public static void Main()
  {
     CodegenTestEntrypoint();
  }
}

pavelsavara added this to the 11.0.0 milestone Feb 11, 2026

pavelsavara requested review from adamperlin, davidwrighton and jkotas February 11, 2026 12:37

pavelsavara self-assigned this Feb 11, 2026

pavelsavara added the arch-wasm WebAssembly architecture label Feb 11, 2026

Copilot AI review requested due to automatic review settings February 11, 2026 12:37

pavelsavara added area-Host os-browser Browser variant of arch-wasm labels Feb 11, 2026

Copilot started reviewing on behalf of pavelsavara February 11, 2026 12:38 View session

Copilot AI reviewed Feb 11, 2026

View reviewed changes

src/coreclr/vm/webcildecoder.cpp Outdated Show resolved Hide resolved

pavelsavara requested a review from elinor-fung February 11, 2026 15:47

jkotas reviewed Feb 11, 2026

View reviewed changes

src/coreclr/vm/peimagelayout.h Outdated Show resolved Hide resolved

jkotas reviewed Feb 11, 2026

View reviewed changes

src/coreclr/vm/webcildecoder.cpp Outdated Show resolved Hide resolved

Copilot AI review requested due to automatic review settings February 11, 2026 20:39

Copilot started reviewing on behalf of pavelsavara February 11, 2026 20:40 View session

Copilot AI reviewed Feb 11, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings February 11, 2026 21:06

Copilot started reviewing on behalf of pavelsavara February 11, 2026 21:07 View session

Copilot AI reviewed Feb 11, 2026

View reviewed changes

src/coreclr/vm/webcildecoder.cpp Outdated Show resolved Hide resolved

src/coreclr/vm/webcildecoder.cpp Outdated Show resolved Hide resolved

src/native/corehost/browserhost/host/assets.ts Outdated Show resolved Hide resolved

src/coreclr/vm/webcildecoder.cpp Outdated Show resolved Hide resolved

This was referenced Feb 12, 2026

Unable to pull image from mcr.microsoft.com #117164

Open

System.Security.Cryptography.CryptographicException : m_safeCertContext is an invalid handle. #124279

Closed

pavelsavara force-pushed the loading_webcil1 branch from 5adef6d to 102345a Compare February 12, 2026 21:28

Copilot AI review requested due to automatic review settings February 12, 2026 21:28

Copilot started reviewing on behalf of pavelsavara February 12, 2026 21:29 View session

Copilot AI reviewed Feb 12, 2026

View reviewed changes

src/coreclr/utilcode/pedecoder.cpp Show resolved Hide resolved

Copilot AI review requested due to automatic review settings February 12, 2026 21:57

Copilot started reviewing on behalf of pavelsavara February 12, 2026 21:58 View session

Copilot AI reviewed Feb 18, 2026

View reviewed changes

Update src/mono/wasm/Wasm.Build.Tests/Common/BuildEnvironment.cs

22f47a4

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

Copilot AI review requested due to automatic review settings February 18, 2026 13:18

Copilot started reviewing on behalf of pavelsavara February 18, 2026 13:19 View session

Copilot AI reviewed Feb 18, 2026

View reviewed changes

src/tasks/Microsoft.NET.WebAssembly.Webcil/WebcilConverter.cs Show resolved Hide resolved

src/tasks/Microsoft.NET.WebAssembly.Webcil/WebcilWasmWrapper.cs Outdated Show resolved Hide resolved

pavelsavara added 3 commits February 18, 2026 14:42

rename to Webcil

92bb0f6

feedback

138b2ca

fix

1c53edb

Copilot AI review requested due to automatic review settings February 18, 2026 15:43

Copilot started reviewing on behalf of pavelsavara February 18, 2026 15:45 View session

Copilot AI reviewed Feb 18, 2026

View reviewed changes

src/coreclr/utilcode/pedecoder.cpp Show resolved Hide resolved

src/coreclr/utilcode/pedecoder.cpp Show resolved Hide resolved

adamperlin reviewed Feb 18, 2026

View reviewed changes

src/coreclr/utilcode/pedecoder.cpp Show resolved Hide resolved

adamperlin reviewed Feb 18, 2026

View reviewed changes

src/coreclr/utilcode/pedecoder.cpp Show resolved Hide resolved

adamperlin reviewed Feb 18, 2026

View reviewed changes

build-analysis bot mentioned this pull request Feb 18, 2026

Checkout failure: "Git fetch failed with exit code 128" dotnet/arcade#9009

Open

2 tasks

adamperlin mentioned this pull request Feb 18, 2026

Avoid const_cast in methods on PEDecoder #124569

Open

pavelsavara added 2 commits February 18, 2026 21:19

cleanup

73ab4f6

Merge branch 'main' into loading_webcil1

2b4b14e

Copilot AI review requested due to automatic review settings February 18, 2026 20:19

Copilot started reviewing on behalf of pavelsavara February 18, 2026 20:20 View session

Copilot AI reviewed Feb 18, 2026

View reviewed changes

src/native/corehost/browserhost/loader/assets.ts Show resolved Hide resolved

pavelsavara added 2 commits February 19, 2026 16:41

Merge branch 'main' into loading_webcil1

0506d99

# Conflicts: # src/native/corehost/browserhost/loader/assets.ts # src/native/libs/System.Native.Browser/native/index.ts

rename WebcilHeader.cs

928ff8d

Copilot AI review requested due to automatic review settings February 19, 2026 15:43

Copilot started reviewing on behalf of pavelsavara February 19, 2026 15:44 View session

Copilot AI reviewed Feb 19, 2026

View reviewed changes

	const SString sDll(SString::Literal, W(".dll"));
	const SString sExe(SString::Literal, W(".exe"));

Conversation

pavelsavara commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Enable WebCIL support for CoreCLR on Browser/WASM

WebCIL format v1.0 with 16-byte section alignment and IMAGE_SECTION_HEADER format

CoreCLR PEDecoder: native WebCIL parsing

PEImage / PEAssembly integration

Browser host loader: WebCIL module instantiation

DAC support gap

Uh oh!

dotnet-policy-service bot commented Feb 11, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

davidwrighton commented Feb 11, 2026

Uh oh!

Uh oh!

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!

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!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

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!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

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!

adamperlin Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

pavelsavara Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

adamperlin Feb 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pavelsavara Feb 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

pavelsavara commented Feb 11, 2026 •

edited

Loading

adamperlin Feb 18, 2026 •

edited

Loading

pavelsavara Feb 18, 2026 •

edited

Loading

adamperlin Feb 18, 2026 •

edited

Loading

pavelsavara Feb 18, 2026 •

edited

Loading

adamperlin commented Feb 19, 2026 •

edited

Loading