ASP.NET Core 3.0 is shaping up to be awesome with the addition of Blazor. This unique development model allows you to write client-side web app logic in C# rather than using JavaScript. A big win for developers who are lost in the world of Javascript but still need to write interactive client logic. But how can you upgrade your existing app to this new framework?

I'm currently working on rebuilding my blog in ASP.NET Core 3.0 as an exercise and because I feel much more at home in C# and .NET. As part of this, I've tried different client frameworks for my content editor and settled on Blazor as it means I can stick completely to C#.

In this post I'll show you how I integrated Blazor into my project and how you can add server-side Blazor components to your existing ASP.NET Core web application.

What is Blazor?

Blazor is a new set of  components that are part of the upcoming ASP.NET Core 3.0 release. Blazor allows you to write client-side logic in your web application using C#.

Blazor uses the Razor syntax to create Razor Components. The syntax should feel very familiar, since you're already using Razor syntax in your MVC applications.

There are two flavors for hosting Blazor components in your web application: Client-side and server-side. The client-side version runs your C# code in the browser on the computer of the visiting user using web assembly.

Client-side hosting model for Blazor

So when a user clicks a button on the page, the event handler, written in C#, that is connected to the button is run in the browser.

The server-side variant works exactly the same, but runs the same code on the server. The client browser interacts with the server-side code through a SignalR connection.

Server-side hosting model for Blazor

This means that when a user clicks a button, an event is sent to the server over SignalR where it is processed inside the razor component that is hosted on the page.

Choosing between server-side and client-side

Whether you want to run your Blazor components entirely in the browser or on the server depends largely on the people that are going to visit your website.

When your audience uses older computers with older browsers then server-side Blazor is a great option. It works on most older browsers and only requires a SignalR connection to be kept open to the server.

In the server-side hosting model, the server runs a so-called circuit per component to maintain the state of the component. This means that there's additional overhead involved in running server-side Blazor.

If your audience uses mostly modern webbrowsers then using client-side Blazor is a good idea. It eliminates the circuits on the server, freeing up your webserver to do other things.

In my project I used server-side Blazor. I have a modern browser, but I felt that the server-side blazor required fewer steps to integrate so that's what I'll cover in this post.

Integrating server-side Blazor in your web application

When you've got an existing ASP.NET core application and you want to benefit from the rich client capabilities of Blazor components you'll need to perform three steps:

  1. Enable the server-side blazor dependencies
  2. Extend the HTTP pipeline with Blazor
  3. Create and host the actual Blazor components

Let's start by enabling server-side blazor components.

Step 1: Enable the server-side blazor dependencies

Modify the ConfigureServices method in the Startup.cs file, and add the following code:

services.AddServerSideBlazor();

This enables the server-side blazor dependencies.

Step 2: Extend the HTTP pipeline with Blazor

Now that we have the runtime dependencies for Blazor, let's extend the HTTP pipeline with Blazor components:

app.UseRouting();

app.UseEndpoints(endpoints =>
{
    // .. Other endpoint mappings
    endpoints.MapBlazorHub();
});

The first line enables endpoint routing in ASP.NET Core. The next line maps the endpoints in the application. Usually, you'll find mappings for razor pages and MVC controllers. Extend this with the MapBlazorHub method call to enable Blazor.

Step 3: Create and host the actual Blazor components

Finally, when you've setup the HTTP pipeline and dependencies for Blazor, create a new file ContentEditor.razor file with the following content:

<h3>ContentEditor</h3>

@code {

}

A razor component is similar to a normal Razor Page or Razor view. It can contain HTML mixed with Razor syntax. Unique for a Razor component is the @code section which defines the behavior for the component. It can contain C# methods, and properties.

Tip: Store razor components in a Components folder, so you'll have Views, Pages, and Components separated from each other. This makes for a much clearer and cleaner setup.

To render the component on a page, include the following code in the Razor view or page where you want the component to be loaded:

@page
@model FizzyLogic.Areas.Editor.Pages.Posts.NewModel
@{
    ViewBag.Title = "Create new post";
}
<script src="~/_framework/blazor.server.js"></script>
<ContentEditor>@(await Html.RenderComponentAsync<ContentEditor>())</ContentEditor>

In this example, I've created a Razor page New.cshtml which has a code-behind model named NewModel.

To host Blazor components on this page, include the script _framework/blazor.server.js before rendering the component itself.

Render the component by invoking Html.RenderComponentAsync with the type of the component that you want to render.

Wrap the component in a custom HTML element to tell the browser that it's dealing with a custom element. This is required for Blazor to work correctly.

Tip: The name of the component doesn't need to match the name of the custom HTML element, although it does make it clear what component is being rendered.

Summary

So, there you go, it doesn't take a lot to integrate Blazor into existing ASP.NET Core applications. No more Javascript misery!