Основы ASP.NET Core Blazor

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

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-ответа, используемого поисковыми системами для вычисления ранжирования страниц. За предварительной отрисовкой всегда следует окончательная отрисовка на сервере или клиенте.

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

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

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

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

• Как правило, в примерах используются соглашения ASP.NET Core/C# для кода и рекомендации по разработке ПО. Дополнительные сведения см. в следующих ресурсах:
  • рекомендации по проектированию платформы ASP.NET Core (dotnet/aspnetcore репозиторий GitHub)
  • Соглашения о написании кода C# (руководство по C#)
• Код проекта, пути к файлам, имена файлов, имена шаблонов проектов и другие специализированные термины приведены на английском языке (США) и обычно заключены в код.
• Компоненты обычно указываются с помощью имени их класса C# (в стиле Pascal), перед которым приведено слово "компонент". Например, типичный компонент отправки файлов называется "компонентом FileUpload".
• Обычно имя класса C# компонента не отличается от его имени файла.
• Маршрутизируемые компоненты обычно задают для своих относительных URL-адресов имя класса компонента в формате kebab-case. Например, компонент 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 Core 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.

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

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

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

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

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

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

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

Примеры из репозитория GitHub (Blazor) (dotnet/blazor-samples)

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

Более подробная информация, список примеров в репозитории и инструкции по загрузке — все это см. в README-файле репозитория GitHub Blazor.

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

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

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

В репозитории 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 от сообщества см. на странице Awesome Blazor.