Статические файлы Blazor в ASP.NET Core
Примечание.
Это не последняя версия этой статьи. В текущем выпуске см . версию .NET 8 этой статьи.
Предупреждение
Эта версия ASP.NET Core больше не поддерживается. Дополнительные сведения см. в статье о политике поддержки .NET и .NET Core. В текущем выпуске см . версию .NET 8 этой статьи.
Внимание
Эта информация относится к предварительному выпуску продукта, который может быть существенно изменен до его коммерческого выпуска. Майкрософт не предоставляет никаких гарантий, явных или подразумеваемых, относительно приведенных здесь сведений.
В текущем выпуске см . версию .NET 8 этой статьи.
В этой статье описывается Blazor конфигурация приложения для обслуживания статических файлов.
ПО промежуточного слоя статических ресурсов
Этот раздел относится к приложениям на стороне Blazor сервера.
Обслуживание статических ресурсов управляется двумя по промежуточному слоям, описанными в следующей таблице.
ПО промежуточного слоя | API | Версия .NET | Description |
---|---|---|---|
Сопоставление статических ресурсов | MapStaticAssets |
.NET 9 или более поздней версии | Оптимизирует доставку статических ресурсов клиентам. |
Static Files | UseStaticFiles | Все версии .NET | Служит статическим ресурсам клиентам без оптимизации MapStaticAssets , но полезной для некоторых задач, которые MapStaticAssets не могут управлять. |
Настройте ПО промежуточного слоя статических ресурсов карты, вызвав MapStaticAssets
в конвейере обработки запросов приложения следующее:
- Задает заголовки ETag и Last-Modified.
- Задает заголовки кэширования.
- Использует по промежуточному слоям кэширования.
- По возможности обслуживает сжатые статические ресурсы.
- Работает с сеть доставки содержимого (CDN) (например, Azure CDN) для обслуживания статических ресурсов приложения ближе к пользователю.
- Отпечаток ресурсов для предотвращения повторного использования старых версий файлов.
MapStaticAssets
работает путем объединения процессов сборки и публикации для сбора сведений о статических ресурсах в приложении. Эта информация используется библиотекой среды выполнения для эффективного обслуживания статических ресурсов браузерам.
MapStaticAssets
может заменить UseStaticFiles в большинстве ситуаций. MapStaticAssets
Однако оптимизировано для обслуживания ресурсов из известных расположений в приложении во время сборки и публикации. Если приложение обслуживает ресурсы из других расположений, таких как диск или внедренные ресурсы, UseStaticFiles следует использовать.
MapStaticAssets
заменяет вызовы UseBlazorFrameworkFiles UseBlazorFrameworkFiles в приложениях, обслуживающих Blazor WebAssembly файлы платформы, и явно вызывается в нейBlazor Web App, так как API автоматически вызывается при вызовеAddInteractiveWebAssemblyComponents.
MapStaticAssets
предоставляет следующие преимущества, которые недоступны при вызове 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 обычно обрабатывается пользовательским кодом или сторонними инструментами.
По промежуточному слоям статических файлов (UseStaticFiles) полезно в следующих ситуациях, которые MapStaticAssets
не могут обрабатываться:
- Применение префикса пути к Blazor WebAssembly статическим файлам активов, который рассматривается в разделе префикса ресурсовBlazor WebAssembly.
- Настройка сопоставлений файлов расширений с определенными типами контента и настройка параметров статических файлов, которые рассматриваются в разделе "Сопоставления файлов" и "Статические параметры файла".
Использование ресурсов со по промежуточному слоям статических файлов карты
Этот раздел относится к приложениям на стороне Blazor сервера.
Ресурсы используются через ComponentBase.Assets
свойство, которое разрешает отпечатанный URL-адрес для данного ресурса. В следующем примере Начальная загрузка, Blazor таблица стилей приложения шаблона проекта (app.css
) и таблица стилей изоляции CSS связаны в корневом компоненте, как правило 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["BlazorWeb-CSharp.styles.css"]" />
Импорт карт
Этот раздел относится к приложениям на стороне Blazor сервера.
Компонент ImportMap
представляет элемент карты импорта (<script type="importmap"></script>
), который определяет карту импорта для скриптов модулей. Компонент ImportMap
помещается в <head>
содержимое корневого компонента, как правило App
, компонент (Components/App.razor
).
<ImportMap />
Если пользователь ImportMapDefinition
не назначен компоненту ImportMap
, карта импорта создается на основе ресурсов приложения.
В следующих примерах показаны пользовательские определения карты импорта и создаваемые ими карты импорта.
Базовая карта импорта:
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