Blazor: руководство по WebAssembly и Server

Лого Blazor, иконка фреймворка Blazor

Быстрые ссылки

Что такое Blazor?
Режим Hybrид
Настройка Blazor
Обзор среды Blazor
Исправление проблем с цветовой схемой Visual Studio
Динамический контент
Как работает стилизация
Жизненный цикл компонентов
Взаимодействие с JavaScript
Навигация и маршрутизация
Библиотеки для Blazor
Будущее Blazor

Что такое Blazor?

Blazor — это фреймворк для создания интерактивных веб-приложений на C# и .NET. Он расширяет возможности знакомых ASP.NET и Razor, но добавляет поведение, которое раньше требовало JavaScript. Главная идея: одна экосистема (C#, .NET) для frontend и backend.

Коротко о ключевых концепциях:

WebAssembly (WASM): бинарный формат, в который можно собрать .NET runtime и приложения. Браузер загружает эти артефакты и выполняет .NET прямо на клиенте.
Blazor WebAssembly (Blazor Client): приложение и .NET runtime загружаются в браузер. Интерфейс обновляется локально без постоянных обращений к серверу.
Blazor Server: логика выполняется на сервере; клиент подключается через SignalR для передачи команд и изменений DOM.

Определение термина: WebAssembly — компактный двоичный формат для выполнения кода в браузере, поддерживает разные языки.

Важно: Blazor — не попытка «убрать JavaScript», а возможность писать UI-логику на C# там, где это имеет смысл.

Режимы работы Blazor

Blazor поддерживает несколько схем размещения. Выбор влияет на время загрузки, масштабируемость и безопасность.

Blazor WebAssembly (клиентская сборка)

Выполняется в браузере с помощью .NET runtime, скомпилированного под WASM.
Преимущества: независимость от сервера, мгновенная интерактивность после загрузки, хороший UX при навигации внутри приложения.
Ограничения: большие DLL-файлы увеличивают время загрузки; ранние реализации использовали интерпретатор, а не AOT, поэтому старт может быть медленнее; браузерные ограничения по памяти.

Практический совет: минимизируйте размер загружаемых пакетов: удаляйте неиспользуемые пакеты, используйте trimming и lazy-load модулей.

Blazor Server

Сервер выполняет .NET код и управляет состоянием компонентов. Клиент — тонкий слой, который получает инструкции об изменениях DOM через SignalR.
Преимущества: маленькие загрузки на клиенте, доверенная среда выполнения, проще обрабатывать секреты и доступ к ресурсам сервера.
Ограничения: нагрузка на сервер и масштабирование при большом числе одновременных подключений; возможны задержки при медленных сетях.

Важный момент: SignalR использует WebSockets, но автоматически падает на другие транспортные механизмы при необходимости.

Гибридный режим и prerendering

Prerendering (предварительный рендеринг) позволяет серверу отрисовать страницу HTML и отправить её клиенту. Затем Blazor «подхватывает» страницу и делает её интерактивной.
Это даёт быстрое первое отображение и последующую интерактивность.
Минусы: страницы могут дважды загружать данные (серверная отрисовка и клиентская загрузка), поэтому требуется синхронизация состояния (state persistence) между сервером и клиентом.

Совет: при использовании API и prerendering реализуйте сервисы и на клиенте, и на сервере, либо используйте общий слой доступа к данным с возможностью вызова напрямую при prerendering.

Настройка Blazor

Visual Studio умеет генерировать шаблоны проектов.

Шаги создания проекта:

Откройте Visual Studio и создайте новый проект.
Найдите шаблон «Blazor» и выберите Blazor WebAssembly или Blazor Server.

Диалог выбора шаблона проекта Blazor в Visual Studio

Задайте имя проекта и целевую версию .NET.
Для шаблона Blazor WebAssembly по умолчанию создаётся структура из трёх проектов: Client, Server и Shared.

Структура проекта: Client, Server, Shared

Примечание: Blazor WebAssembly можно хостить как статический сайт (NGINX, S3). Если у вас есть API, его выгодно включить в тот же репозиторий, чтобы делиться моделями и DTO.

Важно: при запуске шаблона Blazor Server приложение подключится к серверу по SignalR для обработки событий.

Запуск проекта и панель отладки Visual Studio

Обзор среды Blazor

Основные точки входа и файлы:

wwwroot/index.html — реальный HTML, который загружается первым в клиентских приложениях. Он подключает Blazor JavaScript и отображает «страницу загрузки».
Program.cs — конфигурирует host, сервисы, HttpClient и вызывает Build/Run.
App.razor — корневой компонент, который содержит и определяет маршрутизацию приложения.
MainLayout.razor и NavMenu.razor — общие компоненты макета и навигации.

Код примера: файл Program.cs создаёт WebAssemblyHost или Host для серверного варианта, добавляет сервисы и регистрацию зависимостей.

Структура входных файлов и App.razor

Организация проектов в шаблоне

Client — пользовательский интерфейс и компоненты.
Server — API и backend-логика на ASP.NET Core.
Shared — общие модели и DTO между клиентом и сервером.

Такое разделение упрощает поддержку контрактов и повторное использование моделей.

Исправление цветовой схемы Visual Studio

Если вы работаете с Razor и у вас неудобные цвета синтаксиса, это легко поправить через Tools > Options > Environment > Fonts and Colors.

Найдите «Razor Directive» и выберите более контрастный цвет фона и текста.
Найдите «HTML Server-Side Script» и настройте аналогично.

Настройка шрифтов и цветов Razor Directive

Важно: улучшение читаемости синтаксиса сокращает усталость глаз и снижает риск ошибок при работе с смешанным C#/HTML.

Динамический контент и взаимодействие с API

Файл FetchData.razor — отличный пример взаимодействия клиента с API.

Основные шаблоны:

Декларативный роутинг: @page “/fetchdata”
Внедрение зависимостей: @inject HttpClient Http
@code блок содержит состояние (forecasts) и методы для загрузки данных.
Управление состоянием: когда изменяется поле forecasts, Blazor автоматически перерисовывает компонент.

Пример паттерна загрузки данных в компоненте:

@page "/fetchdata"
@inject HttpClient Http

Погода

@if (forecasts == null)
{
    Загрузка...
}
else
{
     ... 
}

@code {
    private WeatherForecast[] forecasts;

    protected override async Task OnInitializedAsync()
    {
        forecasts = await Http.GetFromJsonAsync("WeatherForecast");
    }
}

События и обработчики:

Используйте @onclick для кнопок, передавайте ссылки на методы.
Для простых inline-обработчиков можно применять лямбда-выражения.

Пример inline-обработчика:

События клавиатуры и ввод:

Если вы хотите реагировать на Enter в поле ввода, связывайте @onkeydown и @oninput одновременно. KeyboardEventArgs не содержит значение ввода, поэтому вам придётся хранить строку отдельно и проверять код клавиши:



@code {
    private string searchValue;

    public void Enter(KeyboardEventArgs e)
    {
        if (e.Code == "Enter" || e.Code == "NumpadEnter")
        {
            // выполнить поиск
        }
    }
}

Совет: для сложной логики ввода используйте Bound properties и оптимизируйте частоту запросов с помощью debounce.

Как работает стилизация

Blazor поддерживает обычные CSS-файлы и scoped CSS для компонентов.

Общий файл: wwwroot/css/site.css
Scoped CSS: создайте файл с тем же именем, что и компонент, но с расширением .razor.css (например, Counter.razor.css). Тогда Blazor сгенерирует уникальные селекторы, применяемые только к компоненту.

Пример сгенерированного CSS:



/* /Pages/Counter.razor.rz.scp.css */

h1[b-3xxtam6d07] {
  color: brown;
}

SASS/LESS: можно подключить препроцессор, но это требует дополнительной конфигурации сборки и инструментов.

Жизненный цикл компонентов

Blazor имеет последовательность методов жизненного цикла, аналогичную React, но с C# синтаксисом. Основные точки:

SetParametersAsync / OnParametersSet / OnParametersSetAsync — вызываются, когда параметры компонента изменяются.
OnInitialized / OnInitializedAsync — первичная инициализация компонента.
ShouldRender — можно переопределить, чтобы контролировать повторные рендеры.
OnAfterRender / OnAfterRenderAsync — вызываются после рендера (полезны для вызовов JS interop после первого рендера).

Быстрый ментальный модель: параметры обновляются сверху вниз; инициализация выполняется один раз; после асинхронных операций компонент может рендериться дважды — при начале и при завершении операции.

Важно: при использовании async/await учитывайте, что StateHasChanged может вызываться несколько раз. Планируйте логику так, чтобы избежать лишних рендеров.

Взаимодействие с JavaScript

Blazor поддерживает двунаправленный interop.

Вызов JS из C#:

private async Task ConvertArray()
{
    text = new(await JS.InvokeAsync("convertArray", quoteArray));
}

Вызов .NET из JS:

DotNet.invokeMethodAsync('{ASSEMBLY NAME}', '{.NET METHOD ID}', {ARGUMENTS});

Вы можете использовать NPM-пакеты, но чаще предпочитают NuGet-обёртки, если они доступны. При подключении JS-библиотек управляйте загрузкой скриптов через _Host.cshtml или index.html и используйте IJSRuntime для вызовов.

Навигация и маршрутизация

Маршрутизация в Blazor происходит через директиву @page и компонент Router в App.razor. Ключевые моменты:

Одному компоненту можно назначить несколько маршрутов.
Параметризованные маршруты: используйте фигурные скобки, например /search/{query}.
Порядок маршрутов важен: точные совпадения обрабатываются раньше параметризованных.

Проблема SPA: при изменении URL Blazor может не обновить состояние компонента, если параметры не изменились. Решение — подписка на NavigationManager.LocationChanged и ручная обработка обновления состояния.

Пример подписки:

NavigationManager.LocationChanged += HandleLocationChanged;

private void HandleLocationChanged(object sender, LocationChangedEventArgs e)
{
    InvokeAsync(() => {
        // обновить состояние
        StateHasChanged();
    });
}

Совет: если компонент использует параметры URL, вызывать OnParametersSetAsync из обработчика — правильный способ избежать дублирования кода.

Библиотеки для Blazor

Экосистема Blazor уже содержит множество библиотек:

Компонентные библиотеки: Radzen, Blazorise, MudBlazor и другие. Некоторые из них бесплатны, некоторые — с коммерческой лицензией.
Утилиты для форм, валидации, графиков, таблиц и т. д.

Рекомендация: используйте готовые библиотеки для ускорения разработки и прототипирования, а затем при необходимости стилизуйте компоненты под дизайн проекта.

Сравнение библиотек компонентов Blazor

Будущее Blazor

Microsoft активно развивает Blazor: планы покрывают Blazor Desktop и Blazor Native — возможность запускать Blazor-приложения в десктоп- и мобильных средах с использованием WebView и нативных контролов. Уже сейчас есть пути запускать Blazor внутри Electron.

Blazor на рабочем столе: использование WebView и нативных контейнеров

Практические рекомендации по выбору хостинга модели

Если приложение должно быстро открываться и работать без постоянного подключения к серверу — выбирайте Blazor WebAssembly.
Если важна безопасность, работа с секретами или тесная интеграция с серверными ресурсами — Blazor Server.
Если нужен баланс — используйте prerendering и гибридный подход.

Ниже — decision tree, который поможет выбрать модель развертывания.

flowchart TD
  A[Начало: у вас есть приложение] --> B{Нужно ли офлайн-работа?}
  B -- Да --> C[Blazor WebAssembly]
  B -- Нет --> D{Нужен ли быстрый первый рендер?}
  D -- Да --> E[Prerendering + Blazor WebAssembly]
  D -- Нет --> F{Сильно нагруженные соединения?}
  F -- Да --> C
  F -- Нет --> G[Blazor Server]
  E --> H[Рассмотрите state persistence]
  C --> H
  G --> H
  H --> I[Подготовить CI/CD и мониторинг]

Проверочные списки по ролям

Разработчик:

Настроить шаблон проекта и разделение Client/Server/Shared.
Настроить HttpClient и обработку ошибок сети.
Минимизировать размер сборки (trim, lazy load).
Писать компоненты с тестами и четкими контрактами.

DevOps/Инфраструктура:

Подготовить CDN для статических артефактов (для WASM).
Настроить Auto-scaling для SignalR (для Server).
Настроить мониторинг задержек и использования ресурсов.

Дизайнер/Frontend:

Выбрать компонентную библиотеку и оформить тему.
Настроить scoped CSS и SASS pipeline.
Проверить контрастность и доступность (a11y).

Продуктовый менеджер:

Определить критические пользовательские потоки и требования к времени первого рендера.
Выбрать стратегию хостинга на основании требований к безопасности и офлайн-работе.

Мини-методология для разработки Blazor-приложения

Прототип: используйте готовую UI-библиотеку и создайте основные экраны.
Соглашение по API: выработайте контракт (Shared DTO).
Сетевые слои: реализуйте абстракции сервисов (интерфейсы) для клиента и сервера.
State management: выберите подход (локальные состояния компонентов, scoped services, Flux-подобные паттерны).
Оптимизация: профилирование загрузки и размера бандлов, внедрение lazy-loading.
Тестирование: unit-тесты для компонентной логики, end-to-end тесты для сценариев.
Развертывание: подготовка CI/CD, статическая отдача WASM через CDN (если применимо).

Тест-кейсы и критерии приёмки

Компонент загрузки данных (FetchData):
- При корректном ответе сервера таблица отображается и содержит N строк.
- При ошибке сети отображается уведомление об ошибке.
- При медленном соединении отображается индикатор загрузки.
Навигация:
- Переходы по ссылкам обновляют URL и состояние приложения.
- При ручном изменении URL компоненты корректно обрабатывают параметры.
JS interop:
- Вызов JS-функции возвращает ожидаемые данные.
- Ошибки в JS корректно логируются и не ломают приложение.
Производительность:
- Время до интерактивности (Time To Interactive) укладывается в целевой порог для выбранной модели.
- Количество сетевых запросов оптимизировано.

Производительность и оптимизация

Минимизируйте зависимости: выбирайте NuGet-пакеты сознательно.
Включайте trimming и публикацию в режиме Release.
Используйте lazy-loading для больших модулей и бандлов.
Для WASM — CDN + кеширование для DLL и статики.
Для Server — балансировка нагрузки и масштабирование SignalR-хабов.

Важно измерять: используйте браузерные инструменты для анализа загрузки, а также APM (Application Performance Monitoring) для серверной части.

Безопасность и конфиденциальность

Никогда не храните секреты в клиентах (WASM). Секреты и ключи должны оставаться на сервере.
Валидация входных данных должна быть реализована на сервере, особенно при доверенном API.
При работе с персональными данными учитывайте требования к защите (шифрование, аудит доступа).
Для GDPR/локальных требований документируйте, где и как хранятся данные и кто имеет к ним доступ.

Советы по миграции с JavaScript SPA на Blazor

Начните с отдельных страниц/виджетов: внедряйте Blazor в существующий проект постепенно.
Используйте interop для тех библиотек JS, которые нельзя заменить сразу.
Параллельно поддерживайте общий API и DTO в Shared-проекте.
Проводите A/B тестирование производительности и UX, чтобы сравнить варианты.

Советы по устранению типичных проблем

Долгая загрузка WASM: применяйте тримминг, lazy-load и CDN.
Масштабирование Blazor Server: используйте масштабирование пулов и распределённые хранилища состояния.
Двойная загрузка данных при prerendering: примените сохранение состояния компонента между серверной и клиентской сторонами.

Краткий глоссарий

WASM: WebAssembly, бинарный формат выполнения в браузере.
SignalR: библиотека для реального времени в ASP.NET Core, обеспечивает WebSocket-подключения и fallback.
Prerendering: предварительная отрисовка HTML на сервере до инициализации клиента.
Scoped CSS: CSS, применяемый только к конкретному компоненту.

Заключение

Blazor даёт мощный путь к созданию интерактивных приложений на C# без полной зависимости от JavaScript. Выбор между WebAssembly и Server зависит от требований к офлайн-работе, времени первого рендера и масштабируемости. Практикуйте разделение ответственности, используйте готовые библиотеки, тестируйте производительность и планируйте стратегию развертывания заранее.

Важно: начните с малого — прототипа с одной страницы — и постепенно расширяйте приложение, оценивая влияние на UX и инфраструктуру.

Сводка ключевых шагов:

Выберите модель хостинга (WASM/Server/Hybrid);
Настройте структуру Client/Server/Shared;
Реализуйте доступ к API через общий контракт;
Оптимизируйте сборку и загрузку;
Автоматизируйте CI/CD и мониторинг.

Полное руководство по Blazor: WebAssembly, Server и лучшие практики