Blazor lets you build interactive web UIs using C# instead of JavaScript. Whether you target WebAssembly for offline-capable apps or Blazor Server for real-time experiences, you write the same component model, enjoy full .NET tooling, and ship faster.
In this tutorial, you'll build a Todo Dashboard from the ground up. You'll learn how components work, how to bind data, handle forms, manage state, call APIs, and deploy production-ready apps. By the end, you'll have practical experience with Blazor .NET 8's new render modes, streaming SSR, QuickGrid, and authentication patterns.
The Todo Dashboard evolves from a simple list to a full-featured app with:
Blazor for .NET 8 brings unified render modes, streaming server-side rendering, and productivity enhancements that make building interactive web UIs faster and more flexible. Here's what makes Blazor .NET 8 compelling:
Choose per page or component: SSR for static content, InteractiveServer for real-time updates, InteractiveWebAssembly for offline, or Auto for best of both worlds.
Progressively send markup as data becomes available for faster perceived page loads on dashboards and reports with slow data sources.
C# 12 primary constructors for component parameters and collection expressions for list rendering make code more concise and expressive.
Built-in data grid with sorting, filtering, pagination, and virtualization out of the box—no third-party libraries needed for common scenarios.
Streamlined authentication scaffolding with better protected content patterns and improved integration with ASP.NET Core Identity.
.NET 8 is an LTS release supported through November 2026. Start with SSR plus interactive islands for optimal UX and performance. Use full WebAssembly when offline capability is required or when you need maximum client-side scalability.
You need the .NET 8 SDK to build Blazor applications. The SDK includes templates for both Blazor Server and Blazor WebAssembly projects.
Download from dotnet.microsoft.com/download and verify installation:
dotnet --version
# Should show 8.0.x or higher# Blazor Web App (default: SSR with optional interactivity)
dotnet new blazor -n TodoDashboard
cd TodoDashboard
dotnet run
# Blazor WebAssembly (client-side only)
dotnet new blazorwasm -n TodoDashboard.Wasm
# With Auto interactivity (hybrid SSR/interactive)
dotnet new blazor -n TodoDashboard --interactivity Auto
Your app will start on https://localhost:5001. The default template includes sample components demonstrating weather data and counter interactions.
TodoDashboard/
├── Components/
│ ├── Layout/
│ │ ├── MainLayout.razor
│ │ └── NavMenu.razor
│ ├── Pages/
│ │ ├── Home.razor
│ │ ├── Counter.razor
│ │ └── Weather.razor
│ ├── _Imports.razor # Global using statements
│ └── App.razor # Root component
├── wwwroot/ # Static assets
├── appsettings.json
├── Program.cs # App configuration
└── TodoDashboard.csprojFor data grids with built-in features, add the QuickGrid package:
dotnet add package Microsoft.AspNetCore.Components.QuickGridvar builder = WebApplication.CreateBuilder(args);
// Add services
builder.Services.AddRazorComponents()
.AddInteractiveServerComponents()
.AddInteractiveWebAssemblyComponents();
var app = builder.Build();
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseAntiforgery();
// Map Razor components with render modes
app.MapRazorComponents<App>()
.AddInteractiveServerRenderMode()
.AddInteractiveWebAssemblyRenderMode();
app.Run();Visual Studio 2022 (17.8+), Visual Studio Code with C# Dev Kit, and JetBrains Rider (2023.3+) all support Blazor with hot reload, IntelliSense, and component debugging.
Blazor components are reusable UI chunks written in Razor syntax (.razor files). Components combine HTML markup with C# logic and can nest, pass parameters, and respond to events.
<div class="todo-card">
<h3>@Title</h3>
<p>@Description</p>
<button @onclick="HandleClick">Mark Complete</button>
</div>
@code {
[Parameter]
public string Title { get; set; } = string.Empty;
[Parameter]
public string Description { get; set; } = string.Empty;
[Parameter]
public EventCallback OnComplete { get; set; }
private async Task HandleClick()
{
await OnComplete.InvokeAsync();
}
}Blazor components have lifecycle methods you can override for initialization, parameter changes, and rendering:
@page "/todo/{Id:int}"
@inject ITodoService TodoService
<h2>@todo?.Title</h2>
<p>@todo?.Description</p>
@code {
[Parameter]
public int Id { get; set; }
private TodoItem? todo;
protected override async Task OnInitializedAsync()
{
// Load data once on initialization
todo = await TodoService.GetByIdAsync(Id);
}
protected override async Task OnParametersSetAsync()
{
// Reload if Id parameter changes
if (Id > 0)
{
todo = await TodoService.GetByIdAsync(Id);
}
}
protected override async Task OnAfterRenderAsync(bool firstRender)
{
if (firstRender)
{
// JS interop safe here - DOM is ready
await JSRuntime.InvokeVoidAsync("scrollToTop");
}
}
}C# 12 primary constructors work beautifully with component parameters for cleaner code:
@code {
[Inject]
private ITodoService TodoService { get; set; } = default!;
[Inject]
private ILogger<TodoList> Logger { get; set; } = default!;
[Parameter]
public string Filter { get; set; } = "all";
private List<TodoItem> todos = new();
protected override async Task OnInitializedAsync()
{
todos = await TodoService.GetAllAsync();
Logger.LogInformation("Loaded {Count} todos", todos.Count);
}
}@inject ITodoService TodoService
@inject ILogger<TodoList> Logger
@code {
[Parameter]
public string Filter { get; set; } = "all";
private List<TodoItem> todos = [];
protected override async Task OnInitializedAsync()
{
todos = await TodoService.GetAllAsync();
Logger.LogInformation("Loaded {Count} todos", todos.Count);
}
}@page "/route" - Define routable component@inject Service - Inject dependency@using Namespace - Import namespace@attribute [Authorize] - Apply attributes to component@rendermode InteractiveServer - Set component render mode@key - Help Blazor identify elements in listsAvoid heavy work in OnAfterRender without guards—it runs on every render. Use the firstRender parameter to execute logic only once. Use StateHasChanged() sparingly; Blazor automatically re-renders after event handlers complete.
Blazor provides declarative data binding with @bind for two-way synchronization between UI and C# properties. Forms include validation with DataAnnotations or FluentValidation.
@page "/binding-demo"
<h3>Current Value: @currentValue</h3>
<!-- Two-way binding -->
<input @bind="currentValue" />
<!-- Two-way binding with event -->
<input @bind="currentValue" @bind:event="oninput" />
<!-- Formatted binding -->
<input type="date" @bind="selectedDate" @bind:format="yyyy-MM-dd" />
<!-- Controlled binding (C# 12 style) -->
<input value="@controlledValue"
@oninput="@(e => controlledValue = e.Value?.ToString() ?? "")" />
@code {
private string currentValue = "";
private DateTime selectedDate = DateTime.Today;
private string controlledValue = "";
}@page "/todo/create"
@inject ITodoService TodoService
@inject NavigationManager Navigation
<h2>Create Todo</h2>
<EditForm Model="@model" OnValidSubmit="HandleSubmit">
<DataAnnotationsValidator />
<ValidationSummary />
<div class="form-group">
<label>Title:</label>
<InputText @bind-Value="model.Title" class="form-control" />
<ValidationMessage For="@(() => model.Title)" />
</div>
<div class="form-group">
<label>Description:</label>
<InputTextArea @bind-Value="model.Description" class="form-control" />
<ValidationMessage For="@(() => model.Description)" />
</div>
<div class="form-group">
<label>Priority:</label>
<InputSelect @bind-Value="model.Priority" class="form-control">
<option value="Low">Low</option>
<option value="Medium">Medium</option>
<option value="High">High</option>
</InputSelect>
</div>
<div class="form-group">
<label>
<InputCheckbox @bind-Value="model.IsUrgent" />
Mark as Urgent
</label>
</div>
<button type="submit" class="btn btn-primary">Create</button>
<button type="button" class="btn btn-secondary" @onclick="Cancel">Cancel</button>
</EditForm>
@code {
private TodoCreateModel model = new();
private async Task HandleSubmit()
{
await TodoService.CreateAsync(model);
Navigation.NavigateTo("/todos");
}
private void Cancel()
{
Navigation.NavigateTo("/todos");
}
}
public class TodoCreateModel
{
[Required]
[StringLength(100, MinimumLength = 3)]
public string Title { get; set; } = string.Empty;
[StringLength(500)]
public string? Description { get; set; }
[Required]
public string Priority { get; set; } = "Medium";
public bool IsUrgent { get; set; }
}For complex validation rules, use FluentValidation:
// Install: dotnet add package FluentValidation
using FluentValidation;
public class TodoCreateModelValidator : AbstractValidator<TodoCreateModel>
{
public TodoCreateModelValidator()
{
RuleFor(x => x.Title)
.NotEmpty().WithMessage("Title is required")
.Length(3, 100).WithMessage("Title must be 3-100 characters")
.Must(NotContainBadWords).WithMessage("Title contains inappropriate content");
RuleFor(x => x.Description)
.MaximumLength(500).WithMessage("Description too long");
RuleFor(x => x.Priority)
.Must(p => new[] { "Low", "Medium", "High" }.Contains(p))
.WithMessage("Invalid priority");
}
private bool NotContainBadWords(string title)
{
var badWords = new[] { "spam", "test" };
return !badWords.Any(word => title.Contains(word, StringComparison.OrdinalIgnoreCase));
}
}Use C# 12 record types with validation attributes for form models. Records provide value semantics and immutability by default, making state management clearer. For controlled inputs, use @bind:get and @bind:set directives for fine-grained control.
Blazor routing maps URLs to components using the @page directive. The router supports parameters, constraints, query strings, and programmatic navigation.
@* Simple route *@
@page "/todos"
@* Route with parameter *@
@page "/todo/{id:int}"
@* Optional parameter *@
@page "/search/{query?}"
@* Multiple constraints *@
@page "/posts/{year:int:min(2020)}/{month:int:range(1,12)}"
@* Catch-all parameter *@
@page "/docs/{*path}"
@code {
[Parameter]
public int Id { get; set; }
[Parameter]
public string? Query { get; set; }
[Parameter]
public int Year { get; set; }
[Parameter]
public int Month { get; set; }
[Parameter]
public string? Path { get; set; }
}@page "/search"
@inject NavigationManager Navigation
<h2>Search Results</h2>
<input @bind="searchQuery" @bind:event="oninput" />
<button @onclick="Search">Search</button>
<p>Query: @Query</p>
<p>Page: @Page</p>
@code {
[Parameter]
[SupplyParameterFromQuery]
public string? Query { get; set; }
[Parameter]
[SupplyParameterFromQuery(Name = "page")]
public int Page { get; set; } = 1;
private string searchQuery = "";
private void Search()
{
Navigation.NavigateTo($"/search?query={searchQuery}&page=1");
}
}@inject NavigationManager Navigation
<button @onclick="NavigateToTodos">View Todos</button>
<button @onclick="NavigateToDetail">View Detail</button>
<button @onclick="GoBack">Go Back</button>
@code {
private void NavigateToTodos()
{
Navigation.NavigateTo("/todos");
}
private void NavigateToDetail()
{
Navigation.NavigateTo($"/todo/{42}");
}
private void GoBack()
{
Navigation.NavigateTo("/", replace: true);
}
protected override void OnInitialized()
{
// Get current URL
var uri = Navigation.Uri;
var baseUri = Navigation.BaseUri;
// Listen to location changes
Navigation.LocationChanged += HandleLocationChanged;
}
private void HandleLocationChanged(object? sender, LocationChangedEventArgs e)
{
Console.WriteLine($"Navigated to {e.Location}");
}
public void Dispose()
{
Navigation.LocationChanged -= HandleLocationChanged;
}
}<Router AppAssembly="@typeof(App).Assembly">
<Found Context="routeData">
<RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
<FocusOnNavigate RouteData="@routeData" Selector="h1" />
</Found>
<NotFound>
<PageTitle>Not Found</PageTitle>
<LayoutView Layout="@typeof(MainLayout)">
<div class="not-found">
<h1>404 - Page Not Found</h1>
<p>The page you're looking for doesn't exist.</p>
<a href="/">Return to Home</a>
</div>
</LayoutView>
</NotFound>
</Router>With SSR render mode, the first load is server-rendered HTML. Interactive render modes (Server or WebAssembly) then hydrate the page, enabling client-side navigation. This provides fast initial loads with SPA-like navigation after hydration completes.
State management in Blazor ranges from local component state to shared application state. Choose the right approach based on scope and lifetime requirements.
@page "/counter"
<h2>Counter: @count</h2>
<button @onclick="Increment">Increment</button>
<button @onclick="Decrement">Decrement</button>
<button @onclick="Reset">Reset</button>
@code {
private int count = 0;
private void Increment() => count++;
private void Decrement() => count--;
private void Reset() => count = 0;
}Cascading values pass data down the component tree without explicit parameters at each level:
@* MainLayout.razor *@
<CascadingValue Value="@currentTheme">
@Body
</CascadingValue>
@code {
private string currentTheme = "light";
}
@* Child component anywhere in the tree *@
@code {
[CascadingParameter]
public string Theme { get; set; } = "light";
}public class TodoStateService
{
private List<TodoItem> _todos = [];
public event Action? OnChange;
public IReadOnlyList<TodoItem> Todos => _todos.AsReadOnly();
public void AddTodo(TodoItem todo)
{
_todos.Add(todo);
NotifyStateChanged();
}
public void RemoveTodo(int id)
{
var todo = _todos.FirstOrDefault(t => t.Id == id);
if (todo != null)
{
_todos.Remove(todo);
NotifyStateChanged();
}
}
public void UpdateTodo(TodoItem updatedTodo)
{
var index = _todos.FindIndex(t => t.Id == updatedTodo.Id);
if (index != -1)
{
_todos[index] = updatedTodo;
NotifyStateChanged();
}
}
private void NotifyStateChanged() => OnChange?.Invoke();
}
// Register in Program.cs
builder.Services.AddScoped<TodoStateService>();@page "/todos"
@inject TodoStateService StateService
@implements IDisposable
<h2>Todos (@StateService.Todos.Count)</h2>
@foreach (var todo in StateService.Todos)
{
<div class="todo-item">
<span>@todo.Title</span>
<button @onclick="() => Delete(todo.Id)">Delete</button>
</div>
}
@code {
protected override void OnInitialized()
{
StateService.OnChange += StateHasChanged;
}
private void Delete(int id)
{
StateService.RemoveTodo(id);
}
public void Dispose()
{
StateService.OnChange -= StateHasChanged;
}
}Avoid accidental singleton cross-user state in Blazor Server apps. Use scoped services where identity or user-specific data matters. Singleton services are shared across all users and circuits—only use them for truly global, immutable data.
Most Blazor apps don't need JavaScript, but when you do need browser APIs or third-party libraries, JavaScript interop provides the bridge. Use it sparingly and wrap it in services for testability.
@page "/interop-demo"
@inject IJSRuntime JS
<button @onclick="ShowAlert">Show Alert</button>
<button @onclick="CopyText">Copy to Clipboard</button>
<button @onclick="GetScreenSize">Get Screen Size</button>
<p>@message</p>
@code {
private string message = "";
private async Task ShowAlert()
{
await JS.InvokeVoidAsync("alert", "Hello from Blazor!");
}
private async Task CopyText()
{
await JS.InvokeVoidAsync("navigator.clipboard.writeText", "Copied text");
message = "Text copied to clipboard";
}
private async Task GetScreenSize()
{
var width = await JS.InvokeAsync<int>("eval", "window.innerWidth");
var height = await JS.InvokeAsync<int>("eval", "window.innerHeight");
message = $"Screen: {width}x{height}";
}
}export function copyToClipboard(text) {
return navigator.clipboard.writeText(text);
}
export function readFromClipboard() {
return navigator.clipboard.readText();
}
export function showNotification(message, duration = 3000) {
const notification = document.createElement('div');
notification.className = 'notification';
notification.textContent = message;
document.body.appendChild(notification);
setTimeout(() => {
notification.remove();
}, duration);
}@inject IJSRuntime JS
@implements IAsyncDisposable
<button @onclick="Copy">Copy: @TextToCopy</button>
@code {
[Parameter]
public string TextToCopy { get; set; } = "";
private IJSObjectReference? module;
protected override async Task OnAfterRenderAsync(bool firstRender)
{
if (firstRender)
{
module = await JS.InvokeAsync<IJSObjectReference>(
"import", "./js/clipboard.js");
}
}
private async Task Copy()
{
if (module is not null)
{
await module.InvokeVoidAsync("copyToClipboard", TextToCopy);
await module.InvokeVoidAsync("showNotification", "Copied!");
}
}
public async ValueTask DisposeAsync()
{
if (module is not null)
{
await module.DisposeAsync();
}
}
}@inject IJSRuntime JS
@implements IDisposable
<div id="map"></div>
@code {
private DotNetObjectReference<MapComponent>? objRef;
protected override async Task OnAfterRenderAsync(bool firstRender)
{
if (firstRender)
{
objRef = DotNetObjectReference.Create(this);
await JS.InvokeVoidAsync("initMap", "map", objRef);
}
}
[JSInvokable]
public void OnMapClick(double lat, double lng)
{
Console.WriteLine($"Map clicked at {lat}, {lng}");
StateHasChanged();
}
public void Dispose()
{
objRef?.Dispose();
}
}
// In JavaScript:
// function initMap(elementId, dotnetHelper) {
// map.on('click', (e) => {
// dotnetHelper.invokeMethodAsync('OnMapClick', e.latlng.lat, e.latlng.lng);
// });
// }Before reaching for JS interop, check if Blazor has a built-in component. Use <InputFile> for file uploads, <NavigationManager> for routing, and <AuthorizeView> for auth. Wrap interop in services for easier unit testing.
Blazor integrates with ASP.NET Core Identity for Server apps and supports token-based authentication for WebAssembly apps calling backend APIs.
using Microsoft.AspNetCore.Identity;
var builder = WebApplication.CreateBuilder(args);
// Add authentication and authorization
builder.Services.AddAuthentication();
builder.Services.AddAuthorization();
// Add Identity (if using database)
builder.Services.AddIdentity<IdentityUser, IdentityRole>()
.AddEntityFrameworkStores<ApplicationDbContext>()
.AddDefaultTokenProviders();
builder.Services.AddRazorComponents()
.AddInteractiveServerComponents();
var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapRazorComponents<App>()
.AddInteractiveServerRenderMode();
app.Run();@page "/dashboard"
@attribute [Authorize]
<h2>Dashboard</h2>
<p>Welcome, @context.User.Identity?.Name</p>
<AuthorizeView>
<Authorized>
<p>You are logged in.</p>
</Authorized>
<NotAuthorized>
<p>Please log in.</p>
</NotAuthorized>
</AuthorizeView>
<AuthorizeView Roles="Admin">
<Authorized>
<button>Admin Action</button>
</Authorized>
</AuthorizeView>
<AuthorizeView Policy="RequireManagerRole">
<Authorized>
<p>Manager content</p>
</Authorized>
</AuthorizeView>// Register policy in Program.cs
builder.Services.AddAuthorization(options =>
{
options.AddPolicy("RequireManagerRole", policy =>
policy.RequireRole("Manager"));
options.AddPolicy("CanEditTodos", policy =>
policy.RequireClaim("Permission", "Edit"));
options.AddPolicy("SeniorEmployee", policy =>
policy.RequireAssertion(context =>
context.User.HasClaim(c =>
c.Type == "EmployeeLevel" &&
int.Parse(c.Value) >= 5)));
});// Install: Microsoft.AspNetCore.Components.WebAssembly.Authentication
var builder = WebAssemblyHostBuilder.CreateDefault(args);
builder.Services.AddHttpClient("TodoApi", client =>
client.BaseAddress = new Uri(builder.HostEnvironment.BaseAddress))
.AddHttpMessageHandler<BaseAddressAuthorizationMessageHandler>();
builder.Services.AddScoped(sp => sp.GetRequiredService<IHttpClientFactory>()
.CreateClient("TodoApi"));
// OIDC authentication
builder.Services.AddOidcAuthentication(options =>
{
builder.Configuration.Bind("Auth0", options.ProviderOptions);
options.ProviderOptions.ResponseType = "code";
});
await builder.Build().RunAsync();@page "/login"
@inject NavigationManager Navigation
@inject AuthenticationStateProvider AuthStateProvider
<EditForm Model="@model" OnValidSubmit="HandleLogin">
<DataAnnotationsValidator />
<div class="form-group">
<label>Email:</label>
<InputText @bind-Value="model.Email" class="form-control" />
<ValidationMessage For="@(() => model.Email)" />
</div>
<div class="form-group">
<label>Password:</label>
<InputText @bind-Value="model.Password" type="password" class="form-control" />
<ValidationMessage For="@(() => model.Password)" />
</div>
<button type="submit" class="btn btn-primary">Login</button>
@if (!string.IsNullOrEmpty(errorMessage))
{
<div class="alert alert-danger">@errorMessage</div>
}
</EditForm>
@code {
private LoginModel model = new();
private string errorMessage = "";
private async Task HandleLogin()
{
// Authenticate user (implement with your auth service)
var success = await AuthenticateUser(model.Email, model.Password);
if (success)
{
Navigation.NavigateTo("/");
}
else
{
errorMessage = "Invalid credentials";
}
}
private Task<bool> AuthenticateUser(string email, string password)
{
// Implement authentication logic
return Task.FromResult(true);
}
}
public class LoginModel
{
[Required, EmailAddress]
public string Email { get; set; } = "";
[Required]
public string Password { get; set; } = "";
}For WebAssembly apps, use the Microsoft.AspNetCore.Components.WebAssembly.Authentication package templates to wire OAuth quickly. Configure your identity provider (Auth0, Azure AD, IdentityServer) and let the package handle token management, refresh, and protected API calls.
Blazor .NET 8 introduces flexible render modes that let you choose how each component executes. Combined with streaming rendering and performance optimizations, you can build fast, scalable applications.
@page "/products"
@* No render mode = Static SSR (default) *@
<h2>Products</h2>
@foreach (var product in products)
{
<div class="product">
<h3>@product.Name</h3>
<p>$@product.Price</p>
</div>
}
@code {
private List<Product> products = [];
protected override async Task OnInitializedAsync()
{
products = await GetProductsAsync();
}
}
// Best for: SEO-friendly content, static pages, initial page loads@page "/dashboard"
@rendermode InteractiveServer
<h2>Live Dashboard</h2>
<p>Updates: @updateCount</p>
@code {
private int updateCount = 0;
private Timer? timer;
protected override void OnInitialized()
{
timer = new Timer(_ =>
{
updateCount++;
InvokeAsync(StateHasChanged);
}, null, 1000, 1000);
}
}
// Best for: Real-time updates, low-latency interactions, internal apps@page "/editor"
@rendermode InteractiveWebAssembly
<h2>Offline Editor</h2>
<textarea @bind="content" @bind:event="oninput"></textarea>
<p>Characters: @content.Length</p>
@code {
private string content = "";
}
// Best for: Offline capability, high user scalability, client-heavy apps@page "/hybrid"
@rendermode InteractiveAuto
<h2>Hybrid Component</h2>
<button @onclick="Increment">Count: @count</button>
@code {
private int count = 0;
private void Increment() => count++;
}
// Best for: Best of both worlds—SSR first load, then interactive based on availability@page "/report"
@attribute [StreamRendering(true)]
<h2>Sales Report</h2>
@if (salesData == null)
{
<p>Loading...</p>
}
else
{
<table>
@foreach (var item in salesData)
{
<tr>
<td>@item.Product</td>
<td>$@item.Revenue</td>
</tr>
}
</table>
}
@code {
private List<SalesItem>? salesData;
protected override async Task OnInitializedAsync()
{
// Simulate slow data source
await Task.Delay(2000);
salesData = await FetchSalesDataAsync();
}
}Streaming sends initial markup quickly, then streams updates as data arrives. This improves perceived performance but may affect SEO crawlers that don't wait for streaming content. Test with Google Search Console and consider SSR without streaming for critical SEO pages.
@page "/users"
@using Microsoft.AspNetCore.Components.QuickGrid
<h2>User List</h2>
<QuickGrid Items="@users" Pagination="@pagination">
<PropertyColumn Property="@(u => u.Name)" Sortable="true" />
<PropertyColumn Property="@(u => u.Email)" Sortable="true" />
<PropertyColumn Property="@(u => u.Role)" />
<TemplateColumn Title="Actions">
<button @onclick="() => Edit(context)">Edit</button>
<button @onclick="() => Delete(context.Id)">Delete</button>
</TemplateColumn>
</QuickGrid>
<Paginator State="@pagination" />
@code {
private IQueryable<User> users = new List<User>().AsQueryable();
private PaginationState pagination = new() { ItemsPerPage = 10 };
protected override async Task OnInitializedAsync()
{
var allUsers = await GetUsersAsync();
users = allUsers.AsQueryable();
}
}ShouldRender() override to control when components update<Virtualize> for large lists to render only visible itemsdotnet-trace to identify bottlenecks<Virtualize Items="@items" Context="item">
<div class="item">
<h4>@item.Title</h4>
<p>@item.Description</p>
</div>
</Virtualize>
@code {
private List<Item> items = Enumerable.Range(1, 10000)
.Select(i => new Item { Title = $"Item {i}" })
.ToList();
}Testing Blazor components ensures UI behavior and logic work correctly. bUnit provides a testing framework specifically designed for Blazor components.
# Create test project
dotnet new xunit -n TodoDashboard.Tests
cd TodoDashboard.Tests
# Add bUnit
dotnet add package bUnit
dotnet add package bUnit.web
# Add reference to your Blazor project
dotnet add reference ../TodoDashboard/TodoDashboard.csprojusing Bunit;
using Xunit;
public class CounterTests : TestContext
{
[Fact]
public void Counter_Increments_When_Button_Clicked()
{
// Arrange
var cut = RenderComponent<Counter>();
// Act
cut.Find("button").Click();
// Assert
cut.Find("p").TextContent.Should().Contain("1");
}
[Fact]
public void Counter_Starts_At_Zero()
{
// Arrange
var cut = RenderComponent<Counter>();
// Assert
cut.Find("p").TextContent.Should().Contain("0");
}
}using Bunit;
using Xunit;
using Microsoft.Extensions.DependencyInjection;
public class TodoFormTests : TestContext
{
[Fact]
public void Form_Shows_Validation_Error_For_Empty_Title()
{
// Arrange
var cut = RenderComponent<TodoForm>();
// Act - try to submit without filling form
cut.Find("form").Submit();
// Assert
cut.Find(".validation-message")
.TextContent.Should().Contain("Title is required");
}
[Fact]
public async Task Form_Calls_Service_On_Valid_Submit()
{
// Arrange
var mockService = new Mock<ITodoService>();
Services.AddSingleton(mockService.Object);
var cut = RenderComponent<TodoForm>();
// Act
cut.Find("input[name='title']").Change("New Todo");
cut.Find("form").Submit();
// Assert
await cut.InvokeAsync(() => { });
mockService.Verify(s => s.CreateAsync(It.IsAny<TodoItem>()), Times.Once);
}
}using Bunit;
using Xunit;
using Moq;
public class TodoListTests : TestContext
{
[Fact]
public void TodoList_Displays_Todos_From_Service()
{
// Arrange
var mockService = new Mock<ITodoService>();
mockService.Setup(s => s.GetAllAsync())
.ReturnsAsync(new List<TodoItem>
{
new() { Id = 1, Title = "Test Todo 1" },
new() { Id = 2, Title = "Test Todo 2" }
});
Services.AddSingleton(mockService.Object);
// Act
var cut = RenderComponent<TodoList>();
// Assert
cut.FindAll(".todo-item").Count.Should().Be(2);
cut.Find(".todo-item").TextContent.Should().Contain("Test Todo 1");
}
}Focus on testing component behavior, not implementation details. Test user interactions (clicks, form submissions), state changes, and service calls. Run tests in CI with dotnet test for confidence before deployment.
Blazor apps deploy to various hosting environments. Server apps run on ASP.NET Core hosts, while WebAssembly apps are static files served from any web server or CDN.
# Publish for production
dotnet publish -c Release -o ./publish
# Publish to folder with self-contained runtime
dotnet publish -c Release -r linux-x64 --self-contained -o ./publish# Standard WASM publish
dotnet publish -c Release
# With AOT compilation (requires wasm-tools)
dotnet workload install wasm-tools
dotnet publish -c Release -p:RunAOTCompilation=trueFROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["TodoDashboard.csproj", "./"]
RUN dotnet restore
COPY . .
RUN dotnet build -c Release -o /app/build
FROM build AS publish
RUN dotnet publish -c Release -o /app/publish
FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "TodoDashboard.dll"]# Blazor Server to App Service
az webapp up --name my-blazor-app --resource-group mygroup --runtime "DOTNET|8.0"
# Blazor WASM to Static Web Apps
az staticwebapp create \
--name my-blazor-wasm \
--resource-group mygroup \
--source https://github.com/user/repo \
--location "East US" \
--branch main \
--app-location "src" \
--output-location "wwwroot"{
"Logging": {
"LogLevel": {
"Default": "Warning",
"Microsoft.AspNetCore": "Warning"
}
},
"ConnectionStrings": {
"DefaultConnection": "Server=prod-server;Database=todos;..."
},
"ApplicationInsights": {
"InstrumentationKey": "your-key-here"
}
}// Install: Microsoft.ApplicationInsights.AspNetCore
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddApplicationInsightsTelemetry(options =>
{
options.ConnectionString = builder.Configuration["ApplicationInsights:ConnectionString"];
});
var app = builder.Build();
app.Run();Use GitHub Actions to automate builds and deployments. Enable response compression and cache headers for WASM assets. For Server apps, configure server GC settings and connection limits for optimal performance under load.
Upgrading from Blazor .NET 7 to .NET 8 is straightforward. Most component code works unchanged; the main task is adopting the new render mode model.
TargetFramework to net8.0dotnet restore and fix any warnings<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net7.0</TargetFramework>
<Nullable>enable</Nullable>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly" Version="7.0.15" />
</ItemGroup>
</Project><Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net8.0</TargetFramework>
<Nullable>enable</Nullable>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly" Version="8.0.0" />
</ItemGroup>
</Project>The biggest change in .NET 8 is the unified render mode model. Update your components to specify their render behavior:
@page "/counter"
<h2>Counter</h2>
<button @onclick="Increment">@count</button>
@code {
private int count = 0;
private void Increment() => count++;
}@page "/counter"
@rendermode InteractiveServer
<h2>Counter</h2>
<button @onclick="Increment">@count</button>
@code {
private int count = 0;
private void Increment() => count++;
}Blazor .NET 8 has minimal breaking changes:
@rendermode directiveIJSRuntime callsMost Blazor .NET 7 component code ports directly to .NET 8. The main work is choosing appropriate render modes for each page and component. Start with SSR for static content and add interactive modes where needed. Test thoroughly, especially authentication and JavaScript interop.
You've learned Blazor fundamentals. Here's where to continue your journey:
Clone the complete Todo Dashboard with basic and advanced implementations:
git clone https://github.com/dotnet-guide-com/tutorials.git
cd tutorials/blazor
# Run basic Todo Dashboard
cd TodoDashboard.Basic
dotnet run
# Run advanced version (auth + EF Core)
cd ../TodoDashboard.Advanced
dotnet runblazor and blazor-server-sideUse Blazor Server for internal apps with low latency requirements and simpler deployment—no need to download the .NET runtime to the browser. Use WebAssembly for client-heavy apps that need offline capability or high user scalability without server connections. Use Auto render mode to get the best of both worlds—SSR on first load with interactive mode based on connection availability and performance characteristics.
Render modes control how components execute. Static SSR is fast and SEO-friendly for content pages. InteractiveServer maintains a SignalR connection for real-time updates. InteractiveWebAssembly runs entirely in the browser with offline support. Auto mode combines SSR for initial load with interactive mode afterward. Start with SSR plus interactive islands for optimal performance—use full interactivity only where needed.
Most Blazor apps don't need JavaScript. Blazor provides built-in components for forms, navigation, file uploads, and authentication. Use JavaScript interop only for browser APIs not exposed to C# (clipboard, localStorage, geolocation) or when integrating third-party JavaScript libraries. Wrap interop calls in services for better testability and maintainability.
Use the Microsoft.AspNetCore.Components.WebAssembly.Authentication package with OAuth/OIDC. Configure AuthenticationStateProvider, add HttpClient with BaseAddressAuthorizationMessageHandler for automatic token injection, and protect routes with AuthorizeView and [Authorize] attributes. Never trust WebAssembly client-side logic alone—always validate and authorize on the server API.
Use QuickGrid with virtualization for built-in sorting, filtering, and efficient rendering of large datasets. For custom solutions, use the <Virtualize> component to render only visible items in scrollable lists. Load data in pages from the server rather than materializing entire collections in memory. Use the @key directive to help Blazor identify and efficiently update list items.
Yes. Configure multiple render modes in Program.cs and annotate components with @rendermode directives. You can have SSR pages with InteractiveServer islands for real-time features and even lazy-load WebAssembly components for heavy client-side processing. This hybrid approach optimizes for initial load speed while enabling rich interactivity where needed.
Razor Pages are server-rendered page-based applications with traditional request/response model—each interaction triggers a full page reload. Blazor uses component-based architecture with interactivity through SignalR (Server) or WebAssembly. Blazor enables SPA-like experiences without JavaScript frameworks. Use Razor Pages for simple CRUD apps with traditional forms. Use Blazor for rich, interactive UIs with client-side state management.
Use streaming SSR for pages with slow data sources (external APIs, complex database queries) where you want to show content progressively rather than waiting for all data. Streaming sends initial markup quickly with loading placeholders, then streams updates as data arrives. Ideal for dashboards and reports. Be aware that streaming content may affect SEO crawlers that don't wait for streamed updates—test with Google Search Console and consider standard SSR for critical SEO pages.