Бөлісу құралы:


Интеграция компонентов ASP.NET Core Razor в приложения ASP.NET Core

В этой статье описываются Razor сценарии интеграции компонентов для приложений ASP.NET Core.

Razor Интеграция компонентов

Razor компоненты можно интегрировать в Razor Pages, MVC и другие типы приложений ASP.NET Core. Razor компоненты также можно интегрировать в любое веб-приложение, включая приложения, не основанные на ASP.NET Core, в качестве пользовательских HTML-элементов.

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

Использование неизменяемых компонентов в страницах или представлениях

Используйте следующее руководство, чтобы интегрировать 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:

Примечание.

Примеры, приведенные в этом разделе, — 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.

После принятия решения о том, какой режим отрисовки следует принять:

Добавьте ссылку на 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>и других тегов. Компонент включает макет с @layoutRazor директивой в верхней части файла определения компонента, 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 Razor