Using the bootstrapper

The Uno.Wasm.Bootstrap package provides a runtime bootstrapper of the Microsoft.NET.Sdk.WebAssembly SDK from .NET 9.

This package only provides the bootstrapping features to run a .NET assembly and write to the javascript console, through Console.WriteLine. To write an app that provides UI functionalities, make sur to check out https://aka.platform.uno/get-started.

This work is based on the excellent work from @praeclarum's OOui Wasm MSBuild task.

Prepare your machine

On the command line, type the following to install the WebAssembly workload:

dotnet workload install wasm-tools

How to use the Bootstrapper with .NET 9 and later

  • Create a .NET 9 Console Application, and update it with the following basic definition:

    <Project Sdk="Microsoft.NET.Sdk.WebAssembly">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Uno.Wasm.Bootstrap" Version="9.0.*" />
</ItemGroup>

</Project>

  • Add a main entry point:

    class Program
{
    static void Main(string[] args)
    {
        Console.WriteLine("Hello from C#!");
    }
}

  • In Visual Studio 2022, press F5 to start with the debugger

  • A browser window will appear with your application

  • The output of the Console.WriteLine will appear in the javascript debugging console

How to use the Visual Studio 2022 Debugger

To enable the debugging, make sure that the following line is present in your Properties/launchSettings.json file:

"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}"

in every profile section of the file, below each "launchBrowser": true, line.

Press F5 to start debugging.

Alternate deployment methods

Install the dotnet serve tool:

dotnet tool install -g dotnet-serve

Once installed, launch the server by using the following command:

cd MyApp.Wasm
dotnet publish -c Debug
dotnet serve -d bin\Debug\net9.0\publish\wwwroot -p 8000

You application will be available http://localhost:8000.

Upgrading from previous versions of the Uno.Wasm.Bootstrap package

Moving from version 8.x to 9.x may require changing the used MSBuild SDK for your project.

  • If your project contains Sdk="Uno.Sdk", you will need to update the Uno.Sdk to 5.5 or later.
  • If your project contains Sdk="Microsoft.NET.Sdk.Web", you'll need to change it to Sdk="Microsoft.NET.Sdk.WebAssembly".

Once done, make sure to install the WebAssembly tools from .NET:

dotnet workload install wasm-tools

By default, the .NET runtime does not load all resource assemblies, but if you want to load all resources regardless of the user's culture, you can add the following to your project file:

<PropertyGroup>
    <WasmShellLoadAllSatelliteResources>true</WasmShellLoadAllSatelliteResources>
</PropertyGroup>

If you're not using the Uno.SDK and that you are using AOT with WasmShellMonoRuntimeExecutionMode set to InterpreterAndAOT, you'll also need to keep WasmShellMonoRuntimeExecutionMode and add the following:

<PropertyGroup>
   <RunAOTCompilation>true</RunAOTCompilation>
</PropertyGroup>

If not set, you may get the error error MSB4036: The "MonoAOTCompiler" task was not found".

Threading

Microsoft’s runtime team has made major changes in .NET 9 to how threads interact with the DOM and JavaScript, aiming to improve stability.

Since threading was, and continues to be an experimental feature, these changes now prevent managed code from running on the main JavaScript thread — something Uno Platform depends on.

As a result, WebAssembly threading is currently not supported in Uno Platform apps. However, as Microsoft’s runtime team is working on it, we hope that the support for threading may return in future .NET 10 preview builds.

IDBFS

In version 8.x and earlier of the bootstrapper, IDBFS support was enabled by default.

Moving the .NET 9, the default interpreter runtime does not enable it by default. Read this documentation in order to restore IDBFS support.

Interop

  • Module.mono_bind_static_method is not available anymore, you'll need to use Module.getAssemblyExports instead.
  • .NET 9 upgrades to emscripten 3.1.56 for which .bc native files are not supported properly. Use .a or .o extensions instead for native dependencies.

Deprecated APIs

  • The Uno.Wasm.Boostrap.DevServer package is not needed anymore and can be removed
  • WasmShellOutputPackagePath has been removed. Use $(PublishDir)
  • WasmShellOutputDistPath has been removed. Use $(PublishDir)
  • WasmShellBrotliCompressionQuality, WasmShellCompressedExtension and WasmShellGenerateCompressedFiles have been removed, the compression is done by the .NET SDK
  • WasmShellEnableAotGSharedVT has been removed.
  • WasmShellEnableEmscriptenWindows has been removed, the .NET SDK manages emscripten
  • WasmShellEnableLongPathSupport has been removed, the .NET SDK manages the build
  • WasmShellEnableNetCoreICUhas been removed, the .NET SDK manages localization
  • WasmShellForceDisableWSL and WasmShellForceUseWSL have been removed, Windows and Linux are supported natively by the .NET SDK.
  • WashShellGeneratePrefetchHeaders has been removed.
  • WasmShellNinjaAdditionalParameters has been removed, the .NET SDK manages the build
  • WasmShellObfuscateAssemblies, WasmShellAssembliesExtension and AssembliesFileNameObfuscationMode have been removed, the .NET SDK uses WebCIL to achieve the same result.
  • WasmShellPrintAOTSkippedMethods has been removed
  • WasmShellPThreadsPoolSize has been removed in favor of the official .NET SDK parameters
  • MonoRuntimeDebuggerEnabled has been removed, the .NET SDK manages the debugger
  • WashShellUseFileIntegrity has been removed, the .NET SDK manages the assets integrity

Bootstrapper versions and .NET runtimes

Each major version of the bootstrapper targets a different version of the .NET Runtime.

Note

Between version 3.x and 8.x, the bootstrapper is using custom builds of the runtime, maintained here: https://github.com/unoplatform/Uno.DotnetRuntime.WebAssembly

Note

Bootstrapper builds version 4.x-dev were based on developments builds of .NET 7 and were later versioned 7.x-dev to match the appropriate runtime.

Previous releases documentation