dotnet-webassembly

WebAssembly for .NET

[!NOTE] WebAssembly 3.0 is supported. WASM files that use features newer than the ratified 3.0 standard may encounter errors.

A library able to create, read, modify, write, execute, and DLL-convert WebAssembly (WASM) files from .NET-based applications.

• Zero dependencies: Execution does not use an interpreter or a 3rd party library.
• WASM instructions are mapped to their .NET CIL equivalents and converted to native machine language by the .NET JIT compiler.
• Runs in-process in .NET, providing fast interop between the host application and the loaded WASM.

Available on NuGet at https://www.nuget.org/packages/WebAssembly.

Getting Started

• Use the WebAssembly.Module class to create, read, modify, and write WebAssembly (WASM) binary files.
  • Module.ReadFromBinary reads a stream into an instance, which can then be inspected and modified through its properties.
    • Files using ratified WebAssembly 3.0 features load fine; those using newer proposals may experience errors.
  • WriteToBinary on a module instance writes binary WASM to the provided stream.
• Use the WebAssembly.Runtime.Compile class to execute WebAssembly (WASM) binary files using the .NET JIT compiler or convert it to a .NET DLL.
  • Most WASM files have many imports and exports--you'll need to cover these yourself.
  • Every ratified-3.0 spec-suite category passes, with only minor known deviations in NaN bit-pattern edge cases.
  • Proposals newer than the ratified 3.0 standard aren't supported yet.
  • Execution follows the deterministic profile: results are reproducible across hosts.
  • Saving to a DLL requires .NET 9 or higher and has several additional steps.

If you hit a problem, write a bug report with the repro steps and links to any files needed.

Sample: Create and execute a WebAssembly file in memory

…

Sample: Convert a WASM file to a .NET DLL

The saving process uses the PersistedAssemblyBuilder feature introduced in .NET 9. Aided by MetadataLoadContext, this example produces a DLL for .NET 8.

…

To use the new DLL, you directly reference it in your .csproj.

  
    bin\HelloWorld.dll 
  

Once the DLL reference is in place, you can access it just like any other .NET library.

var helloWorld = new Converted.HelloWorld((module, field) =>
{
    // Imports are defined by the original WASM and must be supplied by you.
    if (module == "env" && field == "sayc")
        return new FunctionImport(new Action(raw => Console.Write((char)raw)));

    throw new Exception($"Unknown import: {module} {field}");
});

// You can directly access anything exported by the WASM.
var result = helloWorld.main();

Other Information

• Breaking Change Log
• Examples