Поделиться через

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

  • Статья

Примечание.

Это не последняя версия этой статьи. В текущем выпуске см . версию .NET 9 этой статьи.

Предупреждение

Эта версия ASP.NET Core больше не поддерживается. Дополнительные сведения см. в политике поддержки .NET и .NET Core. В текущем выпуске см . версию .NET 9 этой статьи.

Внимание

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

В текущем выпуске см . версию .NET 9 этой статьи.

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

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

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

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

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

Внимание

При использовании Blazor Web Appбольшинства Blazor компонентов примера документации требуется интерактивность для работы и демонстрации концепций, описанных в статьях. При тестировании примера компонента, предоставленного в статье, убедитесь, что приложение принимает глобальное взаимодействие или компонент принимает интерактивный режим отрисовки.

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

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

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

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

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

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

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

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

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

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

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

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

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

  • Как правило, в примерах используются соглашения ASP.NET Core/C# для кода и рекомендации по разработке ПО. Дополнительные сведения см. в следующих ресурсах:
  • Код проекта, пути к файлам, имена файлов, имена шаблонов проектов и другие специализированные термины приведены на английском языке (США) и обычно заключены в код.
  • Компоненты обычно указываются с помощью имени их класса 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 операторы, другие директивы в алфавитном порядке.
  • Хотя для членов не требуется private , модификаторы доступа используются в примерах статей и примерах приложений. Например, private указывается для объявления поля с именем maxAllowedFiles как private int maxAllowedFiles = 3;.
  • Значения параметров компонента приводят к зарезервированным @ символамRazor, но это не обязательно. Литералы (например, логические значения), ключевые слова (например, this) и null как значения параметров компонента не префиксируются с @префиксом, но это также просто соглашение о документации. Если вы хотите, собственный код может префиксирует литералы @ .
  • Классы C# используют ключевое this слово и избегайте полей префикса с подчеркиванием (_), назначенными конструкторам, которые отличаются от рекомендаций по проектированию платформы ASP.NET Core.
  • В примерах, использующих первичные конструкторы (C# 12 или более поздней версии), параметры первичного конструктора обычно используются непосредственно членами класса.

Дополнительные сведения о Razor синтаксисе компонентов приведены вRazor разделе синтаксиса ASP.NET Основных Razor компонентов.

Ниже приведен пример компонента счетчика и часть приложения, созданного из шаблона проекта 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++;
}

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

@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++;
}

@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++;
    }
}

@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++;
    }
}

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

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

@code {
    private int currentCount = 0;

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

@page "/counter"

<h1>Counter</h1>

<p>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 Web App режиме отрисовки принимает режим отрисовки, чтобы определить модель размещения, которая используется, где она отрисовывается, а также отображается ли она статически на сервере, отрисовывается для взаимодействия пользователей на сервере или отрисовывается для взаимодействия пользователей на клиенте (обычно с предварительной отрисовкой на сервере).

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

В следующей таблице показаны доступные режимы отрисовки компонентов отрисовки Razor в .Blazor Web App Режимы отрисовки применяются к компонентам с @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.

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

Подмножество 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).

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

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

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

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

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

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

Пример репозитория содержит два типа примеров:

  • Примеры фрагментов приложений предоставляют примеры кода, которые отображаются в статьях. Эти приложения компилируются, но не обязательно запускаются приложения. Эти приложения полезны для простого получения примера кода, отображаемого в статьях.
  • Примеры приложений для компиляции Blazor и запуска статей для следующих сценариев:
    • Blazor Server с EF Core
    • Blazor Server и Blazor WebAssembly с SignalR;
    • ведение журнала с поддержкой областей Blazor WebAssembly.

Дополнительные сведения и список примеров в репозитории см 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 КБ = 1 024 байта
Мегабайт (МБ) 10242 байта 1 МБ = 1 048 576 байт
Gigabyte (ГБ) 1 0243 байта 1 ГБ = 1 073 741 824 байта

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

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

Чтобы сообщить о потенциальной ошибке на платформе или оставить отзыв о продукте, создайте заявку о проблеме для команды по продукту 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 от сообщества см. на странице Awesome Blazor.

Примечание.

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