An experimental web UI framework using C#/Razor and HTML, running client-side via WebAssembly
The arrival of WebAssembly creates the possibility of building client-side web applications using languages and runtimes that are more typically used for native app development. Blazor runs .NET code in the browser via a small, portable .NET runtime called DotNetAnywhere (DNA) compiled to WebAssembly.
The programming model will be familiar to anyone who's worked with Razor (the C#/HTML page format used by ASP.NET MVC and ASP.NET Pages).
To get started building an app or working on Blazor itself, see Getting Started.
Could something like this really be practical? How big would the apps be to download?
Yes, it could be practical. A "hello world" app that runs Razor in the browser with this template is around 300KB, which is smaller than typical apps from some other single-page-app (SPA) frameworks. That 300KB includes everything: the small .NET runtime, core libraries, application code, and wrapper libraries needed to bootstrap and interop with the WebAssembly code.
That's before any real optimisation attempt. If there was a proper attempt at code stripping to remove all non-called corlib code, it could get smaller.
What about browsers that don't support WebAssembly?
Is this actually .NET in the browser?
It's not the regular .NET Framework or .NET Core runtime. It's a third-party .NET runtime called DotNetAnywhere, which has been updated and extended in various ways to support being compiled to WebAssembly, to load and run .NET Core assemblies, and with some additional functionality such as basic reflection and so on.
Can I build a real production app with this?
No. It's incredibly incomplete. For example, many of the .NET APIs you would expect to be able to use are not implemented.
Why isn't there an issue tracker? How do I file issues?
You don't file issues. There's no support for this. It's experimental.
If you would like to contribute, you can submit a pull request though.
Why does this exist?
To see how well such a framework might work, and how much anyone would care. Note that it's a personal project rather than an official Microsoft project.
Building an app with Blazor
Install the VS extension, then use File->New project, and choose Blazor Application from the Web category.
To start the application in VS, just press F5 or Ctrl+F5 as usual.
To start the application on the command line, run
dotnet blazor serve.
Once your app is running, you can edit its
cshtml files, and the application will update automatically.
This project template gives you a standalone Blazor application. That is, it's not hosted on an ASP.NET server (at least, not one you can see). The idea is that ultimately you could deploy your client-side Blazor app as a set of purely static files that could be served from any web technology (Rails, PHP, a static file host, etc.). Therefore, server-side prerendering is not supported in this mode.
If you want to see a Blazor app hosted within an ASP.NET server, with server-side prerendering support, see the
ClientServerApp sample mentioned in the next section.
What about cross-platform CLI developers?
This should all work on Linux/macOS since .NET Core is cross platform, but I just haven't made a
dotnet new template for it yet.
Hacking on Blazor itself
If you want to extend Blazor itself, the setup is a bit more involved.
- .NET Core 2.0 preview 3 or later. I've been using SDK build 6764.
- Visual Studio 2017.3 or later. I've been using VS2017.3 Preview 3 and Preview 4. Older preview versions don't work.
- Clone this repo
- In a command prompt at the root of the repo, run
dotnet restore Blazor.Core.sln
- Now open
ClientServerApp, then right click on
ClientServerApp.Serverand choose "Set as StartUp Project".
- Launch the application using Ctrl+F5
You can now work on the sample application, or modify the Blazor runtime, compiler, host, or the
corlib project. You can also debug into any of these projects when they executing on the server (e.g., during runtime Razor compilation or server-side prerendering).
Warning: For some reason it seems necessary to use Rebuild all after making changes to the Blazor projects: just building the sample application alone doesn't get the changes, even though it has a project reference to the Blazor library projects. Let me know if you can solve this!
Hacking on the DNA runtime
If you want to make changes to the DNA runtime itself, which is written in C and compiled with Emscripten (for example, to support new corlib features), see these instructions.
Working on the project template and Visual Studio extension
The project template and VS extension are in a different solution,
Blazor.ProjectTemplate.sln. This is because the project template project needs to reference the Blazor libraries via NuGet package references, not project references, because it depends on
<DotNetCliToolReference>. So, it can only be compiled once you've built the
*.nupkg files for the Blazor packages. To do this:
- At the project root, run
dotnet restore Blazor.Core.slnif you didn't already
build-packages.cmdto create a set of NuGet package files in your local
dotnet restore Blazor.ProjectTemplate.slnso it picks up your new
- Optionally, if you want a
.vsixfile you could redistribute, run
.vsixfile will appear in your
Now you can open
Blazor.ProjectTemplate.sln in Visual Studio. If your VS instance doesn't already have the Visual Studio extension development toolset installed, it will prompt you to install that. And yes, you do actually need to do that.
Finally, you can either:
- Set the
MyApplicationproject as the startup project and launch it (Ctrl+F5) as a standalone app. This is equivalent to what a developer will get when they create a project with the template.
- Or, set the
Blazor.VSExtensionproject as the startup project and launch it (Ctrl+F5). This will launch the Visual Studio Experimental instance with the project template installed into it, so you can create a new project with it.