Поделиться через


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

Сопоставление статических ресурсов работает путем объединения процессов сборки и публикации для сбора сведений о статических ресурсах в приложении. Эта информация используется библиотекой среды выполнения для эффективного обслуживания статических ресурсов браузерам.

Сопоставление статических ресурсов может заменить 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).

Подробные сведения см. в статье Статические файлы в 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 статические файлы платформы сопоставляются с использованием маршрутизации конечных точек, а ПО промежуточного слоя статических файлов больше не используется.

Этот раздел относится ко всем выпускам и 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 файл:UseStaticFiles

    var 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:

Пример:

Создайте новую папку в серверном проекте с именем 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} — это замещающий текст изображения.

Выполнить приложение.

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