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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Чтобы получить дополнительную информацию, список образцов в репозитории и инструкции по скачиванию, см. файл README в репозитории образцов на GitHub.

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

BasicTestApp в справочном источнике ASP.NET Core (dotnet/aspnetcore)

Кратные байтам

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

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

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

• Stack Overflow (с тегом blazor)
• General ASP.NET Core Slack Team
• Blazor Гитер

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

• Четкое объяснение проблемы: Следуйте инструкциям в шаблоне задачи GitHub, предоставленном подразделением продукта при ее открытии.
• проект Minimal repro: Поместите проект на GitHub, чтобы инженеры продуктовой единицы могли его скачать и запустить. Вставьте перекрёстную ссылку на проект в первый комментарий к задаче.

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

Для сообщений о проблемах или предложениях по улучшению Visual Studio используйте опции Report a Problem или Suggest a Feature внутри Visual Studio, которые открывают внутренние задачи для Visual Studio. Дополнительную информацию см. в разделе Visual Studio Feedback.

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

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

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

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