Исправление дублирующей загрузки данных, мерцания UI и проблем с сохранением состояния при использовании пререндеринга в интерактивных компонентах Blazor.
- Звёзды на GitHub
- 5 942
- Файлы
- 1
- Последний коммит
- 11 нояб. 2026 г.
- Лицензия
- MIT
- Разрешённые инструменты
- —
Что делает навык support-prerendering?
Исправление дублирующей загрузки данных, мерцания UI и проблем с сохранением состояния при использовании пререндеринга в интерактивных компонентах Blazor.
Сводка сгенерирована из SKILL.md навыка.
О skill support-prerendering
Разработчики, создающие приложения на Blazor, используют этот SKILL для решения распространенных проблем, возникающих при переходе от статического HTML-пререндеринга к интерактивным рантаймам. Он устраняет такие технические сложности, как дублирование запросов данных в OnInitializedAsync, мерцание интерфейса при переключении режимов и ошибки null reference, когда компоненты ожидают использования API, доступных только в браузере. Этот SKILL предоставляет методы для управления сохранением состояния, гарантируя, что данные, загруженные во время начального рендеринга на сервере, будут доступны после начала интерактивной сессии.
Агент должен загрузить этот SKILL, когда разработчику необходимо внедрить атрибут [PersistentState] или сервис PersistentComponentState для синхронизации данных. Его также используют для отключения пререндеринга в определенных компонентах или исключения страниц из интерактивной маршрутизации с помощью атрибута [ExcludeFromInteractiveRouting]. Используя такие инструменты, как RendererInfo.IsInteractive, разработчики могут защищать выполнение кода, чтобы предотвратить ошибки на этапе статического рендеринга. Данный SKILL предназначен для исправления существующих багов пререндеринга, а не для первоначальной настройки проекта или общего написания компонентов.
Что агент может делать с ним
- 1Предотвращение дублирующих вызовов APIПрименение сохранения состояния, чтобы данные, загруженные во время пререндеринга, не запрашивались повторно при подключении интерактивного рантайма.
- 2Отключение пререндеринга для конкретных компонентовОтключение пререндеринга для компонентов, которым требуется немедленный доступ к браузерным API.
- 3Доступ к HttpContext на определенных страницахПринудительная полная перезагрузка страниц, которым требуется доступ к cookies или заголовкам запроса.
- 4Защита кода, предназначенного только для интерактивного режимаИспользование проверок рантайма, чтобы определенная логика выполнялась только после подключения интерактивного рантайма.
Написано на основе skill SKILL.md. Каждый сценарий использования проверен по цитате из него.
Как установить навык support-prerendering
Каждая команда копирует папку навыка в каталог навыков клиента. Перезапустите клиент или начните новую сессию, чтобы загрузить его.Установка навыка support-prerendering в Плагин
/plugin marketplace add dotnet/skills /plugin install dotnet-blazor@dotnet-agent-skills
Установка навыка support-prerendering в Claude Code
~/.claude/skills/support-prerendering/SKILL.md
$ npx degit dotnet/skills/plugins/dotnet-blazor/skills/support-prerendering ~/.claude/skills/support-prerenderingУстановка навыка support-prerendering в Claude Code (project)
.claude/skills/support-prerendering/SKILL.md
$ npx degit dotnet/skills/plugins/dotnet-blazor/skills/support-prerendering .claude/skills/support-prerenderingУстановка навыка support-prerendering в Codex
~/.agents/skills/support-prerendering/SKILL.md
$ npx degit dotnet/skills/plugins/dotnet-blazor/skills/support-prerendering ~/.agents/skills/support-prerenderingУстановка навыка support-prerendering в Gemini CLI
~/.gemini/skills/support-prerendering/SKILL.md
$ npx degit dotnet/skills/plugins/dotnet-blazor/skills/support-prerendering ~/.gemini/skills/support-prerenderingУстановка навыка support-prerendering в Claude.ai
npx degit dotnet/skills/plugins/dotnet-blazor/skills/support-prerendering support-prerendering && zip -r support-prerendering.zip support-prerendering # claude.ai → Customize → Skills → + → Create skill → Upload a skill → support-prerendering.zip
Автоматические проверки
Запущено 15 нояб. 2026 г.Полный отчёт →Прошёл наши автоматические проверки. Это не аудит безопасности: прочитайте скрипты, прежде чем агент их запустит. Как работают проверки
- Связанный и доступный исходный репозиторийdotnet/skills/plugins/dotnet-blazor/skills/support-prerendering is public and reachablegithub.com/dotnet/skills/tree/HEAD/plugins/dotnet-blazor/ski ↗Пройдено
- Open source лицензия (OSI)MITspdx.org/licenses/MIT.html ↗Пройдено
- Коммит или релиз за последний годLast commit 2026-11-11github.com/dotnet/skills/commits ↗Пройдено
- В скриптах нет загрузки с запуском и кражи учётных данныхNo scripts in the skill folderПройдено
- В SKILL.md нет скрытых инструкцийNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/dotnet/skills/blob/HEAD/plugins/dotnet-blazor/ski ↗Пройдено
- Заранее разрешённые инструменты ограниченыNo pre-approved tools; the agent asks before using onegithub.com/dotnet/skills/blob/HEAD/plugins/dotnet-blazor/ski ↗Пройдено
- SKILL.md соответствует формату Agent SkillsValid name and description; says when to use it; 217 linesgithub.com/dotnet/skills/blob/HEAD/plugins/dotnet-blazor/ski ↗Пройдено
SKILL.md
Открыть на GitHubSupport Prerendering
How Prerendering Works
Prerendering is on by default for all interactive render modes. The server renders the component as static HTML and ships it to the browser immediately. Then the interactive runtime (Server/WebAssembly) loads and re-renders the component with full interactivity.
This means:
OnInitializedAsyncruns twice — once during prerender (static), once when the interactive runtime attaches.OnAfterRenderAsyncis NOT called during prerender — only after the interactive render.- Internal navigation between interactive pages (interactive routing) skips prerendering — prerendering only happens on full page loads.
Step 1 — Read the Project's AGENTS.md
Check the project's AGENTS.md for the Interactivity Mode and Interactivity Scope:
| Mode | Prerendering applies? |
|---|---|
| None (Static SSR) | No — there's no interactive handoff |
| Server | Yes |
| WebAssembly | Yes |
| Auto | Yes |
If the mode is None, this skill doesn't apply.
Persist State Across Prerender → Interactive
The most common prerendering problem: data loaded in OnInitializedAsync during prerender is thrown away and re-fetched when the interactive runtime attaches. This causes flicker and duplicate API/DB calls.
Recommended: [PersistentState] attribute
Annotate properties to automatically serialize during prerender and restore on interactive activation:
@page "/forecasts"
@rendermode InteractiveServer
<h1>Weather</h1>
@if (Forecasts is null)
{
<p>Loading...</p>
}
else
{
@foreach (var f in Forecasts)
{
<p>@f.Date: @f.TemperatureC°C</p>
}
}
@code {
[PersistentState]
public WeatherForecast[]? Forecasts { get; set; }
protected override async Task OnInitializedAsync()
{
Forecasts ??= await ForecastService.GetForecastsAsync();
}
}
The ??= pattern is critical — it means "only fetch if the property wasn't already restored from prerender state."
Multiple instances of the same component
When the same component type appears multiple times, use @key to disambiguate state:
@foreach (var item in items)
{
<ItemCard @key="item.Id" />
}
Advanced: PersistentComponentState service
For complex scenarios (dynamic keys, custom serialization), use the imperative API:
@inject PersistentComponentState ApplicationState
@code {
private List<Order>? orders;
protected override async Task OnInitializedAsync()
{
ApplicationState.RegisterOnPersisting(PersistOrders);
if (!ApplicationState.TryTakeFromJson<List<Order>>("orders", out var restored))
{
orders = await OrderService.GetOrdersAsync();
}
else
{
orders = restored;
}
}
private Task PersistOrders()
{
ApplicationState.PersistAsJson("orders", orders);
return Task.CompletedTask;
}
}
Disable Prerendering
Disable prerendering when a component depends on browser APIs immediately or when the prerender+interactive double render causes problems you can't solve with [PersistentState].
On a component definition
@rendermode @(new InteractiveServerRenderMode(prerender: false))
Replace InteractiveServerRenderMode with InteractiveWebAssemblyRenderMode or InteractiveAutoRenderMode as needed.
On a component instance
<MyChart @rendermode="new InteractiveServerRenderMode(prerender: false)" />
On the entire app
In App.razor:
<HeadOutlet @rendermode="new InteractiveServerRenderMode(prerender: false)" />
<Routes @rendermode="new InteractiveServerRenderMode(prerender: false)" />
Note: A parent's prerendering setting overrides children. If <Routes> disables prerendering, individual pages cannot re-enable it.
Exclude Pages from Interactive Routing
In a globally interactive app, some pages may need HttpContext (cookies, request headers, response status codes). These pages must render via static SSR, not inside the interactive runtime.
Use [ExcludeFromInteractiveRouting]:
@page "/privacy"
@attribute [ExcludeFromInteractiveRouting]
<h1>Privacy Policy</h1>
This forces a full page reload when navigating to this page, exiting interactive routing. The page renders as static SSR with full HttpContext access.
In App.razor, conditionally apply the render mode:
<!DOCTYPE html>
<html>
<head>
<HeadOutlet @rendermode="RenderModeForPage" />
</head>
<body>
<Routes @rendermode="RenderModeForPage" />
<script src="_framework/blazor.web.js"></script>
</body>
</html>
@code {
[CascadingParameter]
public HttpContext HttpContext { get; set; } = default!;
private IComponentRenderMode? RenderModeForPage =>
HttpContext.AcceptsInteractiveRouting() ? InteractiveServer : null;
}
Replace InteractiveServer with the app's configured render mode.
Detect Prerender vs Interactive at Runtime
Use RendererInfo to guard code that should only run interactively:
protected override async Task OnInitializedAsync()
{
if (RendererInfo.IsInteractive)
{
// Only runs during the interactive render, not during prerender
await StartSignalRConnection();
}
}
RendererInfo properties:
IsInteractive—falseduring prerender,trueafter interactive runtime attachesName—"Static"during prerender,"Server"or"WebAssembly"when interactive
Client Services Fail During Prerender
Components in the .Client project prerender on the server. Services registered only in the client Program.cs (e.g., IWebAssemblyHostEnvironment) won't be available during prerender.
Fix by one of:
- Register a matching service on the server — both
Program.csfiles provide the service - Make the service optional — use constructor injection with a nullable default:
public MyComponent(IMyService? svc = null) - Create a service abstraction — interface in
.Client, implementations in both projects - Disable prerendering for that component
Don'ts
- Don't call JS interop in
OnInitializedAsync— JS isn't available during prerender. UseOnAfterRenderAsync(firstRender). - Don't assume
OnInitializedAsyncruns once — it runs twice with prerendering. Always use[PersistentState]or??=guards. - Don't use
HttpContextin interactive components — it's only available during the static prerender, not during the interactive lifetime. Use[ExcludeFromInteractiveRouting]for pages that need it. - Don't disable prerendering as a first resort — it hurts perceived load time and SEO. Use
[PersistentState]to preserve state instead.
Файлы в этом навыке
1Вопросы о навыке support-prerendering
Как установить навык support-prerendering в Claude Code?
Выполните npx degit dotnet/skills/plugins/dotnet-blazor/skills/support-prerendering ~/.claude/skills/support-prerendering. Claude Code загружает навыки из ~/.claude/skills (все проекты) или .claude/skills (один проект) и использует навык, когда его описание соответствует задаче.
Какие клиенты могут использовать навык support-prerendering?
Любой клиент, который читает формат Agent Skills: Claude Code, Codex, Gemini CLI и claude.ai (загрузить как ZIP). Скрипты в навыке выполняются только там, где клиент разрешает выполнение кода.
Как предотвратить повторный запрос данных во время пререндеринга?
Используйте атрибут [PersistentState] для свойств или сервис PersistentComponentState, чтобы сериализовать данные во время пререндеринга и восстановить их при подключении интерактивного рантайма.
Можно ли отключить пререндеринг для конкретного компонента?
Да, вы можете отключить его, передав режим рендеринга с параметром prerender, установленным в false, например: @rendermode @(new InteractiveServerRenderMode(prerender: false)).
Почему JS interop не работает в OnInitializedAsync?
JavaScript недоступен на этапе пререндеринга. Вам следует перенести вызовы JS interop в метод OnAfterRenderAsync.