Project Structure and App.razor

Analogy categoryAnalogies

A default Blazor Web App project (created via dotnet new blazor) follows a predictable folder layout: Components/ holds your .razor files, split into Pages/ (routable components), Layout/ (shell components like MainLayout.razor), and shared reusable components at the top level; wwwroot/ holds static assets like CSS, images, and JavaScript; and Program.cs is the entry point that configures services and the request pipeline. Understanding this layout is the first step to navigating any Blazor codebase.

🏏

Cricket analogy: It's like a franchise's setup for an IPL season: the squad (Components/Pages) is separate from the coaching staff and dugout roles (Layout), the kit and equipment room (wwwroot) is separate from both, and the team charter (Program.cs) sets the rules everyone follows.

App.razor: The Root Document

Components/App.razor is the root component that renders the actual HTML document: it contains the <head> with stylesheet links and the <HeadOutlet> component (which lets pages inject page-specific <PageTitle> and <HeadContent>), and the <body> with a <Routes> component wrapped in a <CascadingAuthenticationState> if authentication is used. This is analogous to index.html in a JavaScript SPA, but because it's a Razor component itself, it can also declare a render mode that becomes the default for the whole app.

🏏

Cricket analogy: App.razor is like the stadium itself: it's the fixed structure (pitch, stands, floodlights) that every match (page) is played within, while the specific match details change each time — the stadium doesn't change, but what's shown inside it does.

Layout Components

A layout is a component that implements LayoutComponentBase and exposes a @Body placeholder where the current page's content is injected; MainLayout.razor (found in Components/Layout/) typically wraps a navigation sidebar (NavMenu.razor) around @Body. Individual pages opt into a layout with the @layout directive, or inherit the default set in Routes.razor, so you can have multiple layouts (e.g., a public layout and an authenticated dashboard layout) within one app.

🏏

Cricket analogy: MainLayout is like the broadcast studio's fixed graphics overlay (score bug, sponsor banners) that frames every ball bowled, while @Body is the live camera feed of the actual delivery that changes constantly within that fixed frame.

razor

@* Components/Layout/MainLayout.razor *@
@inherits LayoutComponentBase

<div class="page">
    <div class="sidebar">
        <NavMenu />
    </div>

    <main>
        <div class="top-row px-4">
            <a href="https://learn.microsoft.com/aspnet/core/" target="_blank">About</a>
        </div>

        <article class="content px-4">
            @Body
        </article>
    </main>
</div>

The Components/_Imports.razor file applies @using statements to every component in its folder and subfolders automatically, which is why you rarely see explicit @using Microsoft.AspNetCore.Components.Web at the top of individual page files — it's already inherited from the root _Imports.razor.

Components/Pages holds routable pages, Components/Layout holds shell layouts, and wwwroot holds static assets.
Program.cs is the app's entry point, configuring services and the ASP.NET Core request pipeline.
App.razor is the root component that renders the actual HTML document, similar to index.html in a JS SPA.
App.razor contains <HeadOutlet> for per-page <PageTitle> and <HeadContent> injection.
A layout implements LayoutComponentBase and exposes @Body where the current page's content is injected.
Pages opt into a layout via the @layout directive or inherit the default from Routes.razor.
_Imports.razor applies @using directives to every component in its folder and subfolders automatically.

Practice what you learned

1. Which folder in a default Blazor Web App project holds static assets like CSS and images?

2. What is the role of App.razor?

3. What base class must a layout component implement?

4. How does a page component specify a non-default layout?

5. What does _Imports.razor do?

Was this page helpful?

Blazor Server vs Blazor WebAssembly

Your First Razor Component

Related Study Notes in Microsoft Technologies

Browse all study notes

Microsoft Technologies

Windows 10 / UWP Development Study Notes

.NET · 30 topics

Microsoft Technologies

Windows Batch Scripting Study Notes

Batch · 30 topics

Microsoft Technologies

MFC (Microsoft Foundation Classes) Study Notes

C++ · 30 topics

Microsoft Technologies

Silverlight Study Notes

.NET · 30 topics

Microsoft Technologies

XAML Study Notes

.NET · 30 topics

Microsoft Technologies

WPF (Windows Presentation Foundation) Study Notes

.NET · 30 topics

Topics covered

#BlazorStudyNotes#MicrosoftTechnologies#ProjectStructureAndAppRazor#Project#Structure#App#Razor#StudyNotes#SkillVeris#ExamPrep

Project Structure and App.razor