How To Create Blazor Project

Intro

Purpose

Build your first web app with Blazor.

Prerequisites

None.

Time to Complete

10-15 minutes

Scenario

Create, use, and modify a simple counter component.

Download and install

To start building .NET apps, download and install the .NET SDK (Software Development Kit).

Check everything installed correctly

Once you've installed, open a new command prompt and run the following command:

Once you've installed, open a new terminal and run the following command:

If the installation succeeded, you should see an output similar to the following:

Command prompt

                              Usage: dotnet [options]                Usage: dotnet [path-to-application]                                Options:                -h|--help         Display help.                --info            Display .NET information.                --list-sdks       Display the installed SDKs.                --list-runtimes   Display the installed runtimes.                                path-to-application:                The path to an application .dll file to execute.

If everything looks good, select the Continue button below to go to the next step.

Got an error?

If you receive a 'dotnet' is not recognized as an internal or external command error, make sure you opened a new command prompt. If you can't resolve the issue, use the I ran into an issue button below to get help fixing the problem.

Create your app

In your command prompt, run the following command to create your app:

In your terminal, run the following command to create your app:

Command prompt

                              dotnet new blazorserver -o BlazorApp --no-https

This command creates your new Blazor app project and places it in a new directory called BlazorApp inside your current location.

Navigate to the new BlazorApp directory created by the previous command:

Command prompt

                              cd BlazorApp

Take a quick look at the contents of the BlazorApp directory. Several files were created in the BlazorApp directory, to give you a simple Blazor app that is ready to run.

Program.cs is the entry point for the app that starts the server and where you configure the app services and middleware.
App.razor is the root component for the app.
The Pages directory contains some example web pages for the app.
BlazorApp.csproj defines the app project and its dependencies.
The launchSettings.json file inside the Properties directory defines different profile settings for the local development environment. A port number ranging between 5000-5300 is automatically assigned at project creation and saved on this file.

Take note of the BlazorApp directory path as you will use it later in the tutorial.

If everything looks good, select the Continue button below to go to the next step.

Got an error?

If you receive a message similar to Template "Blazor Server App" could not be created. Access to the path 'C:\Windows\System32\BlazorApp' is denied, change your current directory to one where you have permissions to create a new folder and try to run the command again. If you can't resolve the issue, use the I ran into an issue button below to get help fixing the problem.

If Windows can't find the SDK when you try to create the project and you are sure you have installed the SDK, your machine might have an issue with the PATH environment variable. See this Stack Overflow post for instructions on how to diagnose and fix this issue.

If you can't resolve the issue you're having, select the I ran into an issue button below to get help fixing the problem.

Run your app

In your command prompt, run the following command:

In your terminal, run the following command:

Command prompt

                              dotnet watch

The dotnet watch command will build and start the app, and then update the app whenever you make code changes. You can stop the app at any time by selecting Ctrl+C.

Wait for the app to display that it's listening on http://localhost:<port number> and for the browser to launch at that address.

Wait for the app to display that it's listening on http://localhost:<port number> and then open a browser and navigate to that address. In this example, dotnet watch showed it was listening on http://localhost:5000.

Once you get to the following page, you have successfully run your first Blazor app!

The home page of your site contains some text and presents several tabs on the left to click and explore.

The displayed page is defined by the Index.razor file located inside the Pages directory. This is what its contents look like:

Pages/Index.razor

                              @page "/"                                <PageTitle>Index</PageTitle>                                <h1>Hello, world!</h1>                                Welcome to your new app.                                <SurveyPrompt Title="How is Blazor working for you?" />

It already contains the code that sets it as the homepage and displays the text "Hello, world!" and "Welcome to your new app". It also includes a SurveyPrompt component that renders a link to the Blazor feedback survey.

Try the counter

In the running app, navigate to the Counter page by clicking the Counter tab in the sidebar on the left. The following page should then be displayed:

The Counter page presents a Click me button to increment the count showed on the page.

Select the Click me button to increment the count without a page refresh. Incrementing a counter in a webpage normally requires writing JavaScript, but with Blazor you can use C#.

You can find the implementation of the Counter component at Counter.razor file located inside the Pages directory.

Pages/Counter.razor

                              @page "/counter"                                <PageTitle>Counter</PageTitle>                                <h1>Counter</h1>                                <p role="status">Current count: @currentCount</p>                                <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>                                @code {                                  private int currentCount = 0;                                                  private void IncrementCount()                                  {                                  currentCount++;                                  }                }

A request for /counter in the browser, as specified by the @page directive at the top, causes the Counter component to render its content.

Each time the Click me button is selected:

The onclick event is fired.
The IncrementCount method is called.
The currentCount is incremented.
The component is rendered to show the updated count.

Add a component

Each of the .razor files defines a UI component that can be reused.

Open the Index.razor file in a text editor of your choice. The Index.razor file already exists, and it was created when you ran the dotnet new command. It's located in the Pages folder inside the BlazorApp directory that was created earlier.

Add a Counter component to the app's homepage by adding a <Counter /> element at the end of the Index.razor file.

Pages/Index.razor

                              @page "/"                                <PageTitle>Counter</PageTitle>                                <h1>Hello, world!</h1>                                Welcome to your new app.                                <SurveyPrompt Title="How is Blazor working for you?" />                                <Counter />

Once this change is saved, the dotnet watch command will apply the change to the running app so that the Counter component shows up on the home page.

The home page now contains a Counter that displays a count and button.

Modify a component

Component parameters are specified using attributes or child content, which allow you to set properties on the child component. Define a parameter on the Counter component for specifying how much it increments with every button click:

Add a public property for IncrementAmount with a [Parameter] attribute.
Change the IncrementCount method to use the IncrementAmount when incrementing the value of currentCount.

The following code shows how to achieve that. The highlighted lines show the changes.

Pages/Counter.razor

                              @page "/counter"                                <PageTitle>Counter</PageTitle>                                <h1>Counter</h1>                                <p>Current count: @currentCount</p>                                <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>                                @code {                                  private int currentCount = 0;                                                  [Parameter]                                  public int IncrementAmount { get; set; } = 1;                                                  private void IncrementCount()                                  {                                  currentCount += IncrementAmount;                                  }                }

In Index.razor, update the <Counter> element to add an IncrementAmount attribute that changes the increment amount to ten as shown by the highlighted line in the following code:

Pages/Index.razor

                              @page "/"                                <h1>Hello, world!</h1>                                Welcome to your new app.                                <SurveyPrompt Title="How is Blazor working for you?" />                                <Counter IncrementAmount="10" />

The Index component now has its own counter that increments by ten each time the Click me button is selected, as shown in the following image. The Counter component (Counter.razor) at /counter continues to increment by one.

The homepage now contains a Counter that increments by 10 showing counter at 40.

Next steps

Congratulations, you've built and run your first Blazor app!

Keep learning

Now that you've got the basics, continue building your first Blazor app with Blazor self-guided learning module on Microsoft Learn where you will build a to-do list app.

Microsoft Learn: Build a Blazor todo list app

Blazor 101

Let Jeff walk you through building a full Blazor app from start to finish: