Xamarin.Forms with Web Assembly

This guide will show you how to use Ooui.Wasm to build a Xamarin.Forms app deployed in a web assembly.

All of these steps are written using the command line on Mac, but you can instead use Visual Studio and Windows to accomplish the same thing!

1. Create a new app

mkdir MyFormsApp
cd MyFormsApp
dotnet new console

2. Reference Ooui.Wasm

Ooui.Wasm is a package that references the Ooui package and contains a build target to generate the web assembly build.

dotnet add package Ooui.Wasm

3. Reference Ooui.Forms

Ooui.Forms is a backend for Xamarin.Forms that uses Ooui.

dotnet add package Ooui.Forms

4. Build a UI

Edit Program.cs to be:

using System;
using Ooui;
using Xamarin.Forms;

namespace MyFormsApp
{
    class Program
    {
        static void Main(string[] args)
        {
            // Initialize Xamarin.Forms
            Forms.Init ();

            // Create the UI
            var page = new ContentPage();
            var stack = new StackLayout();
            var button = new Xamarin.Forms.Button {
                Text = "Click me!"
            };
            stack.Children.Add(button);
            page.Content = stack;

            // Add some logic to it
            var count = 0;
            button.Clicked += (s, e) => {
                count++;
                button.Text = $"Clicked {count} times";
            };

            // Publish a root element to be displayed
            UI.Publish("", page.GetOouiElement());
        }
    }
}

This is a little app with a button that counts its click.

This example builds the UI in code, but you can use XAML instead. Doing so from the command-line is tricky so I suggest using Visual Studio when working with XAML.

The last line of Main is important - all web assembly apps must Publish a root element to be displayed. The last line converts a Xamarin.Forms Page into the Ooui.Element that Publish expects.

5. Build the app

dotnet build

(The first time you build with Ooui.Wasm will be slow. That's because it's downloading the mono wasm SDK.)

In addition to building your app, this will also generate all the files you need to run your app in a web assembly. Those files are put in the dist directory. Let's take a look:

ls -al bin/Debug/netcoreapp2.0/dist/

-rw-r--r--  1 fak  staff      960 Mar 14 11:44 index.html
drwxr-xr-x  4 fak  staff      128 Mar 14 11:44 managed
-rw-r--r--  1 fak  staff   167240 Feb 28 20:39 mono.js
-rw-r--r--  1 fak  staff  1769591 Feb 28 20:39 mono.wasm
-rw-r--r--  1 fak  staff    14304 Mar 14 11:44 ooui.js
-rw-r--r--  1 fak  staff      284 Feb 28 20:39 server.py

• index.html is a static web page that is custom generated for your projects and lists all of its dependencies and its entry point.
• mono.js is a bridge between the browser's javascript world and mono running in the web assembly. You can blissfully ignore its banality.
• mono.wasm this is it - the big enchilada - mono running in a web assembly.
• ooui.js is the standard Ooui JS library that makes working with the DOM easy.
• server.py is a terrible hack. Sorry. So you would think you can just load index.html and see your app run. That would make sense. But that won't work. :-( Problem is, wasm is new and browsers refuse to load it from your local disk. To work around this, we need a dumb static content web server. This is it. Sorry it's in Python, let's fix that...
• managed is a directory that contains your app's assemblies. Let's look:

ls -al bin/Debug/netcoreapp2.0/dist/managed/

-rw-r--r--  1 fak  staff     4096 Mar 14 11:44 MyApp.dll
-rw-r--r--  1 fak  staff  3675136 Feb 28 20:39 mscorlib.dll

We can see that our app is only 4k, but it depends on mscorlib (as all apps do). The total app size is less than 4 MB and caches nicely. (Yes, yes, we can do better!)

6. Run the web assembly app

cd bin/Debug/netcoreapp2.0/dist
python server.py

Your app is now running on http://localhost:8000.

(If you're on Windows, you might have to install Python first.)

If you open that page you will briefly see "Loading..." and then a giant blue button will appear. Click away!

Hit Ctrl+C to kill the web server.

7. Deploying your Web App

Since web assembly apps run locally in the browser, serving them is a breeze.

Copy the dist directory to your favorite static web server. That server can be anything from Azure, to Amazon S3, to some Apache Thing running Linux Something.