Project Structure

A Blazor project is an ASP.NET Core project with a folder of .razor files in it. Nothing is hidden and nothing is generated behind your back, but a handful of small files carry more weight than their size suggests. Knowing which ones saves a lot of searching later.

This lesson walks the project the template gives you and names the job of each part. Create the project as you read, so the file names mean something.

# Create a Blazor Web App
dotnet new blazor -o EmployeePortal

# Or ask for interactivity up front: None, Server, WebAssembly or Auto
dotnet new blazor -o EmployeePortal --interactivity Server

cd EmployeePortal

# Build, run, and rebuild when a file is saved
dotnet watch run

• dotnet new blazor creates the current Blazor Web App template: server-rendered by default, with interactivity added per component.
• The interactivity switch decides which render modes the project is wired up for. It sets up registrations in Program.cs, so choosing wrongly now costs you a few lines later rather than a new project.
• dotnet watch run rebuilds and reloads the browser when you save a .razor file. It shortens the edit-and-look loop enough to be worth the habit.
• The console prints the address it is listening on. Use the https one: the template configures a local development certificate, and some browser features are unavailable over plain http.

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddHttpClient<EmployeeApiClient>(client =>
{
    client.BaseAddress = new Uri(builder.Configuration["EmployeeApi:BaseAddress"]!);
});

var app = builder.Build();

app.UseStaticFiles();
app.UseAntiforgery();

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

app.Run();

• AddRazorComponents registers what the framework needs in order to render components. AddInteractiveServerComponents adds the server interactive render mode; a project that also runs components in the browser adds the WebAssembly equivalent alongside it.
• The typed HttpClient registration means a component can ask for an EmployeeApiClient and receive one with its base address already set from configuration. Dependency injection has its own lesson later in this course; the point here is that this file is where the answer lives.
• The exclamation mark after the configuration lookup tells the compiler you expect a value there. A missing setting then fails loudly at startup rather than quietly later.
• UseAntiforgery is required for form posts. The template includes it, and removing it breaks EditForm when a form is rendered on the server.
• MapRazorComponents names the root component, App. AddInteractiveServerRenderMode is what makes @rendermode InteractiveServer legal — without it, requesting a page that asks for that mode fails with a message about the render mode not being configured.
• Recent templates call MapStaticAssets instead of UseStaticFiles, which adds fingerprinting and compression for static files. UseStaticFiles still works and is shown here because it is the form you will meet in most existing projects.

@* _Imports.razor — inherited by every component in this folder and below *@
@using Microsoft.AspNetCore.Components.Forms
@using Microsoft.AspNetCore.Components.Routing
@using Microsoft.AspNetCore.Components.Web
@using EmployeePortal.Components
@using EmployeePortal.Models

@* Routes.razor *@
<Router AppAssembly="typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" DefaultLayout="typeof(Layout.MainLayout)" />
        <FocusOnNavigate RouteData="routeData" Selector="h1" />
    </Found>
</Router>

• Everything in _Imports.razor is a using directive that every component below it inherits. Add a namespace here once instead of at the top of every file.
• It does not reach plain .cs files. A service class still needs its own using directives, which surprises people who added a namespace here and cannot work out why the class will not compile.
• Router scans the named assembly for components carrying @page and builds the route table at startup. You never register a route by hand.
• RouteView renders the matched component inside DefaultLayout. That is why a page shows the navigation and footer without asking for them.
• FocusOnNavigate moves keyboard focus to the first h1 after a navigation. Without it, someone using a keyboard or a screen reader stays parked where the old link was and the new page goes unannounced.
• In a Blazor Web App, an address matching nothing is handled by the server, which returns a 404. A standalone WebAssembly application has no server in that loop, so its router carries a NotFound section instead.

{
  "EmployeeApi": {
    "BaseAddress": "https://localhost:7180/"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*"
}

• Nested keys are read with a colon between the levels, which is the EmployeeApi:BaseAddress lookup used in Program.cs.
• appsettings.Development.json overrides these values on a developer machine, and environment variables override both. That ordering is how the same build runs in three environments.
• A Blazor Server project reads this file on the server, so it is never downloaded. A standalone WebAssembly project's configuration is served to the browser, so treat every value in that one as public and keep credentials behind an API.