DotWasm.Encoding 0.1.0

DotWasm

A WebAssembly runtime implemented in C# for .NET

Overview

DotWasm is an experimental WebAssembly runtime written in C#. It is implemented in 100% pure C# and supports nearly all WebAssembly 3.0 proposals, including Wasm GC.

Features

• Implemented entirely in pure C#
• Implements WebAssembly 3.0–equivalent proposals (excluding Threads)
• Nearly 100% passing the official test suite
• No dynamic code generation; compatible with NativeAOT

Requirements

DotWasm requires .NET 10.0 or above.

.NET CLI

dotnet add DotWasm

Package Structure

Package	NuGet	Description
DotWasm		Bundle containing all packages
DotWasm.Models		C# models for Wasm binaries
DotWasm.Encoding		Package providing Wasm binary decoding functionality
DotWasm.Validation		Package providing Wasm binary validation
DotWasm.Runtime		Package providing Wasm binary execution functionality

Quick Start

;; example.wat
(module
  (func $add (param $x i32) (param $y i32) (result i32)
    local.get $x
    local.get $y
    i32.add
  )
  (export "add" (func $add))
)

using DotWasm.Encoding;
using DotWasm.Runtime;

var bytes = File.ReadAllBytes("example.wasm");
var module = WasmEncoding.Decode(bytes);

var store = new WasmStore();
var linker = new WasmLinker(store);
var instance = linker.Instantiate(module);

Span<WasmValue> results = new WasmValue[1];
instance.Invoke("add", [1, 2], results);

int result = results[0].I32;
Console.WriteLine(result); // 3

Retrieving Exports

You can obtain exported globals, memories, etc. from the Wasm side using the instance.TryGetExported**() family of methods.

;; example.wat
(module
  (global $g (export "my_global") (mut i32) (i32.const 42))
)

var instance = linker.Instantiate(module);

if (instance.TryGetExportedGlobal("my_global", out var global))
{
    Console.WriteLine(global.Value.I32);
    global.Value = 100;
}

Integrating with Host Environment

Through the WasmLinker API you can provide host functions, memories, and other imports to the Wasm side.

var addFunc = new HostFunction
{
    Type = new FuncType
    {
        Parameters = [WasmTypes.I32, WasmTypes.I32],
        Results = [WasmTypes.I32],
    },
    Delegate = static (ReadOnlySpan<WasmValue> args, Span<WasmValue> results) =>
    {
        var a = args[0].I32;
        var b = args[1].I32;
        results[0] = WasmValue.FromI32(a + b);
    },
};
linker.RegisterFunction("env", "hostAdd", addFunc);

var memory = new MemoryInstance(1);
source.CopyTo(memory.Data);
linker.RegisterMemory("env", "hostMemory", memory);

var global = new GlobalInstance
{
    Mutable = true,
    ValueType = WasmTypes.I32,
    Value = 43,
};
linker.RegisterMemory("env", "hostGlobal", global);

ExternalReference

You can pass opaque host references to the Wasm side as ExternalReference.

var gameObject = new GameObject("obj");

var global = new GlobalInstance
{
    Mutable = true,
    ValueType = WasmTypes.ExternRef(isNullable: false),
    Value = ExternalReference.Create(gameObject),
};

linker.RegisterMemory("env", "object", global);

Proposals

DotWasm currently supports the following proposals:

Performance

DotWasm is designed to minimize dynamic GC allocations, but it is not currently heavily optimized for execution speed. Because DotWasm avoids dynamic code generation to support AOT, its performance lags significantly behind JIT-based runtimes like Wasmtime.

Below are benchmark results for converting a 128x128 image to grayscale.

The comparison used the following libraries:

• wasmtime-dotnet
• WaaS
• WACS

As shown above, DotWasm is considerably slower. This is a known issue and is planned to be improved before a stable release.

License

MIT License