What is Blazor? A Tutorial on Building Web Apps with Authentication
Tags: dotnet, security, programming
Published: 2022-03-29 14:09:46

### Learn how to build client-side Web apps using Blazor and how to secure them with Auth0.

### <br>

**TL;DR:** This tutorial introduces the Blazor framework by guiding you in building a simple Web application with C#. It will also show you how to integrate your Blazor application with Auth0 in order to secure it. You can find the full application code [in this GitHub repository](https://github.com/auth0-blog/blazor-quiz-manager).

## What Is Blazor?

Blazor has been gaining in popularity, especially after the [release of .NET Core 3.0](https://auth0.com/blog/exploring-dotnet-core-3-whats-new/), which enriched it with many interesting features. Subsequent versions of .NET consolidated its foundations, and the interest around it is growing so much that Microsoft is betting a lot on its future. But what is Blazor exactly?

[Blazor](https://dotnet.microsoft.com/apps/aspnet/web-apps/blazor) is a programming framework to build client-side Web applications with .NET. It allows .NET developers to use their C# and [Razor](https://docs.microsoft.com/en-us/aspnet/core/razor-pages) knowledge to build interactive UIs running in the browser. Developing client-side applications with Blazor brings a few benefits to .NET developers:

- They use C# and Razor instead of JavaScript and HTML.
- They can leverage the whole .NET functionalities.
- They can share code across the server and client.
- They can use the .NET development tools they are used to.

In a nutshell, Blazor promises .NET developers to let them build client Web applications with the development platform they are comfortable with.

### The hosting models

Blazor provides you with two ways to run your Web client application: *Blazor Server* and *Blazor WebAssembly*. These are called *hosting models*.

The *Blazor Server* hosting model runs your application on the server within an ASP.NET Core application. The UI is sent to the browser, but UI updates and event handling are performed on the server side. This is similar to traditional Web applications, but the communication between the client side and the server side happens over a [SignalR](https://docs.microsoft.com/en-us/aspnet/core/signalr/introduction) connection. The following picture gives you an idea of the overall architecture of the Blazor Server hosting model:

![Blazor Server architecture diagram](https://images.ctfassets.net/23aumh6u8s0i/7tRowtql53bX6b4BO7Vd46/e0ff8a50ccfdcd2e6ccfdddcc6fe39c6/blazor-server-diagram)

The Blazor Server hosting model provides a few benefits, such as a smaller download size of the client app and the compatibility with not recent browsers. However, it has some drawbacks compared to a classic Single Page Application (SPA), like a higher latency due to the roundtrip between the client and the server for most user interactions and the challenging scalability in high traffic scenarios.

The *Blazor WebAssembly* hosting model, also known as *Blazor WASM*, lets your application run entirely on the user's browser. The full code of the application, including its dependencies and the .NET runtime, is compiled into [WebAssembly](https://webassembly.org/), downloaded by the user's browser, and locally executed. The following picture describes the hosting model of Blazor WebAssembly:

![Blazor WebAssembly architecture diagram](https://images.ctfassets.net/23aumh6u8s0i/5aN8vvvYexEGNKGKgzHVtl/cf35c378d6209f2c0be35e97c3b353a9/blazor-webassembly-diagram)

The benefits provided by the Blazor WebAssembly hosting model are similar to those provided by Single Page Applications. After the download, the application is independent of the server, apart from the needed interactions. Also, you don't need an ASP.NET Core Web server to host your application. You can use any Web server, since the result of the WebAssembly compilation is just a set of static files.

On the other side, you should be aware of the drawbacks of this hosting model. The Blazor WebAssembly hosting model requires that [the browser supports WebAssembly](https://caniuse.com/wasm). In addition, the initial download of the application may take some time.

<include src="TweetQuote" quoteText="You don't need an ASP.NET Core Web server to host Blazor WebAssembly applications."/>

### Blazor roadmap

Blazor promises a great opportunity for .NET developers. Microsoft's goals on the Blazor project are very ambitious, especially for Blazor WebAssembly. In their vision, not only will Blazor WebAssembly become the main hosting model, but it will also drive a great revolution in the **development of clients**.

The [Blazor WebAssembly hosting model](https://visualstudiomagazine.com/articles/2019/09/26/blazor-future.aspx) will include Single Page Applications compiled into WebAssembly, Progressive Web Apps, hybrid mobile applications, Electron-based desktop applications, and native applications.

## Prerequisites

Before starting to build your Blazor application, you need to ensure you have installed the right tools on your machine. In particular, you need .NET 6.0 SDK or above. You can check if you have the correct version installed by typing the following command in a terminal window:

```bash
dotnet --version
```

You should get the value `6.0.100` or above as a result. If you don't, you should [download the .NET SDK](https://dotnet.microsoft.com/download/dotnet/6.0) and install it on your machine.

If you are going to use Visual Studio, be aware that you need to use at least Visual Studio 2019 16.8 or Visual Studio for Mac 8.9.

> **Note**: If you update Visual Studio to the latest version, you will get the required .NET SDK bundled.

## Building a Blazor Server Application

To get started with Blazor, you will build a simple quiz application that shows a list of questions with multiple answers and assigns you a score based on the correct answers you provide. You will create this application using the Blazor Server hosting model. If you are interested in [building and securing the same application by using the Blazor WebAssembly, please check out this article](https://auth0.com/blog/securing-blazor-webassembly-apps/).

So, create a basic Blazor Server project by typing the following command in a terminal window:

```bash
dotnet new blazorserver -o QuizManager
```

This command uses the `blazorserver` template to generate the project for your application in the `QuizManager` folder. This newly created folder has a lot of content but, apart from the root folder, the relevant folders that you are going to touch are:

- The `Data` folder: it contains the models and the services implementing the business logic.
- The `Pages` folder: this contains the Razor components that generate the HTML views. In particular, this folder contains the `_Host.cshtml` Razor page, which acts as the starting point of the Web UI.
- The `Shared` folder: it contains Razor components and other elements shared among pages

### Creating the model and the service

As a first step, delete the files inside the `Data` folder. Next, add a `QuizItem.cs` file into this folder and paste in the following code:

```c#
// Data/QuizItem.cs

namespace QuizManager.Data
{
    public class QuizItem
    {
        public string Question { get; set; }
        public List<string> Choices { get; set; }
        public int AnswerIndex { get; set; }
        public int Score { get; set; }

        public QuizItem()
        {
            Choices = new List<string>();
        }
    }
}
```

This class implements the model for each item of the quiz. It provides a question, a list of possible answers, the zero-based index of the correct answer, and the score assigned when the user gives the correct answer.

In the same `Data` folder, add a second file named `QuizService.cs` with the following content:

```c#
// Data/QuizService.cs

namespace QuizManager.Data
{
    public class QuizService
    {
        private static readonly List<QuizItem> Quiz;

        static QuizService()
        {
            Quiz = new List<QuizItem> {
                new QuizItem
                {
                    Question = "Which of the following is the name of a Leonardo da Vinci's masterpiece?",
                    Choices = new List<string> {"Sunflowers", "Mona Lisa", "The Kiss"},
                    AnswerIndex = 1,
                    Score = 3
                },
                new QuizItem
                {
                    Question = "Which of the following novels was written by Miguel de Cervantes?",
                    Choices = new List<string> {"The Ingenious Gentleman Don Quixote of La Mancia", "The Life of Gargantua and of Pantagruel", "One Hundred Years of Solitude"},
                    AnswerIndex = 0,
                    Score = 5
                }
            };
        }

        public Task<List<QuizItem>> GetQuizAsync()
        {
            return Task.FromResult(Quiz);
        }
    }
}
```

This class defines a quiz as a list of `QuizItem` instances initialized by the `QuizService()` constructor. For simplicity, the list is implemented with a static variable, but in a real-world scenario, it should be persisted into a database. The `GetQuizAsync()` method simply returns the value of the `Quiz` variable.

Now, move to the root of your project and edit the `Program.cs` file by applying the changes shown in the following code:

```c#
// Program.cs

using Microsoft.AspNetCore.Components;
// ...other using clauses...

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddServerSideBlazor();
// 👇 existing code
//builder.Services.AddSingleton<WeatherForecastService>();
builder.Services.AddSingleton<QuizService>();
// ☝️ new code

var app = builder.Build();

// ...existing code...
```

With this change, you registered the `QuizService` service you defined above instead of the service of the sample application coming with the default Blazor project template.

### Creating Razor components

Now that you've created the model and the service of the application, it's time to implement the UI. Blazor leverages [Razor](https://docs.microsoft.com/en-us/aspnet/core/mvc/views/razor) as a template processor to produce dynamic HTML. In particular, Blazor uses [Razor components](https://docs.microsoft.com/en-us/aspnet/core/blazor/components) to build up the application UI. Razor components are self-contained units of markup and code that can be nested and reused even in other projects. They are implemented in file with the `.razor` extension.

<include src="TweetQuote" quoteText="Razor components are the basic UI elements in a Blazor application."/>

To show the quiz to the user and let them interact with it, you need to implement a specific view as a Razor component. So, move to the `Pages` folder and remove the `Counter.razor` and `FetchData.razor` files. These files belonged to the default sample project. Then, add in the same folder the `QuizViewer.razor` file with the following content:

```c#
// Pages/QuizViewer.razor

 @page "/quizViewer"

 @using QuizManager.Data
 @inject QuizService QuizRepository

 <h1>Take your quiz!</h1>
 <p>Your current score is @currentScore</p>

@if (quiz == null)
{
    <p><em>Loading...</em></p>
}
else
{
    int quizIndex = 0;
    @foreach (var quizItem in quiz)
    {
        <section>
            <h3>@quizItem.Question</h3>
            <div class="form-check">
            @{
                int choiceIndex = 0;
                quizScores.Add(0);
            }
            @foreach (var choice in quizItem.Choices)
            {
                int currentQuizIndex = quizIndex;
                <input class="form-check-input" type="radio" name="@quizIndex" value="@choiceIndex" @onchange="@((eventArgs) => UpdateScore(Convert.ToInt32(eventArgs.Value), currentQuizIndex))"/>@choice<br>

                choiceIndex++;
            }
            </div>
        </section>

        quizIndex++;
    }
}

@code {
    List<QuizItem> quiz;
    List<int> quizScores = new List<int>();
    int currentScore = 0;

    protected override async Task OnInitializedAsync()
    {
        quiz = await QuizRepository.GetQuizAsync();
    }

    void UpdateScore(int chosenAnswerIndex, int quizIndex)
    {
        var quizItem = quiz[quizIndex];

        if (chosenAnswerIndex == quizItem.AnswerIndex)
        {
            quizScores[quizIndex] = quizItem.Score;
        } else
        {
            quizScores[quizIndex] = 0;
        }
        currentScore = quizScores.Sum();
    }
}
```

Take a look at the code of this component. Its first line uses the `@page` directive to define this component as a page, which is a UI element that is directly reachable through an address (`/quizViewer` in this case) in the Blazor's routing system. Then, you have the `@using` directive, which provides access to the `QuizManager.Data` namespace where you defined the `QuizItem` model and the `QuizService` service. The `@inject` directive asks the dependency injection system to get an instance of the `QuizService` class mapped to the `QuizRepository` variable.

After these initializations, you will find the markup defining the UI. As you can see, this part is a mix of HTML and C# code whose purpose is to build the list of questions with the respective possible answers represented as radio buttons.

The final block of the component is enclosed in the `@code` directive. This is where you put the logic of the component. In the case of the `QuizViewer` component,  you have the `OnInitializedAsync()`  and the `UpdateScore()` methods. The first method is called when the component is initialized, and it basically gets the quiz data by invoking the `GetQuizAsync()` method of the `QuizRepository` service instance. The `UpdateScore()` method is called when the user clicks one of the proposed answers, and it updates the list of the assigned scores according to the answer chosen by the user. In the same method, the value of the current score is computed and assigned to the `currentScore` variable. The value of this variable is shown above the list of questions, as you can see in the markup.

Now, go to apply the final touch by moving in the `Shared` folder and replacing the content of the `NavMenu.razor` file with the following code:

```c#
// Shared/NavMenu.razor

<div class="top-row ps-3 navbar navbar-dark">
    <div class="container-fluid">
        <a class="navbar-brand" href="">QuizManager</a>
        <button title="Navigation menu" class="navbar-toggler" @onclick="ToggleNavMenu">
            <span class="navbar-toggler-icon"></span>
        </button>
    </div>
</div>

<div class="@NavMenuCssClass" @onclick="ToggleNavMenu">
    <nav class="flex-column">
        <div class="nav-item px-3">
            <NavLink class="nav-link" href="" Match="NavLinkMatch.All">
                <span class="oi oi-home" aria-hidden="true"></span> Home
            </NavLink>
        </div>
        <div class="nav-item px-3">
            <NavLink class="nav-link" href="quizViewer">
                <span class="oi oi-list-rich" aria-hidden="true"></span> Quiz
            </NavLink>
        </div>
    </nav>
</div>

@code {
    private bool collapseNavMenu = true;

    private string? NavMenuCssClass => collapseNavMenu ? "collapse" : null;

    private void ToggleNavMenu()
    {
        collapseNavMenu = !collapseNavMenu;
    }
}
```

The `NavMenu.razor` file contains the definition of the navigation bar component of the application. The code you put its this file defines a navigation menu of two items: one pointing to the home page and the other to the `QuizViewer` component.

You're not going to change the *App* component implemented by the `App.razor` file in the project root folder yet, but it's still worth taking a look at anyway.

```html
// App.razor

<Router AppAssembly="@typeof(App).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
        <FocusOnNavigate RouteData="@routeData" Selector="h1" />
    </Found>
    <NotFound>
        <PageTitle>Not found</PageTitle>
        <LayoutView Layout="@typeof(MainLayout)">
            <p role="alert">Sorry, there's nothing at this address.</p>
        </LayoutView>
    </NotFound>
</Router>
```

This component attaches the Blazor routing system to your application by using the built-in *Router* component. It enables navigation among the pages of your application, distinguishing when the page is found from when it does not exist. For more information about the Blazor routing system, check the [official documentation](https://docs.microsoft.com/en-us/aspnet/core/blazor/routing).

<details>
  <summary>⚠️ If you are using a Mac, please, read! ⚠️</summary>
At the time of writing, Mac users are affected by an issue when running an ASP.NET Core application via the .NET CLI. You may get the following dialog window when run :


![Keychain message issue in Mac](https://images.ctfassets.net/23aumh6u8s0i/3Io0TQcelmQbkgNnAoXjzm/2bde77c4f9a50bca9c740841dad624a3/keychain-message-mac-issue.png)

This is due to [a known issue with the .NET CLI on macOS](https://github.com/dotnet/sdk/issues/22544). The current workaround requires that you open the `QuizManager.csproj` file and add the `<UseAppHost>false</UseAppHost>` element as shown below:

```xml
<!-- QuizManager.csproj -->

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

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <!--👇 new element --->
    <UseAppHost>false</UseAppHost>
  </PropertyGroup>

</Project>
```

If you use Visual Studio, you are not affected by this issue.
</details>

### Running your Blazor Server application

Now you have your quiz application, so launch it by typing the following command in a terminal window:

```shell
dotnet run
```

> If this is the very first time you run an ASP.NET Core application, you should trust the HTTPS development certificate included in the .NET Core SDK. This task depends on your operating system. Please, take a look at the [official documentation](https://docs.microsoft.com/en-us/aspnet/core/security/enforcing-ssl?view=aspnetcore-3.0&tabs=visual-studio#trust) to apply the proper procedure.
>
> You may also be requested to allow the application to access the developer certificate key.

After a few seconds, you should get your application up and running. Take a look at your terminal window to get the address your application is listening to. In my case, I got the address [`https://localhost:7290`](https://localhost:7290), and I will refer to it throughout the article.

> Starting with .NET 6.0, any ASP.NET project created through a template is assigned a random port between 5000 and 5300 for HTTP and between 7000 and 7300 for HTTPS. See [this document](https://docs.microsoft.com/en-us/aspnet/core/release-notes/aspnetcore-6.0?view=aspnetcore-6.0#tgp) for more information.

So, if you open your browser at that address, you should get access to the home page, as shown by the following picture:

![Blazor application default home page](https://images.ctfassets.net/23aumh6u8s0i/3Dw7eHdnXOnz9xEAcXGL3A/dd4b4b48f5db82171ce27eecb97add44/blazor-server-home-page.png)

Selecting the *Quiz* item in the navigation menu, you should get the interactive quiz you built so far. It should look like the following picture:

![Quiz view in the Blazor application](https://images.ctfassets.net/23aumh6u8s0i/5d0gen7BSw1fIqXjLjWWdX/83acaccd02495141db7c653b5496c1ff/blazor-server-quiz-view.png)

If you open the developer tools of your browser, click on the *Network* tab, and refresh, you will discover that the communication between the client side and the server side of your application doesn't use HTTP, but it is a bi-directional binary communication managed by SignalR. The following picture shows the WebSocket channel in Chrome developer tools:

![Blazor server communication based on SignalR](https://images.ctfassets.net/23aumh6u8s0i/3klQMC5GJmJApzMbmDA0a7/727752c284581d03c766f7bbd2e5af53/blazor-server-signalr-communication.png)


[Read more...](https://auth0.com/blog/what-is-blazor-tutorial-on-building-webapp-with-authentication/?utm_source=content_synd&utm_medium=sc&utm_campaign=dotnet)