Blazor Conventions

Blazor Development Conventions

Apply these practices when writing, reviewing, or refactoring Blazor applications.

Code Style and Structure

• Write idiomatic Blazor and C# code that follows established .NET conventions
• Use Razor Components (.razor files) for all component-based UI
• For complex components with injected services or significant logic, use the code-behind with @inherits pattern: define a base class (e.g., DeviceDetailsBase : NexusPageComponentBase) and reference it with @inherits DeviceDetailsBase in the .razor file
• Keep small, presentational components inline with @code { } blocks
• Create custom base components for shared concerns across pages — e.g., a PageComponentBase that provides common injections (NavigationManager, AuthenticationState, ISnackbar) and helper methods (IsAuthenticatedAsync(), RedirectToLogin())
• Use async/await for all non-blocking UI operations — never block on Task.Result or .Wait() inside components, as this deadlocks the synchronization context

Naming Conventions

• PascalCase for components, methods, properties, public members, and component parameters
• camelCase for private fields and local variables
• Prefix private fields with underscore (_orderService)
• Prefix interfaces with I (IOrderService)
• Name component files to match the component class (OrderList.razor for OrderList)

Component Lifecycle

Blazor components follow a well-defined lifecycle. Understanding when each method runs prevents redundant work and subtle bugs.

• Implement IDisposable or IAsyncDisposable to clean up event subscriptions and cancellation tokens — leaked subscriptions cause memory leaks and ghost updates
• Use firstRender in OnAfterRenderAsync to run one-time JS interop or DOM setup
• Avoid calling StateHasChanged() inside OnInitializedAsync or OnParametersSetAsync — Blazor calls it automatically after these methods complete

Data Binding

• Use @bind for two-way binding to input elements: <input @bind="searchText" />
• Use @bind:event to control when the binding updates (e.g., @bind:event="oninput" for real-time updates vs the default onchange)
• Use @bind:after to run logic after a bound value changes without writing a manual setter
• For component parameters, expose a Value / ValueChanged pair to support @bind-Value from parent components:

[Parameter] public string Value { get; set; } = string.Empty;
[Parameter] public EventCallback<string> ValueChanged { get; set; }

Component Communication

• Parent to child: pass data via [Parameter] properties
• Child to parent: use EventCallback<T> to notify the parent of changes
• Deep tree sharing: use [CascadingParameter] with <CascadingValue> to avoid prop-drilling through intermediate components
• Keep EventCallback over Action/Func for event handling — EventCallback automatically triggers a re-render on the correct component and handles async delegates

Dependency Injection

In code-behind base classes, use [Inject] on properties. In .razor files, use @inject:

// Code-behind pattern (preferred for complex components)
[Inject] protected GatewayService GatewayService { get; set; }
[Inject] protected IDialogService DialogService { get; set; }
[Inject] protected ISnackbar SnackBarService { get; set; }
[Inject] protected NavigationManager Navigation { get; set; }

• Register services with the correct scope: Scoped for per-circuit (Server) or per-user (WASM) services, Singleton for shared state and hub connections, Transient for stateless utilities
• Avoid injecting Scoped services into Singleton services — this captures a stale instance (the captive dependency problem)

Separation of Concerns

• Components handle UI rendering and user interaction only
• Extract business logic into injectable services
• Use dedicated model or DTO classes for data transfer — do not pass entity or database models directly to components
• Isolate HTTP calls in typed service classes rather than calling HttpClient directly from components

Modern C# Features

Leverage current C# language features for clarity and conciseness:

• Records for immutable data models and DTOs (record OrderDto(int Id, string Name, decimal Total);)
• Pattern matching in event handlers and conditional rendering logic
• Global usings in _Imports.razor for commonly used namespaces
• File-scoped namespaces in code-behind files
• Nullable reference types — enable project-wide and handle nullability explicitly in component parameters and service returns

Error Handling and Validation

Page and API Error Handling

• Wrap data-loading calls in try-catch within lifecycle methods and present user-friendly feedback via ISnackbar:

try
{
    await LoadDataAsync(cancellationToken);
}
catch (UnauthorizedAccessException)
{
    RedirectToLogin();
}
catch (Exception ex)
{
    SnackBarService.Add($"Failed to load data: {ex.Message}", Severity.Error);
}

• Catch NavigationException separately — it is expected in Blazor Server when navigation aborts rendering
• Use ErrorBoundary for catching unhandled rendering exceptions when appropriate
• Configure a global error handler page with app.UseExceptionHandler("/Error")

Form and Input Patterns

• Use EditForm with DataAnnotationsValidator for form-heavy scenarios with validation
• For search/filter UIs, use component library inputs (e.g., MudTextField, MudSelect) with debouncing:

<MudTextField DebounceInterval="500"
             
              @bind-Value="SearchQuery"
              Placeholder="Search..." />

Performance Optimization

Blazor re-renders components more often than you might expect. These patterns keep the UI responsive.

Reduce Unnecessary Renders

• Override ShouldRender() and return false when the component output has not changed — this skips the entire diff and DOM patch cycle
• Use @key on list items so Blazor can match existing elements by identity instead of recreating them on every render
• Mark child components with @rendermode appropriately (Server vs WebAssembly vs Static SSR) based on interactivity needs
• Avoid allocating new objects (lambdas, collections, anonymous types) inside render logic — each allocation looks like a "change" to the diffing engine

Server vs WebAssembly Considerations

• On Server, minimize SignalR payload by keeping component state small and avoiding large objects in memory per circuit
• On WebAssembly, use lazy loading (<Router>) to defer assembly downloads and reduce initial payload
• Use IAsyncEnumerable streaming with Server to progressively render large datasets without loading everything into memory

public class StateContainer
{
    public bool IsDarkMode { get; private set; }
    public event Action? OnThemeChange;

    public void UseDarkMode(bool darkMode)
    {
        IsDarkMode = darkMode;
        OnThemeChange?.Invoke();
    }
}

public class DataStateService : IDataStateService, IDisposable
{
    public List<DeviceType> DeviceTypes { get; private set; } = [];
    public DeviceSearchState SearchState { get; } = new();
    public event Action? DeviceStateUpdated;
    // ... fetch, cache, notify
}

[PersistentState]
public List<Device>? Devices { get; set; }