C# / .NET Compendium PLEN
.NET / C# / Web API, Blazor

The standard Blazor project structure

Blazor WebAssembly (standalone, with no separate backend)

MyBlazorApp/
├── wwwroot/                       ← static files, served directly
│   ├── css/
│   │   └── app.css
│   ├── index.html                 ← the only "real" HTML file, the SPA entry point
│   ├── favicon.png
│   ├── manifest.json              ← z rozmowy o PWA
│   └── service-worker.js          ← z rozmowy o PWA
├── Pages/                         ← komponenty routowalne (@page)
│   ├── Home.razor
│   ├── Counter.razor
│   ├── Orders/
│   │   ├── OrderList.razor
│   │   └── OrderDetails.razor
├── Shared/                        ← shared components, layouts
│   ├── MainLayout.razor
│   ├── NavMenu.razor
│   └── OrderCard.razor            ← a reusable component (without @page)
├── Models/                        ← models/DTOs used in the UI
│   └── OrderDto.cs
├── Services/                      ← logika, klienci API
│   ├── IOrderApiClient.cs
│   └── OrderApiClient.cs
├── wwwroot/appsettings.json       ← konfiguracja (adres API itp.)
├── _Imports.razor                 ← globalne "using" dla wszystkich .razor
├── App.razor                      ← the routing root (<Router>)
├── Program.cs                     ← punkt startowy, konfiguracja DI
└── MyBlazorApp.csproj

Key files - what they do

Program.cs - the starting point, DI (exactly the same container we discussed with WPF/Web API):

var builder = WebAssemblyHostBuilder.CreateDefault(args);
builder.RootComponents.Add<App>("#app");

builder.Services.AddHttpClient<IOrderApiClient, OrderApiClient>(client =>
    client.BaseAddress = new Uri(builder.Configuration["ApiBaseUrl"]));
builder.Services.AddScoped<IOrderApiClient, OrderApiClient>();

await builder.Build().RunAsync();

App.razor - the application root, defines routing:

<Router AppAssembly="@typeof(App).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
    </Found>
    <NotFound>
        <LayoutView Layout="@typeof(MainLayout)">
            <p>Strona nie znaleziona</p>
        </LayoutView>
    </NotFound>
</Router>

_Imports.razor - global usings, so you don't repeat them in every component:

@using System.Net.Http
@using Microsoft.AspNetCore.Components.Routing
@using MyBlazorApp.Models
@using MyBlazorApp.Services

wwwroot/index.html - the entry point for WASM (the only "real" HTML):

<!DOCTYPE html>
<html>
<head>
    <link href="css/app.css" rel="stylesheet" />
</head>
<body>
    <div id="app">Loading...</div>
    <script src="_framework/blazor.webassembly.js"></script>
</body>
</html>

Shared/MainLayout.razor - the shared layout (header, menu, footer):

@inherits LayoutComponentBase

<div class="page">
    <NavMenu />
    <main>
        @Body
    </main>
</div>

Blazor Server - a slightly different structure

MyBlazorServerApp/
├── wwwroot/
│   └── css/site.css
├── Pages/
│   ├── _Host.cshtml               ← the startup file (a Razor Page, not .razor!), serves the first page
│   ├── Home.razor
│   └── Orders/
├── Shared/
│   ├── MainLayout.razor
│   └── NavMenu.razor
├── Data/                          ← often instead of Services/ in the default template
│   └── OrderService.cs
├── Hubs/                          ← optional, if you have your own SignalR hubs besides the default Blazor one
├── App.razor
├── Program.cs
├── appsettings.json                ← configi PO STRONIE SERWERA (connection stringi itd.)
└── MyBlazorServerApp.csproj

The key difference: Pages/_Host.cshtml (a Razor Page, not a Blazor component) - this is a classic ASP.NET Core page that renders the first Blazor component and loads the blazor.server.js script (SignalR). Direct database access from Data/OrderService.cs is more natural here (because the code runs on the server anyway, as we discussed with SignalR/circuits).

// Program.cs - Blazor Server
builder.Services.AddRazorPages();
builder.Services.AddServerSideBlazor();
builder.Services.AddDbContext<AppDbContext>(options => options.UseSqlServer(connectionString)); // direct EF Core

app.MapBlazorHub(); // endpoint SignalR
app.MapFallbackToPage("/_Host");

.NET 8+ Blazor Web App (the combined model, with Render Modes)

The new, unified template combining everything we discussed with Render Modes:

MyBlazorWebApp/
├── Client/                        ← a separate PROJECT for WASM components
│   ├── Program.cs
│   ├── _Imports.razor
│   └── Pages/
│       └── Counter.razor          ← komponent renderowany jako WASM
├── Components/                    ← components rendered server-side (by default)
│   ├── Layout/
│   │   ├── MainLayout.razor
│   │   └── NavMenu.razor
│   ├── Pages/
│   │   ├── Home.razor
│   │   └── Weather.razor
│   ├── App.razor                  ← the root, now contains <html>/<head>/<body>
│   └── Routes.razor                ← wydzielony routing (osobno od App.razor)
├── wwwroot/
├── Program.cs                     ← host WSZYSTKICH render modes naraz
└── MyBlazorWebApp.csproj

The key novelty - Program.cs configures both models at once:

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents()      // Interactive Server
    .AddInteractiveWebAssemblyComponents(); // Interactive WebAssembly

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode()
    .AddInteractiveWebAssemblyRenderMode()
    .AddAdditionalAssemblies(typeof(MyBlazorWebApp.Client._Imports).Assembly); // a reference to the Client project

Client/ is a separate project (.csproj) in the same solution - the code there is compiled to WASM and actually downloaded by the browser, whereas Components/ in the main project renders server-side by default, unless you explicitly mark a component with @rendermode InteractiveWebAssembly.


A typical architecture with a separate Web API

For Blazor WASM communicating with a separate backend (exactly the "WPF/Blazor → Web API → EF Core" architecture):

MySolution/
├── MyApp.Client/              ← Blazor WASM (frontend)
│   ├── Pages/
│   ├── Services/
│   │   └── OrderApiClient.cs  ← HttpClient for API calls
│   └── Program.cs
├── MyApp.Api/                 ← ASP.NET Core Web API (backend)
│   ├── Controllers/
│   │   └── OrdersController.cs
│   ├── Services/
│   │   └── OrderService.cs
│   ├── Data/
│   │   └── AppDbContext.cs
│   └── Program.cs
└── MyApp.Shared/              ← a SHARED project with DTOs, used by BOTH of the above
    └── DTOs/
        └── OrderDto.cs

MyApp.Shared is an important, practical pattern - a project with shared DTOs/Commands/Queries, referenced by both Client and Api. Thanks to this, an OrderDto as a record (as we discussed) is defined once, not duplicated on both sides - a contract change in one place is visible on both sides of the compilation.

Summary - how to choose a structure

Scenario Structure
A simple WASM application, a small team The standard blazorwasm template (Pages/Shared/Services)
Blazor Server, direct access to the database The standard blazorserver template (Data/ instead of Services/)
.NET 8+, you want the flexibility of Render Modes Blazor Web App (Client + Components in one solution)
WASM + a separate, reusable Web API (e.g. also for WPF/mobile) Three projects: Client, Api, Shared (DTOs)
Buy me a coffee