Steve Sanderson's Blog

Using gRPC-Web with Blazor WebAssembly

Wed, 15 Jan 2020 00:00:00 +0000

If you already know all about gRPC and gRPC-Web, you can skip ahead to adding gRPC services to a Blazor WebAssembly application. And if you just want some sample Blazor WebAssembly + gRPC-Web apps, see this repo.

The status quo

In Blazor WebAssembly, like in all other browser-based single-page app (SPA) technologies, by far the most common way to exchange data and trigger server-side operations is JSON-over-HTTP. It’s simple: the client makes an HTTP request to some pre-agreed URL, with a pre-agreed HTTP method, sending JSON data in a pre-agreed shape, and then the server performs an operation and replies with a pre-agreed HTTP-status code and JSON data in a pre-agreed shape.

This generally works well, and people who do it can often lead fulfilling lives¹. However, two weaknesses stand out:

JSON is a very verbose data format. It’s not optimised for bandwidth.
There’s no mechanism to guarantee that all these pre-agreed details of URLs, HTTP methods, status codes (etc.) are actually consistent between server and client.

What’s gRPC?

gRPC is a Remote Procedure Call (RPC) mechanism originally developed by Google. For the purposes of a SPA, you can think of it as an alternative to JSON-over-HTTP. It directly fixes the two weaknesses listed above:

It’s optimised for minimal network traffic, sending efficient binary-serialised messages
You can guarantee at compile time that the server and client agree about what endpoints exist, and what shape of data will be sent and received, without having to specify any URLs/status codes/etc.

So how does this work? To author a gRPC service, you write a .proto file which is a language-independent description of a set of RPC services and their data shapes. From this, you can code-generate strongly-typed server and client classes in whatever language you wish, so that conformity with your protocol is guaranteed at compile time. Then at runtime, gRPC deals with the (de)serialization of your data and sends/receives messages in an efficient format (protobuf by default).

Another great benefit is that it’s not REST, so you don’t have to have constant arguments with coworkers about which HTTP methods and status codes are the most blessed and auspicious ones for your scenario. It’s just simple RPC, which is all we’ve ever really wanted since we were little kids.

Why isn’t everyone already using gRPC in their SPAs?

Traditionally it’s not been possible to use gRPC from browser-based applications, because gRPC requires HTTP/2, and browsers don’t expose any APIs that let JS/WASM code control HTTP/2 requests directly.

But there is a solution! gRPC-Web is an extension to gRPC which makes it compatible with browser-based code (technically, it’s a way of doing gRPC over HTTP/1.1 requests). gRPC-Web hasn’t become prevalent yet because not many server or client frameworks have offered support for it… until now.

ASP.NET Core has offered great gRPC support since the 3.0 release. And now, building on this, we’re about to ship preview support for gRPC-Web on both server and client. If you want to dig into the details, here’s the excellent pull request from James Newton-King where it’s all implemented.

Adding gRPC services to a Blazor WebAssembly application

There’s no project template for this yet, so adding gRPC support to a Blazor WebAssembly app involves quite a lot of steps, detailed here. But the good news is that you only have to do this setup once. When you’re up and running, adding further gRPC endpoints and calling them is absolutely trivial.

First, since the gRPC-Web packages haven’t been published to NuGet.org yet, for now you’ll need to add a couple of temporary package feeds to get the nightly previews.

You can add a NuGet.config file at the root of your solution like this one. Hopefully a month or two from now this won’t be needed.

Adding gRPC services to a Blazor WebAssembly “hosted” application

If you’re hosting a Blazor WebAssembly application on ASP.NET Core server, then by default you have three projects: client, server, and shared. I’ve found that the most convenient place to define a gRPC service is in the shared project, because then its generated classes are available to both server and client.

To get started, edit your shared project’s .csproj to add references to the necessary gRPC packages:

  <ItemGroup>
    <PackageReference Include="Google.Protobuf" Version="3.11.2" />
    <PackageReference Include="Grpc.Net.Client" Version="2.27.0-dev202001100801" />
    <PackageReference Include="Grpc.Tools" Version="2.27.0-dev202001081219">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
  </ItemGroup>

If these packages won’t restore correctly, be sure you added the nightly feeds.

Now you can create a .proto file to define your services. For example, inside your shared project add a file called greet.proto, containing this:

syntax = "proto3";
option csharp_namespace = "GrpcGreeter";
package greet;

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply);
}

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}

To make the gRPC tooling generate server and client classes from this, go into your shared project’s .csproj and add this:

  <ItemGroup>
    <Protobuf Include="greet.proto" />
  </ItemGroup>

The solution should build without errors at this point.

Exposing a gRPC service from the server

In your server project, create a new class called GreeterService, containing this:

using Grpc.Core;
using GrpcGreeter;

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(HelloRequest request, ServerCallContext context)
    {
        var reply = new HelloReply { Message = $"Hello from gRPC, {request.Name}!" };
        return Task.FromResult(reply);
    }
}

This class inherits from Greeter.GreeterBase, which is generated for you automatically from the .proto file. So when you add new endpoints to the .proto, there will be new methods for you to override here to provide an implementation.

The last bit on the server is to expose this as a gRPC-Web service using the new APIs. You’ll need to reference a package for this, so in your server project’s .csproj, add the following package references:

<PackageReference Include="Grpc.AspNetCore" Version="2.27.0-dev202001100801" />
<PackageReference Include="Grpc.AspNetCore.Web" Version="2.27.0-dev202001100801" />

Now in your server’s Startup.cs file, modify ConfigureServices to add the following line:

services.AddGrpc();

Note: If you’re only going to expose gRPC services, you might not need MVC controllers any more, in which case you could remove services.AddMvc() and endpoints.MapDefaultControllerRoute() from below.

Just underneath app.AddRouting(); add the following, which deals with mapping incoming gRPC-Web requests to look like gRPC ones to the server:

app.UseGrpcWeb();

Finally, register your gRPC-Web service class inside the app.UseEndpoints block with the following line at the top of the block:

endpoints.MapGrpcService<GreeterService>().EnableGrpcWeb();

That’s it, your gRPC-Web server is ready!

Consuming a gRPC service from the client

In your client project’s .csproj, you’ll want to add references to the following two nightly packages:

<PackageReference Include="Grpc.Net.Client.Web" Version="2.27.0-dev202001100801" />
<PackageReference Include="Microsoft.AspNetCore.Blazor.Mono" Version="3.2.0-preview1.20052.1" />

The latter one is to work around an issue in Blazor WebAssembly that will be fixed in the next preview in a couple of weeks. If these packages won’t restore correctly, be sure you added the nightly feeds.

Now set up your client app’s dependency injection system to be able to provide instances of GreeterClient. This will let you invoke the gRPC service from anywhere in your client app. In the client project’s Startup.cs, add the following inside the ConfigureServices method:

services.AddSingleton(services =>
{
    // Create a gRPC-Web channel pointing to the backend server
    var httpClient = new HttpClient(new GrpcWebHandler(GrpcWebMode.GrpcWeb, new HttpClientHandler()));
    var baseUri = services.GetRequiredService<NavigationManager>().BaseUri;
    var channel = GrpcChannel.ForAddress(baseUri, new GrpcChannelOptions { HttpClient = httpClient });

    // Now we can instantiate gRPC clients for this channel
    return new Greeter.GreeterClient(channel);
});

Note that Greeter.GreeterClient is code-generated for you from the .proto file. You don’t have to implement it manually! But you will also need to add the following using statements to make the above code compile:

using GrpcGreeter;
using Grpc.Net.Client;
using Grpc.Net.Client.Web;
using Microsoft.AspNetCore.Components;
using System.Net.Http;

We’re very nearly there now! There’s a working server, and hopefully a working client. We just have to actually call some gRPC services from some UI. For example, in your Index.razor file, replace the contents with this:

@page "/"
@using GrpcGreeter
@inject Greeter.GreeterClient GreeterClient

<h1>Invoke gRPC service</h1>

<p>
    <input @bind="yourName" placeholder="Type your name" />
    <button @onclick="GetGreeting" class="btn btn-primary">Call gRPC service</button>
</p>

Server response: <strong>@serverResponse</strong>

@code {
    string yourName = "Bert";
    string serverResponse;

    async Task GetGreeting()
    {
        var request = new HelloRequest { Name = yourName };
        var reply = await GreeterClient.SayHelloAsync(request);
        serverResponse = reply.Message;
    }
}

Try it out in a browser now. The UI will look like this:

… and if you check out the requests in the dev tools’ network tab, you’ll see it’s sending and receiving binary protobuf messages:

Summary and sample

Now you’ve got the basics in place, you can go much further and use gRPC for all data exchange between server and client, if you wish. The gRPC tooling will code-generate all the data transfer classes for you, make the network traffic more efficient, as well as eliminate HTTP-over-JSON concerns like URLs, HTTP methods, status codes, and serialization.

For a fractionally more detailed example, here’s a complete Blazor WebAssembly hosted application that uses gRPC for fetching “weather forecast” data. If you’re interested in the exact steps needed to upgrade from the default JSON-based solution to a gRPC-Web one, see this diff that shows exactly what I changed.

Adding gRPC services to a Blazor WebAssembly “standalone” application

If you’re building a pure standalone Blazor WebAssembly application - not hosted on ASP.NET Core - then we can’t make any assumptions about what kind of server you will have. Let’s just say you have some gRPC-Web compatible service endpoint to call. Maybe it’s exposed by an ASP.NET Core server on some other host, or maybe it’s an Envoy gRPC-Web wrapper around another gRPC service. The only thing we’re concerned about here is configuring your Blazor WebAssembly application to consume it.

Most of the steps for setting up your client app are the same as in the “hosted” case above. However in some ways it’s a bit trickier because we can’t rely on some of the assumptions we can make in the “hosted” case. Here are the differences:

Getting and using the .proto file

Presumably your external gRPC service maintainer can supply you with the .proto file defining that service. It’s up to you to copy that into your client project and add a <Proto> item referencing it in your .csproj. For the tooling to work, you’ll also need to add package references like these.

Configuring the client DI service

Like in the “hosted” case, you’ll add code to your Startup.cs to add a gRPC-Web client service. The main difference this time is that you have to know what base URL is used to reach your external service, since we can no longer assume it’s the same base URL that your client app is being served from. So, your DI service entry may look more like the following:

services.AddSingleton(services =>
{
#if DEBUG
    var backendUrl = "https://localhost:5001"; // Local debug URL
#else
    var backendUrl = "https://some.external.url:12345"; // Production URL
#endif

    // Now we can instantiate gRPC clients for this channel
    var httpClient = new HttpClient(new GrpcWebHandler(GrpcWebMode.GrpcWeb, new HttpClientHandler()));
    var channel = GrpcChannel.ForAddress(backendUrl, new GrpcChannelOptions { HttpClient = httpClient });
    return new Greeter.GreeterClient(channel);
});

This varies the URL based on whether you built in debug mode or not.

Summary and sample

That’s it! Now your standalone Blazor WebAssembly application can consume an external gRPC-Web service. For a complete runnable example, here’s a sample standalone app that invokes a gRPC-Web service on an external URL. This sample comes with an actual gRPC-Web server for testing too, but you can consider that separate. If you want to see exactly what I changed, here’s the diff versus the default project template output.

Your feedback requested

If you want to go further with gRPC, see the ASP.NET Core gRPC docs.

Please give us feedback about your opinions and experiences with gRPC-Web, as this will help us make a choice about how and whether to make gRPC-Web a standard feature in future versions of ASP.NET Core. You can post feedback either as comments here, or perhaps better still on GitHub as an issue with “feedback” in the title.

Fulfilling lives not guaranteed ↩

Meet WebWindow, a cross-platform webview library for .NET Core

Mon, 18 Nov 2019 00:00:00 +0000

My last post investigated ways to build a .NET Core desktop/console app with a web-rendered UI without bringing in the full weight of Electron. This seems to have interested a lot of people, so I decided to upgrade it to newer technologies and add cross-platform support.

The result is a little NuGet package called WebWindow that you can add to any .NET Core console app. It can open a native OS window (Windows/Mac/Linux) containing web-based UI, without your app having to bundle either Node or Chromium.

I’ve also decoupled it from Blazor. You can now host any kind of web UI inside the window. The repo contains a sample that uses Vue.js, and another that uses Blazor.

Caution: This library is super-pre-alpha quality. If you’re thinking of building something real with this, see the notes at the end of this post. So far, this is just another prototype.

“Hello World” example

Create a new .NET Core 3 C# console application, and then add a reference to the WebWindow NuGet package:

<ItemGroup>
  <PackageReference Include="WebWindow" Version="0.1.0-20191120.3" />
</ItemGroup>

Next, add code to the Main method in your Program class.

static void Main(string[] args)
{
    var window = new WebWindow("My super app");
    window.NavigateToString("<h1>Hello, world!</h1> This window is from a .NET Core app.");
    window.WaitForExit();
}

That’s it! Now depending on which OS you’re running, your app will display a window like one of the following:

The example here uses NavigateToString(html) to render some HTML from a hardcoded .NET string. You can also use:

NavigateToUrl(url) to display content from an HTTP server (local or remote)
NavigateToLocalFile(path) to display an HTML file from the local disk, where path is absolute or relative to the current working directory. The HTML file can reference other resources such as images, JS, CSS, etc., relative to its own location on disk. Example here.

As a slightly more advanced option, you can configure the WebWindow to handle a custom scheme such as myapp:// and specify a delegate (callback) that returns arbitrary content for each URL within that scheme. Example here and here.

Once your web content is running, the low-level way to communicate between JavaScript and .NET is using the APIs window.external.sendMessage/receiveMessage in JS (example) and webWindowInstance.SendMessage and webWindowInstance.OnWebMessageReceived in .NET - (example). However if you’re building a Blazor app, you don’t need to use these low-level APIs and can use Blazor’s regular JS interop feature instead.

Hosting a Blazor app

WebWindow isn’t coupled to Blazor. Here’s an example of using Vue.js to render a simple directory-explorer app inside a WebWindow.

But if you do want to use Blazor, that’s extremely clean and easy. I’ve also made a small add-on package, WebWindow.Blazor, that lets you host a Blazor app with one line in your Program.Main:

static void Main(string[] args)
{
    ComponentsDesktop.Run<Startup>("My Blazor App", "wwwroot/index.html");
}

To recap, this does not involve WebAssembly, Node.js, or a privately-bundled copy of Chromium. It’s just .NET Core running natively, communicating directly with the OS’s own web rendering technology. The result, this time in macOS:

The complete WebWindow+Blazor sample is here.

How it works

On Windows, WebWindow uses the new Chromium-based Edge via webview2, assuming you have that browser installed (it could fall back on older Edge if you don’t, but I haven’t implemented that)
On Mac, it uses the OS’s built-in WKWebView, which is the same technology behind Safari
On Linux, it uses WebKitGTK+2, which is yet again a WebKit-based technology

The whole point of this, compared with using Electron, is to produce apps that are smaller to download and use less memory. But does it actually? Here are the stats for download size:

As you can see, whether you choose “standalone” (bundles a copy of the .NET Core runtime) or “framework-dependent” (rely on .NET Core being installed in the target OS) makes a vast difference to the resulting app size. Framework-dependent WebWindow apps can be truly tiny, since they only contain your own app’s binaries and aren’t bundling either a runtime or a browser.

And now, stats for memory use:

On Windows, WebWindow and Electron are using the same browser technology (Chromium), which eats up most of the memory. That explains why the difference between them isn’t huge. On Linux and Mac, the difference between using a self-bundled browser and the OS’s built in technology is more substantial.

Will this be supported and maintained?

Currently I’m not making any promises! It’s best to think of it as yet another experiment for now. It’s possible that if enough other people want to get involved, it would be possible to create a proper open-source community project.

What’s most urgently needed is someone with C++ experience to come and rewrite my prototype-quality C++ and Objective-C code the way it actually should be done. The chance that I’ve got all the memory management right here is close to zero. Maybe it should use CMake or another sane build config system too. (Note: it does have a cross-platform CI build on Azure DevOps though.)

There’s also a large number of features you’d really want to add if you intended to use this in production. For example, the ability to set an app icon, to add a native menu bar, and so on. If you’re interested in contributing such functionality and will make it work cross-platform, please head over to the repo!

Exploring lighter alternatives to Electron for hosting a Blazor desktop app

Fri, 01 Nov 2019 00:00:00 +0000

Electron was first open-sourced in 2014, and gained immediate popularity as a way to build desktop apps using web technologies (HTML+CSS+JS). At the core of its design is the idea of bundling a predictable environment:

It bundles its own copy of Chromium, so you know for sure how your HTML/CSS will be rendered and don’t have to worry about random old versions of IE (etc.)
It bundles its own copy of Node.js, so you have a known version of a portable programming platform that goes beyond the browser sandbox and can interact with the host OS directly

These choices offered a lot of value five years ago, but in late 2019 you might choose differently. And these choices are also key to why Electron has a reputation for being unusually resource-hungry. A default blank Electron 8.0.0 application is 164MB to download (66MB compressed), and runs as 4 separate processes consuming 150MB RAM in total.

It’s completely possible that these numbers look fine to you and are satisfactory for your scenario. If that’s the case, good for you! This post is not an attempt to bash Electron, which is a well-run project that people are clearly using successfully. In this post, I simply want to consider what other options we might have.

How light could it get?

What if…

…we didn’t bundle Chromium, but instead used whatever webview already exists in the OS? In 2019, just about any desktop OS is going to have a sufficiently modern, usually Chromium-based browser, ready to go. For your app, it likely doesn’t matter whether it’s Chromium from last week or last year.
…we didn’t bundle Node, but instead made use of the programming environment already in the OS, or optionally brought a different one? A framework-dependent .NET Core app can easily be under 1MB, and a standalone one (i.e., bundling its own copy of .NET Core) can get down to ~20MB linked and compressed.

Various Electron-lite alternative projects have already sprung up [1]. Of course, there are also PWAs, but that’s not what this post is about, since PWAs don’t have native access to the underlying OS.

Blazor on Electron

We’ve had a lot of interest in using Blazor to build cross-platform desktop apps. It’s not surprising: combining the performance and productivity of C#/.NET with the familiarity of HTML/CSS UI rendering is powerful and appealing.

So, we published a sample and an experimental package for hosting Blazor on Electron. The key innovation here is that it’s not running on WebAssembly, but rather uses the normal cross-platform .NET Core runtime to achieve full native .NET performance and enable full access to the host OS without any browser sandbox limitations.

You can try this out today. Just note that it’s only an “asplabs” project, as we haven’t yet made any commitment to ship and support this technology.

Blazor on pure webview

It’s not hard to imagine how a Blazor hybrid desktop app could be slimmed down dramatically further. We could swap out Electron for a pure OS-native web view, reasoning that in 2019, there’s virtually always a good enough one available on your target machine. Plus we don’t really need Node as a cross-platform programming environment, since .NET Core already plays that role for us.

To verify this, I built an experiment called BlazorDesktop. This is very similar to BlazorElectron, and in fact most of the code is a copy-paste from it. Again, it runs on native .NET Core (so not on WebAssembly), but now it’s running on a much smaller rendering stack, without any bundled Chromium or Node.js.

It’s a fully-functional Blazor application into which you can add any native .NET Core-based functionality, and runs as an extremely lightweight desktop app - see below for numbers. Unlike a PWA, it’s not limited to the browser sandbox.

If you’re interested in trying this out, please note that it’s purely a quick proof-of-concept, and currently is Windows only. Expanding it to be cross-platform wouldn’t be too hard (I’d use something like webview to add Mac+Linux support) but is not something I’m actively doing right now. Send a PR if you’re interested.

The stats

Not surprisingly, this minimal Blazor + webview application is significantly smaller and less memory-hungry than one built on the whole Chromium + Node stack:

One of the neat things about .NET Core apps is that, with a simple switch, you can control whether the publish output bundles its own copy of the .NET Core runtime (a.k.a. standalone), or whether it assumes the runtime will already be installed on the target OS (a.k.a. framework-dependent). This is captured in the first graph above, and you can see it makes a huge difference to the output size, since the Blazor libraries themselves are very compact.

In corporate environments where you know that certain software is already installed, you can safely distribute tiny < 1MB framework-dependent apps, where the same binaries run on any supported OS. But for public distribution, you’d most likely publish a standalone app - generating different binaries for each of Windows, Mac, and Linux users.

Note that about 200KB of the compressed Blazor webview app above consists of Bootstrap styling, so you could drop that if you’re using something else.

What would have to be built to make this viable

As I’ve said, Blazor Desktop is currently just a quick proof-of-concept, built entirely during the waking part of my return journey from NDC Sydney. It would have a long way to go to turn into a viable product.

It would need:

Cross-platform support, e.g., using webview
Edge (Chromium) support, so that on Windows 10 we’re using the OS’s own Chromium-based browser instead of the Edge-based webview used in my prototype. This would also enable access to Chrome-style browser dev tools automatically.
Handling the scenario where a suitable webview can’t be found. In the rare case where a user’s OS doesn’t supply an acceptable webview technology, we could prompt the user and download a standalone Chromium distribution (likely via CEF).
Desktop APIs - this is the big one that would be expensive to achieve from scratch. Electron doesn’t just use Node as a general-purpose programming environment; it also ships a set of cross-platform APIs for interacting with the desktop OS for tasks like copying to clipboard, changing the taskbar/dock icon, displaying native dropdown menus, showing native prompts/dialogs, and many more such things. .NET Core itself supplies a huge proportion of the APIs that applications need, but today it doesn’t address many of the desktop-focused ones, since there isn’t today any standard cross-platform .NET Core-based UI technology. Any realistic app needs these capabilities. Conceivably it might be worth bundling Node just to get cross-platform implementations for these APIs (though still without bundling Chromium).
Publishing and downloading updates automatically

Feedback requested

My reason for writing this is mainly to learn more about how the developer community feels about these technologies. Do you have scenarios for building hybrid desktop apps with .NET+HTML+CSS? Would you be happy to use Blazor with Electron, or do you feel it’s necessary to have something more bare-metal?

Footnote: existing Electron alternatives

Many people have thought about building lighter alternatives to Electron over the years. Various open-source projects now exist, though it’s not clear that any really have the critical momentum for mass adoption. Some of them, like Chromely, eliminate Node and only bundle Chromium. Others, like Neutralino, eliminate Chromium and only bundle a Node-based programming model combined with the host OS’s browser technology. At the ultra-minimal end, webview is simply an abstraction over the idea of a webview: it shows your HTML/CSS in whatever browser technology is built into the host OS, and doesn’t provide any cross-platform programming model of its own.

File uploads with Blazor

Fri, 13 Sep 2019 00:00:00 +0000

For a long time we’ve expected that we’d add a built-in “file input” feature to Blazor. This would let users pick local files and supply them to your application. Possible uses cases include:

You want to upload and store those files on a server
Or, you want to read and import some data from them
Or, you want to present an editor UI for the file

It applies equally to client-side or server-side Blazor. In client-side Blazor, you’re loading the file into the .NET application’s memory, which can then edit it locally or could make an HTTP request to transfer it to some backend server. In server-side Blazor, your code is already running on the server, but you still want to be able to read files picked by the user.

Existing options

There are already several open-source or third-party libraries in this area (example from Rémi Bourgarel, example from SyncFusion). It’s especially worth mentioning Tewr’s BlazorFileReader library, which does an excellent job and is quite similar to what I’m proposing in this post.

What I want out of a great file input component is:

Does not require setting up a separate server-side API endpoint. The file data needs to get into Blazor via the existing JS interop mechanism.
Provides access to the file data as a regular .NET Stream, so other code can handle it just the same as if it were a normal file on disk.
- This must literally stream the content into the .NET process, since we don’t want to depend on loading it all into memory at once.
Works independently of SignalR message size limits and file API buffer sizes
- This is what several of the existing options don’t manage. By default, SignalR imposes a limit of 32KB for incoming messages, and .NET APIs like Stream.CopyToAsync use much larger internal buffers, so the streaming logic needs to work with this and not require reconfiguration.
… while achieving near-native-HTTP transfer speeds
- This is the hardest bit, not addressed by existing solutions as far as I know. There are simple ways to satisfy all the requirements above if you’re willing to accept greatly reduced upload rates. I’ll talk about the challenges and solutions later in this post.

Introducing <InputFile>

As a possible starting point for a future built-in feature, I’ve published a NuGet package called BlazorInputFile (source on GitHub), which provides a component called <InputFile>.

Its features include uploading a single file (sample source):

Or, multi-file upload and progress notifications (sample source):

Or, custom UI including drag-drop support (sample source):

Installation

First, be sure you’re on the latest 3.0.0-preview9 version of Blazor, or newer if you’re reading this from the future. You can use either server-side or client-side (WebAssembly).

Add a dependency on the BlazorInputFile package in your .csproj:

<ItemGroup>
    <PackageReference Include="BlazorInputFile" Version="0.1.0-preview" />
</ItemGroup>

For server-side Blazor

Reference the package’s JavaScript file by editing your _Host.cshtml to add the following. It can go in the <body> or in <head>, wherever you want:

<script src="_content/BlazorInputFile/inputfile.js"></script>

Now in your _Imports.razor, add:

@using BlazorInputFile

Temporary caveat: Until .NET Core 3.0 ships, there’s a bug you need to work around if you’re hosting on IIS Express. Thanks to Tewr for originally reporting this.

That’s it - you’re ready to go! Move on to usage instructions.

For client-side Blazor

Due to a bug that we’ll fix before client-side Blazor is shipped, you can’t just reference inputfile.js from _content. Instead you’ll have to manually copy the contents of inputfile.js from GitHub into a file in your project. For example, put it directly into wwwroot, and then add the following reference into your index.html:

<script src="inputfile.js"></script>

This manual file-copying step for client-side Blazor will be fixed and eliminated soon. Finally, in your _Imports.razor, add:

@using BlazorInputFile

Usage

In one of your components, you can now add an <InputFile> component. You’ll also want to add an event handler for OnChange so you can respond when files are picked:

<InputFile OnChange="HandleFileSelected" />

@code {
    void HandleFileSelected(IFileListEntry[] files)
    {
        // Do something with the files, e.g., read them
    }
}

In this case, we’re only allowing single-file selection, so the files array will have either zero or one entry. You can read metadata about the file even before you actually transfer the contents of the file anywhere:

<InputFile OnChange="HandleFileSelected" />

@if (file != null)
{
    <p>Name: @file.Name</p>
    <p>Size in bytes: @file.Size</p>
    <p>Last modified date: @file.LastModified.ToShortDateString()</p>
    <p>Content type (not always supplied by the browser): @file.Type</p>
}

@code {
    IFileListEntry file;

    void HandleFileSelected(IFileListEntry[] files)
    {
        file = files.FirstOrDefault();
    }
}

You can read data from the file either immediately on selection, or later (e.g., when the user clicks an ‘upload’ button). To read the data, just access file.Data which is a Stream. For example, to count the number of lines in a text file:

<InputFile OnChange="HandleFileSelected" />

@if (file != null)
{
    <p>Number of lines read: @numLines</p>
    <button @onclick="CountLines">Count</button>
}

@code {
    int numLines;
    IFileListEntry file;

    void HandleFileSelected(IFileListEntry[] files)
    {
        file = files.FirstOrDefault();
    }

    async Task CountLines()
    {
        numLines = 0;
        using (var reader = new System.IO.StreamReader(file.Data))
        {
            while (await reader.ReadLineAsync() != null)
            {
                numLines++;
            }
        }
    }
}

Important: You can only use asynchronous APIs on this stream (e.g., ReadLineAsync, not ReadLine), because the data has to be transferred over the network.

If you want to support multiple file selection, just add a multiple attribute:

<InputFile multiple OnChange="HandleFileSelected" />

… and now your event handler will receive a IFileListEntry[] that can contain multiple entries.

Implementation notes

For client-side Blazor (i.e., on WebAssembly), the data transfer between the browser’s JavaScript APIs and .NET is very simple and near-instant, since it’s all running locally. <InputFile> uses Blazor’s low-level unmarshalled interop APIs to copy the requested chunks of the binary data directly into .NET memory without needing any serialization.

For server-side Blazor (i.e., via SignalR), there’s a lot more going on. We have to fetch chunks via IJSRuntime which only allows JSON-serializable data, and imposes a limit on the size of each returned chunk. By default, SignalR’s maximum message size is 32KB.

Bandwidth, latency, and security

Other libraries approaching this problem have required users to configure a SignalR message size greater than whatever maximum buffer size is used by the I/O APIs you’re using (e.g., the default for CopyToAsync is about 128KB). As well as being inconvenient for developers, this still leaves a serious performance issue. Since each chunk is being fetched sequentially, the maximum transfer rate becomes limited not only by network bandwidth, but also by network latency. If your round-trip ping time from client to server is L (e.g., L = 0.2 sec), and your SignalR message size is S (e.g., S = 32KB by default), then the tranfer rate cannot exceed S/L (in this example, 32/0.2 = 160 KB/sec), even if you have a terrabit network connection.

Additionally, even if your SignalR message size is arbitrarily large, the I/O APIs you’re using might themselves use smaller buffers. I often see code that reads data from streams in 1 KB chunks. For L=0.2, that would result in a maximum transfer rate of just 5KB/sec! It’s not enough just to wrap a BufferedStream around the source, since then you wouldn’t get progress notifications as often.

My goal here is to get much closer to using your full network bandwidth. The approach this library uses is parallelism: the .NET side sets up a data structure that can hold many chunks (default total size is around 1MB), and asks the JS side to populate segments within it via a lot of concurrent interop calls. The parallelism amortises the latency, so the bottleneck ends up being your actual network bandwidth, which is what we want. But to maximise UI responsiveness, the I/O operations don’t wait for that whole ~1MB structure to be filled - they receive completion notifications as each smaller segment comes in from the JS side.

Also, for security reasons, we don’t want to trust the JS-side code to send us as much data as it wants. That would let misbehaving clients occupy as much .NET memory as they want. So, all the transfer operations are initiated from the .NET side, and we can be sure to make full use of the allowed memory but no more.

The net result of all this is that developers don’t have to reconfigure SignalR or specify custom buffer sizes when making file API calls. It all just works efficiently and safely by default.

Perf numbers

For client-side Blazor (WebAssembly), the data transfer speed is limited only by your CPU. You can load a 10 MB file into .NET memory almost instantly. On my machine, loading a 100 MB file into a .NET byte array takes about a second.

To test with server-side Blazor, I deployed an application to a server about 4000 miles from me (so there’s plenty of latency), and tried uploading a 20MB file.

With a plain native HTTP upload on a fast office connection, the upload time was around 9 to 10 seconds. On the same network, transferring via <InputFile> took around 12 to 14 seconds.
For the same 20MB file but over a slower cafe wifi connection, the native HTTP upload times were between 21 and 26 seconds. On the same network, transferring via <InputFile> took between 23 and 27 seconds.

It’s entirely expected that <InputFile> takes ~30% longer than native HTTP uploads, because it has to base64 encode the data since IJSRuntime only allows JSON responses. For smaller files, e.g., under 5MB, it’s unlikely that users will perceive any difference, and the vast level of extra convenience offered by <InputFile> (e.g., no need to set up a separate API endpoint) makes this well worthwhile. We’ll also be able to eliminate the base64 penalty in the future by adding support for binary responses to JS interop calls, or expose SignalR’s built-in streaming mechanisms, at which point there should be no meaningful speed difference versus native HTTP uploads.

Integrating FluentValidation with Blazor

Wed, 04 Sep 2019 00:00:00 +0000

FluentValidation is a popular validation library for .NET Core by Jeremy Skinner. It has some advantages over .NET Core’s built-in DataAnnotations validation system, such as a richer set of rules, easier configuration, and easier extensibility.

Blazor ships with built-in support for forms and validation, but Blazor doesn’t know about FluentValidation, and FluentValidation doesn’t know about Blazor. So, how can we make them work nicely together?

A simple validation example

With FluentValidation, you define a validator class for the model types you want to validate. For example, if you have this Customer class:

public class Customer
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

… then you might define a CustomerValidator class as follows:

public class CustomerValidator : AbstractValidator<Customer>
{
    public CustomerValidator()
    {
        RuleFor(customer => customer.FirstName).NotEmpty().MaximumLength(50);
        RuleFor(customer => customer.LastName).NotEmpty().MaximumLength(50);
    }
}

More interesting rules are possible, but let’s start with this. Now say you want to have a UI for creating Customer instances in Blazor. You could use the following in a .razor component:

<EditForm Model="customer" OnValidSubmit="SaveCustomer">
    <FluentValidator TValidator="CustomerValidator" />

    <h3>Your name</h3>
    <InputText placeholder="First name" @bind-Value="customer.FirstName" />
    <InputText placeholder="Last name" @bind-Value="customer.LastName" />
    <ValidationMessage For="@(() => customer.FirstName)" />
    <ValidationMessage For="@(() => customer.LastName)" />

    <p><button type="submit">Submit</button></p>
</EditForm>

@code {
    private Customer customer = new Customer();

    void SaveCustomer()
    {
        Console.WriteLine("TODO: Actually do something with the valid data");
    }
}

This uses Blazor’s built-in EditForm, InputText, and ValidationMessage components to track the state of the editing process and display any validation error messages. Here’s how this looks:

How it works

So we’ve got FluentValidation rules working with Blazor – but how? The answer is the <FluentValidator> component. This is not built-in to Blazor, but rather is a quick example I’ve made to show how you can do this integration. The code and explanation for <FluentValidator> is later in this blog post.

Validating child objects

What if each Customer also has an Address, and we want to validate the properties on that child object? For example, update the Customer class to:

public class Customer
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public Address Address { get; } = new Address();
}

public class Address
{
    public string Line1 { get; set; }
    public string City { get; set; }
    public string Postcode { get; set; }
}

… and update the validation class to:

public class CustomerValidator : AbstractValidator<Customer>
{
    public CustomerValidator()
    {
        RuleFor(customer => customer.FirstName).NotEmpty().MaximumLength(50);
        RuleFor(customer => customer.LastName).NotEmpty().MaximumLength(50);
        RuleFor(customer => customer.Address).SetValidator(new AddressValidator());
    }
}

public class AddressValidator : AbstractValidator<Address>
{
    public AddressValidator()
    {
        RuleFor(address => address.Line1).NotEmpty();
        RuleFor(address => address.City).NotEmpty();
        RuleFor(address => address.Postcode).NotEmpty().MaximumLength(10);
    }
}

As you can see, FluentValidation uses the SetValidator API to reference one validator class from another. To create a UI for this, you could update your <EditForm> to:

<EditForm Model="customer" OnValidSubmit="SaveCustomer">
    <!-- Leave the rest here unchanged -->

    <h3>Your address</h3>
    <div>
        <InputText placeholder="Line 1" @bind-Value="customer.Address.Line1" />
        <ValidationMessage For="@(() => customer.Address.Line1)" />
    </div>
    <div>
        <InputText placeholder="City" @bind-Value="customer.Address.City" />
        <ValidationMessage For="@(() => customer.Address.City)" />
    </div>
    <div>
        <InputText placeholder="Postcode" @bind-Value="customer.Address.Postcode" />
        <ValidationMessage For="@(() => customer.Address.Postcode)" />
    </div>

    <p><button type="submit">Submit</button></p>
</EditForm>

… and you get:

Validating collections

Let’s consider a more advanced scenario. Each Customer has a set of PaymentMethod objects. They must have at least one. PaymentMethod instances can be of different types, and the validation rules in effect depend on the type. To represent all this, you could add the following property to Customer:

public List<PaymentMethod> PaymentMethods { get; } = new List<PaymentMethod>();

… and define PaymentMethod with:

public class PaymentMethod
{
    public enum Type { CreditCard, HonourSystem }

    public Type MethodType { get; set; }

    public string CardNumber { get; set; }
}

To configure the validation rules, update CustomerValidator’s constructor to add:

RuleFor(customer => customer.PaymentMethods)
    .NotEmpty()
    .WithMessage("You have to define at least one payment method");
RuleForEach(customer => customer.PaymentMethods)
    .SetValidator(new PaymentMethodValidator());

… with PaymentMethodValidator defined as:

public class PaymentMethodValidator : AbstractValidator<PaymentMethod>
{
    public PaymentMethodValidator()
    {
        RuleFor(card => card.CardNumber)
            .NotEmpty().CreditCard()
            .When(method => method.MethodType == PaymentMethod.Type.CreditCard);
    }
}

As you can see, RuleForEach applies to each entry in a collection, and When lets you apply rules conditionally based on other properties. In this example, the CardNumber property has to be valid a credit card number, but only when the MethodType is CreditCard.

Creating a list editor in Blazor is pretty simple. Generally you just @foreach over each item in the list to display it, plus offer an “Add item” button and “Remove item” buttons. For example, add the following inside the <EditForm>:

<h3>
    Payment methods
    [<a href @onclick="AddPaymentMethod">Add new</a>]
</h3>
<ValidationMessage For="@(() => customer.PaymentMethods)" />

@foreach (var paymentMethod in customer.PaymentMethods)
{
    <p>
        <InputSelect @bind-Value="paymentMethod.MethodType">
            <option value="@PaymentMethod.Type.CreditCard">Credit card</option>
            <option value="@PaymentMethod.Type.HonourSystem">Honour system</option>
        </InputSelect>

        @if (paymentMethod.MethodType == PaymentMethod.Type.CreditCard)
        {
            <InputText placeholder="Card number" @bind-Value="paymentMethod.CardNumber" />
        }
        else if (paymentMethod.MethodType == PaymentMethod.Type.HonourSystem)
        {
            <span>Sure, we trust you to pay us somehow eventually</span>
        }

        <button type="button" @onclick="@(() => customer.PaymentMethods.Remove(paymentMethod))">Remove</button>

        <ValidationMessage For="@(() => paymentMethod.CardNumber)" />
    </p>
}

… where AddPaymentMethod should be declared inside the @code block as follows:

void AddPaymentMethod()
{
    customer.PaymentMethods.Add(new PaymentMethod());
}

This lets users both add and remove payment methods, and choose a type for each one. Validation rules vary according to the type:

If you want the completed code for this sample, it’s in this Gist. There you’ll also find the source for the FluentValidator component, which is also discussed more below.

Note that this is only a prototype-level integration between Blazor and FluentValidation. There are some caveats discussed below. It’s not something I’m personally planning to extend further and offer support for, but perhaps someone who wants to use it might want to take it further and ship a NuGet package.

Blazor’s forms and validation extensibility

Blazor ships with built-in support for forms and validation. These concepts aren’t welded to the core of Blazor itself, but rather live in an optional package called Microsoft.AspNetCore.Components.Forms. The intention is that if you don’t like any aspect of how this works, you can replace it – either that entire package, or just parts of it.

That optional Forms package contains two main pieces of functionality:

A system for tracking edits within a form and associated validation messages. This is implemented as components like <EditForm>, <InputText>, <InputSelect>, <ValidationSummary>, and so on. This isn’t itself tied to any particular validation or metadata framework.
The <DataAnnotationsValidator> component, which provides integration with .NET Core’s System.ComponentModel.DataAnnotations library (which is a specific validation and metadata framework).

The example in this blog post continues using items from #1 but completely replaces #2. That is, instead of having <DataAnnotationsValidator> inside the <EditForm>, we created and used a new thing called <FluentValidator>.

What a custom validator component such as <FluentValidator> needs to do is:

Receive an EditContext as a cascading parameter
Hook into EditContext’s OnFieldChanged and OnValidationRequested events so it knows when something is happening in the UI
Add or remove validation messages in a ValidationMessageStore whenever it wants. There’s no prescribed timing or lifecycle for this, so you can use literally any flow you want, e.g., for asynchronous validation or whatever else.

The implementation I made for FluentValidator does exactly this.

Reflections on the integration code

By far the most complex aspect of <FluentValidator>’s logic is handling the difference between how EditContext identifies fields and how FluentValidation does.

Blazor identifies fields using an (object, propertyName) pair, where object is an object reference and propertyName is a string
FluentValidation identifies fields using a property-chain string such as Address.Line1 or PaymentMethods[2].Expiry.Month

The reason for Blazor’s approach is to support UI composition. Imagine you wanted to create an <AddressEditor> component. It should be able to receive Address instances from anywhere and edit them with validation. It would be a burden on the developer if they had to somehow pass in property-chain prefixes and combine strings to represent how to locate items within the <AddressEditor> form. It would be especially unpleasant in dynamic list scenarios. The (object, propertyName) system greatly simplifies this, because AddressEditor can simply identify fields as something like (AddressInstance, "Line1") without having to know anything about how the AddressInstance is reached from some parent-level object(s). I’m sure there are advantages to FluentValidation’s approach too. Integrating these two frameworks means being able to translate between the two representations, so that’s what the majority of the complex logic is doing.

Overall, the two biggest caveats with the <FluentValidator> logic I’ve provided here are:

It doesn’t yet support validating individual fields. Instead, each time there’s an OnFieldChanged event, it revalidates the entire object. This is inefficient plus you can see validation messages for fields you haven’t yet edited.
- To fix this, we’d need some way to enumerate all the validatable properties reachable from the root object. Then inside the OnFieldChanged event, we’d take eventArgs.FieldIdentifier and translate that into a FluentValidation path chain string by checking which path string corresponds to the FieldIdentifier. Then we could tell FluentValidation only to validate that one property.
- Alternatively, FluentValidation could offer another overload to the Validate API that takes a callback that returns true/false for each field being considered to say whether or not it should be validated on this occasion.
The async validation experience won’t be great as-is. From the FluentValidation docs, I see that if you have any async rules, then you’re not allowed to call Validate any more, and must instead call ValidateAsync. This returns a Task, so you can’t get the validation results until all the async ones have completed.
- To fix this, maybe FluentValidation could have an API that returns the synchronous results immediately, then a series of notifications as each of the async ones complete, so you can keep updating the UI.

It’s completely possible that FluentValidation already has all the integration points needed to do a better job of integrating than I did. If you know I missed something, please let me know!

Unit testing Blazor components - a prototype

Thu, 29 Aug 2019 00:00:00 +0000

One of our design goals for Blazor is to offer an absolutely first-rate testing system. Writing tests for your components should be natural, produtive, and satisfying. Those tests should run fast and reliably. We’ve have a placeholder issue for this, but it’s out of scope for the initial (.NET Core 3.0) release.

So, I think it’s time to start clarifying how this can work.

Goals

We do have a lot of experience writing tests for Blazor components. While building the framework itself, a substantial portion of the code we write is:

Unit tests, which directly execute methods on components and renderers, and make assertions about the resulting render batches and UI diffs inside them. These tests are extremely fast and robust, but unfortunately also extremely low-level. You wouldn’t normally want to express your tests in terms of Blazor’s low-level internal UI diff description format.
End-to-end (E2E) tests, which use Selenium to control a headless browser instance and make assertions about the state of the browser DOM. These tests are high-level (in that they talk about familiar concepts like HTML and actions like clicking), but they are also very slow (each one can take multiple seconds to run) and great care has to be taken to make them robust and not depend on the timings of async UI updates. It’s also not really possible to mock external services in these tests.

We think it will be possible for Blazor to include a set of test helpers that give you the benefits of both approaches, and the drawbacks of neither.

The core idea is simply to provide unit test helpers that let you mount your components inside a “test renderer”. This will behave like browser automation, but no actual browser will be involved (not even a headless one). It’s just pure .NET code, so runs with the speed and robustness of pure unit tests.

A prototype

To get the conversation going, I’ve put a prototype here. Let’s take a look.

Consider the classic “counter” example, in a file called Counter.razor:

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Increment</button>

@code {
    int currentCount = 0;

    void IncrementCount()
    {
        currentCount++;
    }
}

My prototype unit test package, Microsoft.AspNetCore.Components.Testing, provides a class TestHost that lets you mount components and interact with them inside any traditional unit testing system (e.g., xUnit, NUnit). So if your unit test project has a reference to the application project, you can write tests as follows:

public class CounterTest
{
    private TestHost host = new TestHost();

    [Fact]
    public void CountStartsAtZero()
    {
        var component = host.AddComponent<Counter>();
        Assert.Equal("Current count: 0", component.Find("p").InnerText);
    }

    [Fact]
    public void CanIncrementCount()
    {
        var component = host.AddComponent<Counter>();

        component.Find("button").Click();

        Assert.Equal("Current count: 1", component.Find("p").InnerText);
    }
}

As you can see, TestHost is a way to render components under unit tests. You can find rendered elements in terms of CSS selectors, then you can either make assertions about them or trigger events on them. This is very much like traditional browser automation, but is implemented without using any actual browser.

TestHost also provides a way to supply DI services, such as mock instances, so you can describe how your component must behave when external services do certain things (e.g., when authentication or data access fails). As an example of that, consider the classic “weather forecasts” page (see FetchData.razor in any brand-new Blazor project). This uses HttpClient to fetch and display data from an external source. You could write a unit test for that as follows:

public class FetchDataTest
{
    private TestHost host = new TestHost();

    [Fact]
    public void DisplaysLoadingStateThenRendersSuppliedData()
    {
        // Set up a mock HttpClient that we'll be able to use to test arbitrary responses
        var req = host.AddMockHttp().Capture("/sample-data/weather.json");

        // Initially shows loading state
        var component = host.AddComponent<FetchData>();
        Assert.Contains("Loading...", component.GetMarkup());

        // Now simulate a response from the HttpClient
        host.WaitForNextRender(() => req.SetResult(new[]
        {
            new FetchData.WeatherForecast { Summary = "First" },
            new FetchData.WeatherForecast { Summary = "Second" },
        }));

        // Now we should be displaying the data
        Assert.DoesNotContain("Loading...", component.GetMarkup());
        Assert.Collection(component.FindAll("tbody tr"),
            row => Assert.Contains("First", row.OuterHtml),
            row => Assert.Contains("Second", row.OuterHtml));
    }
}

Let’s do some TDD

You probably know this, but to recap: Test-driven Development (TDD) is the process of writing software through tests. For each behavior your software should have, you first write a unit test (which fails, because your software doesn’t have that behavior yet), then you implement the behavior, and then you see that your test now passes.

Whether or not TDD really works depends a lot on whether the type of software you’re writing is amenable to unit testing and whether the technologies you’re using give you good ways of isolating units of code and a fast enough feedback loop.

My hope, then, is that Blazor can offer unit test helpers that give you what you need so that TDD is not only viable but even enjoyable, even when writing components with very detailed user interactions.

As an experiment, pretend you’re building a “todo list” component in Blazor. It needs to let users type in items, add them to a list, and check them off when they are done. Pretty obvious stuff. You might start with the following TodoList.razor component:

@page "/todo"

<h1>Todo</h1>
<ul>
    @foreach (var item in items)
    {
        <li>@item.Text</li>
    }
</ul>

<form>
    <input placeholder="Type something..." />
    <button type="submit">Add</button>
</form>

@code {
    private List<TodoItem> items = new List<TodoItem>();

    class TodoItem
    {
        public string Text { get; set; }
        public bool IsDone { get; set; }
    }
}

Currently, it doesn’t do anything. Typing and clicking “Add” does nothing. Let’s write a unit test describing the behavior we want. This would go into a separate unit testing project that references the app project:

public class TodoListTest
{
    private TestHost host = new TestHost();

    [Fact]
    public void InitiallyDisplaysNoItems()
    {
        var component = host.AddComponent<TodoList>();
        var items = component.FindAll("li");
        Assert.Empty(items);
    }

    [Fact]
    public void CanAddItem()
    {
        // Arrange
        var component = host.AddComponent<TodoList>();

        // Act
        component.Find("input").Change("My super item");
        component.Find("form").Submit();

        // Assert
        Assert.Collection(component.FindAll("li"),
            li => Assert.Equal("My super item", li.InnerText.Trim()));
    }
}

If you run this either on the command line with dotnet test or in VS’s built-in runner, you’ll see that InitiallyDisplaysNoItems passes, but CanAddItem fails (because we haven’t yet implemented it):

The actual reported failure comes from our call to .Change - it reports The element does not have an event handler for the event ‘onchange’.. This makes sense because we’re trying to trigger “change” on the input, but there’s nothing bound to that element.

Let’s implement the adding behavior, by using @bind to wire up a “change” listener on the input, plus an @onsubmit listener on the form that actually adds items:

<form @onsubmit="AddItem">
    <input placeholder="Type something..." @bind="newItemText" />
    <button type="submit">Add</button>
</form>

@code {
    private string newItemText;
    private List<TodoItem> items = new List<TodoItem>();

    void AddItem()
    {
        items.Add(new TodoItem { Text = newItemText });
    }

    class TodoItem { /* Leave as before */ }
}

And now, the test passes:

OK, that’s good, but I just remembered something else: each time you submit an item, we should auto-clear out the textbox so you can type in the next one. To see whether this already happens, try updating the unit test to check the textbox becomes empty:

[Fact]
public void CanAddItem()
{
    // ... leave the existing code here, and just add the following ...
    Assert.Empty(component.Find("input").GetAttributeValue("value", ""));
}

Oops, no - now this test fails with Assert.Empty() Failure. This shows we’re not clearing out the textbox after add. To implement this, update the AddItem method:

void AddItem()
{
    items.Add(new TodoItem { Text = newItemText });
    newItemText = null;
}

… and now the test passes. We’ve implemented the basics of adding items:

Now, what about having checkboxes to mark items as done, and counting the number of remaining items? We could express that in a unit test by saying there must be an element with CSS class .remaining that shows the count, and that each li should contain a checkbox you can toggle:

[Fact]
public void ShowsCountOfRemainingItems()
{
    // Arrange: list with two items
    var component = host.AddComponent<TodoList>();
    component.Find("input").Change("Item 1");
    component.Find("form").Submit();
    component.Find("input").Change("Item 2");
    component.Find("form").Submit();

    // Assert 1: shows initial 'remaining' count
    Assert.Equal("2", component.Find(".remaining").InnerText);

    // Act/Assert 2: updates count when items are checked
    component.Find("li:first-child input[type=checkbox]").Change(true);
    Assert.Equal("1", component.Find(".remaining").InnerText);
}

Of course, this initially fails, because there is no .remaining item. But we can implement the behavior by changing the markup in TodoList.razor:

<h1>Todo (<span class="remaining">@items.Count(x => !x.IsDone)</span>)</h1>
<ul>
    @foreach (var item in items)
    {
        <li>
            <input type="checkbox" @bind="item.IsDone" />
            @item.Text
        </li>
    }
</ul>

… and now the test passes. Not surprisingly, if you run the app in an actual browser, you can also see it working:

Status

So far, this is just a prototype, and we don’t plan to ship anything of this kind in the 3.0 release this year. My expectation is that we’ll be looking for your feedback as this prototype evolves over time. Maybe the final result will look just like this, or maybe it will be unrecognisably different in the end.

At some point I expect we will ship unit test helpers in a preview package so you can get started using them for real, and ultimately have them in the box with the 5.0 release in late 2020.

IndexedDB in Blazor

Sat, 03 Aug 2019 00:00:00 +0000

Almost all rich client-side web apps (SPAs) involve interacting with a data store. Normally, that data store is held on some server, and the browser-based app queries it by making HTTP calls to some API endpoint. Another option, though, is to store a database client-side in the browser. The great benefit of doing so is that it permits completely instant querying, and can even work offline.

IndexedDB has been around for ages, and remains the dominant way to put a client-side database in your SPA. It’s an indexed store of JSON objects, which lets you configure your own versioned data schema and perform efficient queries against the indexes you’ve defined. Naturally, it works both offline and online.

Using IndexedDB with Blazor

You could use the native IndexedDB APIs through Blazor’s JS interop capability. But you’ll have a rough time, because - to put it kindly - the IndexedDB APIs are atrocious. IndexedDB came onto the scene before Promise, so it has an events-based asynchrony model, which is a disaster to work with.

So, I was pretty intrigued when I heard about Reshiru.Blazor.IndexedDB.Framework, a NuGet package described as:

An easy way to interact with IndexedDB and make it feel like EFCore

Taking the bizarre IndexedDB APIs and turning them into nice, idiomatic .NET ones? Let’s have a look.

Update: Internally, Reshiru.Blazor.IndexedDB.Framework is built on TG.Blazor.IndexedDB by William Tulloch, which surfaces the IndexedDB features in .NET. Reshiru’s package builds on this by adding an EF-like DB context API.

Getting started

First, in your Blazor app’s .csproj, add a reference to the Reshiru.Blazor.IndexedDB.Framework:

<PackageReference Include="Reshiru.Blazor.IndexedDB.Framework" Version="1.0.1" />

In your Startup.cs’s ConfigureServices, set up the IIndexedDbFactory. As far as I know, the IndexedDbFactory doesn’t maintain any state so it’s safe to make it singleton, but if in the future it becomes stateful, you’d want to use scoped:

services.AddScoped<IIndexedDbFactory, IndexedDbFactory>();

Now you’re ready to define your data schema. This package makes it dead easy, since as with EF, it’s just C# classes:

namespace MyApp.Data
{
    // Represents the database
    public class ExampleDb : IndexedDb
    {
        public ExampleDb(IJSRuntime jSRuntime, string name, int version) : base(jSRuntime, name, version) { }

        // These are like tables. Declare as many of them as you want.
        public IndexedSet<Person> People { get; set; }
    }

    public class Person
    {
        [Key]
        public long Id { get; set; }

        [Required]
        public string FirstName { get; set; }

        [Required]
        public string LastName { get; set; }
    }
}

The [Key] property will be populated automatically by the package using the auto-incrementing unique value given by the browser to each stored entity.

The [Required] annotations aren’t used by the data store at all, but I want them so my edit form will have validation rules later.

Querying for data

Next it’s time to build some UI that shows what’s in the DB and lets you add and remove items.

To make the Reshiru IndexedDB APIs available in your .razor files, add the following to _Imports.razor in the root folder of the app:

@using Blazor.IndexedDB.Framework
@using MyApp.Data // Or wherever your data classes are

Then, at the top of some .razor component that will fetch and display data, inject the DB service:

@inject IIndexedDbFactory DbFactory

You can now write a @code block that will get access to the database via the DbFactory and fetch some data from it:

@code {
    List<Person> people;

    protected override async Task OnInitAsync()
    {
        using var db = await DbFactory.Create<ExampleDb>();
        people = db.People.ToList();
    }
}

Notice that I’m using a C# using declaration. This is a brand-new C# language feature, so to make this compile, it’s necessary to use the latest version of the compiler. Enable this by putting the following into a <PropertyGroup> in your .csproj:

<LangVersion>preview</LangVersion>

Finally, we can add some Razor markup to display the contents of the people list:

<h1>People</h1>

@if (people != null)
{
    <table class="table">
        <thead>
            <tr>
                <th>ID</th>
                <th>First name</th>
                <th>Last name</th>
            </tr>
        </thead>
        <tbody>
            @foreach (var person in people)
            {
                <tr>
                    <td>@person.Id</td>
                    <td>@person.FirstName</td>
                    <td>@person.LastName</td>
                </tr>
            }
        </tbody>
    </table>
}

Looks good! Running the application now, you’ll see it fetch and display zero items, because of course the database is empty. But if you use the browser’s dev tools, you can see that the Reshiru IndexedDB NuGet package did in fact create the database matching our schema:

Inserting data

Blank databases aren’t very interesting. Let’s make a form into which users can enter details for a new entity, and then insert it into the database. Here’s a very basic validated form using standard Blazor APIs, which I put into the same .razor file as above:

<fieldset>
    <legend>Add new person</legend>
    <EditForm Model="@newPerson" OnValidSubmit="@SaveNewPerson">
        <InputText @bind-Value="@newPerson.FirstName" placeholder="First name..." />
        <InputText @bind-Value="@newPerson.LastName" placeholder="Last name..." />
        <button type="submit">Add</button>

        <p><ValidationSummary /></p>
        <DataAnnotationsValidator />
    </EditForm>
</fieldset>

@code {
    Person newPerson = new Person();

    async Task SaveNewPerson()
    {
        // TODO
    }

    // ... rest as before
}

This displays as follows. As you can see, it enforces the validation rules defined on the model type:

All that remains is to put in some implementation for the SaveNewPerson method:

async Task SaveNewPerson()
{
    using var db = await this.DbFactory.Create<ExampleDb>();
    db.People.Add(newPerson);
    await db.SaveChanges();

    // Refresh list and reset the form
    newPerson = new Person();
    await OnInitAsync();
}

… and that’s all there is to it. The user can now insert new records to their client-side database without any requests having to go to a server:

In case you’re wondering, the browser’s dev tools also confirm that the data was saved:

Deleting data

To complete this example, let’s put in some Delete buttons. I added the following markup at the end of the <tr> that gets rendered for each row:

<td><button @onclick="@(() => DeletePerson(person))">Delete</button></td>

… and added the following C# handler method to the @code block:

async Task DeletePerson(Person person)
{
    using var db = await this.DbFactory.Create<ExampleDb>();
    db.People.Remove(person);
    await db.SaveChanges();
    await OnInitAsync();
}

A bigger example

The most compelling benefits of client-side databases are:

Instant querying (with no HTTP traffic per query)
Offline support

To experience this with the Reshiru.Blazor.IndexedDB.Framework package, I built a very simple “recipe database” app that:

Fetches a database of recipes from the server, and uses it to populate a client-side database. This is only fetched once, and remains stored in the browser.
Offers instant search-on-every-keystroke for recipes in that database

It would be pretty trivial to make this work offline using a service worker.

Likewise, it would be simple enough to make the app synchronize updates with changes coming from the server. Give each record a “modified date”, and have the SPA request all records modified since the last batch it received, and insert/update/delete those.

Here’s how it looks:

The source code is available here.

What I learned

After my quick experiment with the recipes app, I think there are some really great aspects of the Reshiru.Blazor.IndexedDB.Framework, and some aspects that make it not quite ready yet.

On the positive side, the package does a fantastic job of keeping the APIs simple and familiar for .NET developers. It’s as easy as, or perhaps easier than, using Entity Framework. The data schema is inferred directly from your model classes, and all aspects of serialization are handled for you. I’m convinced it’s possible to create an experience on par with EF backed by IndexedDB in the browser.

However, I suspect this package has a couple more steps to go before it’s really practical for use in a real application, both of which are already tracked in GitHub issues:

It doesn’t yet have any foreign key (FK) support (issue #8)
- Currently it’s limited to JSON-serializing your entire entities, without any native way to represent associations between them
It can’t yet query against IndexedDB itself, but instead loads the entire DB into .NET memory (fixing this is a planned feature)
- It’s pretty slow right now, and one of the major reasons is that when you do DbFactory.Create, it literally fetches all the data and deserializes it into an in-memory collection. Querying is then done in .NET memory via normal LINQ operations. So currently, it’s not actually using the native indexes on the IndexedDB.

Since both of these capabilities already exist in the underlying TG.Blazor.IndexedDB package, it’s probably quite feasible for them to be surfaced through Reshiru’s DB context APIs.

I’m greatly looking forwards to seeing this package mature, as it’s clearly showing that a great client-side database experience is possible on .NET on WebAssembly.

Blazor: a technical introduction

Tue, 06 Feb 2018 00:00:00 +0000

Today the ASP.NET team announced that Blazor has moved into the ASP.NET organization, and we’re beginning an experimental phase to see whether we can develop it into a supported shipping product. This is a big step forwards!

What is Blazor? It’s a framework for browser-based (client-side) applications written in .NET, running under WebAssembly. It gives you all the benefits of a rich, modern single-page application (SPA) platform while letting you use .NET end-to-end, including sharing code across server and client. The announcement post covers more about the intended use cases, timescales, and so on.

In this blog post, I want to provide some deeper technical details for those interested in how it actually works.

Running .NET in the browser

The first step to building a .NET-based SPA framework is to have a way of running .NET code inside web browsers. We can at last do this based on open standards, supporting any web browser (without any plugins), thanks to WebAssembly.

WebAssembly is now supported by all mainstream browsers, including on mobile devices. It’s a compact bytecode format optimised for minimum download sizes and maximum execution speed. Despite what a lot of developers first assume, it does not introduce new security concerns, because it isn’t regular assembly code (e.g., x86/x64 or similar) - it’s a new bytecode format that can only do what JavaScript can do.

So how does that let us run .NET? Well, the Mono team is adding support for WebAssembly. In case you missed the news, Mono has been part of Microsoft since 2016. Mono is the official .NET runtime for client platforms (e.g., native mobile apps and games). WebAssembly is yet another client platform, so it makes sense that Mono should run on it.

Mono aims to run under WebAssembly in two modes: interpreted and AOT.

Interpreted mode

In interpreted mode, the Mono runtime itself is compiled to WebAssembly, but your .NET assembly files are not. The browser can then load and execute the Mono runtime, which in turn can load and execute standard .NET assemblies (regular .NET .dll files) built by the normal .NET compilation toolchain.

This is similar to how, for the desktop CLR, the core internals of the CLR are distributed precompiled to native code, which then loads and executes .NET assembly files. One key difference is that the desktop CLR uses just-in-time (JIT) compilation extensively to make execution faster, whereas Mono on WebAssembly is closer to a pure interpretation model.

Ahead-of-time (AOT) compiled mode

In AOT mode, your application’s .NET assemblies are transformed to pure WebAssembly binaries at build time. At runtime, there’s no interpretation: your code just executes directly as regular WebAssembly code. It’s still necessary to load part of the Mono runtime (e.g., parts for low-level .NET services like garbage collection), but not all of it (e.g., parts for parsing .NET assemblies).

This is similar to how the ngen tool has historically allowed AOT compilation of .NET binaries to native machine code, or more recently, CoreRT provides a complete native AOT .NET runtime.

Interpreted versus AOT

Which mode is best? We don’t know yet.

What we do know is that interpreted mode provides a much faster development cycle than AOT. When you change your code, you can rebuild it using the normal .NET compiler and have the updated application running in your browser in seconds. An AOT rebuild, on the other hand, might take minutes.

So one obvious thought is that interpreted mode might be for development, and AOT mode might be for production.

But that might not turn out to be the case, because interpreted mode is surprisingly much faster than you’d think, and we hear from Xamarin folks who use .NET for native mobile apps that regular (non-AOT) .NET assemblies are very small and compression-friendly compared with AOT-compiled assemblies. We’re keeping our options open until we can measure the differences objectively.

Blazor, a SPA framework

Being able to run .NET in the browser is a good start, but it’s not enough. To be a productive app builder, you’ll need a coherent set of standard solutions to standard problems such as UI composition/reuse, state management, routing, unit testing, build optimisation, and much more. These should be designed around the strengths of .NET and the C# language, making the most of the existing .NET ecosystem, and packaged with the first-rate tooling support that .NET developers expect.

Blazor provides that. It’s inspired by today’s top SPA frameworks such as React, Vue, and Angular, plus some Microsoft UI stacks such as Razor Pages. The goal is to provide what web developers have found most successful in a way that fits neatly with .NET.

Components

In all recent SPA frameworks, applications are built out of components. A component usually represents a piece of UI, such as a page, a dialog, a tabset, or a data entry form. Components can be nested, reused, and shared between projects.

In Blazor, a component is a .NET class, which you can either write directly (e.g., as a C# class) or more commonly in the form of a Razor markup page (i.e., a .cshtml file).

Razor, which has been around since 2010, is a syntax for combining markup with C# code. It’s designed completely for developer productivity, letting you switch between markup and C# without ceremony, with complete intellisense support throughout. Here’s an example of how you could express a simple custom dialog component as a Razor file called MyDialog.cshtml:

<div class="my-styles">
  <h2>@Title</h2>
  @RenderContent(Body)
  <button onclick=@OnOK>OK</button>
</div>

@functions {
    public string Title { get; set; }
    public Content Body { get; set; }
    public Action OnOK { get; set; }
}

When you want to use this component elsewhere, the tooling knows what you’re doing:

Many design patterns are possible on this simple foundation. This includes patterns you might recognise from other SPA frameworks, such as stateful components, functional stateless components, and higher-order components. You can nest components, generate them procedurally, share them via class libraries, unit test them without needing any browser DOM, and generally have a good life.

Infrastructure

When you create a new project, Blazor will offer the core facilities that most applications need. This includes:

Layouts
Routing
Dependency injection
Lazy loading (i.e., loading parts of the app on demand as a user navigates)
Unit testing harness

As an important design point, all of these are optional. If you don’t use some of them, the implementation is stripped out of your app on publish by the IL linker.

Another important design point is that only a few very low-level pieces are baked into the framework. For example, routing and layouts are not baked in: they are implemented in “user space”, i.e., code that an application developer can write without using any internal APIs. So if you don’t like our routing or layout systems, you can replace them with your own. Our current layouts prototype is implemented in only about 30 lines of C#, so you could easily understand and replace it if you wanted.

Deployment

Obviously a major part of the target market for Blazor is ASP.NET developers. For those, we’ll ship ASP.NET middleware so you can serve a Blazor UI seamlessly, plus get advanced features like server-side prerendering.

Equally important to us are developers who don’t yet use .NET for anything. To make Blazor a viable consideration for developers using Node.js, Rails, PHP, or anything else on the server, or even for serverless web apps, we absolutely don’t require you to use .NET on the server. A Blazor app, when built, produces a dist/ directory containing nothing but static files. You can host this on GitHub pages, cloud storage services, from Node.js servers, or anything else you like.

.NET standard is way of saying what capability level a .NET runtime provides, or what capability level a .NET assembly file requires. If your .NET runtime supports netstandard2.0 and below, and you have an assembly that targets netstandard2.0 or above, then you can use that assembly on that runtime.

Mono on WebAssembly will support netstandard2.0 or some higher version (depending release timeframes). This means you can share your standard .NET class libraries across backend server code and in browser-based apps. For example, you could have a project containing your business’s domain model classes and use it both on server and client. It also means you can pull in packages from NuGet.

However, not all .NET APIs make sense in the browser. For example, you can’t listen on arbitrary TCP sockets in a browser, so System.Net.Sockets.TcpListener can’t do anything useful. Likewise you pretty much certainly shouldn’t be using System.Data.SqlClient directly from a browser app. This is OK because (1) browsers do support the APIs that people actually need to build web apps, and (2) because .NET standard has a way of accounting for this. For APIs that don’t apply to a given platform, the base class library (BCL) will throw a PlatformNotSupported exception. In the short term there will be cases where this is not ideal, but over time NuGet package authors will make adjustments to allow for different platforms. If .NET wants to expand into the world’s most widely deployed app platform then this is an inevitable stepping stone.

JavaScript/TypeScript interop

Even if you’re building your browser-based app in C#/F#, you’ll still sometimes want to use third-party JavaScript libraries, or directly put in a bit of your own JavaScript/TypeScript to reach newly-emerging browser APIs.

This should be very simple, as (not surprisingly) WebAssembly is designed to interoperate with JavaScript, and we can expose that nicely to .NET code.

To work with third-party JavaScript libraries, we’re exploring the option of using TypeScript type definitions to present them to your C# code with full intellisense. This would make the top 1000-or-so JS libraries trivial to consume.

To call other JS libraries or your own custom JS/TS code from .NET, the current approach is to register a named function in a JavaScript/TypeScript file, e.g.:

// This is JavaScript
Blazor.registerFunction('doPrompt', message => {
  return prompt(message);
});

… and then wrap it for calls from .NET:

// This is C#
public static bool DoPrompt(string message)
{
    return RegisteredFunction.Invoke<bool>("doPrompt", message);
}

The registerFunction approach has the benefit of working nicely with JavaScript build tools such as Webpack.

And to save you the trouble of doing this for standard browser APIs, the Mono team is working on a library that exposes standard browser APIs to .NET.

Optimisation

Traditionally, .NET has focused on platforms where application binary size isn’t a major concern. It doesn’t really matter whether your server-side ASP.NET application is 1MB or 50MB. It’s only a moderate concern for native desktop or mobile apps. But for browser apps, payload size is critical.

An argument people have made is that, for .NET on WebAssembly, the download is pretty much a one-time thing. We can use normal browser HTTP caching (or fancy service worker stuff if you like) to ensure a given user only fetches the core runtime once. If it’s on a CDN, the user only pays the cost once across all .NET-based web apps.

It’s true, but I don’t think that’s good enough on its own. If it’s 20MB, it’s still much too big even if the user only fetches it once. This is not meant to feel like a browser plugin, after all - it’s a standards-compliant web app. The first-ever load must be fast.

As such we’re putting a lot of thought into getting the download size down. Here are three phases of size optimisation we have in mind:

1. Mono runtime stripping

The Mono runtime itself contains a lot of desktop-specific features. We hope that the Blazor packages will contain a trimmed version of Mono that is substantially smaller than the full-fat distribution. In a hand-optimisation experiment, I was able to remove over 70% of the mono .wasm file while keeping a basic app working.

2. Publish-time IL stripping

The .NET IL linker (originally based on the Mono linker) does static analysis to figure out which parts of .NET assemblies can ever get called by your app, then it strips out everything else.

This is equivalent to tree shaking in JavaScript, except the IL linker is much more fine-grained, operating at the level of individual methods. This removes all the system library code you’re not using and makes a huge difference in typical cases, often cutting out another 70+% of the remaining app size.

3. Compression

Finally, and most obviously, we expect your web server to support HTTP compression. This typically cuts the remaining payload size by a further 75%.

Overall, a .NET-based browser app is never going to be as tiny as a minimal React app, but the goal is to make it small enough that a typical user on an average connection won’t notice or care even on their first ever load, and of course things will be cached fully for subsequent loads.

What’s the point of it all?

Whether it pleases you or not, web development is going to change over the next few years. WebAssembly will allow web developers to choose from a much wider range of languages and platforms than ever before. This is a good thing - our world is finally growing up! Developers building server-side software or native apps have always been able to pick languages and programming paradigms that best match their target problem and their team culture and background. Do you like functional programming with Haskell or Lisp for your financial app? Need some low-level C? More of an Apple dev and want to reuse your Swift skills? They’re all coming to the web.

Don’t be overwhelmed. It doesn’t mean you have to know all languages. It just means we all get to be regular software developers. Your existing expertise with browser programming is still relevant and valuable, but you’ll have more ways of expressing your ideas and more connections with other software communities.

So our initiative here is to put .NET up near the front, rather than trailing years behind.

Current status

Feeling keen to give this a go? Whoa there - we’re still very early in this project. There isn’t yet a download, and most of the above is still a work in progress. Most of you should just relax and wait for the first pre-alpha bits to appear in another month or so.

Remember, Blazor so far is an experiment of the ASP.NET team. We’re taking some months to figure out whether we can make a supported, shipping product of this. As yet it’s not committed, so don’t base your business plans around it!

If you’re super keen, please have a look the repo, try building it, run the tests, and talk to us. Maybe even find a // TODO comment and submit a PR, or tell us about your great feature ideas.

Running Blazor on Mono in the browser

Sun, 05 Nov 2017 00:00:00 +0000

Blazor is an experimental single-page application (SPA) framework that runs on .NET in the browser.

Unlike prior efforts at getting C# to run client-side, Blazor isn’t transpiling or doing any other fragile tricks: instead, it’s got an actual .NET runtime that loads and runs standard .NET assemblies via WebAssembly (or asm.js for older browsers). This means you get full-fidelity .NET - everything behaves exactly like .NET on the desktop/server.

If you want a demo of what it’s like to build an app with it, watch 5 minutes of this video from NDC Oslo.

I’ll say this again later, but to be sure you’re clear: this is an experiment, and it’s not an official Microsoft product.

Backstory: it started with DotNetAnywhere (DNA)

Back in April, I was trying to think of ways to run .NET under WebAssembly, when coincidentally I stumbled across an HN comment about DotNetAnywhere (DNA), a .NET runtime I’d never heard of before. A quick look at its GitHub repo showed that it’s incredibly compact - the whole implementation is just a handful of plain C files. Its extreme simplicity meant that, even though it well predates WebAssembly and hadn’t even been maintained for over 5 years, it only took a few hours and a few minor tweaks to get it compiled as a WebAssembly binary. To my great surprise, it loaded and executed simple .NET assemblies on the first attempt without any complaints.

Blazor, an app framework

Blazor takes this basis and lets you build an app with it. It uses Razor files, which combine C# and HTML markup, to define components that present your data and update when anything changes (a bit like React or Angular components). It also inherits Razor Pages concepts such as layouts and so on.

This is purely experimental. You can’t build a production application with this, for so many reasons. It exists as a way of finding out what a .NET-based SPA framework might look like, and whether people would have any interest in it.

Nonetheless, some folks from the ASP.NET team and some community members have become interested and contributed a bunch of great enhancements, such as ncave doing some very impressive low-level work to improve DNA, and David Fowler and Stephan Halter from the ASP.NET team getting prototype debugging support working as part of a team hackathon event.

Hitting limitations in DNA

It’s extremely impressive that Chris Dunelm single-handedly created an incredibly compact .NET runtime, so compact that the whole thing (including assembly execution, garbage collection, threading) compiles down to 60KB of WebAssembly. Yes, seriously, 60KB - that’s not a typo - and it does actually work. For more about DNA, see Matt Warren’s post.

But it’s probably not the future. Chris stopped working on DNA about 6 years ago, so it’s a long way behind a modern .NET runtime. It lacks some critical things such as proper reflection support and working with netstandard assemblies, and there are some known bugs such as crashing with certain types of generic method invocations. And when it crashes, it gives you basically no clue about why.

During the ASP.NET team hackathon, the thing that most commonly frustrated and slowed people down was not being able to rely on having the complete standard .NET base class library, and not really knowing what runtime features were supported. So .NET in the browser can only be viable if there’s a true, robust, complete production-grade runtime that can run on WebAssembly/asm.js. But where would a miracle like that come from?

Mono on WebAssembly

Not content with just running Mono on all desktop/server platforms, plus iOS/watchOS, Android, smart TVs and the like, Miguel de Icaza from the Mono team has announced a plan to bring it to WebAssembly. And now, Rodrigo Kumpera is just one pull request away from getting WASM-capable Mono interpreter support merged into mono:master. This is exactly what’s needed: a proper, performant, robust, and feature-complete modern .NET runtime on WebAssembly - under active development by a whole team, no less :)

Blazor on Mono

Based on Rodrigo’s excellent work, I’ve migrated Blazor to run on Mono. The result is that it has the same features as before, minus the prototype debugging support, but now it executes faster and it supports a vastly more complete .NET API surface, and virtually every aspect of the runtime works correctly like on desktop/server. It even (usually) provides sensible error messages if you cause unhandled exceptions.

Getting started

If you want to try it out, install the prerequisites:

VS2017.3 or later
.NET Core 2.0 SDK

… and then install the 0.3.0 (or later) build of Blazor.VSExtension.vsix, the VS project template. Then you can do File->New Blazor application and follow along building an app like in this demo.

Caveats

As mentioned before, this is not intended for production use - it’s purely experimental. So let me know what you think of it!
Apologies to non-VS users - although this technology is completely cross-platform, I haven’t yet created a dotnet new template for it, so at the moment there is only a VS project template.
As a result of this migration to Mono, the default Blazor app size has exploded from the reasonable 300KB it was on DNA (which included the runtime, core libraries, application code, etc.) to an almighty 4MB. This is because we’re not yet performing IL-stripping on the builds (i.e, the .NET equivalent of tree shaking), and the Mono runtime is bundling a great many desktop-specific features that are irrelevant on the web. And it’s not even minified. I expect that when we optimise the builds, this size will come down substantially.

ASP.NET Core + Angular 2 template for Visual Studio

Tue, 04 Oct 2016 00:00:00 +0000

Now that ASP.NET Core, Angular 2, and TypeScript 2 have all shipped final versions, it’s a great time to combine them all into one powerful rich web application platform.

For many months, I’ve been working with some great community contributors on our GitHub repo to build supporting libraries, packages, and ultimately what we hope is the ideal starting-point template for such applications. As well as just the basics of hosting a TypeScript-coded Angular 2 site on ASP.NET Core, the template includes:

Server-side prerendering, so your UI can show up very quickly, even before the browser downloads your JavaScript code
Webpack middleware integration, so that during development, you don’t need to keep rebuilding your client-side application, or even have to run a watcher tool in the background
Hot module replacement, so that during development, whenever you edit a TypeScript file, a CSS file, or other client-side resource, your changes are pushed into the browser immediately without reloading the page (so you don’t lose your active debugging session, etc.)
Fast and lean builds. In development, you don’t have to wait for webpack to re-analyse third-party code each time you change your own code, because we factor third-party code out into a separate bundle. Also, in development, your ultra-fast builds include full source maps to aid debugging, whereas in production you get minimal minified output. During publishing to production, it automatically uses production builds.

What if you want to use a different framework? Do you prefer React, React+Redux, or Knockout? We’ve also made equivalent Yeoman templates for those.

What if you want to use a different IDE or develop on Linux or ~~OS X~~ macOS? If you’re not using Visual Studio on Windows, that’s fine: use our Yeoman generator to get equivalent Angular 2, React, React+Redux, or Knockout projects that work with VS Code or any other editor on any operating system. .NET Core is fully cross-platform, after all.

Installation

First make sure you have installed these prerequisites. Things will not work without them!

Visual Studio 2015 Update 3. Note that Update 2 is not enough. You need Update 3, because it fixes some issues with NPM, plus it’s a prerequisite for TypeScript 2.0.
.NET Core 1.0.1
TypeScript 2.0 for Visual Studio 2015. If Visual Studio keeps complaining Cannot find name 'require', it’s because you forgot to install this.
Node.js version 4 or later. We temporarily don’t support Node 0.x because of this issue, but might re-add support for Node 0.x in the future. To check your Node version, run node -v in a command prompt.

Now you’ve checked the prerequisites are installed, just download and install the ASP.NET Core Template Pack extension.

Creating and running a project

When you have the prerequisites listed above, and have installed the ASP.NET Core Template Pack extension, you can go to Visual Studio’s File New Project menu, expand the Web category, and pick ASP.NET Core Angular 2 Starter Application (.NET Core):

Give your project a name and click OK.

Now, wait patiently as Visual Studio restores all the Node.js (NPM) dependencies! This can take several minutes if your internet connection isn’t screamingly fast.

At this point, you’re likely to encounter what looks like a problem, but actually isn’t. When Visual Studio finishes restoring the NPM dependencies, it will show “Dependencies - not installed”:

However, VS is wrong! The fact that you see the packages listed with their version numbers like that means they are installed. You can ignore the “not installed” message in this particular case, but if it bothers you enough, you can follow Hanselman’s steps to fix it.

You can now run your project. Press Ctrl+F5 to launch without debugging (like any other VS project), or tap on the “Play” icon in the toolbar (labelled IIS Express) if you’re not into keyboard shortcuts. It will appear:

Server-side prerendering

Have a click around the starter site. You’ll find a couple of examples of simple components built with Angular 2. It doesn’t seem like much is going on, but there are some cool things happening behind the scenes.

The first thing is that, even though this is an Angular 2 app that normally runs in the browser, your ASP.NET Core server can run it on the server too, so it just sends plain HTML down to the browser that doesn’t even need JavaScript to be displayed.

To prove this to yourself, try disabling JavaScript in your browser altogether (for Chrome users, open the Developer Tools, press F1, check the Disable JavaScript box, then reload the page while leaving the Developer Tools open):

You’ll find that your application appears just the same as before, even though your browser can’t execute any client-side code. You can still navigate around by clicking the sidebar links. But note: navigation is the only thing that will work, because that’s a basic HTML feature. On the “counter” screen, you’ll find the counter button does nothing if you click it, because that’s wired up to a JavaScript event handler, and you don’t have JavaScript right now.

So what’s the point of server-side prerendering?

The point isn’t really to support browsers that don’t have JavaScript enabled. That would only work in the extreme case where you application has no functionality besides navigation (and in that case, why are you building it as a SPA?).

The real benefits are:

It gives a dramatic improvement to perceived performance for your users. Even if they are on a slow device and a slow internet connection, they get to see your application’s UI in a fraction of a second and perhaps read whatever information you’re showing them. In the background, your potentially large bundle of JavaScript is downloading, parsing, and executing in the background, and then automatically takes over to make your application fully functional on the client. This is much better than just showing a blank screen while the application loads.
It supports web crawlers that might not execute JavaScript. As far as any search engine is concerned, you are just returning plain old HTML, so your site can be crawled and indexed in the normal way.

There are limitations with server-side rendering. Notably, your application code can’t just assume it always runs in a browser. If you try to reference the browser’s DOM directly, you’ll get an error like window is undefined when it runs server-side. Fortunately that’s rarely a problem, because in a well-architected Angular app (or React, etc.), the framework really doesn’t want you to mess with the DOM directly anyway, so you shouldn’t be assuming browser primitives regardless of server-side rendering.

If you don’t want to use server-side prerendering for some reason, disable it by removing the asp-prerender-module attribute from the <app> element in Views/Home/Index.cshtml.

Webpack integration

The code in this application is written in TypeScript. That means you need a build step before it can be run. The same would be true if you used SASS (compiles to CSS) or wanted your library code to be bundled and minified.

The dominant build system for modern JavaScript applications today is Webpack. It’s like Grunt or Gulp, but for 2016. It handles TypeScript compilation, bundling and minification, and about a million other things that people have contributed plugins for. We use it in the template, and it enables a couple of cool features:

Webpack dev middleware

Normally, whenever you change one of your TypeScript files, you’d have to run webpack on the command line to regenerate the compiled JavaScript files under wwwroot/dist. But the webpack dev middleware feature saves you the trouble of doing that.

If your application is running in development mode, which it is by default when you launch from Visual Studio, then Webpack is running in the background and intercepting any requests for files under http://yoursite/dist. It handles any such request by returning the compiled file that would be at that location, accounting for any changes you’ve made to the source files.

Because the Webpack compiler remains active in memory, it’s able to produce incrementally compiled updates in a tiny fraction of the usual build time (usually on the order of a few tenths of a second), so your development experience isn’t interrupted as it otherwise would be.

Hot module replacement (HMR)

You know what an incredible drag it is to have to reload your page each time you change something? Well, I admit it’s not the pinnacle of human suffering, but it is a waste of time if you had a debugging session in progress, or otherwise had state in the browser’s memory that will get lost on reload.

HMR solves this. It’s enabled by default when you’re running in development mode, and it watches for any changes to your Angular application source files (TypeScript, HTML, CSS, etc.). When something changes, it does a fast incremental compilation, using the in-memory Webpack compiler instance, and pushes the changes to any active browser windows. Your application will update on the fly, without reloading the page.

To see this working, open your browser’s debug console while it’s in development mode (e.g., launched from Visual Studio). You’ll see this message:

See [HMR] connected? That means it’s ready to receive changes. Try editing one of your source files. For example, edit ClientApp/app/components/home/home.component.html as in this beautiful animated GIF:

The same works if you edit CSS or even images that have been loaded via Webpack require statements.

Configuring webpack

You’ll find the Webpack configuration files in the project root, called webpack.config.js and webpack.config.vendor.js. Now, Webpack is a powerful and sophisticated tool, enough to write whole books about. So don’t be disappointed if it’s not all obvious at first glance. Do be prepared to take some time to learn Webpack if you really want to customise it.

The only notable thing about how it’s set up in this project is that we’ve split third-party dependency code (i.e., “vendor” code) into a separate bundle, controlled by the webpack.config.vendor.js file. This makes rebuilds much faster, because Webpack doesn’t have to re-analyze large libraries like Angular 2 on every build.

You can add extra third-party dependencies to your webpack.config.vendor.js, as in the example below. Whenever you do, run webpack --config webpack.config.vendor.js on the command line to update the vendor bundle. If you need to, install the Webpack command-line tool first by running npm install -g webpack.

Adding third-party libraries

Most JavaScript libraries these days are distributed on NPM. Such libraries are pretty easy to include in your project (assuming they work with the other technologies you’ve chosen, such as Angular 2).

For example, let’s say you want to use Font Awesome, the “iconic font and CSS toolkit”. In Visual Studio, open your package.json file, and add "font-awesome": "^4.6.3" to the list. Visual Studio will auto-complete the package name and suggest the current version number to you. Now save your edited package.json file, and VS will fetch and install your new NPM dependency. Alternatively, you can run npm install --save font-awesome on the command line.

Now let’s add it to the vendor bundle. Open your webpack.config.vendor.js file, and inside the array called vendor (the one that includes '@angular/common', '@angular/compiler', etc.), add font-awesome/css/font-awesome.css. The order doesn’t matter, but alphabetical is nice:

How did we know to reference font-awesome/css/font-awesome.css? Well, if it was a JavaScript library, you’d just reference the package name (e.g., moment for Moment.js). But since what we want from font-awesome is a CSS file (and other things referenced by that CSS file, such as fonts or images), we give the path to the CSS file we want, as specified by the Font Awesome docs.

Next, it’s important to rebuild your wwwroot/dist/vendor.js bundle. We don’t rebuild this all the time automatically, because it takes a little while (like 10 seconds maybe). So in a command prompt, at your project root, run webpack --config webpack.config.vendor.js. If you don’t already have the webpack tool installed, you’ll need to run npm install -g webpack first.

Now Font Awesome’s CSS file (and its other dependencies, such as fonts or SVG files) is in your vendor bundle, so now you can just use it. For example, in ClientApp/app/components/navmenu/navmenu.component.html, you could use Font Awesome’s “calculator” icon:

… and it will show up on your page:

Note: If you get a message like Uncaught ReferenceError: vendor_1e69f8aba84bb345782b is not defined, it’s because either (1) you forgot to run webpack --config webpack.config.vendor.js or (2) you did so, but haven’t yet restarted your application. Because vendor file changes are infrequent and take some processing time, we don’t do rebuild them automatically or integrate them with HMR, so on the rare occasions where you modify your vendor bundle contents, you will need to rebuild it yourself and restart your ASP.NET application.ke

Publishing to Azure

Before you can deploy, you need to work around a bug in the template that we’ll fix very soon. We (i.e., me) forgot to include webpack-dev-externals in the list of NPM dependencies, and you do need it during publishing.

Go to package.json, and in the list of dependencies, add "webpack-node-externals": "^1.4.3".

Now let’s deploy

You can publish an application created with this template to any ASP.NET Core host using any normal deployment mechanism. For those who specifically want to deploy to Azure, here’s one way to do it.

First, from the Azure portal, create a new Web App.

Important! Specify a Node.js version If you don’t, it will use an old version, and deployment will fail. Go to the Application settings pane for your new Web App, and you’ll see a config entry called WEBSITE_NODE_DEFAULT_VERSION. Edit the value, entering a recent Node.js version such as 6.7.0:

After saving that change, go to the Deployment Credentials config pane, and enter some new credentials.

Then, under Deployment options, set up Local Git repository.

After this, when you go to Overview, you’ll be able to copy your new Git clone url.

Back in a command prompt at the root of your Angular 2 app (the directory containing ClientApp, Startup.cs, etc.), initialize a Git repo:

git init
git add .
git commit -m "My first commit"

You can now add Azure as a remote for your Git repo, using the “Git clone url” you got from the Azure portal earlier:

git remote add azure https://your-user-name@my-angular2-site.scm.azurewebsites.net:443/my-angular2-site.git

Obviously, don’t just copy and paste what you see above exactly - replace the URL with the one for your own Web App.

Now you can push the current version of your app to Azure:

git push --set-upstream azure master

Enter the credentials you chose a moment ago, then sit back and wait while the deployment proceeds. The first deployment will take a few minutes. When it’s finished, visit your site’s URL and be delighted with your magnificent creation!

Feedback

If you have general comments on the scope and direction of this project, please post below! I’d love to know how useful (or not) this is to you. As I mentioned above, if you’re looking for similar project templates for React, React+Redux, or Knockout, or if you’re not using Windows or Visual Studio, you’re not being left out: you can use our Yeoman generator instead.

Or, if you encounter any specific issues and think you’ve found a bug, please file an issue on Github (please don’t post it as a comment to this blog post)

Steve Sanderson's Blog

Using gRPC-Web with Blazor WebAssembly

The status quo

What’s gRPC?

Why isn’t everyone already using gRPC in their SPAs?

Adding gRPC services to a Blazor WebAssembly application

Adding gRPC services to a Blazor WebAssembly “hosted” application

Exposing a gRPC service from the server

Consuming a gRPC service from the client

Summary and sample

Adding gRPC services to a Blazor WebAssembly “standalone” application

Getting and using the .proto file

Configuring the client DI service

Summary and sample

Your feedback requested

Meet WebWindow, a cross-platform webview library for .NET Core

“Hello World” example

Hosting a Blazor app

How it works

Will this be supported and maintained?

Exploring lighter alternatives to Electron for hosting a Blazor desktop app

How light could it get?

Blazor on Electron

Blazor on pure webview

The stats

What would have to be built to make this viable

Feedback requested

Footnote: existing Electron alternatives

File uploads with Blazor

Existing options

Introducing <InputFile>

Installation

For server-side Blazor

For client-side Blazor

Usage

Implementation notes

Bandwidth, latency, and security

Perf numbers

Integrating FluentValidation with Blazor

A simple validation example

How it works

Validating child objects

Validating collections

Blazor’s forms and validation extensibility

Reflections on the integration code

Unit testing Blazor components - a prototype

Goals

A prototype

Let’s do some TDD

Status

IndexedDB in Blazor

Using IndexedDB with Blazor

Getting started

Querying for data

Inserting data

Deleting data

A bigger example

What I learned

Blazor: a technical introduction

Running .NET in the browser

Interpreted mode

Ahead-of-time (AOT) compiled mode

Interpreted versus AOT

Blazor, a SPA framework

Components

Infrastructure

Deployment

Code sharing and netstandard

JavaScript/TypeScript interop

Optimisation

What’s the point of it all?

Current status

Running Blazor on Mono in the browser

Backstory: it started with DotNetAnywhere (DNA)

Blazor, an app framework

Hitting limitations in DNA

Mono on WebAssembly

Blazor on Mono

ASP.NET Core + Angular 2 template for Visual Studio

Installation