Author Blazor Component
Core Rules
- Data flows down via
[Parameter]. Events flow up viaEventCallback<T>(neverAction/Func). - Never mutate
[Parameter]properties. Copy to a private field inOnParametersSet. - Use
[Parameter] public T Prop { get; set; }— neverrequiredorinit(causes BL0007). - Use
[EditorRequired]for required parameters. - Handle all states: loading, empty, loaded, error — each with
@if/@else. - Use
@keyon repeated elements in loops for efficient diffing. - Use
IReadOnlyList<T>(notIEnumerable<T>) for collection parameters.
RenderFragment & Generics
csharp[Parameter] public RenderFragment? ChildContent { get; set; } [Parameter] public RenderFragment<TItem>? RowTemplate { get; set; } // generic template
Use @typeparam TItem for generic components.
File Patterns
- Single-file:
.razorwith@codeblock when logic < ~50 lines. - Code-behind:
.razor+.razor.cswithpartial classwhen logic > ~50 lines.
Disposal
Implement IAsyncDisposable (not IDisposable) when the component owns subscriptions, timers, or CTS.
In DisposeAsync: unsubscribe (-=), cancel CTS, dispose resources. Never call StateHasChanged.
Async Patterns
awaitevery async operation. Never use.Result,.Wait(),Task.Run,ContinueWith,Thread.Start.- Debounce:
Task.Delay+CancellationTokenSource. Cancel old CTS, create new, await delay, do work. Never useSystem.Threading.TimerorSystem.Timers.Timer. - Polling: Loop in
OnInitializedAsyncwithawait Task.Delay(interval, token)— stays on sync context. - External events (
Action<T>): Useasync voidhandler +await InvokeAsync(() => { state++; StateHasChanged(); })+catch→DispatchExceptionAsync. Never_ = InvokeAsync(...). - Cancel CTS in
DisposeAsync. Don't catchObjectDisposedException— use CTS cancellation.
Don'ts
required/initon[Parameter]— runtime failure- Mutate
[Parameter]— copy to private field inOnParametersSet Action/Funcfor events — useEventCallback<T>Task.Run/.Result/.Wait()/Timer for debounce — deadlock or thread-pool escape- Inline
styleattributes — use CSS classes ordata-*attributes catch { throw; }— usewhenguard or let exceptions propagate- Gold-plating: ARIA, wrapper divs, accessibility features not requested
_ = InvokeAsync(...)— swallows exceptions; useasync void+DispatchExceptionAsync
