Статические файлы Blazor в ASP.NET Core
Примечание.
Это не последняя версия этой статьи. В текущем выпуске см . версию .NET 9 этой статьи.
Предупреждение
Эта версия ASP.NET Core больше не поддерживается. Дополнительные сведения см. в политике поддержки .NET и .NET Core. В текущем выпуске см . версию .NET 9 этой статьи.
Внимание
Эта информация относится к предварительному выпуску продукта, который может быть существенно изменен до его коммерческого выпуска. Майкрософт не предоставляет никаких гарантий, явных или подразумеваемых, относительно приведенных здесь сведений.
В текущем выпуске см . версию .NET 9 этой статьи.
В этой статье описывается Blazor конфигурация приложения для обслуживания статических файлов.
Доставка статических ресурсов в серверных приложениях Blazor
Обслуживание статических ресурсов осуществляется с помощью соглашений о маршрутизации конечных точек или ПО промежуточного слоя, описанного в следующей таблице.
Функция | API | Версия .NET | Description |
---|---|---|---|
Сопоставление соглашений о маршрутизации статических активов конечных точек | MapStaticAssets | .NET 9 или более поздней версии | Оптимизирует доставку статических ресурсов клиентам. |
ПО промежуточного слоя статических файлов | UseStaticFiles | Все версии .NET | Служит статическим ресурсам клиентам без оптимизации статических ресурсов карты, но полезно для некоторых задач, которые не могут управлять статическими ресурсами. |
Настройте статические ресурсы карты путем вызова MapStaticAssets в конвейере обработки запросов приложения, который выполняет следующие действия:
- Задает заголовки ETag и Last-Modified.
- Задает заголовки кэширования.
- Использует по промежуточному слоям кэширования.
- По возможности обслуживает сжатые статические ресурсы.
- Работает с сеть доставки содержимого (CDN) (например, Azure CDN) для обслуживания статических ресурсов приложения ближе к пользователю.
- Отпечаток ресурсов для предотвращения повторного использования старых версий файлов.
Сопоставление статических ресурсов работает путем объединения процессов сборки и публикации для сбора сведений о статических ресурсах в приложении. Эта информация используется библиотекой среды выполнения для эффективного обслуживания статических ресурсов браузерам.
Сопоставление статических ресурсов может заменить UseStaticFiles в большинстве ситуаций. Однако статические ресурсы карты оптимизированы для обслуживания ресурсов из известных расположений в приложении во время сборки и публикации. Если приложение обслуживает ресурсы из других расположений, таких как диск или внедренные ресурсы, UseStaticFiles следует использовать.
Сопоставление статических ресурсов (MapStaticAssets) заменяет вызовы UseBlazorFrameworkFiles в приложениях, обслуживающих Blazor WebAssembly файлы платформы, и явным образом вызов UseBlazorFrameworkFiles в ней Blazor Web App не требуется, так как API автоматически вызывается при вызове AddInteractiveWebAssemblyComponents.
Статические ресурсы карты предоставляют следующие преимущества, которые недоступны при вызове UseStaticFiles:
- Сжатие во время сборки для всех ресурсов в приложении, включая JavaScript (JS) и таблицы стилей, но исключая ресурсы изображений и шрифтов, которые уже сжаты. Сжатие Gzip (
Content-Encoding: gz
) используется во время разработки. Gzip с сжатием Brotli (Content-Encoding: br
) используется во время публикации. - Отпечаток для всех ресурсов во время сборки с строкой в кодировке Base64 хэша SHA-256 каждого файла. Это позволяет повторно использовать старую версию файла, даже если старый файл кэшируется. Отпечатанные ресурсы кэшируются с помощью
immutable
директивы, которая приводит к тому, что браузер никогда не запрашивает ресурс снова, пока он не изменится. Для браузеров, которые не поддерживают директивуimmutable
,max-age
добавляется директива .- Даже если ресурс не отпечаток, содержимое
ETags
создается для каждого статического ресурса с помощью хэша отпечатков пальцев файла в качествеETag
значения. Это гарантирует, что браузер загружает только файл, если его содержимое изменяется (или файл загружается в первый раз). - Внутренне сопоставляет Blazor физические ресурсы с отпечатками пальцев, что позволяет приложению:
- Найдите автоматически созданные Blazor ресурсы, такие как Razor компонентная область CSS для Blazorфункции изоляции CSS и JS ресурсы, описанные JS в картах импорта.
- Создайте теги ссылок в
<head>
содержимом страницы для предварительной загрузки ресурсов.
- Даже если ресурс не отпечаток, содержимое
- Во время тестирования разработки Горячая перезагрузка Visual Studio:
- Сведения о целостности удаляются из ресурсов, чтобы избежать проблем при изменении файла во время работы приложения.
- Статические ресурсы не кэшируются, чтобы браузер всегда извлекает текущее содержимое.
Если включены режимы интерактивного веб-просмотра или интерактивного автоматического отрисовки:
- Blazor создает конечную точку для предоставления коллекции ресурсов в виде JS модуля.
- URL-адрес выводится в текст запроса в виде сохраняемого состояния компонента, когда компонент WebAssembly отображается на странице.
- Во время загрузки Blazor WebAssembly извлекает URL-адрес, импортирует модуль и вызывает функцию, чтобы получить коллекцию активов и восстановить ее в памяти. URL-адрес зависит от содержимого и кэшируется навсегда, поэтому эти затраты оплачиваются только один раз на пользователя, пока приложение не будет обновлено.
- Коллекция ресурсов также предоставляется по URL-адресу, доступному для чтения человеком,
_framework/resource-collection.js
поэтому JS имеет доступ к коллекции ресурсов для расширенной навигации или реализации функций других платформ и сторонних компонентов.
Статические ресурсы карты не предоставляют функции для минификации или других преобразований файлов. Minification обычно обрабатывается пользовательским кодом или сторонними инструментами.
По промежуточному слоям статических файлов () полезно в следующих ситуациях, которые не могут обрабатывать статические ресурсы (UseStaticFilesMapStaticAssets).
- Применение префикса пути к Blazor WebAssembly статическим файлам активов, который рассматривается в разделе префикса ресурсовBlazor WebAssembly.
- Настройка сопоставлений файлов расширений с определенными типами контента и настройка параметров статических файлов, которые рассматриваются в разделе "Сопоставления файлов" и "Статические параметры файла".
Подробные сведения см. в статье Статические файлы в ASP.NET Core.
Доставка ресурсов с помощью соглашений о маршрутизации статических ресурсов карты
Этот раздел относится к приложениям на стороне Blazor сервера.
Ресурсы передаются через ComponentBase.Assets свойство, которое разрешает отпечатанный URL-адрес для данного ресурса. В следующем примере Начальная загрузка, Blazor таблица стилей шаблона проекта (app.css
) и таблица стилей изоляции CSS (на основе пространства BlazorSample
имен приложения) связаны в корневом компоненте, как правило App
, компонент (Components/App.razor
):
<link rel="stylesheet" href="@Assets["bootstrap/bootstrap.min.css"]" />
<link rel="stylesheet" href="@Assets["app.css"]" />
<link rel="stylesheet" href="@Assets["BlazorSample.styles.css"]" />
Импорт карт
Этот раздел относится к приложениям на стороне Blazor сервера.
Компонент "Карта импорта" (ImportMap) представляет элемент карты импорта (<script type="importmap"></script>
), который определяет карту импорта для скриптов модулей. Компонент "Карта импорта" помещается в <head>
содержимое корневого компонента, как правило App
, компонент (Components/App.razor
).
<ImportMap />
Если пользователь ImportMapDefinition не назначен компоненту "Карта импорта", карта импорта создается на основе ресурсов приложения.
В следующих примерах показаны пользовательские определения карты импорта и создаваемые ими карты импорта.
Базовая карта импорта:
new ImportMapDefinition(
new Dictionary<string, string>
{
{ "jquery", "https://cdn.example.com/jquery.js" },
},
null,
null);
Предыдущий код приводит к следующему сопоставлению импорта:
{
"imports": {
"jquery": "https://cdn.example.com/jquery.js"
}
}
Карта импорта с областью действия:
new ImportMapDefinition(
null,
new Dictionary<string, IReadOnlyDictionary<string, string>>
{
["/scoped/"] = new Dictionary<string, string>
{
{ "jquery", "https://cdn.example.com/jquery.js" },
}
},
null);
Предыдущий код приводит к следующему сопоставлению импорта:
{
"scopes": {
"/scoped/": {
"jquery": "https://cdn.example.com/jquery.js"
}
}
}
Импорт карты с целостностью:
new ImportMapDefinition(
new Dictionary<string, string>
{
{ "jquery", "https://cdn.example.com/jquery.js" },
},
null,
new Dictionary<string, string>
{
{ "https://cdn.example.com/jquery.js", "sha384-abc123" },
});
Предыдущий код приводит к следующему сопоставлению импорта:
{
"imports": {
"jquery": "https://cdn.example.com/jquery.js"
},
"integrity": {
"https://cdn.example.com/jquery.js": "sha384-abc123"
}
}
Объединение определений карты импорта (ImportMapDefinition) с ImportMapDefinition.Combine.
Импорт карты, созданной ResourceAssetCollection из статического ресурса, с соответствующими уникальными URL-адресами:
ImportMapDefinition.FromResourceCollection(
new ResourceAssetCollection(
[
new ResourceAsset(
"jquery.fingerprint.js",
[
new ResourceAssetProperty("integrity", "sha384-abc123"),
new ResourceAssetProperty("label", "jquery.js"),
])
]));
Предыдущий код приводит к следующему сопоставлению импорта:
{
"imports": {
"./jquery.js": "./jquery.fingerprint.js"
},
"integrity": {
"jquery.fingerprint.js": "sha384-abc123"
}
}
Настройте ПО промежуточного слоя статических файлов для предоставления статических ресурсов клиентам, вызвав UseStaticFiles в конвейере обработки запросов приложения. Подробные сведения см. в статье Статические файлы в ASP.NET Core.
В выпусках до .NET 8 статические файлы платформы, Blazor такие как Blazor скрипт, обслуживаются через ПО промежуточного слоя статических файлов. В .NET 8 или более поздней версии Blazor статические файлы платформы сопоставляются с использованием маршрутизации конечных точек, а ПО промежуточного слоя статических файлов больше не используется.
Сводка по статическим форматам файлов <link>
href
Этот раздел относится ко всем выпускам и Blazor приложениям .NET.
В следующих таблицах перечислены форматы статических файлов <link>
href
по выпуску .NET.
Расположение содержимого, в котором размещаются статические <head>
ссылки на файл, см. в разделе ASP.NET структура проекта CoreBlazor. Ссылки на статические ресурсы также можно предоставлять с помощью <HeadContent>
компонентов в отдельных Razor компонентах.
Расположение содержимого, в котором размещаются статические <head>
ссылки на файл, см. в разделе ASP.NET структура проекта CoreBlazor.
.NET 9 или более поздней версии
Тип приложения | Значение href |
Примеры |
---|---|---|
Blazor Web App | @Assets["{PATH}"] |
<link rel="stylesheet" href="@Assets["app.css"]" /> <link href="@Assets["_content/ComponentLib/styles.css"]" rel="stylesheet" /> |
Blazor Server† | @Assets["{PATH}"] |
<link href="@Assets["css/site.css"]" rel="stylesheet" /> <link href="@Assets["_content/ComponentLib/styles.css"]" rel="stylesheet" /> |
Автономный Blazor WebAssembly | {PATH} |
<link rel="stylesheet" href="css/app.css" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" /> |
.NET 8.x
Тип приложения | Значение href |
Примеры |
---|---|---|
Blazor Web App | {PATH} |
<link rel="stylesheet" href="app.css" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" /> |
Blazor Server† | {PATH} |
<link href="css/site.css" rel="stylesheet" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" /> |
Автономный Blazor WebAssembly | {PATH} |
<link rel="stylesheet" href="css/app.css" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" /> |
.NET 7.x или более ранние версии
Тип приложения | Значение href |
Примеры |
---|---|---|
Blazor Server† | {PATH} |
<link href="css/site.css" rel="stylesheet" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" /> |
Размещено Blazor WebAssembly: | {PATH} |
<link href="css/app.css" rel="stylesheet" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" /> |
Blazor WebAssembly | {PATH} |
<link href="css/app.css" rel="stylesheet" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" /> |
Blazor Server† поддерживается в .NET 8 или более поздней версии, но больше не является шаблоном проекта после .NET 7.
При внедрении .NET 8 или более поздней версии рекомендуется обновлять размещенные Blazor WebAssembly приложения Blazor Web App.
Режим проекта статического веб-ресурса
Этот раздел относится к .Client
проекту объекта Blazor Web App.
Обязательный <StaticWebAssetProjectMode>Default</StaticWebAssetProjectMode>
параметр в .Client
проекте Blazor Web App отменяет Blazor WebAssembly поведение статических активов обратно в значения по умолчанию, чтобы проект работал в рамках размещенного проекта. Пакет Blazor WebAssembly SDK (Microsoft.NET.Sdk.BlazorWebAssembly
) настраивает статические веб-ресурсы определенным способом для работы в автономном режиме с сервером, просто используюющим выходные данные из библиотеки. Это не подходит для Blazor Web Appприложения, где часть WebAssembly приложения является логической частью узла и должна вести себя больше как библиотека. Например, проект не предоставляет пакет стилей (например, BlazorSample.Client.styles.css
) и вместо этого предоставляет узел пакету проектов, чтобы узел может включить его в собственный пакет стилей.
Изменение значения (Default
) <StaticWebAssetProjectMode>
или удаление свойства из .Client
проекта не поддерживается.
Статические файлы в средах,Development
отличных от среды
Этот раздел относится к статическим файлам на стороне сервера.
При локальном запуске приложения статические веб-ресурсы включены только в Development среде. Чтобы включить статические файлы для сред, отличных от Development локальной разработки и тестирования (например, Staging), вызовите UseStaticWebAssets WebApplicationBuilder его в Program
файле.
Предупреждение
Вызовите UseStaticWebAssets для конкретного окружения, чтобы предотвратить активацию компонента в рабочей среде, так как он обслуживает файлы из отдельных расположений на диске, отличном от диска проекта, если он вызывается в рабочей среде. В примере в этом разделе проверяется наличие Staging окружения путем вызова IsStaging.
if (builder.Environment.IsStaging())
{
builder.WebHost.UseStaticWebAssets();
}
Префикс для Blazor WebAssembly ресурсов
Этот раздел относится к Blazor Web Apps.
Используйте параметр конечной WebAssemblyComponentsEndpointOptions.PathPrefix точки, чтобы задать строку пути, указывающую префикс для Blazor WebAssembly ресурсов. Путь должен соответствовать проекту приложения, на который Blazor WebAssembly ссылается ссылка.
endpoints.MapRazorComponents<App>()
.AddInteractiveWebAssemblyRenderMode(options =>
options.PathPrefix = "{PATH PREFIX}");
В предыдущем примере {PATH PREFIX}
заполнитель является префиксом пути и должен начинаться с косой черты (/
).
В следующем примере префикс пути имеет значение /path-prefix
:
endpoints.MapRazorComponents<App>()
.AddInteractiveWebAssemblyRenderMode(options =>
options.PathPrefix = "/path-prefix");
Базовый путь к статическому веб-ресурсу
Этот раздел относится к автономным Blazor WebAssembly приложениям.
Публикация приложения помещает статические ресурсы приложения, включая Blazor файлы платформы (_framework
ресурсы папок), в корневой путь (/
) в опубликованных выходных данных. Свойство <StaticWebAssetBasePath>
, указанное в файле проекта (.csproj
), задает базовый путь к некорневому пути:
<PropertyGroup>
<StaticWebAssetBasePath>{PATH}</StaticWebAssetBasePath>
</PropertyGroup>
В предыдущем примере заполнитель {PATH}
— это путь.
Без задания <StaticWebAssetBasePath>
свойства автономное приложение публикуется по адресу /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/
.
В предыдущем примере заполнитель — это Moniker (например, {TFM}
TFM). net6.0
<StaticWebAssetBasePath>
Если свойство в автономном Blazor WebAssembly приложении задает путь к опубликованному статичному ресурсу, корневой путь app1
к приложению в опубликованных выходных данных./app1
В файле проекта автономного Blazor WebAssembly приложения (.csproj
):
<PropertyGroup>
<StaticWebAssetBasePath>app1</StaticWebAssetBasePath>
</PropertyGroup>
В опубликованных выходных данных путь к автономному Blazor WebAssembly приложению имеет значение /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/
.
В предыдущем примере заполнитель — это Moniker (например, {TFM}
TFM). net6.0
Этот раздел относится к изолированным приложениям Blazor WebAssembly и размещенным решениям Blazor WebAssembly.
Публикация приложения помещает статические ресурсы приложения, включая Blazor файлы платформы (_framework
ресурсы папок), в корневой путь (/
) в опубликованных выходных данных. Свойство <StaticWebAssetBasePath>
, указанное в файле проекта (.csproj
), задает базовый путь к некорневому пути:
<PropertyGroup>
<StaticWebAssetBasePath>{PATH}</StaticWebAssetBasePath>
</PropertyGroup>
В предыдущем примере заполнитель {PATH}
— это путь.
Без задания свойства <StaticWebAssetBasePath>
клиентское приложение размещенного решения или изолированного приложения публикуется по следующим путям:
- В проекте Server размещенного решения Blazor WebAssembly:
/BlazorHostedSample/Server/bin/Release/{TFM}/publish/wwwroot/
- В изолированном приложении Blazor WebAssembly:
/BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/
Если свойство <StaticWebAssetBasePath>
в проекте Client размещенного приложения Blazor WebAssembly или в изолированном приложении Blazor WebAssembly задает в качестве пути опубликованного статического ресурса значение app1
, корневой путь к приложению в опубликованных выходных данных будет иметь значение /app1
.
В файле проекта приложения Client (.csproj
) или в файле проекта изолированного приложения Blazor WebAssembly (.csproj
):
<PropertyGroup>
<StaticWebAssetBasePath>app1</StaticWebAssetBasePath>
</PropertyGroup>
В опубликованных выходных данных:
- Путь к клиентскому приложению в проекте Server размещенного решения Blazor WebAssembly:
/BlazorHostedSample/Server/bin/Release/{TFM}/publish/wwwroot/app1/
- Путь к изолированному приложению Blazor WebAssembly:
/BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/
Свойство <StaticWebAssetBasePath>
чаще всего используется для управления путями к опубликованным статическим ресурсам нескольких приложений Blazor WebAssembly в одном размещенном развертывании. Дополнительные сведения см. в статье Несколько размещенных приложений Blazor WebAssembly ASP.NET Core. Свойство также применяется в изолированных приложениях Blazor WebAssembly.
В предыдущих примерах заполнитель является {TFM}
моникером целевой платформы (TFM) (например, net6.0
).
Сопоставления файлов и статические параметры файлов
Этот раздел относится к статическим файлам на стороне сервера.
Чтобы создать дополнительные сопоставления файлов с помощью FileExtensionContentTypeProvider или настроить другие StaticFileOptions, используйте один из следующих способов. В следующих примерах заполнитель {EXTENSION}
является расширением файла, а заполнитель {CONTENT TYPE}
— типом содержимого. Пространство имен для следующего API.Microsoft.AspNetCore.StaticFiles
Настройка параметров с помощью внедрения зависимостей (DI) в
Program
файле с помощью StaticFileOptions:var provider = new FileExtensionContentTypeProvider(); provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}"; builder.Services.Configure<StaticFileOptions>(options => { options.ContentTypeProvider = provider; }); app.UseStaticFiles();
StaticFileOptions Передайте непосредственно в
Program
файл:UseStaticFilesvar provider = new FileExtensionContentTypeProvider(); provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}"; app.UseStaticFiles(new StaticFileOptions { ContentTypeProvider = provider });
Чтобы создать дополнительные сопоставления файлов с помощью FileExtensionContentTypeProvider или настроить другие StaticFileOptions, используйте один из следующих способов. В следующих примерах заполнитель {EXTENSION}
является расширением файла, а заполнитель {CONTENT TYPE}
— типом содержимого.
Настройка параметров с помощью внедрения зависимостей (DI) в
Program
файле с помощью StaticFileOptions:using Microsoft.AspNetCore.StaticFiles; ... var provider = new FileExtensionContentTypeProvider(); provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}"; builder.Services.Configure<StaticFileOptions>(options => { options.ContentTypeProvider = provider; });
Этот подход настраивает тот же поставщик файлов, который использовался для обслуживания скрипта Blazor . Убедитесь, что настраиваемая конфигурация не вмешивается в обслуживание скрипта Blazor . Например, не удаляйте сопоставление для файлов JavaScript, настраивая поставщик с помощью
provider.Mappings.Remove(".js")
.Используйте два вызова UseStaticFiles в
Program
файле:- Настройте пользовательский поставщик файлов при первом вызове с помощью StaticFileOptions.
- Второе ПО промежуточного слоя служит Blazor скрипту, который использует конфигурацию статических файлов по умолчанию, предоставляемую Blazor платформой.
using Microsoft.AspNetCore.StaticFiles; ... var provider = new FileExtensionContentTypeProvider(); provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}"; app.UseStaticFiles(new StaticFileOptions { ContentTypeProvider = provider }); app.UseStaticFiles();
Чтобы избежать конфликтов при обслуживании
_framework/blazor.server.js
, можете использовать MapWhen для выполнения пользовательского ПО промежуточного слоя для статических файлов.app.MapWhen(ctx => !ctx.Request.Path .StartsWithSegments("/_framework/blazor.server.js"), subApp => subApp.UseStaticFiles(new StaticFileOptions() { ... }));
Предоставление файлов из нескольких расположений
Инструкции, приведенные в этом разделе, применяются только к Blazor Web Apps.
Для обслуживания файлов из нескольких расположений с помощью CompositeFileProvider:
- Добавьте пространство имен в Microsoft.Extensions.FileProviders начало
Program
файла проекта сервера. - В файле проекта
Program
сервера перед вызовомUseStaticFiles:- PhysicalFileProvider Создайте путь к статическим ресурсам.
- Создайте объект CompositeFileProvider из WebRootFileProvider и .PhysicalFileProvider Назначьте составной поставщик файлов обратно приложению WebRootFileProvider.
Пример:
Создайте новую папку в серверном проекте с именем AdditionalStaticAssets
. Поместите изображение в папку.
Добавьте следующую using
инструкцию в начало файла проекта Program
сервера:
using Microsoft.Extensions.FileProviders;
Добавьте следующий код в файл проекта Program
сервера перед вызовомUseStaticFiles:
var secondaryProvider = new PhysicalFileProvider(
Path.Combine(builder.Environment.ContentRootPath, "AdditionalStaticAssets"));
app.Environment.WebRootFileProvider = new CompositeFileProvider(
app.Environment.WebRootFileProvider, secondaryProvider);
В разметке компонентаHome.razor
приложения Home
() сослаться на изображение с тегом<img>
:
<img src="{IMAGE FILE NAME}" alt="{ALT TEXT}" />
В предыдущем примере:
- Заполнитель
{IMAGE FILE NAME}
— это имя файла изображения. Нет необходимости предоставлять сегмент пути, если файл изображения находится в корнеAdditionalStaticAssets
папки. - Заполнитель
{ALT TEXT}
— это замещающий текст изображения.
Выполнить приложение.
Дополнительные ресурсы
ASP.NET Core