WebAssembly (Wasm) is an exciting new(ish) virtual machine and (assembly) instruction format. Wasm was born in the browser and is an important part of theBlazor project. The second act for Wasm is cloud computing, for apps and functions. WebAssembly System Interface (WASI) is the new enabler, providing a way for WebAssembly code to call and implement arbitrary APIs, safely and across languages. It is now possible to create WASI apps with .NET using thewasi-experimental workload in .NET 8. We’re exploring these new technologies and running .NET apps in this environment …. really, anywhere.

This post will help you understand the broadening use of Wasm and describe what’s already possible with .NET. They say that history doesn’t repeat itself, but that it rhymes. We’re back for another round of “write once, run anywhere”. WASI apps are portable binaries that run on any hardware or operating system and are not specific to any programming language. This time, it feels different. It’s not just vendor neural; it’s everything neutral.

Wasm and WASI

Wasm may be offering us a reboot of compute in the cloud, with the promise of a single cloud-native binary, higher density, and cheaper multi-tenancy. It also opens up the possibility of edge compute for the same reasons. In fact,CloudFlare andFastly already host public compute at the edge with Wasm.

Wasm is different than running an app in a Linux container, which is a (good and clever) re-packaging of existing standards and code. Wasm is more like running an app in an environment with no operating system, with just assembly code, memory, and standardized (and gated) access to the outside world (via WASI).

TheHyperlight presentation at Build 2023 (4m video) provides insight into what a Wasm-enabled cloud might look like. It demonstrates a Blazor app running in a new lighweight and secure hypervisor. Hyperlight sparks the imagination on new hosting paradigms.

WebAssembly System Interface (WASI),WebAssembly Interface Types (WIT), andWebAssembly Component Model are the key specs in this latest round of Wasm innovation. They are very much still in the design phase andundergoing significant change. This post (and the .NET 8 implementation) is oriented around WASI Preview 1. We expect the .NET 9 implementation to use WASI Preview 2.

WIT andwit-bindgen enable components written in any source language to communicate and with the host system.Implementation of WIT support for C# is lead by@silesmo. Wasm and WIT together define theApplication Binary Interface (ABI).

We expect WASI to become a standard set of WIT types that provide access tolow-level functionality (likegetting the time andreading a file). These low-level types effectively form a “Wasm standard library” across programming languages and operating systems. We’re never had standard and shared functionality that Rust devs and .NET devs, for example, could both use. There isn’t any widely-deployed historical precedent of native code that exposed APIs withOO-ish shape (like interfaces) that could be used across programming languages and operating systems.

The standard WIT types start withwasi- and define the “platform”. You can think of them in a similar way to theSystem namespace in .NET (matching the ‘S’ in WASI). Continuing the analogy, you can create your own .NET namespaces beyond theSystem ones, and the same is true with WIT.

These posts do a great job of framing WASI in more detail.

• Standardizing WASI: A system interface to run WebAssembly outside the web
• Announcing the Bytecode Alliance: Building a secure by default, composable future for WebAssembly
• WebAssembly: An Updated Roadmap for Developers

The promise on the horizon is being able to take an existing .NET app or library and compile it to a Wasm target. Our design instinct is to implement WIT interfaces relatively high into the .NET stack (like create an ADO.NET Data Provider forwasi-sql), which would enable existing code (including many existing NuGet packages) to just work, particularly for code without native dependencies.

Wasm apps are run in a Wasm runtime, likewasmtime. Much like Docker, you can configure that runtime with specific capabilities. For example, if you want Wasm code to have access to a key/value store, you canexpose a key/value interface to it, which could be backed by a local database or a cloud service.

Wasm runtimes are intended to be embeddable within apps. In fact, there is awasmtime package forhosting Wasm in .NET apps. .NET code can run as Wasm, but .NET apps can hostwasmtime?!? Yes, this space can start to seem circular. While these scenarios seem circular, theymight end up being pretty useful, vaguely similar to howAppDomains have been used. It’s also reminiscent of all the “docker in docker” scenarios.

We expect a lot more innovation, more Wasm runtimes, and more industry participants. In fact, Wasm has gradulated to aW3C spec. The W3C is a perfect home for Wasm, to let it grow as a broad industry spec, just like HTML and XML before it.

wasi-experimental workload

.NET 8 includes a new workload calledwasi-experimental. It builds on top of the Wasm functionality used by Blazor, extending it to run inwasmtime and invoke WASI interfaces. It is far from done, but already enables useful functionality.

Let’s move on from theory to demonstrating the new capabilities.

After installing the.NET 8 SDK, you can install thewasi-experimental workload.

dotnet workload install wasi-experimental

Note: This command may require admin permisions, for example withsudo on Linux and macOS.

You also need to installwasmtime to run the Wasm code you are soon going to produce.

Try a simple example with thewasi-console template.

$ dotnet new wasiconsole -o wasiconsole$ cd wasiconsole$ cat Program.cs using System;Console.WriteLine("Hello, WASI Console!");$ dotnet runWasmAppHost --runtime-config /Users/rich/wasiconsole/bin/Debug/net8.0/wasi-wasm/AppBundle/wasiconsole.runtimeconfig.jsonRunning: wasmtime run --dir . -- dotnet.wasm wasiconsoleUsing working directory: /Users/rich/wasiconsole/bin/Debug/net8.0/wasi-wasm/AppBundleHello, WASI Console!

The app was run usingwasmtime. There is no x64 or Arm64 here, just Wasm.

dotnet run is providing extra information (in the console output) to help explain what is going on. That will likely change in future. All of the interaction with the host system is managed bywasmtime.

We can look a bit deeper at theAppBundle directory.

$ ls -l bin/Release/net8.0/wasi-wasm/AppBundletotal 24872-rwxr--r--  1 rich  staff  11191074 Oct 31 07:53 dotnet.wasm-rwxr--r--  1 rich  staff   1526128 Oct 11 14:00 icudt.datdrwxr-xr-x  6 rich  staff       192 Nov 19 19:35 managed-rwxr-xr-x  1 rich  staff        48 Nov 19 19:35 run-wasmtime.sh-rw-r--r--  1 rich  staff       915 Nov 19 19:35 runtimeconfig.bindrwxr-xr-x  2 rich  staff        64 Nov 19 19:35 tmp-rw-r--r--  1 rich  staff      1457 Nov 19 19:35 wasiconsole.runtimeconfig.json$ ls -l bin/Release/net8.0/wasi-wasm/AppBundle/managed total 3432-rw-r--r--  1 rich  staff    27136 Nov 19 19:35 System.Console.dll-rw-r--r--  1 rich  staff  1711616 Nov 19 19:35 System.Private.CoreLib.dll-rw-r--r--  1 rich  staff     5632 Nov 19 19:35 System.Runtime.dll-rw-r--r--  1 rich  staff     5120 Nov 19 19:35 wasiconsole.dll

The SDK published the app into a self-contained deployment. The .NET runtime —dotnet.wasm — has already been compiled to Wasm (on our build machines). The app anddotnet.wasm are loaded together inwasmtime, which runs all the code. The actual managed code of the app — in themanaged directory — is interpreted at runtime, just like with Blazor WebAssembly.@yowl and@SingleAccretion community members have been experimenting withWasm and native AOT.

You might be wondering why we need all these files to be separate, when the obviously better option is to have onewasiconsole.wasm file. We can do that, too, but it is covered a little later in the post, since we need to install a bit more software on the machine (that doesn’t currently come with thewasi-experimental workload).

What doesRuntimeInformation tell us?

RuntimeInformation is one of my favorite types. It gives us a better sense of the target environment.

We can change the sample a tiny bit to show some more useful information.

using System;using System.Runtime.InteropServices;Console.WriteLine($"Hello {RuntimeInformation.OSDescription}:{RuntimeInformation.OSArchitecture}");Console.WriteLine($"With love from {RuntimeInformation.FrameworkDescription}");

It produces this output.

Hello WASI:WasmWith love from .NET 8.0.0

The first line is interesting. The operating system isWASI and the architecture isWasm. That makes sense, with a little more context. There is a mention earlier in the post that Wasm can be thought as “no operating system”, however, we cannot simply call itWasm since the existing browser and WASI environments are quite different. As a result, the only coherent name for this environment isWASI, whileWasm is unambigiously the “chip architecture”.

Wasm is a 32-bit compute environment, which means that 2^32 bytes are addressable. However, a Wasm runtime can be configured to usememory64, enabling access to >4GB of memory. We don’t have support for that yet.

Accessing the host file system

Wasmtime (and other Wasm runtimes) provide the option to map a host directory to a guest directory. This is similar to volume mounting with Docker from a user standpoint, however, the implementation details are different.

Let’s look at a simple app that depends of directory mounting. Itconverts markdown to HTML using theMarkdig package. It’s fair to say that Markdig wasn’t written to run as Wasm. Markdig is happy as long as a cozy managed environment can be created for it and that’s what we’ve done.

Let’s try on a Mac M1 (Arm64) machine.

$ pwd/Users/rich/git/wasm-samples/tomarkup$ dotnet publish$ cd bin/Release/net8.0/wasi-wasm/AppBundle $ cat run-wasmtime.shwasmtime run --dir . dotnet.wasm tomarkup $*$ ./run-wasmtime.sh A valid inputfile must be provided.$  wasmtime run --dir . --mapdir /markdown::/Users/rich/markdown --mapdir /tmp::/Users/rich dotnet.wasm tomarkup $* /markdown/README.md /tmp/README.html$ ls ~/*.html/Users/rich/README.html$ cat ~/markdown/README.md | head -n 3  # .NET Runtime[![Build Status](https://dev.azure.com/dnceng-public/public/_apis/build/status/dotnet/runtime/runtime?branchName=main)](https://dev.azure.com/dnceng-public/public/_build/latest?definitionId=129&branchName=main)$ cat ~/README.html | head -n 3       <h1>.NET Runtime</h1><p><a href="https://dev.azure.com/dnceng-public/public/_build/latest?definitionId=129&amp;branchName=main"><img src="https://dev.azure.com/dnceng-public/public/_apis/build/status/dotnet/runtime/runtime?branchName=main" alt="Build Status" /></a><a href="https://github.com/dotnet/runtime/labels/help%20wanted"><img src="https://img.shields.io/github/issues/dotnet/runtime/help%20wanted?style=flat-square&amp;color=%232EA043&amp;label=help%20wanted" alt="Help Wanted" /></a>

--mapdir is mounting the directories, from host to guest.

As you can see, amarkdown file has been converted to HTML. The first three lines of each file have been shown for brevity.

The CLI gestures required for directory mounting are currently a bit inconvenient. That’s something we’ll need to look at in a future release. It’s a really a question of howdotnet run andwasmtime run should relate.

But can it word count?

I recently publishedThe Convenience of System.IO, which focused on word counting. Can we get the same code to run as Wasm and see how fast it runs?

The word counting benchmarks in that post were run on Linux x64. Let’s keep that the same, but run as Wasm this time.

$ pwd/Users/rich/git/convenience/wordcount/count$ grep asm count.csproj     <RuntimeIdentifier>wasi-wasm</RuntimeIdentifier>    <WasmSingleFileBundle>true</WasmSingleFileBundle>$ dotnet publish$ cd bin/Release/net8.0/wasi-wasm/AppBundle/$ WASMTIME_NEW_CLI=0 wasmtime run --mapdir /text::/home/rich/git/convenience/wordcount count.wasm $* /text/Clarissa_Harlowe    11716  110023  610515 /text/Clarissa_Harlowe/clarissa_volume1.txt    12124  110407  610557 /text/Clarissa_Harlowe/clarissa_volume2.txt    11961  109622  606948 /text/Clarissa_Harlowe/clarissa_volume3.txt    12168  111908  625888 /text/Clarissa_Harlowe/clarissa_volume4.txt    12626  108593  614062 /text/Clarissa_Harlowe/clarissa_volume5.txt    12434  107576  607619 /text/Clarissa_Harlowe/clarissa_volume6.txt    12818  112713  628322 /text/Clarissa_Harlowe/clarissa_volume7.txt    12331  109785  611792 /text/Clarissa_Harlowe/clarissa_volume8.txt    11771  104934  598265 /text/Clarissa_Harlowe/clarissa_volume9.txt        9     153    1044 /text/Clarissa_Harlowe/summary.md   109958  985714  5515012 total

I updated theproject file to include<RuntimeIdentifier>wasi-wasm</RuntimeIdentifier> and<WasmSingleFileBundle>true</WasmSingleFileBundle> and commented out thePublishAot related properties. I also added aruntimeconfig.template.json file. No changes were made to the app code.

We now have the whole app in a single file bundle.

$ ls -l bin/Release/net8.0/wasi-wasm/AppBundle/total 6684-rw-r--r-- 1 rich rich    1397 Nov 19 19:59 count.runtimeconfig.json-rwxr-xr-x 1 rich rich 6827282 Nov 19 19:59 count.wasm-rw-r--r-- 1 rich rich     915 Nov 19 19:59 runtimeconfig.bin-rwxr-xr-x 1 rich rich      27 Nov 19 19:59 run-wasmtime.shdrwxr-xr-x 2 rich rich    4096 Nov 19 19:59 tmp

That looks better. The app is just shy of 7MB. I had to install theWASI-SDK to use theWasmSingleFileBundle property and set an environment variable to enabledotnet publish to find the required tools.

$ echo $WASI_SDK_PATH/home/rich/wasi-sdk/wasi-sdk-20.0/

There was a recent breaking change in wasmtime. I chose to useWASMTIME_NEW_CLI=0 to get back to the old behavior for running the sample.

Let’s get back to performance. First, run as wasm (executing managed code via an interpreter):

$ time WASMTIME_NEW_CLI=0 wasmtime run --mapdir /text::/home/rich/git/convenience/wordcount count.wasm $* /text/Clarissa_Harlowe    11716  110023  610515 /text/Clarissa_Harlowe/clarissa_volume1.txt    12124  110407  610557 /text/Clarissa_Harlowe/clarissa_volume2.txt    11961  109622  606948 /text/Clarissa_Harlowe/clarissa_volume3.txt    12168  111908  625888 /text/Clarissa_Harlowe/clarissa_volume4.txt    12626  108593  614062 /text/Clarissa_Harlowe/clarissa_volume5.txt    12434  107576  607619 /text/Clarissa_Harlowe/clarissa_volume6.txt    12818  112713  628322 /text/Clarissa_Harlowe/clarissa_volume7.txt    12331  109785  611792 /text/Clarissa_Harlowe/clarissa_volume8.txt    11771  104934  598265 /text/Clarissa_Harlowe/clarissa_volume9.txt        9     153    1044 /text/Clarissa_Harlowe/summary.md   109958  985714  5515012 totalElapsed time (ms): 821Elapsed time (us): 821223.8real    0m0.897suser    0m0.846ssys 0m0.030s

Now with our (even more)experimental native AOT support for Wasm.

$ time WASMTIME_NEW_CLI=0 wasmtime run --mapdir /text::/home/rich/git/convenience/wordcount count.wasm $* /text/Clarissa_Harlowe    11716  110023  610515 /text/Clarissa_Harlowe/clarissa_volume1.txt    12124  110407  610557 /text/Clarissa_Harlowe/clarissa_volume2.txt    11961  109622  606948 /text/Clarissa_Harlowe/clarissa_volume3.txt    12168  111908  625888 /text/Clarissa_Harlowe/clarissa_volume4.txt    12626  108593  614062 /text/Clarissa_Harlowe/clarissa_volume5.txt    12434  107576  607619 /text/Clarissa_Harlowe/clarissa_volume6.txt    12818  112713  628322 /text/Clarissa_Harlowe/clarissa_volume7.txt    12331  109785  611792 /text/Clarissa_Harlowe/clarissa_volume8.txt    11771  104934  598265 /text/Clarissa_Harlowe/clarissa_volume9.txt        9     153    1044 /text/Clarissa_Harlowe/summary.md   109958  985714  5515012 totalElapsed time (ms): 60Elapsed time (us): 60322.2real    0m0.107suser    0m0.064ssys 0m0.045s

Now, run with CoreCLR on Linux x64:

$ time ./app/count ../Clarissa_Harlowe/    11716  110023  610515 ../Clarissa_Harlowe/clarissa_volume1.txt    12124  110407  610557 ../Clarissa_Harlowe/clarissa_volume2.txt    11961  109622  606948 ../Clarissa_Harlowe/clarissa_volume3.txt    12168  111908  625888 ../Clarissa_Harlowe/clarissa_volume4.txt    12626  108593  614062 ../Clarissa_Harlowe/clarissa_volume5.txt    12434  107576  607619 ../Clarissa_Harlowe/clarissa_volume6.txt    12818  112713  628322 ../Clarissa_Harlowe/clarissa_volume7.txt    12331  109785  611792 ../Clarissa_Harlowe/clarissa_volume8.txt    11771  104934  598265 ../Clarissa_Harlowe/clarissa_volume9.txt        9     153    1044 ../Clarissa_Harlowe/summary.md   109958  985714  5515012 totalElapsed time (ms): 77Elapsed time (us): 77252.9real    0m0.128suser    0m0.096ssys 0m0.014s

Those are interesting results. We’ve got interpretation, AOT, and JIT code generation approaches to compare. The Wasm intepreter is able to count (just shy of) one million words in just under one second while AOT-compiled Wasm and the JIT runtime can do the same around 100 milliseconds.

Note:Main method is the time to runmain, as measured byStopWatch.Process is the complete process duration, as measured bytime.

This chart shows all of the results in context, including those in theThe convenience of System.IO post.

wasmtime JIT compiles the Wasm code to the target environment (in this case to Linux+x64). It’s possible to AOT the Wasm code, usingwamr, for example. I’ll leave that for another post.

Light-weight functions

Hmmm … But if we were using the Wasm more like a typical function than an app, we might not be counting a million words, but doing something more light-weight. Let’s re-run the comparison, but with the smallest file instead.

With Wasm, using our interpreter:

$ time WASMTIME_NEW_CLI=0 wasmtime run --mapdir /text::/home/rich/git/convenience/wordcount count.wasm $* /text/Clarissa_Harlowe/summary.md        9     153    1044 /text/Clarissa_Harlowe/summary.mdElapsed time (ms): 21Elapsed time (us): 21020.8real    0m0.098suser    0m0.083ssys 0m0.014s

With Wasm and native AOT:

$ time WASMTIME_NEW_CLI=0 wasmtime run --mapdir /text::/home/rich/git/convenience/wordcount count.wasm $* /text/Clarissa_Harlowe/summary.md        9     153    1044 /text/Clarissa_Harlowe/summary.mdElapsed time (ms): 0Elapsed time (us): 825.3real    0m0.048suser    0m0.035ssys 0m0.014s

Again, with CoreCLR:

$ time ./app/count ../Clarissa_Harlowe/summary.md         9     153    1044 ../Clarissa_Harlowe/summary.mdElapsed time (ms): 16Elapsed time (us): 16100real    0m0.063suser    0m0.027ssys 0m0.019s

This chart shows all of the results in context, this time for the smaller document.

Interesting. For a smaller workload, the performance differences between some of these options starts to close. We can also see the differences in runtime startup costs. It’s too early to say, but these dynamics may be a key consideration for this technology. An important caveat is that word counting is just one scenario and other scenarios may have quite different results. For now, this sample is providing a sufficient taste of what to expect.

This is all still early days. As we get farther, we’ll want to test more interesting scenarios to developer a more representative understanding. I’m also sure that some of these performance numbers will improve.

Aslight improvement in functionality

The promise of WASI is being able to rely on a set of interfaces (and matching implementations) with rich functionality.SpiderLighting delivers on this promise.

SpiderLightning: A set of WIT interfaces that abstract distributed application capabilities and a runtime CLI for running Wasm applications that use these capabilities.

As stated earlier, WASI is intended to define the same kind of platform functionality we have with theSystem namespace (but a small subset of that). You can see the interface definitions for (at least one vision of) that in the SpiderLightingwit directory.

If you’ve got wits about you, then use your wits

You should be able to walk up to anyWIT interface, reference it, see its full type shape, and start coding with it. We’re still a couple steps away from the final experience, but that’s the vision.

SpiderLighting ships a handy CLI tool calledslight that wires upwasmtime, your app, theWASI SDK and any of the WIT implementations required by your app (as declared in aslightfile.toml).

The SpiderLighting team told us they builtslight (and related components) as a tool to help them develop thewasi-cloud-core specification, to enable serverless capabilities. In the near future, we expect other app hosts, likeFermyon Spin, to use wasi-cloud-core interfaces and then we’d use one of those hosts instead ofslight.

We have a set ofSpiderlight samples. The following sample creates a WASI key-value store and then prints to the console. Note thatdotnet run is usingslight as an implementation detail.

using SpiderLightning;using var keyValue = new KeyValue("placeholder-name");keyValue.Set("somekey", "Hello from .NET. This value is from a SpiderLightning key-value store.");Console.WriteLine(keyValue.GetString("somekey"));

Remember thatKeyValue isn’t a C# type but a WASI interface projected into C#.

Here’s what the code looks like when run.

$ pwd/home/rich/git/spiderlightning-dotnet$ docker run --rm -it -v $(pwd):/source -w /source/sample/ConsoleApp wasi-sdk dotnet run -c ReleaseHello from .NET. This value is from a SpiderLightning key-value store.

I’m running the app in acontainer that has all the required dependencies installed. Can containers and WASI be used together? For sure.

You can build apps that rely on the WASI SDK in alimited set of environments and run them withslight in alarger set of environments. Windows and macOS Arm64 seem to be worst off for support. That will certainly change over time.

Web scenarios

A lot of the interest in WASI is to enable hosting small and portable Wasm functions and apps. A key aspect of that is using some form of web programming model. At the moment, we don’t have ASP.NET Core enabled with WASI. For now, we’ve exposed thehttp-server WASI type.

It enables thefollowing pattern.

HttpServer.OnIncomingRequest(request =>{    return new HttpResponse(200)        .WithBody($"<h1>Hello!</h1> You did a {request.Method} request to {request.Uri} with {request.Headers.Count} headers")        .WithHeaders(new[] { KeyValuePair.Create("content-type", "text/html") });});

That’s a bit low-level. Thedelegate also isn’t async friendly. Here’ssome hints into how async might eventually work.

I tried writing abigger sample with this API. It’s currently blocked because we don’t have a way to callhttps endpoints. I could have worked around that by copying all the required JSON files locally, but wouldn’t be nearly as compelling.

This area is the most interesting, but is also the least defined. We expect that we’re at least a year away from being able to run what we all consider real web apps and functions. We’re aiming for a model where you don’t have to change much of your code to use Wasm as a deployment target.

Experiment

The WASI workload is currently an experiment, hence the workload name. It will remain an experiment at least until WASI itelf has a stable 1.0 release. We cannot predict with any certainty when that will be.

There are several backlog items to investigate and resolve:

• Integrated debugging
• AOT support
• dotnet run withwasmtime CLI arguments
• Support for more WASI interfaces, likely via betterwitbindgen support

Closing

The higher-level story is that we’ve been able to adapt our Blazor Wasm implementation — and really .NET as a whole — to this new frontier of portable computing. A lot already works, as demonstrated by these few demos.

You can try out everything (and more) you’ve read in this post with .NET 8. Start with the following command, to install the required software.

dotnet workload install wasi-experimental

Over the next year, we’ll be focused on improving the capability and UX of our current implementation and following along with the general evolution of WASI. We’re also looking forward to watching how cloud teams adopt WASI within their services. To date, we’ve been building enabling technology. As we get farther, we’ll consider focusing on more targeting experiences that pair with a cloud service. For now, that’s all future looking, like the rest of WASI.

Brevity is the soul of wit. — William Shakespeare

If you got this far, you can appreciate that you wouldn’t be nearly so well informed if I’d been brief. But with the length and detail of this post, I’m at my wit’s end.