Статические файлы Blazor в ASP.NET Core

Мақала
07/17/2024

Примечание.

Это не последняя версия этой статьи. В текущем выпуске см . версию .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 предоставляет следующие преимущества, которые недоступны при вызове 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 Веб-приложение	`@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 Веб-приложение	`{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.
"Рекомендуется обновить размещенные Blazor WebAssembly приложения до Blazor веб-приложения при внедрении .NET 8 или более поздней версии.

Режим проекта статического веб-ресурса

Этот раздел относится к .Client проекту Blazor веб-приложения.

Обязательный <StaticWebAssetProjectMode>Default</StaticWebAssetProjectMode> параметр в .Client проекте Blazor веб-приложения возвращает Blazor WebAssembly поведение статических ресурсов обратно к значениям по умолчанию, чтобы проект работал в рамках размещенного проекта. Пакет Blazor WebAssembly SDK (Microsoft.NET.Sdk.BlazorWebAssembly) настраивает статические веб-ресурсы определенным способом для работы в автономном режиме с сервером, просто используюющим выходные данные из библиотеки. Это не подходит для Blazor веб-приложения, где часть webAssembly приложения является логической частью узла и должна вести себя больше как библиотека. Например, проект не предоставляет пакет стилей (например, BlazorSample.Client.styles.css) и вместо этого предоставляет узел пакету проектов, чтобы узел может включить его в собственный пакет стилей.

Изменение значения (Default) или удаление свойства из .Client проекта не поддерживается.<StaticWebAssetProjectMode>

Статические файлы в средах,`Development` отличных от среды

Этот раздел относится к статическим файлам на стороне сервера.

При локальном запуске приложения статические веб-ресурсы включены только по умолчанию в Development среде. Чтобы включить статические файлы для сред, отличных от Development локальной разработки и тестирования (например, Staging), вызовите UseStaticWebAssets WebApplicationBuilder его в Program файле.

Предупреждение

Вызовите UseStaticWebAssets для конкретного окружения, чтобы предотвратить активацию компонента в рабочей среде, так как он обслуживает файлы из отдельных расположений на диске, отличном от диска проекта, если он вызывается в рабочей среде. В примере в этом разделе проверяется наличие Staging окружения путем вызова IsStaging.

if (builder.Environment.IsStaging())
{
    builder.WebHost.UseStaticWebAssets();
}

Префикс для Blazor WebAssembly ресурсов

Этот раздел относится к Blazor веб-приложения.

Используйте параметр конечной 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.

<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 файл:UseStaticFiles

var provider = new FileExtensionContentTypeProvider();
provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";

app.UseStaticFiles(new StaticFileOptions { ContentTypeProvider = provider });

Настройка параметров с помощью внедрения зависимостей (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 в ASP.NET Core

ПО промежуточного слоя статических ресурсов

Использование ресурсов со по промежуточному слоям статических файлов карты

Импорт карт

Сводка по статическим форматам файлов `<link>` `href`

Режим проекта статического веб-ресурса

Статические файлы в средах,`Development` отличных от среды

Префикс для Blazor WebAssembly ресурсов

Базовый путь к статическому веб-ресурсу

Сопоставления файлов и статические параметры файлов

Дополнительные ресурсы

Кері байланыс

Қосымша ресурстар

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

Статические файлы Blazor в ASP.NET Core

ПО промежуточного слоя статических ресурсов

Использование ресурсов со по промежуточному слоям статических файлов карты

Импорт карт

Сводка по статическим форматам файлов <link> href

Режим проекта статического веб-ресурса

Статические файлы в средах,Development отличных от среды

Префикс для Blazor WebAssembly ресурсов

Базовый путь к статическому веб-ресурсу

Сопоставления файлов и статические параметры файлов

Дополнительные ресурсы

Кері байланыс

Қосымша ресурстар

Сводка по статическим форматам файлов `<link>` `href`

Статические файлы в средах,`Development` отличных от среды