Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 41 ยท Getting Started

Setting Up and Project Structure

Install the .NET SDK, create a Blazor Web App with dotnet new, and learn what Program.cs, App.razor, Routes.razor, the Components folder and wwwroot do in a Blazor project.

You can have a Blazor app running in under five minutes. This lesson shows the commands, then walks through every file the template creates, because knowing what lives where makes the rest of the track much easier. Everything here uses .NET 10 and the Blazor Web App template.

Install and create a project

Install the .NET SDK from Microsoft, then open a terminal and check it:

Terminal
dotnet --version

Create and run a new app:

Terminal
dotnet new blazor -o MyFirstApp
cd MyFirstApp
dotnet run

dotnet run builds the project and prints a local address such as http://localhost:5253. Open it in a browser and you will see the template's home page. Edit a .razor file while running with dotnet watch and the page reloads automatically.

The template accepts options that choose how interactive the app is:

Option Meaning
--interactivity Server Components run on the server (the default)
--interactivity WebAssembly Components run in the browser
--interactivity Auto Server first, then WebAssembly
--interactivity None Static server rendering only
--all-interactive Every component interactive by default
--empty A minimal project without sample pages

Example: dotnet new blazor -o Shop --interactivity Auto --all-interactive.

What the template creates

A default Server-interactive project looks like this:

TEXT
MyFirstApp/
  Program.cs
  MyFirstApp.csproj
  appsettings.json
  Properties/launchSettings.json
  Components/
    App.razor
    Routes.razor
    _Imports.razor
    Layout/
      MainLayout.razor
      NavMenu.razor
    Pages/
      Home.razor
      Counter.razor
      Weather.razor
      Error.razor
  wwwroot/
    app.css
    favicon.png
    lib/bootstrap/

Let's go file by file.

Program.cs: the entry point

C#
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseAntiforgery();
app.MapStaticAssets();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

app.Run();

This is a normal ASP.NET Core startup. AddRazorComponents registers the services Blazor needs, MapRazorComponents<App> says "the root component is App", and AddInteractiveServerRenderMode switches on live server interactivity. Services you register on builder.Services become available to components through dependency injection (chapter 6).

App.razor: the HTML shell

App.razor is the root component and the only place that writes the full <html> document:

HTML
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <base href="/" />
    <link rel="stylesheet" href="@Assets["app.css"]" />
    <HeadOutlet />
</head>
<body>
    <Routes />
    <script src="_framework/blazor.web.js"></script>
</body>
</html>

<HeadOutlet /> lets any component add a page title or meta tag. <Routes /> is where your pages appear. blazor.web.js is the small JavaScript file that connects the page to the server (or loads WebAssembly).

Routes.razor and _Imports.razor

Routes.razor contains the Router component, which maps the URL to a page component and applies the default layout:

HTML
<Router AppAssembly="typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" DefaultLayout="typeof(Layout.MainLayout)" />
        <FocusOnNavigate RouteData="routeData" Selector="h1" />
    </Found>
    <NotFound>
        <p>Sorry, there's nothing at this address.</p>
    </NotFound>
</Router>

_Imports.razor holds @using lines that apply to every component in its folder and below, so you do not repeat them:

HTML
@using System.Net.Http
@using Microsoft.AspNetCore.Components.Routing
@using Microsoft.AspNetCore.Components.Web
@using static Microsoft.AspNetCore.Components.Web.RenderMode
@using MyFirstApp
@using MyFirstApp.Components

Routing is the subject of chapter 5; for now treat these two files as plumbing.

Pages and Layout folders

A page is a component with an @page directive that gives it a URL. Home.razor starts with @page "/", Counter.razor with @page "/counter". A layout wraps pages with shared markup such as a header and navigation; MainLayout.razor is the default. Anything under Components/ is a component, and there is no technical difference between a folder named Pages and one named Widgets; the folders are just a convention.

wwwroot

Files in wwwroot are served as-is: CSS, images, fonts and JavaScript. Reference them with root-relative paths such as /images/logo.png.

The .csproj

XML
<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>
</Project>

Nullable turns on nullable reference type warnings. ImplicitUsings adds common namespaces automatically.

A runnable stand-in: the host builder pattern

The real Program.cs follows a pattern: register services, build, then configure the pipeline. Here is that shape in plain C# so you can see why the order matters. It is a stand-in, not ASP.NET Core.

C# Stand-in: register, build, map

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

In real ASP.NET Core the same rule applies: you cannot add services after builder.Build().

Useful commands

Command What it does
dotnet run Build and start the app
dotnet watch Rebuild and refresh when files change
dotnet build Compile only
dotnet publish -c Release Produce deployable output
dotnet new list blazor Show Blazor templates

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file contains the HTML document shell (html, head, body) in a Blazor Web App?

    App.razor is the root component. It writes the document, includes HeadOutlet, Routes and the Blazor script.
  2. 2. What is _Imports.razor for?

    It saves you from repeating the same @using lines in every component.
  3. 3. Where do static files such as images and CSS go?

    wwwroot is served as static content.
  4. 4. Which command rebuilds and refreshes the app automatically as you edit?

    dotnet watch (or dotnet watch run) rebuilds on file changes and refreshes the browser.

Summary

  • dotnet new blazor creates a Blazor Web App; dotnet run starts it, dotnet watch reloads on edits.
  • Program.cs registers services and maps the root App component.
  • App.razor is the HTML shell; Routes.razor holds the router; _Imports.razor shares @using lines.
  • Pages are components with @page; layouts wrap them; wwwroot holds static files.

Next: Your First Component