базовый путь к приложению ASP.NET Core Blazor

В этой статье объясняется базовый путь приложения в приложениях ASP.NET Core Blazor , включая руководство по настройке.

Базовый путь приложения  — это корневой URL-путь приложения. Для успешной маршрутизации в Blazor приложениях требуется настройка фреймворка для любого корневого URL-адреса, который не находится по пути по умолчанию базового приложения /.

Рассмотрим следующее приложение ASP.NET Core и подприложение Blazor:

• Приложение ASP.NET Core называется MyApp:
  • Физическое расположение приложения: d:/MyApp.
  • запросы принимаются по адресу: https://www.contoso.com/{MYAPP RESOURCE}.
• Приложение Blazor, называемое CoolApp, является вложенным приложением в MyApp:
  • Физическое расположение дочернего приложения: d:/MyApp/CoolApp.
  • запросы принимаются по адресу: https://www.contoso.com/CoolApp/{COOLAPP RESOURCE}.

Если для CoolApp не указана дополнительная конфигурация, дочернее приложение в этом сценарии не имеет сведений о своем местоположении на сервере. Например, приложение не может создавать правильные относительные URL-адреса к своим ресурсам, если ему неизвестно, что оно находится по относительному пути URL /CoolApp/. Это также применяется в различных сценариях размещения и использования обратного прокси-сервера, когда приложение не размещается по корневому пути URL.

Предыстория

Назначение тега привязки (href) можно составить с использованием одной из двух конечных точек:

• Абсолютные расположения, включающие схему (если она опущена, используется схема страницы по умолчанию), узел, порт и путь или просто косая черта (/), за которой следует путь.

  Примеры: https://example.com/a/b/c или /a/b/c

• Относительные расположения, содержащие только путь и не начинающиеся с символа / (/). Они разрешаются относительно текущего URL-адреса документа или значения тега <base>, если указано.

  Пример: a/b/c

Наличие косой черты (/) в настроенном базовом пути приложения имеет важное значение для вычисления базового пути для URL-адресов приложения. Например, https://example.com/a имеет базовый путь https://example.com/, а https://example.com/a/ с косой чертой имеет базовый путь https://example.com/a.

Источники ссылок, относящихся к Blazor в приложениях ASP.NET Core:

Если вы отрисовываете Blazor приложение из разных документов (например, /Admin/B/C/ и /Admin/D/E/), необходимо учитывать базовый путь приложения, иначе базовый путь будет отличаться, когда приложение отрисовывается в каждом документе, и ресурсы будут извлекаться из неправильных URL-адресов.

Выберите одну из следующих стратегий, чтобы обеспечить правильное разрешение относительных ссылок:

• Динамически сопоставлять ресурсы с помощью документа, на который они были отрисованы в качестве корневого элемента. Для этого требуется пользовательская логика маршрутизации (например, IDynamicEndpointMetadata или MatcherPolicy) и обычно зарезервирована для сайтов с высокой динамичностью.

Оставшаяся часть этой статьи посвящена реализации согласованного базового пути.

Серверная часть Blazor

Сопоставьте узел серверного приложения SignalR, передавая путь к Blazor в файл MapBlazorHub. Путь к концентратору по умолчанию — Blazor, а следующий пример устанавливает базовый путь концентратора по умолчанию на /_blazor:

app.MapBlazorHub("base/path/_blazor");

Преимущество использования MapBlazorHub заключается в том, что вы можете сопоставить шаблоны, такие как "{tenant}" , а не только конкретные пути.

Вы также можете сопоставить концентратор, если приложение находится в виртуальной папке с разветвленным промежуточным конвейером. В следующем примере запросы к /base/path/ обрабатываются концентратором BlazorSignalR.

app.Map("/base/path", subapp => {
    subapp.UsePathBase("/base/path");
    subapp.UseRouting();
	  subapp.UseAntiforgery();
    subapp.UseEndpoints(endpoints => {
        endpoints.MapBlazorHub("/base/path/_blazor");
        endpoints.MapStaticAssets();
		    endpoints.MapRazorComponents<App>()
				.AddInteractiveServerRenderMode();
	});
});

<base> Настройте тег в соответствии с инструкциями в разделе "Настройка базового пути приложения".

Автономное устройство Blazor WebAssembly

В автономном Blazor WebAssembly приложении настроен только <base> тег в соответствии с инструкциями в разделе "Настройка базового пути приложения".

Настройка базового пути приложения

Чтобы предоставить конфигурацию базового Blazor пути https://www.contoso.com/CoolApp/приложения, задайте базовый путь приложения (<base>), который также называется относительным корневым путем.

Настроив базовый путь приложения, компонент, который не находится в корневом каталоге, может создавать URL-адреса относительно корневого пути приложения. Компоненты, которые существуют на разных уровнях структуры каталогов, могут создавать ссылки на другие ресурсы во всех местах приложения. Базовый путь к приложению также используется для перехвата выбранных гиперссылок, когда целевой объект ссылки href находится в пределах URI-пространства базового пути к приложению. Компонент Router обрабатывает внутреннюю навигацию.

Поместите тег <base> в разметку <head> (расположение <head> содержимого) до элементов, у которых значения атрибутов являются URL, например, у href атрибутов элементов <link>.

• В серверном Blazor приложении используйте следующий подход:

• Вариант 2: Вызовите UsePathBasefirst в конвейере обработки запросов приложения (Program.cs) сразу после того, как WebApplicationBuilder построен (builder.Build()), чтобы настроить базовый путь для любого следующего промежуточного ПО, взаимодействующего с путем запроса:

  app.UsePathBase("/CoolApp");
  

  Вызов UsePathBase рекомендуется, если вы также хотите запускать приложение Blazor Server локально. Например, укажите URL-адрес запуска в файле Properties/launchSettings.json:

  "launchUrl": "https://localhost:{PORT}/CoolApp",
  

  Заполнитель {PORT} в предыдущем примере — это порт, соответствующий защищенному порту в пути конфигурации applicationUrl. В следующем примере показан полный профиль запуска приложения на порту 7279.

  "BlazorSample": {
    "commandName": "Project",
    "dotnetRunMessages": true,
    "launchBrowser": true,
    "applicationUrl": "https://localhost:7279;http://localhost:5279",
    "launchUrl": "https://localhost:7279/CoolApp",
    "environmentVariables": {
      "ASPNETCORE_ENVIRONMENT": "Development"
  }
  

  Подробнее о файле см. в разделе launchSettings.jsonсреды выполнения для ASP.NET Core. Дополнительные сведения о базовых путях Blazor и размещении приложений см. в разделе <base href="/" />, или альтернативы базовому тегу для интеграции MVC Blazor (dotnet/aspnetcore #43191).

• Blazor WebAssembly Автономная (wwwroot/index.html):

  <base href="/CoolApp/">
  

  Требуется завершающий слэш.

Не добавляйте в ссылках в приложении префикс в виде слэша. Избегайте использования разделителя сегментов пути, либо используйте нотацию относительного пути точка-косая черта (./):

• ❌ Неправильно: <a href="/account">
• ✔️ Правильно: <a href="account">
• ✔️ Правильно: <a href="./account">

В Blazor WebAssembly запросах веб-API с HttpClient службой убедитесь, что вспомогательные элементы JSON (HttpClientJsonExtensions) не добавляют префикс к URL-адресам слэшем (/):

• ❌ Неправильно: var rsp = await client.GetFromJsonAsync("/api/Account");
• ✔️ Правильно: var rsp = await client.GetFromJsonAsync("api/Account");

Не добавляйте префикс к относительным ссылкам в Navigation Manager косой чертой. Избегайте использования разделителя сегментов пути или используйте нотацию относительного пути с точкой-слэш (./). Здесь Navigation является внедренной NavigationManager.

• ❌ Неправильно: Navigation.NavigateTo("/other");
• ✔️ Правильно: Navigation.NavigateTo("other");
• ✔️ Правильно: Navigation.NavigateTo("./other");

В стандартных конфигурациях для размещения Azure или служб IIS дополнительная настройка обычно не требуется. В некоторых сценариях размещения, не использующих IIS и обратный прокси, может потребоваться дополнительная конфигурация промежуточного ПО для статических файлов:

• Для правильного обслуживания статических файлов (например, app.UseStaticFiles("/CoolApp");).
• Для выполнения скрипта Blazor (_framework/blazor.*.js). Дополнительные сведения см. в ASP.NET Core Blazor статических файлов.

Приложение Blazor WebAssembly с некорневым относительным путем URL (например, <base href="/CoolApp/">) не сможет найти свои ресурсы при локальном запуске. Для решения этой проблемы во время локальной разработки и тестирования можно предоставить аргумент базового пути, который соответствует значению href тега <base> во время выполнения. Не добавляйте в конце косую черту. Чтобы передать базовый аргумент пути при локальном запуске приложения, выполните dotnet watch команду (или dotnet run) из каталога приложения с параметром --pathbase :

dotnet watch --pathbase=/{RELATIVE URL PATH (no trailing slash)}

Для приложения Blazor WebAssembly с относительным путем URL /CoolApp/ (<base href="/CoolApp/">) команда имеет следующий вид:

dotnet watch --pathbase=/CoolApp

Если вы предпочитаете настроить профиль запуска приложения, чтобы указать pathbase автоматически, а не вручную с dotnet watch (или dotnet run), задайте свойство commandLineArgs в Properties/launchSettings.json. В следующем примере также настраивается URL-адрес запуска (launchUrl):

"commandLineArgs": "--pathbase=/{RELATIVE URL PATH (no trailing slash)}",
"launchUrl": "{RELATIVE URL PATH (no trailing slash)}",

В качестве примера используется CoolApp:

"commandLineArgs": "--pathbase=/CoolApp",
"launchUrl": "CoolApp",

(dotnet watch или dotnet run) с параметром --pathbase или конфигурацией профиля запуска, которая задаёт базовый путь, приложение Blazor WebAssembly отвечает локально по адресу http://localhost:port/CoolApp.

Подробнее о файле см. в разделе launchSettings.jsonсреды выполнения для ASP.NET Core. Дополнительные сведения о Blazor базовых путях и хостинге приложений см. в разделе или об альтернативе базового тега для интеграции Blazor MVC (dotnet/aspnetcore #43191).

Получение базового пути приложения из конфигурации

В следующем руководстве объясняется, как получить путь к <base> тегу из файла параметров приложения для разных сред.

Добавьте файл параметров приложения в приложение. В следующем примере демонстрируется использование среды Staging (appsettings.Staging.json):

{
  "AppBasePath": "staging/"
}

В серверном Blazor приложении загрузите базовый путь из конфигурации в <head> содержимом:

@inject IConfiguration Config

...

<head>
    ...
    <base href="/@(Config.GetValue<string>("AppBasePath"))" />
    ...
</head>

app.UsePathBase($"/{app.Configuration.GetValue<string>("AppBasePath")}");

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

Примеры в этом разделе посвящены предоставлению базового пути приложения из параметров приложения, но подход чтения пути IConfiguration из любого поставщика конфигурации является допустимым. Дополнительные сведения см. в следующих ресурсах:

• Конфигурация Blazor в ASP.NET Core
• Конфигурация в ASP.NET Core