Интеграция компонентов ASP.NET Core Razor в приложения ASP.NET Core
В этой статье описываются Razor сценарии интеграции компонентов для приложений ASP.NET Core.
Razor Интеграция компонентов
Razor компоненты можно интегрировать в Razor Pages, MVC и другие типы приложений ASP.NET Core. Razor компоненты также можно интегрировать в любое веб-приложение, включая приложения, не основанные на ASP.NET Core, в качестве пользовательских HTML-элементов.
Используйте инструкции в следующих разделах в зависимости от требований приложения:
- Чтобы интегрировать компоненты, которые не являются напрямую маршрутизируемыми из запросов пользователей, следуйте инструкциям в разделе "Использование неизменяемых компонентов в страницах или представлениях ". Следуйте этому руководству, когда приложение должно внедрять только компоненты в существующие страницы и представления с помощью вспомогательного средства тега компонента.
- Чтобы интегрировать компоненты с полной Blazor поддержкой, следуйте инструкциям в разделе "Добавление Blazor поддержки" в раздел приложения ASP.NET Core.
Использование неизменяемых компонентов в страницах или представлениях
Используйте следующее руководство, чтобы интегрировать Razor компоненты в страницы или представления существующего Razor приложения Pages или MVC с вспомогательным компонентом тега компонента.
Примечание.
Если приложению требуется напрямую routable компоненты (не внедренные в страницы или представления), пропустите этот раздел и используйте инструкции в разделе "Добавление Blazor поддержки в приложение ASP.NET Core ".
При использовании предварительной подготовки сервера и отрисовки страницы или представления:
- компонент предварительно отображается страницей или представлением;
- исходное состояние компонента, используемое для предварительной визуализации, теряется;
- новое состояние компонента создается при установке подключения SignalR.
Дополнительные сведения о режимах отрисовки, включая неинтерактивную отрисовку статических компонентов, см . в справке тегов компонентов в ASP.NET Core. Сведения о сохранении состояния предварительно созданных Razor компонентов см. в разделе "Справка по тегу состояния компонента" в ASP.NET Core.
Добавьте папку в корневую Components
папку проекта.
Добавьте файл импорта в папку Components
со следующим содержимым. Замените заполнитель {APP NAMESPACE}
пространством имен проекта.
Components/_Imports.razor
:
@using System.Net.Http
@using System.Net.Http.Json
@using Microsoft.AspNetCore.Components.Forms
@using Microsoft.AspNetCore.Components.Routing
@using Microsoft.AspNetCore.Components.Web
@using static Microsoft.AspNetCore.Components.Web.RenderMode
@using Microsoft.AspNetCore.Components.Web.Virtualization
@using Microsoft.JSInterop
@using {APP NAMESPACE}
@using {APP NAMESPACE}.Components
В файле макета проекта (Pages/Shared/_Layout.cshtml
в приложениях Razor Pages или Views/Shared/_Layout.cshtml
в приложениях MVC):
Добавьте следующий
<base>
тег и вспомогательный HeadOutlet компонент тега компонента в разметку<head>
:<base href="~/" /> <component type="typeof(Microsoft.AspNetCore.Components.Web.HeadOutlet)" render-mode="ServerPrerendered" />
Значение
href
(базовый путь к приложению ) в предыдущем примере предполагает, что приложение находится по корневому URL-пути (/
). Если приложение является подчиненным, следуйте инструкциям в разделе Базовый путь к приложению статьи Размещение и развертывание ASP.NET Core Blazor.Компонент HeadOutlet используется для отрисовки содержимого head (
<head>
) для заголовков страниц (компонент PageTitle) и других элементов head (компонент HeadContent), заданных компонентами Razor. Дополнительные сведения см. в статье Управление содержимым head в приложениях ASP.NET Core Blazor.Добавьте тег
<script>
для скриптаblazor.web.js
непосредственно перед разделом отрисовкиScripts
(@await RenderSectionAsync(...)
):<script src="_framework/blazor.web.js"></script>
Платформа Blazor автоматически добавляет
blazor.web.js
скрипт в приложение.
Примечание.
Как правило, макет загружается с помощью файла _ViewStart.cshtml
.
Добавьте в проект нерабочий компонент (no-op App
).
Components/App.razor
:
@* No-op App component *@
Где службы зарегистрированы, добавьте службы для компонентов и служб для Razor поддержки отрисовки компонентов интерактивного сервера.
В верхней части Program
файла добавьте using
инструкцию в начало файла для компонентов проекта:
using {APP NAMESPACE}.Components;
В предыдущей строке измените {APP NAMESPACE}
заполнитель на пространство имен приложения. Например:
using BlazorSample.Components;
Program
В файле перед строкой, которая создает приложение (builder.Build()
):
builder.Services.AddRazorComponents()
.AddInteractiveServerComponents();
Дополнительные сведения о добавлении поддержки для компонентов Interactive Server и WebAssembly см. в разделе ASP.NET Режимы отрисовки CoreBlazor.
Program
В файле сразу после вызова сопоставления Razor страниц (MapRazorPages) в Razor приложении Pages или сопоставления маршрутаMapControllerRoute контроллера по умолчанию в приложении MVC вызовите MapRazorComponents доступные компоненты и укажите корневой компонент приложения (первый загруженный компонент). По умолчанию корневой компонент приложения является компонентом App
(App.razor
). Прицепите вызов для AddInteractiveServerRenderMode настройки интерактивной отрисовки на стороне сервера (интерактивная служба SSR) для приложения:
app.MapRazorComponents<App>()
.AddInteractiveServerRenderMode();
Примечание.
Если приложение еще не было обновлено, чтобы включить по промежуточному слоям антифоргерии, добавьте следующую строку после UseAuthorization вызова:
app.UseAntiforgery();
Интегрируйте компоненты в какую-либо страницу или какое-либо представление. Например, добавьте EmbeddedCounter
компонент в папку проекта Components
.
Components/EmbeddedCounter.razor
:
<h1>Embedded 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++;
}
}
Razor Pages:
На странице Index
проекта приложения Razor Pages добавьте пространство имен компонента EmbeddedCounter
и внедрите компонент в страницу. При загрузке страницы Index
компонент EmbeddedCounter
будет предварительно отрисован на странице. В следующем примере замените заполнитель {APP NAMESPACE}
пространством имен проекта.
Pages/Index.cshtml
:
@page
@using {APP NAMESPACE}.Components
@model IndexModel
@{
ViewData["Title"] = "Home page";
}
<component type="typeof(EmbeddedCounter)" render-mode="ServerPrerendered" />
MVC:
В представлении Index
приложения MVC добавьте пространство имен компонента EmbeddedCounter
и внедрите компонент в представление. При загрузке представления Index
компонент EmbeddedCounter
будет предварительно отрисован на странице. В следующем примере замените заполнитель {APP NAMESPACE}
пространством имен проекта.
Views/Home/Index.cshtml
:
@using {APP NAMESPACE}.Components
@{
ViewData["Title"] = "Home Page";
}
<component type="typeof(EmbeddedCounter)" render-mode="ServerPrerendered" />
Добавление Blazor поддержки в приложение ASP.NET Core
В этом разделе рассматривается добавление Blazor поддержки в приложение ASP.NET Core:
- Добавление статической отрисовки на стороне сервера (статический SSR)
- Включение интерактивной отрисовки на стороне сервера (интерактивная среда SSR)
- Включение интерактивной автоматической (автоматической) или клиентской отрисовки (CSR)
Примечание.
Примеры, приведенные в этом разделе, — BlazorSample
это имя и пространство имен приложения.
Добавление статической отрисовки на стороне сервера (статический SSR)
Добавьте папку Components
в приложение.
Добавьте следующий _Imports
файл для пространств имен, используемых Razor компонентами.
Components/_Imports.razor
:
@using System.Net.Http
@using System.Net.Http.Json
@using Microsoft.AspNetCore.Components.Forms
@using Microsoft.AspNetCore.Components.Routing
@using Microsoft.AspNetCore.Components.Web
@using static Microsoft.AspNetCore.Components.Web.RenderMode
@using Microsoft.AspNetCore.Components.Web.Virtualization
@using Microsoft.JSInterop
@using {APP NAMESPACE}
@using {APP NAMESPACE}.Components
Измените заполнитель пространства имен ({APP NAMESPACE}
) на пространство имен приложения. Например:
@using BlazorSample
@using BlazorSample.Components
Blazor Добавьте маршрутизатор (<Router>
,Router) в приложение в Routes
компонент, который помещается в папку приложенияComponents
.
Components/Routes.razor
:
<Router AppAssembly="typeof(Program).Assembly">
<Found Context="routeData">
<RouteView RouteData="routeData" />
<FocusOnNavigate RouteData="routeData" Selector="h1" />
</Found>
</Router>
App
Добавьте компонент в приложение, который служит корневым компонентом, который является первым компонентом, который загружает приложение.
Components/App.razor
:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<base href="/" />
<link rel="stylesheet" href="@Assets["{ASSEMBLY NAME}.styles.css"]" />
<HeadOutlet />
</head>
<body>
<Routes />
<script src="_framework/blazor.web.js"></script>
</body>
</html>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<base href="/" />
<link rel="stylesheet" href="{ASSEMBLY NAME}.styles.css" />
<HeadOutlet />
</head>
<body>
<Routes />
<script src="_framework/blazor.web.js"></script>
</body>
</html>
Заполнитель {ASSEMBLY NAME}
— это имя сборки приложения. Например, проект с именем сборки использует имя файла таблицы стилей ContosoApp
ContosoApp.styles.css
.
Pages
Добавьте папку в Components
папку для хранения routable Razor компонентов.
Добавьте следующий Welcome
компонент, чтобы продемонстрировать статический SSR.
Components/Pages/Welcome.razor
:
@page "/welcome"
<PageTitle>Welcome!</PageTitle>
<h1>Welcome to Blazor!</h1>
<p>@message</p>
@code {
private string message =
"Hello from a Razor component and welcome to Blazor!";
}
В файле проекта Program
ASP.NET Core:
using
Добавьте инструкцию в начало файла для компонентов проекта:using {APP NAMESPACE}.Components;
В предыдущей строке измените
{APP NAMESPACE}
заполнитель на пространство имен приложения. Например:using BlazorSample.Components;
Добавьте Razor службы компонентов (AddRazorComponents), которые также автоматически добавляют службы антифоргерии (AddAntiforgery). Добавьте следующую строку перед строкой, которая вызывает
builder.Build()
):builder.Services.AddRazorComponents();
Добавьте по промежуточному слоя антифоргерии в конвейер обработки запросов с UseAntiforgeryпомощью . UseAntiforgery вызывается после вызова UseRouting. Если есть вызовы UseRouting и UseEndpoints, вызов UseAntiforgery должен пройти между ними. Вызов UseAntiforgery должен быть помещен после вызовов UseAuthentication и UseAuthorization.
app.UseAntiforgery();
Добавьте MapRazorComponents в конвейер обработки запросов приложения компонент
App
(App.razor
), указанный как корневой компонент по умолчанию (загруженный первым компонентом). Поместите следующий код перед строкой, которая вызываетapp.Run
:app.MapRazorComponents<App>();
При запуске Welcome
приложения компонент обращается к конечной точке /welcome
.
Включение интерактивной отрисовки на стороне сервера (интерактивная среда SSR)
Следуйте инструкциям в разделе "Добавление статической отрисовки на стороне сервера " (статический SSR).
В файле приложения Program
добавьте вызов, в AddInteractiveServerComponents который Razor добавляются службы компонентов:AddRazorComponents
builder.Services.AddRazorComponents()
.AddInteractiveServerComponents();
Добавьте вызов, в AddInteractiveServerRenderMode который Razor сопоставлены компоненты:MapRazorComponents
app.MapRazorComponents<App>()
.AddInteractiveServerRenderMode();
Добавьте следующий Counter
компонент в приложение, которое использует интерактивную отрисовку на стороне сервера (интерактивная служба SSR).
Components/Pages/Counter.razor
:
@page "/counter"
@rendermode InteractiveServer
<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
приложения компонент обращается по адресу /counter
.
Включение интерактивной автоматической (автоматической) или клиентской отрисовки (CSR)
Следуйте инструкциям в разделе "Добавление статической отрисовки на стороне сервера " (статический SSR).
Компоненты, использующие режим интерактивной автоматической отрисовки, изначально используют интерактивный SSR. Среда выполнения .NET и пакет приложений загружаются на клиент в фоновом режиме и кэшируются, чтобы их можно было использовать в будущих визитах. Компоненты, использующие режим интерактивной отрисовки WebAssembly, отображаются только в интерактивном режиме на клиенте после Blazor скачивания пакета и Blazor активации среды выполнения. Помните, что при использовании режимов отрисовки интерактивного авто или интерактивного веб-сайта код компонента, скачанный в клиент, не является частным. Дополнительные сведения см. в режимах отрисовки ASP.NET CoreBlazor.
После принятия решения о том, какой режим отрисовки следует принять:
- Если вы планируете внедрить режим интерактивной автоматической отрисовки, следуйте инструкциям в разделе "Включить интерактивную отрисовку на стороне сервера" (интерактивная служба SSR).
- Если вы планируете использовать только интерактивную отрисовку WebAssembly, продолжайте без добавления интерактивного SSR.
Добавьте ссылку на Microsoft.AspNetCore.Components.WebAssembly.Server
пакет NuGet в приложение.
Примечание.
Рекомендации по добавлению пакетов в приложения .NET см. в разделе Способы установки пакетов NuGet в статье Рабочий процесс использования пакета (документация по NuGet). Проверьте правильность версий пакета на сайте NuGet.org.
Создайте донора Blazor Web App для предоставления ресурсов приложению. Следуйте указаниям в статье "Инструмент для ASP.NET Core Blazor ", выбрав поддержку следующих функций шаблона при создании Blazor Web App.
Для имени приложения используйте то же имя, что и приложение ASP.NET Core, которое приводит к сопоставлению разметки имени приложения в компонентах и сопоставлении пространств имен в коде. Использование того же пространства имен и пространства имен не является обязательным, так как пространства имен можно настроить после перемещения ресурсов из приложения-донора в приложение ASP.NET Core. Однако время сохраняется путем сопоставления пространств имен в начале.
Visual Studio:
- В режиме интерактивной отрисовки выберите auto (Server и WebAssembly).
- Задайте для параметра "Интерактивность" значение "На страницу или компонент".
- Отмените флажок для включения примеров страниц.
.NET CLI:
- Использовать параметр
-int Auto
. - Не используйте
-ai|--all-interactive
этот параметр. -e|--empty
Передайте параметр.
Скопируйте весь .Client
проект из донора Blazor Web Appв папку решения приложения ASP.NET Core.
Внимание
Не копируйте папку .Client
в папку проекта ASP.NET Core. Лучший подход к организации решений .NET — поместить каждый проект решения в собственную папку в папку решения верхнего уровня. Если папка решения над папкой проекта ASP.NET Core не существует, создайте ее. Затем скопируйте .Client
папку проекта из донора Blazor Web App в папку решения. Последняя структура папки проекта должна иметь следующий макет:
BlazorSampleSolution
(папка решения верхнего уровня)BlazorSample
(исходный проект ASP.NET Core)BlazorSample.Client
(.Client
папка проекта от донора Blazor Web App)
Для файла решения ASP.NET Core его можно оставить в папке проекта ASP.NET Core. Кроме того, можно переместить файл решения или создать новую в папке решения верхнего уровня, если проект ссылается на файлы проекта (.csproj
) двух проектов в папке решения.
Если вы назвали донора Blazor Web App при создании проекта донора таким же, как и приложение ASP.NET Core, пространства имен, используемые пожертвованных активов, соответствуют тем в приложении ASP.NET Core. Вам не нужно выполнять дальнейшие шаги для сопоставления пространств имен. Если при создании проекта донора Blazor Web App использовалось другое пространство имен, необходимо настроить пространства имен в пожертвованных ресурсах, если вы планируете использовать rest это руководство точно так же, как показано. Если пространства имен не совпадают, измените пространства имен перед продолжением или измените пространства имен, следуя остальным инструкциям в этом разделе.
Удалите донора Blazor Web App, так как он не имеет дальнейшего использования в этом процессе.
Добавьте проект в .Client
решение:
Visual Studio: щелкните правой кнопкой мыши решение в Обозреватель решений и выберите "Добавить>существующий проект". Перейдите в папку
.Client
и выберите файл проекта (.csproj
)..NET CLI: используйте
dotnet sln add
команду , чтобы добавить.Client
проект в решение.
Добавьте ссылку на проект из проекта ASP.NET Core в клиентский проект:
Visual Studio: щелкните правой кнопкой мыши проект ASP.NET Core и выберите "Добавить>ссылку на проект".
.Client
Выберите проект и нажмите кнопку "ОК"..NET CLI: из папки проекта ASP.NET Core используйте следующую команду:
dotnet add reference ../BlazorSample.Client/BlazorSample.Client.csproj
Предыдущая команда предполагает следующее:
- Имя
BlazorSample.Client.csproj
файла проекта . - Проект
.Client
находится вBlazorSample.Client
папке решения. Папка.Client
находится рядом с папкой проекта ASP.NET Core.
Дополнительные сведения о команде
dotnet add reference
смdotnet add reference
. в документации по .NET.- Имя
Внесите следующие изменения в файл приложения Program
ASP.NET Core:
Добавьте службы компонентов Interactive WebAssembly, где AddInteractiveWebAssemblyComponents Razor добавляются AddRazorComponentsслужбы компонентов.
Для интерактивной автоматической отрисовки:
builder.Services.AddRazorComponents() .AddInteractiveServerComponents() .AddInteractiveWebAssemblyComponents();
Только для интерактивной отрисовки WebAssembly:
builder.Services.AddRazorComponents() .AddInteractiveWebAssemblyComponents();
Добавьте режим интерактивной
.Client
отрисовки WebAssembly (AddInteractiveWebAssemblyRenderMode) и дополнительные сборки для проекта, с MapRazorComponentsкоторыми Razor сопоставляются компоненты.Для интерактивной автоматической отрисовки (авто):
app.MapRazorComponents<App>() .AddInteractiveServerRenderMode() .AddInteractiveWebAssemblyRenderMode() .AddAdditionalAssemblies(typeof(BlazorSample.Client._Imports).Assembly);
Только для интерактивной отрисовки WebAssembly:
app.MapRazorComponents<App>() .AddInteractiveWebAssemblyRenderMode() .AddAdditionalAssemblies(typeof(BlazorSample.Client._Imports).Assembly);
В предыдущих примерах изменитесь
BlazorSample.Client
на соответствие пространству.Client
имен проекта.
Добавьте папку Pages
в .Client
проект.
Если проект ASP.NET Core имеет существующий Counter
компонент:
- Переместите компонент в
Pages
папку.Client
проекта. - Удалите директиву
@rendermode
в верхней части файла компонента.
Если у приложения ASP.NET Core нет Counter
компонента, добавьте следующий Counter
компонент (Pages/Counter.razor
) в .Client
проект:
@page "/counter"
@rendermode InteractiveAuto
<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++;
}
}
Если приложение принимает только интерактивную отрисовку WebAssembly, удалите директиву @rendermode
и значение:
- @rendermode InteractiveAuto
Запустите решение из проекта приложения ASP.NET Core:
Visual Studio: убедитесь, что проект ASP.NET Core выбран в Обозреватель решений при запуске приложения.
.NET CLI: запустите проект из папки проекта ASP.NET Core.
Чтобы загрузить компонент, перейдите Counter
к разделу /counter
.
Реализация Blazorмакета и стилей
При необходимости назначьте компонент макета RouteView
по умолчанию с помощью RouteView.DefaultLayout параметра компонента.
В Routes.razor
следующем примере компонент используется MainLayout
в качестве макета по умолчанию:
<RouteView RouteData="routeData" DefaultLayout="typeof(MainLayout)" />
Дополнительные сведения см. в разделе ASP.NET Макеты ядраBlazor.
Blazor Макет шаблона проекта и таблицы стилей доступны в dotnet/aspnetcore
репозитории GitHub:
MainLayout.razor
MainLayout.razor.css
NavMenu.razor
NavMenu.razor.css
Примечание.
По ссылкам в документации на справочные материалы по .NET обычно загружается ветвь репозитория по умолчанию, которая представляет текущую разработку для следующего выпуска .NET. Чтобы выбрать тег для определенного выпуска, используйте раскрывающийся список Switch branches or tags (Переключение ветвей или тегов). Дополнительные сведения см. в статье Выбор тега версии исходного кода ASP.NET Core (dotnet/AspNetCore.Docs #26205).
В зависимости от того, как вы упорядочиваете файлы макета в приложении, может потребоваться добавить @using
инструкцию для папки файлов макета в файл приложения для их использования в компонентах приложения _Imports.razor
.
Нет необходимости явно ссылаться на таблицы стилей при использовании изоляции CSS. Платформа Blazor автоматически объединяет отдельные таблицы стилей компонентов. Пакетная таблица стилей приложения уже ссылается на компонент приложения App
({ASSEMBLY NAME}.styles.css
где {ASSEMBLY NAME}
заполнитель — имя сборки приложения).
RazorComponentResult
Возврат из действия контроллера MVC
Действие контроллера MVC может возвращать компонент с RazorComponentResult<TComponent>.
Components/Welcome.razor
:
<PageTitle>Welcome!</PageTitle>
<h1>Welcome!</h1>
<p>@Message</p>
@code {
[Parameter]
public string? Message { get; set; }
}
В контроллере:
public IResult GetWelcomeComponent() =>
new RazorComponentResult<Welcome>(new { Message = "Hello, world!" });
Возвращается только разметка HTML для отрисованного компонента. Макеты и разметка HTML-страниц не отображаются автоматически с помощью компонента. Чтобы создать полную Blazor HTML-страницу, приложение может поддерживать макет, предоставляющий разметку HTML для <html>
, <body>
<head>
и других тегов. Компонент включает макет с @layout
Razor директивой в верхней части файла определения компонента, Welcome.razor
например в этом разделе. В следующем примере предполагается, что приложение имеет макет с именем RazorComponentResultLayout
(Components/Layout/RazorComponentResultLayout.razor
):
@using BlazorSample.Components.Layout
@layout RazorComponentResultLayout
Вы можете избежать размещения @using
инструкции для Layout
папки в отдельных компонентах, переместив ее в файл приложения _Imports.razor
.
Дополнительные сведения см. в разделе ASP.NET Макеты ядраBlazor.
Пространства имен компонентов
При использовании настраиваемой папки для хранения компонентов Razor проекта добавьте пространство имен, представляющее эту папку, на страницу или в представление либо в файл _ViewImports.cshtml
. В следующем примере :
- Компоненты хранятся в папке
Components
проекта. - Заполнитель
{APP NAMESPACE}
— это пространство имен проекта.Components
отображает имя папки.
@using {APP NAMESPACE}.Components
Например:
@using BlazorSample.Components
Файл _ViewImports.cshtml
находится в папке Pages
приложения Razor Pages или в папке Views
приложения MVC.
Дополнительные сведения см. в статье Компоненты Razor ASP.NET Core.
Дополнительные ресурсы
ASP.NET Core