Introduction to Wasmtime for .NET

Wasmtime is a standalone runtime capable of executing WebAssembly outside of a web browser.

Wasmtime for .NET is a .NET API for Wasmtime. It enables .NET developers to easily instantiate and execute WebAssembly modules.

For this tutorial, we will create a WebAssembly module from a program written in Rust and use that WebAssembly module from a .NET Core 3.0 application.

Creating a simple WebAssembly module

One of the reasons why WebAssembly is so exciting is that many languages are able to target WebAssembly. This means, for example, a plugin model based on WebAssembly could enable developers to write sandboxed, cross-platform plugins in any number of languages.

Here I've decided to use Rust for the implementation of the WebAssembly module. Rust is a modern systems programming language that can easily target WebAssembly.

If you wish to skip creating the WebAssembly module, download the prebuilt WebAssembly module from this tutorial, copy it to your .NET project directory, and continue from the Using the WebAssembly module from .NET section.

Installing a Rust toolchain

To get started with Rust, install rustup, the manager for Rust toolchains.

This will install both a rustup command and a cargo command (for the active Rust toolchain) to your PATH.

Installing the WebAssembly target

To target WebAssembly with the active Rust toolchain, install the WebAssembly target triple:

rustup target add wasm32-unknown-unknown

Creating the Rust project

Create a new Rust library project named hello:

cargo new --lib hello
cd hello

To target WebAssembly, the library needs to be built as a cdylib (dynamic library) rather than the default of a static Rust library. Add the following to the Cargo.toml file in the project root:

[lib]
crate-type = ["cdylib"]

Implementing the WebAssembly code

The WebAssembly implementation will import a print function from the host environment and pass it a string to print. It will export a run function that will invoke the imported print function.

Replace the code in src/lib.rs with the following Rust code:

extern "C" {
    fn print(address: i32, length: i32);
}

#[no_mangle]
pub unsafe extern fn run() {
    let message = "Hello world!";
    print(message.as_ptr() as i32, message.len() as i32);
}

Note that this example passes the string as a pair of address and length. This is because WebAssembly only supports a few core types (such as integers and floats) and a "string" has no native representation in WebAssembly.

In the future, WebAssembly will support interface types that will enable higher-level abstractions of types like strings so they can be represented in a natural way.

Also note that the address is not actually a physical memory address within the address space of a process but an address within the WebAssembly memory of the module. Thus the WebAssembly module has no direct access to the memory of the host environment.

Building the WebAssembly module

Use cargo build to build the WebAssembly module:

cargo build --target wasm32-unknown-unknown --release

This should create a hello.wasm file in the target/wasm32-unknown-unknown/release directory. We will use hello.wasm in the next section of the tutorial.

As this example is very simple and does not require any of the data from the custom sections of the WebAssembly module, you may use wasm-strip if you have the WebAssembly Binary Toolkit installed:

wasm-strip target/wasm32-unknown-unknown/release/hello.wasm

The resulting file should be less than 200 bytes.

Using the WebAssembly module from .NET

Installing a .NET Core 3.0 SDK

Install a .NET Core 3.0 SDK for your platform if you haven't already.

This will add a dotnet command to your PATH.

Creating the .NET Core project

The .NET program will be a simple console application, so create a new console project with dotnet new:

mkdir tutorial
cd tutorial
dotnet new console

Referencing the Wasmtime for .NET package

To use Wasmtime for .NET from the project, we need to add a reference to the Wasmtime NuGet package:

dotnet add package --version 0.0.1-alpha1 wasmtime

Note that the --version option is required because the package is currently prerelease.

This will add a PackageReference to the project file so that Wasmtime for .NET can be used.

Implementing the .NET code

Replace the contents of Program.cs with the following:

using System;
using Wasmtime;

namespace Tutorial
{
    class Host : IHost
    {
        public Instance Instance { get; set; }

        [Import("print", Module="env")]
        public void Print(int address, int length)
        {
            var message = Instance.Externs.Memories[0].ReadString(address, length);
            Console.WriteLine(message);
        }
    }

    class Program
    {
        static void Main(string[] args)
        {
            using (var engine = new Engine())
            using (var store = engine.CreateStore())
            using (var module = store.CreateModule("hello.wasm"))
            using (dynamic instance = module.Instantiate(new Host()))
            {
                instance.run();
            }
        }
    }
}

The Host class is responsible for implementing the imported functions, globals, memories, and tables for the WebAssembly module. For Wasmtime for .NET, this is done via the Import attribute applied to functions and fields of type Global<T>, MutableGlobal<T>, and Memory (support for WebAssembly tables is not yet implemented). The Instance property of the host is set during instantiation of the WebAssembly module.

Here the host is implementing an import of print in the env module, which is the default import module name for WebAssembly modules compiled using the Rust toolchain.

The Engine is used to create a Store that will store all Wasmtime runtime objects, such as WebAssembly modules and their instantiations.

A WebAssembly module instantiation is the stateful representation of a module that can be executed. Here, the code is casting the Instance to dynamic which allows us to easily invoke the run function that was exported by the WebAssembly module.

Alternatively, the run function could be invoked without using the runtime binding of the dynamic feature like this:

...
using (var instance = module.Instantiate(new Host()))
{
    instance.Externs.Functions[0].Invoke();
}
...

Building the .NET application

Use dotnet build to build the .NET application:

dotnet build

This will create a tutorial.dll in the bin/Debug/netcoreapp3.0 directory that implements the .NET Core application. An executable tutorial (or tutorial.exe on Windows) should also be present in the same directory to run the application.

Running the .NET application

Before running the application, we need to copy the hello.wasm file to the project directory.

Once the WebAssembly module is present in project directory, we can run the application:

dotnet run

Alternatively, we can execute the program directly without building the application again:

bin/Debug/netcoreapp3.0/tutorial

This should result in the following output:

Hello world!

Wrapping up

We did it! We executed a function written in Rust from .NET and a function implemented in .NET from Rust without much trouble at all. And, thanks to the design of WebAssembly, the Rust code was effectively sandboxed from accessing the memory of the .NET application.

Hopefully this introduction to Wasmtime for .NET has offered a small glipse of the potential of using WebAssembly from .NET.

One last note: Wasmtime for .NET is currently in a very early stage of development and the API might change dramatically in the future.