Sdílet prostřednictvím

ASP.NET Core Blazor statické soubory

Poznámka:

Toto není nejnovější verze tohoto článku. Aktuální verzi najdete ve verzi .NET 10 tohoto článku.

Varování

Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v zásadách podpory .NET a .NET Core. Pokud hledáte aktuální vydání, podívejte se na článek ve verzi .NET 9.

Tento článek popisuje Blazor konfiguraci aplikace pro obsluhu statických souborů.

Obecné informace o obsluze statických souborů prostřednictvím konvencí směrování koncových bodů pro statické prostředky najdete v tématu Statické soubory v ASP.NET Core před přečtením tohoto článku.

Statické prostředky rámce předem načtené Blazor

V Blazor Web Appsystému s jsou statické prostředky architektury automaticky předem načteny pomocíLink hlaviček, což umožňuje prohlížeči předem načíst prostředky před načtením a vykreslení počáteční stránky.

V samostatných Blazor WebAssembly aplikacích jsou prostředky rámce naplánovány pro stahování s vysokou prioritou a ukládání do mezipaměti na začátku zpracování stránky v prohlížeči index.html, když:

  • Vlastnost OverrideHtmlAssetPlaceholders MSBuild v souboru projektu aplikace (.csproj) je nastavena na true:

    <PropertyGroup>
  <OverrideHtmlAssetPlaceholders>true</OverrideHtmlAssetPlaceholders>
</PropertyGroup>

  • <link> Následující prvek, který obsahujerel="preload", je přítomn v <head> obsahu wwwroot/index.html:

    <link rel="preload" id="webassembly" />

Statická distribuce prostředků v aplikacích na straně Blazor serveru

Obsluha statických prostředků je řízena buď pomocí konvencí pro směrovací koncové body, nebo middlewaru, jak je popsáno v následující tabulce.

Funkce API Verze .NET Popis
Mapování konvencí pro směrování statických zdrojů řídicího bodu MapStaticAssets .NET 9 nebo novější Optimalizuje doručování statických assetů uživatelům.
Middleware statického souboru UseStaticFiles Všechny verze .NET Poskytuje statické prostředky klientům bez optimalizace mapování statických prostředků, ale je užitečné pro některé úlohy, které Map Static Assets nedokáže spravovat.

Map Static Assets může ve většině situací nahradit UseStaticFiles. Map Static Assets jsou však optimalizované pro obsluhu aktiv ze známých umístění v aplikaci, a to při sestavení a publikování. Pokud aplikace obsluhuje soubory z jiných umístění, jako jsou disky nebo vložené prostředky, UseStaticFiles by se mělo použít.

Mapování statických prostředků (MapStaticAssets) také nahrazuje volání UseBlazorFrameworkFiles v aplikacích, které obsluhují Blazor WebAssembly soubory frameworku, a explicitní volání UseBlazorFrameworkFiles v Blazor Web App není nutné, protože rozhraní API se při vyvolání AddInteractiveWebAssemblyComponents automaticky volá.

Pokud jsou povoleny režimy Interaktivní webAssembly nebo Interaktivní automatické vykreslování:

  • Blazor vytvoří koncový bod pro zveřejnění kolekce prostředků jako modul JS.
  • Adresa URL se odesílá do těla požadavku jako přetrvávající stav komponenty při vykreslení komponenty WebAssembly na stránku.
  • Během spouštění WebAssembly Blazor načte adresu URL, naimportuje modul a zavolá funkci, která načte kolekci prostředků a rekonstruuje ji v paměti. Adresa URL je specifická pro obsah a uložená navždy v mezipaměti, takže tyto režijní náklady se platí jenom jednou za uživatele, dokud se aplikace neaktualizuje.
  • Kolekce prostředků je také zpřístupněna na adrese URL pro čtení člověka (_framework/resource-collection.js), takže JS má přístup k kolekci prostředků pro vylepšenou navigaci nebo k implementaci funkcí jiných architektur a komponent třetích stran.

Middleware statického souboru (UseStaticFiles) je užitečná v následujících situacích, které mapování statických prostředků (MapStaticAssets) nedokáže řešit:

Další informace najdete v tématu Statické soubory v ASP.NET Core.

Doručování assetů pomocí konvencí koncového bodu pro směrování statických assetů mapy

Tato část se týká aplikací na straně Blazor serveru.

Prostředky se doručují prostřednictvím ComponentBase.Assets vlastnosti, která vyřeší URL adresu s otiskem prstu pro daný prostředek. V následujícím příkladu jsou Bootstrap, Blazor šablona stylů aplikace projektu (app.css) a izolační šablona stylů CSS (která vychází z oboru názvů aplikace BlazorSample) propojeny v kořenové komponentě, obvykle komponentě 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"]" />

ImportMap součást

Tato část se vztahuje na Blazor Web App, které volají MapRazorComponents.

Komponenta ImportMap (ImportMap) představuje element mapování importu (<script type="importmap"></script>), který definuje mapování importu pro skripty modulu. Součást Import Map je umístěna v <head> obsahu kořenové komponenty, obvykle komponenta App (Components/App.razor).

<ImportMap />

Pokud není vlastní ImportMapDefinition přiřazen komponentě Mapování importu, mapa importu se vygeneruje na základě prostředků aplikace.

Poznámka:

ImportMapDefinition Vytváření instancí je nákladné, proto doporučujeme jejich uložení do mezipaměti při vytváření další instance.

Následující příklady ukazují vlastní definice import map a import mapy, které vytvoří.

Základní mapování importu:

new ImportMapDefinition(
    new Dictionary<string, string>
    {
        { "jquery", "https://cdn.example.com/jquery.js" },
    },
    null,
    null);

Předchozí kód má za následek následující mapování importu:

{
  "imports": {
    "jquery": "https://cdn.example.com/jquery.js"
  }
}

Mapa importu s vymezeným rozsahem:

new ImportMapDefinition(
    null,
    new Dictionary<string, IReadOnlyDictionary<string, string>>
    {
        ["/scoped/"] = new Dictionary<string, string>
        {
            { "jquery", "https://cdn.example.com/jquery.js" },
        }
    },
    null);

Předchozí kód má za následek následující mapování importu:

{
  "scopes": {
    "/scoped/": {
      "jquery": "https://cdn.example.com/jquery.js"
    }
  }
}

Import mapy s integritou:

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" },
    });

Předchozí kód má za následek následující mapování importu:

{
  "imports": {
    "jquery": "https://cdn.example.com/jquery.js"
  },
  "integrity": {
    "https://cdn.example.com/jquery.js": "sha384-abc123"
  }
}

Zkombinujte definice mapování importu (ImportMapDefinition) s ImportMapDefinition.Combine.

Mapa importu vytvořená z ResourceAssetCollection, která mapuje statické prostředky na jejich odpovídající jedinečné adresy URL:

ImportMapDefinition.FromResourceCollection(
    new ResourceAssetCollection(
    [
        new ResourceAsset(
            "jquery.fingerprint.js",
            [
                new ResourceAssetProperty("integrity", "sha384-abc123"),
                new ResourceAssetProperty("label", "jquery.js"),
            ])
    ]));

Předchozí kód má za následek následující mapování importu:

{
  "imports": {
    "./jquery.js": "./jquery.fingerprint.js"
  },
  "integrity": {
    "jquery.fingerprint.js": "sha384-abc123"
  }
}

Porušení zásad zabezpečení obsahu (CSP) při importu mapy

Tato část se vztahuje na Blazor Web App, které volají MapRazorComponents.

Komponenta ImportMap je vykreslena jako vložená <script> značka, což porušuje přísné zásady zabezpečení obsahu (CSP), které nastavují direktivu default-src nebo script-src.

Pro příklady, jak vyřešit porušení zásad s Subresource Integrity (SRI) nebo kryptografickou nonce, se podívejte na Řešení porušení CSP s Subresource Integrity (SRI) nebo nonce.

Nakonfigurujte Middleware statických souborů, aby poskytoval klientům statické prostředky voláním UseStaticFiles v kanálu zpracování požadavků aplikace. Další informace najdete v tématu Statické soubory v ASP.NET Core.

Ve verzích před .NET 8 jsou statické soubory Blazor rozhraní, jako je skript Blazor, obsluhovány prostřednictvím middleware pro statické soubory. V .NET 8 nebo novějších se statické soubory rámce mapují pomocí směrování koncového bodu a middleware pro statické soubory se už nepoužívá.

Vytvoření otisků pro statická data na straně klienta v samostatných Blazor WebAssembly aplikacích

V samostatných Blazor WebAssembly aplikacích během sestavování a publikování přepíše framework zástupné symboly index.html s hodnotami vypočítanými během sestavování, aby vytvořil otisky prstů statických prostředků pro vykreslování na straně klienta. Otisk prstu se umisťuje do názvu souboru skriptu a pro ostatní prostředky .NET se vygeneruje mapa importu.

Aby bylo možné přijmout otisk prstu, musí se v wwwwoot/index.html souboru samostatné Blazor WebAssembly aplikace nacházet následující konfigurace:

<head>
    ...
    <script type="importmap"></script>
    ...
</head>

<body>
    ...
    <script src="_framework/blazor.webassembly#[.{fingerprint}].js"></script>
    ...
</body>

</html>

V souboru projektu (.csproj), vlastnost je nastavena <OverrideHtmlAssetPlaceholders> na true:

<PropertyGroup>
  <OverrideHtmlAssetPlaceholders>true</OverrideHtmlAssetPlaceholders>
</PropertyGroup>

Při řešení importů pro JavaScriptovou interoperabilitu používá prohlížeč mapu importů k řešení souborů s otisky.

Jakýkoli skript v index.html se značkou otisku prstu je otiskován rámcem. Například soubor skriptu pojmenovaný scripts.js ve složce aplikace wwwroot/js se otiskem prstu přidá #[.{fingerprint}] před příponu souboru (.js):

<script src="js/scripts#[.{fingerprint}].js"></script>

Přiřaďte statickým prostředkům na straně klienta jedinečné identifikátory ve Blazor Web Apps

Pro vykreslování na straně klienta (CSR) v režimech interaktivního automatického nebo interaktivního WebAssembly vykreslování je identifikace statických prostředků na straně serveru povolena přijetím konvencí koncových bodů směrování statických prostředků mapy, komponenty Blazor Web App a vlastnosti . Další informace najdete v tématu Statické soubory v ASP.NET Core.

Pokud chcete naotiskovat další moduly JavaScriptu pro CSR, použijte položku <StaticWebAssetFingerprintPattern> v souboru projektu aplikace (.csproj). V následujícím příkladu se přidá otisk prstu pro všechny soubory dodané .mjs vývojářem v aplikaci:

<ItemGroup>
  <StaticWebAssetFingerprintPattern Include="JSModule" Pattern="*.mjs" 
    Expression="#[.{fingerprint}]!" />
</ItemGroup>

Při řešení importů pro JavaScriptovou interoperabilitu používá prohlížeč mapu importů k řešení souborů s otisky.

Tato část platí pro všechny verze a Blazor aplikace .NET.

Následující tabulky shrnují statické formáty souborů <link>href podle verze .NET.

Umístění <head> obsahu, kde jsou umístěny statické odkazy na soubory, najdete v tématu ASP.NET Blazor Základní struktura projektu. Statické odkazy na prostředky lze také zadat pomocí komponent typu <HeadContent> v jednotlivých Razor komponentách.

Umístění <head> obsahu, kde jsou umístěny statické odkazy na soubory, najdete v tématu ASP.NET Blazor Základní struktura projektu.

.NET 9 nebo novější

Typ aplikace href hodnota Příklady
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" />
Samostatný Blazor WebAssembly {PATH} <link rel="stylesheet" href="css/app.css" />
<link href="_content/ComponentLib/styles.css" rel="stylesheet" />

.NET 8.x

Typ aplikace href hodnota Příklady
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" />
Samostatný Blazor WebAssembly {PATH} <link rel="stylesheet" href="css/app.css" />
<link href="_content/ComponentLib/styles.css" rel="stylesheet" />

.NET 7.x nebo starší

Typ aplikace href hodnota Příklady
Blazor Server† {PATH} <link href="css/site.css" rel="stylesheet" />
<link href="_content/ComponentLib/styles.css" rel="stylesheet" />
Hostované 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† se podporuje v .NET 8 nebo novějším, ale po .NET 7 už není šablona projektu.
Při použití .NET 8 nebo novější doporučujeme aktualizovat hostované Blazor WebAssembly aplikace na Blazor Web App.

Režim projektu statického webového assetu

Tato část se týká .Client projektu Blazor Web App.

Požadované <StaticWebAssetProjectMode>Default</StaticWebAssetProjectMode> nastavení v projektu .Client vrátí chování Blazor Web App statických prostředků Blazor WebAssembly na výchozí nastavení, aby se projekt choval jako součást hostovaného projektu. Sada Blazor WebAssembly SDK (Microsoft.NET.Sdk.BlazorWebAssembly) konfiguruje statické webové prostředky určitým způsobem tak, aby fungovala v samostatném režimu se serverem, který jednoduše využívá výstupy z knihovny. To není vhodné pro Blazor Web App, kde část WebAssembly v aplikaci je logická součást hostitele a musí se chovat podobně jako knihovna. Projekt například nezpřístupňuje sadu stylů (například BlazorSample.Client.styles.css) a místo toho poskytuje hostiteli pouze sadu projektů, aby ji hostitel mohl zahrnout do vlastní sady stylů.

Změna hodnoty (Default) <StaticWebAssetProjectMode> nebo odebrání vlastnosti z .Client projektu se nepodporuje.

Předpona pro Blazor WebAssembly aktiva

Tato část se vztahuje na Blazor Web Apps.

Pomocí možnosti koncového bodu WebAssemblyComponentsEndpointOptions.PathPrefix zadefinujte řetězec cesty, který označuje předponu prostředků Blazor WebAssembly. Cesta musí odpovídat odkazovanému Blazor WebAssembly projektu aplikace.

endpoints.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode(options => 
        options.PathPrefix = "{PATH PREFIX}");

V předchozím příkladu je zástupný symbol {PATH PREFIX} předponou cesty a musí začínat lomítkem (/).

V následujícím příkladu je předpona cesty nastavena na /path-prefix:

endpoints.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode(options => 
        options.PathPrefix = "/path-prefix");

Základní cesta pro statické webové prvky

Tato část se týká samostatných Blazor WebAssembly aplikací.

Publikování aplikace umístí statické prostředky aplikace, včetně Blazor souborů rámce (_framework složkových prostředků), na kořenovou cestu (/) v publikovaném výstupu. Vlastnost <StaticWebAssetBasePath> zadaná v souboru projektu (.csproj) nastaví základní cestu k jiné než kořenové cestě:

<PropertyGroup>
  <StaticWebAssetBasePath>{PATH}</StaticWebAssetBasePath>
</PropertyGroup>

V předchozím příkladu je {PATH} zástupným symbolem cesty.

Bez nastavení <StaticWebAssetBasePath> vlastnosti se publikuje samostatná aplikace na adrese /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/.

V předchozím příkladu {TFM} je zástupným symbolem Moniker cílové architektury (TFM).

<StaticWebAssetBasePath> Pokud vlastnost v samostatné aplikaci Blazor WebAssembly nastaví cestu k publikovanému statickému souboru na app1, kořenová cesta k aplikaci v publikované podobě je /app1.

V souboru projektu samostatné Blazor WebAssembly aplikace (.csproj):

<PropertyGroup>
  <StaticWebAssetBasePath>app1</StaticWebAssetBasePath>
</PropertyGroup>

V publikovaném výstupu je cesta k samostatné aplikaci Blazor WebAssembly/BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/.

V předchozím příkladu {TFM} je zástupným symbolem Moniker cílové architektury (TFM).

Tato část se týká samostatných Blazor WebAssembly aplikací a hostovaných Blazor WebAssembly řešení.

Publikování aplikace umístí statické prostředky aplikace, včetně Blazor souborů rámce (_framework složkových prostředků), na kořenovou cestu (/) v publikovaném výstupu. Vlastnost <StaticWebAssetBasePath> zadaná v souboru projektu (.csproj) nastaví základní cestu k jiné než kořenové cestě:

<PropertyGroup>
  <StaticWebAssetBasePath>{PATH}</StaticWebAssetBasePath>
</PropertyGroup>

V předchozím příkladu je {PATH} zástupným symbolem cesty.

Bez nastavení vlastnosti <StaticWebAssetBasePath> je klientská aplikace hostovaného řešení nebo samostatná aplikace publikována na následujících umístěních:

  • V projektu Server hostovaného řešení Blazor WebAssembly:/BlazorHostedSample/Server/bin/Release/{TFM}/publish/wwwroot/
  • V samostatné aplikaci Blazor WebAssembly: /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/

Pokud vlastnost v projektu hostované aplikace <StaticWebAssetBasePath> nebo v samostatné aplikaci Client nastaví publikovanou cestu k statickým prostředkům Blazor WebAssembly, kořenová cesta k aplikaci v publikovaném výstupu je Blazor WebAssembly.

Client V souboru projektu aplikace (.csproj) nebo v souboru projektu samostatné Blazor WebAssembly aplikace (.csproj):

<PropertyGroup>
  <StaticWebAssetBasePath>app1</StaticWebAssetBasePath>
</PropertyGroup>

V publikovaném výstupu:

  • Cesta k klientské aplikaci v Server projektu hostovaného Blazor WebAssembly řešení: /BlazorHostedSample/Server/bin/Release/{TFM}/publish/wwwroot/app1/
  • Cesta k samostatné Blazor WebAssembly aplikaci: /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/

Vlastnost <StaticWebAssetBasePath> se nejčastěji používá k řízení cest k publikovaným statickým prostředkům více Blazor WebAssembly aplikací v jednom hostovaném nasazení. Další informace najdete v tématu Blazor WebAssembly ASP.NET Core. Tato vlastnost je také efektivní v samostatných Blazor WebAssembly aplikacích.

V předchozích příkladech je {TFM} zástupným znakem Monikeru cílového rámce (TFM).

Mapování souborů a možnosti statického souboru

Tato část se týká statických souborů na straně serveru.

Pokud chcete vytvořit další mapování souborů s FileExtensionContentTypeProvider nebo nakonfigurovat jiné StaticFileOptions, použijte jeden z následujících přístupů. V následujících příkladech {EXTENSION} je zástupným symbolem přípona souboru a {CONTENT TYPE} zástupným symbolem je typ obsahu.

  • Konfigurace možností prostřednictvím injektáže závislostí (DI) v Program souboru pomocí StaticFileOptions:

    using Microsoft.AspNetCore.StaticFiles;

...

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

builder.Services.Configure<StaticFileOptions>(options =>
{
    options.ContentTypeProvider = provider;
});

    Tento přístup konfiguruje stejného zprostředkovatele souborů, který slouží ke zpracování Blazor skriptu. Ujistěte se, že vaše vlastní konfigurace neruší obsluhu Blazor skriptu. Například neodebíjejte mapování souborů JavaScriptu tím, že nakonfigurujete zprostředkovatele pomocí provider.Mappings.Remove(".js").

  • V souboru UseStaticFiles použijte dvě volání Program.

    • Nakonfigurujte vlastního zprostředkovatele souborů při prvním volání pomocí StaticFileOptions.
    • Druhý middleware obsluhuje Blazor skript, který používá výchozí konfiguraci statických souborů poskytovanou architekturou Blazor .
    using Microsoft.AspNetCore.StaticFiles;

...

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

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

  • Můžete se vyhnout narušení poskytování _framework/blazor.server.js při používání MapWhen k spuštění vlastního middleware pro statické soubory.

    app.MapWhen(ctx => !ctx.Request.Path
    .StartsWithSegments("/_framework/blazor.server.js"),
        subApp => subApp.UseStaticFiles(new StaticFileOptions() { ... }));

Obsluha souborů z více umístění

Pokyny v této části platí jenom pro Blazor Web Appy.

Obsluha souborů z více umístění pomocí CompositeFileProvider:

Příklad:

Vytvořte novou složku v projektu serveru s názvem AdditionalStaticAssets. Umístěte obrázek do složky.

Na začátek souboru projektu serveru using přidejte následující Program prohlášení:

using Microsoft.Extensions.FileProviders;

Do souboru projektu Program serveru před voláním UseStaticFilespřidejte následující kód:

var secondaryProvider = new PhysicalFileProvider(
    Path.Combine(builder.Environment.ContentRootPath, "AdditionalStaticAssets"));
app.Environment.WebRootFileProvider = new CompositeFileProvider(
    app.Environment.WebRootFileProvider, secondaryProvider);

Ve značce komponenty Home aplikace (Home.razor) odkazovat na obrázek s tagem <img>:

<img src="{IMAGE FILE NAME}" alt="{ALT TEXT}" />

V předchozím příkladu:

  • Zástupný {IMAGE FILE NAME} symbol je název souboru obrázku. Pokud je soubor obrázku v kořenové složce AdditionalStaticAssets , nemusíte zadávat segment cesty.
  • Zástupný symbol {ALT TEXT} je alternativní text obrázku.

Spustit aplikaci.

Další materiály

  • Last updated on