Основы Blazor в ASP.NET Core

Статьи по основам включают описание основных понятий Blazor. Некоторые понятия связаны с компонентами Razor, которые описаны в следующем разделе этой статьи и подробно рассматриваются в статьях Компоненты.

Основные понятия отрисовки клиента и сервера

Blazor По всей документации, действие, которое происходит в системе пользователя, как сообщается, происходит на стороне клиента или клиента. Действие, которое происходит на сервере, происходит на сервере или на стороне сервера.

Термин отрисовки означает создание разметки HTML, отображаемой браузерами.

• Отрисовка на стороне клиента (CSR) означает, что окончательная разметка HTML создается Blazor WebAssembly средой выполнения на клиенте. Html-код для пользовательского интерфейса, созданного клиентом приложения, не отправляется с сервера на клиент для отрисовки этого типа. Предполагается взаимодействие пользователей со страницей. Нет такой концепции, как статическое отображение на стороне клиента. Предполагается, что CSR является интерактивным, поэтому "интерактивная отрисовка на стороне клиента" и "интерактивная CSR" не используются в отрасли или в Blazor документации.

• Отрисовка на стороне сервера (SSR) означает, что окончательная разметка HTML создается средой выполнения ASP.NET Core на сервере. HTML отправляется клиенту через сеть для отображения браузером клиента. Код HTML для созданного сервером пользовательского интерфейса приложения не создается клиентом для этого типа отрисовки. SSR может быть двух разновидностей:

  • Статический SSR: сервер создает статический HTML-код, который не обеспечивает интерактивность пользователя или состояние Razor компонента.
  • Интерактивный SSR: Blazor события разрешают взаимодействие пользователей и Razor состояние компонента поддерживается платформой Blazor .

• Предварительная отрисовка — это процесс первоначальной отрисовки содержимого страницы на сервере без включения обработчиков событий для отрисованных элементов управления. Сервер выводит HTML-интерфейс страницы как можно скорее в ответ на первоначальный запрос, что делает приложение более адаптивным к пользователям. Предварительная подготовка также может улучшить оптимизацию поисковой системы (SEO), отрисовав содержимое для первоначального HTTP-ответа, используемого поисковыми системами для вычисления ранжирования страниц. За предварительной отрисовкой всегда следует окончательная отрисовка на сервере или клиенте.

Основные понятия статической и интерактивной отрисовки

Razorкомпоненты либо статически отрисовываются, либо отображаются в интерактивном режиме.

Статический или статический отрисовка — это сценарий на стороне сервера, который означает, что компонент отрисовывается без возможности взаимодействия между пользователем и кодом .NET/C#. События JavaScript и HTML-DOM остаются небезопасными, но никакие события пользователя на клиенте не могут обрабатываться с помощью .NET, работающего на сервере.

Интерактивная или интерактивная отрисовка означает, что компонент имеет емкость для обработки событий .NET с помощью кода C#. События .NET обрабатываются на сервере средой выполнения ASP.NET Core или браузером на клиенте средой выполнения WebAssembly Blazor .

Дополнительные сведения об этих понятиях и способах управления статической и интерактивной отрисовкой приведены в статье о режимах отрисовки ASP.NET Core Blazor далее в Blazor документации.

составные части компонента Razor.

Приложения Blazor основаны на компонентах Razor, которые часто называются просто компонентами. Компонентом называется любой элемент пользовательского интерфейса, например страница, диалоговое окно или форма ввода данных. Компоненты являются классами C# .NET, встроенными в сборки .NET.

Razor обозначает способ, которым компоненты обычно записываются в виде страницы разметки Razor для логики и композиции пользовательского интерфейса на стороне клиента. Синтаксис Razor сочетает разметку HTML с кодом C#, позволяя повысить производительность разработчиков. Файлы Razor используют расширение файла .razor.

Хотя некоторые разработчики и онлайн-ресурса Blazor используют термин "компоненты Blazor", в документации вместо него обычно используется "компоненты Razor" или просто "компоненты".

В документации Blazor используются определенные соглашения для обозначения и обсуждения компонентов:

• Код проекта, пути к файлам, имена файлов, имена шаблонов проектов и другие специализированные термины приведены на английском языке (США) и обычно заключены в код.
• Компоненты обычно указываются с помощью имени их класса C# (в стиле Pascal), перед которым приведено слово "компонент". Например, типичный компонент отправки файлов называется "компонентом FileUpload".
• Обычно имя класса C# компонента не отличается от его имени файла.
• Маршрутизируемые компоненты обычно задают для своих относительных URL-адресов имя класса компонента в стиле kebab. Например, компонент FileUpload включает конфигурацию маршрутизации для доступа к отрисовываемому компоненту по относительному URL-адресу /file-upload. Маршрутизация и навигация рассматриваются в статье Маршрутизация и навигация Blazor в ASP.NET Core.
• При использовании нескольких версий компонентов они нумеруются по порядку. Например, FileUpload3 компонент достигается по адресу /file-upload-3.
• Razor Директивы в верхней части определения компонента (.razor file) помещаются в следующий порядок: @page( @rendermode .NET 8 или более поздней версии), @using операторы, другие директивы в алфавитном порядке. Дополнительные сведения о Razor упорядочении директив приведены вRazorразделе синтаксисакомпонентов ASP.NET CoreRazor.
• В примерах статьи используются модификаторы доступа. Например, по умолчанию поля имеют атрибут private, но явно присутствуют в коде компонента. Например, private указывается для объявления поля с именем maxAllowedFiles как private int maxAllowedFiles = 3;.
• Значения параметров компонента приводят к зарезервированным @ символамRazor, но это не обязательно. Литералы (например, логические значения), ключевое слово (например, this) и null как значения параметров компонента не префиксируются с @префиксом, но это также лишь соглашение о документации. Если вы хотите, собственный код может префиксирует литералы @ .
• Как правило, в примерах используются соглашения ASP.NET Core/C# для кода и рекомендации по разработке ПО. Дополнительные сведения см. в следующих ресурсах:
  • Рекомендации по разработке ПО (репозиторий dotnet/aspnetcore на GitHub)
  • Соглашения о написании кода C# (руководство по C#)

Ниже приведен пример компонента счетчика и часть приложения, созданного из шаблона проекта Blazor. Подробно компоненты рассматриваются в статьях Компоненты, которые приведены далее в этой документации. В следующем примере демонстрируются понятия компонентов, описанные в статьях Основы (прежде чем вы приступите к статьям Компоненты, приведенным далее в этой документации).

Counter.razor:

Компонент предполагает, что интерактивный режим отрисовки наследуется от родительского компонента или применяется глобально к приложению.

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

Предыдущий компонент Counter:

• Задает собственный маршрут с помощью директивы @page в первой строке.
• Задает название страницы и заголовок.
• Отрисовывает текущее значение счетчика с помощью @currentCount. currentCount — это целочисленная переменная, определенная в коде C# блока @code.
• Отображает кнопку для запуска метода IncrementCount, который также можно найти в блоке @code и который увеличивает значение переменной currentCount.

Режимы отрисовки

Статьи в узле "Основы" ссылались на концепцию режимов отрисовки. Эта тема подробно рассматривается в статье о режимах отрисовки ядра ASP.NET Blazor в узле компонентов, который отображается после узла основных статей.

Для ранних ссылок на этот узел статей для отрисовки концепций режима отрисовки просто обратите внимание на следующее:

Каждый компонент в Blazor веб-приложении принимает режим отрисовки, чтобы определить модель размещения, которая используется, где она отрисовывается, и отображается ли она статически на сервере, отрисовывается с учетом взаимодействия пользователей на сервере или отрисовывается для взаимодействия пользователей на клиенте (обычно с предварительной отрисовкой на сервере).

Blazor Server и Blazor WebAssembly приложения для выпусков ASP.NET Core до .NET 8 остаются исправленными в концепциях модели размещения, а не режимах отрисовки. Режимы отрисовки концептуально применяются к Blazor веб-приложения в .NET 8 или более поздней версии.

В следующей Blazor таблице показаны доступные режимы отрисовки компонентов отрисовки Razor в веб-приложении. Режимы отрисовки применяются к компонентам с @rendermode директивой для экземпляра компонента или определения компонента. Кроме того, можно задать режим отрисовки для всего приложения.

Имя	Описание	Расположение отрисовки	Интерактивный
Статический сервер	Статическое отрисовка на стороне сервера (статический SSR)	Сервер	❌Нет
Интерактивный сервер	Интерактивная отрисовка на стороне сервера (интерактивная среда SSR) с помощью Blazor Server	Сервер	✔️Да
Интерактивный webAssembly	Отрисовка на стороне клиента (CSR) с помощью Blazor WebAssembly†	Клиент	✔️Да
Интерактивное авто	Интерактивная служба SSR, используемая Blazor Server изначально, а затем CSR при последующих посещениях после Blazor скачивания пакета	Сервер, а затем клиент	✔️Да

†Клиентская отрисовка (CSR) считается интерактивной. "Интерактивная отрисовка на стороне клиента" и "интерактивная CSR" не используются в отрасли или в Blazor документации.

Предыдущая информация о режимах отрисовки — это все, что необходимо знать, чтобы понять статьи узлов основных компонентов. Если вы не знакомы Blazor и читаете Blazor статьи, чтобы уменьшить оглавление, вы можете отложить использование подробных сведений о режимах отрисовки до тех пор, пока вы не достигнете статьи о режимах отрисовки ASP.NET Core Blazor в узле компонентов.

Модель DOM

Ссылки на объектную модель документа используют сокращенную модель DOM.

Дополнительные сведения см. на следующих ресурсах:

• Общие сведения о DOM (документация по MDN)
• Спецификация объектной модели документа уровня 1 (W3C)

Подмножество API .NET для Blazor WebAssembly приложений

Список курируемых api .NET, поддерживаемых в браузере Blazor WebAssembly , недоступен. Однако можно вручную найти список API .NET, аннотированных с [UnsupportedOSPlatform("browser")] помощью обнаружения API .NET, которые не поддерживаются в WebAssembly.

Примечание.

По ссылкам в документации на справочные материалы по .NET обычно загружается ветвь репозитория по умолчанию, которая представляет текущую разработку для следующего выпуска .NET. Чтобы выбрать тег для определенного выпуска, используйте раскрывающийся список Switch branches or tags (Переключение ветвей или тегов). Дополнительные сведения см. в статье Выбор тега версии исходного кода ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Дополнительные сведения см. на следующих ресурсах:

• Библиотеки классов: анализатор совместимости браузеров на стороне клиента
• Аннотирование API как неподдерживаемых на определенных платформах (dotnet/designs репозиторий GitHub)

Примеры приложений

Примеры приложений из документации можно просмотреть и скачать:

Репозиторий GitHub с примерами для Blazor (dotnet/blazor-samples)

Найдите пример приложения, сначала выбрав папку версии, которая соответствует версии .NET, с которую вы работаете.

Примеры приложений в репозитории:

• Blazor Веб-приложение
• Blazor WebAssembly
• Blazor Веб-приложение с EF Core (ASP.NET Core с Entity Framework Core Blazor (EF Core))
• BlazorВеб-приложение с SignalR (использование ASP.NET Core SignalR с Blazor)
• BlazorВеб-приложение с помощью OIDC (защита ASP.NET Core Blazor Web App с помощью OpenID Подключение (OIDC))
• Blazor WebAssemblyведение журнала с поддержкой область (ведение журнала ASP.NET CoreBlazor)
• Blazor WebAssemblyс ASP.NET Core Identity (Secure ASP.NET Core Blazor WebAssembly с ASP.NET Core Identity)

Дополнительные сведения см. в Blazor README.md файле репозитория GitHub.

Базовый тестовый приложение репозитория ASP.NET Core также является полезным набором примеров для различных Blazor сценариев:

BasicTestApp в источнике ссылок ASP.NET Core (dotnet/aspnetcore)

Примечание.

По ссылкам в документации на справочные материалы по .NET обычно загружается ветвь репозитория по умолчанию, которая представляет текущую разработку для следующего выпуска .NET. Чтобы выбрать тег для определенного выпуска, используйте раскрывающийся список Switch branches or tags (Переключение ветвей или тегов). Дополнительные сведения см. в статье Выбор тега версии исходного кода ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Чтобы скачать примеры приложений, выполните следующие действия.

• Скачайте ZIP-файл репозитория Blazor примеров.
• Распакуйте файл .

Байты нескольких

Размеры байтов .NET используют префиксы метрик для не десятичных байтов на основе полномочий 1024.

Имя (сокращенное)	Размер	Пример
Килобайт (КБ)	1024 байт	1 КБ = 1024 байта
Мегабайт (МБ)	10242 байта	1 МБ = 1 048 576 байт
Gigabyte (ГБ)	1 0243 байта	1 ГБ = 1 073 741 824 байта

Запросы в службу поддержки

В репозитории dotnet/AspNetCore.Docs размещаются только проблемы, связанные с документацией. Если вам требуется поддержка по продукту, не открывайте проблему по документации. Помощь можно найти в одном или нескольких из следующих каналов поддержки:

• Stack Overflow (с тегом blazor)
• Общая команда по Slack в ASP.NET Core
• Blazor Gitter

Чтобы сообщить о потенциальной ошибке на платформе или оставить отзыв о продукте, создайте заявку о проблеме для команды по продукту ASP.NET Core в проблемах dotnet/aspnetcore. Для отчетов об ошибках обычно требуется следующее:

• Четкое описание проблемы — следуйте инструкциям в шаблоне проблемы GitHub, предоставленном командой по продукту при создании заявки о проблеме.
• Минимальный проект для воспроизведения проблемы — разместите проект в GitHub, чтобы специалисты команды по продукту могли скачать и выполнить его. Укажите ссылку на проект в первом комментарии проблемы.

Если потенциальная проблема возникла со статьей по Blazor, создайте заявку о проблеме с документацией. Чтобы создать заявку о проблеме с документацией, воспользуйтесь кнопкой отзыва Эта страница и формой внизу статьи, при этом оставьте метаданные при создании первого комментария. Метаданные предоставляют данные для отслеживания и автоматически указывают автора статьи. Если тема уже обсуждалась с командой по продукту, укажите ссылку на проблему разработки в первом комментарии проблемы по документации.

Для проблем или отзывов в Visual Studio используйте жесты отчета о проблеме или предложения функций из Visual Studio, которые открывают внутренние проблемы для Visual Studio. Дополнительные сведения см. разделе обратной связи Visual Studio.

Поддержку по проблемам с Visual Studio Code можно получить на форумах поддержки сообщества. Отчеты об ошибка и отзывы о продуктах можно оставить, создав заявку о проблеме в репозитории microsoft/vscode на GitHub.

Проблемы GitHub с документацией Blazor автоматически помечаются для рассмотрения в проекте Blazor.Docs (репозиторий dotnet/AspNetCore.Docs на GitHub). На получение ответа потребуется некоторое время, особенно если вы создали заявку на выходных или в праздничные дни. Обычно в рабочие дни авторы документации отвечают в течение 24 часов.

Ссылка сообщества на ресурсы Blazor

Коллекцию ссылок на ресурсы Blazor от сообщества см. на странице Awesome Blazor.

Примечание.

Корпорация Майкрософт не владеет страницей Awesome Blazor, не обслуживает и не поддерживает ее, а также большинство продуктов и служб сообщества, описанных и приведенных на ней.