Číst v angličtině

Sdílet prostřednictvím

ASP.NET základních Blazor statických souborů

  • Článek

Poznámka

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

Upozornění

Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v zásadách podpory .NET a .NET Core. Aktuální verzi najdete v tomto článku ve verzi .NET 9.

Důležité

Tyto informace se týkají předběžného vydání produktu, který může být podstatně změněn před komerčním vydáním. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.

Aktuální verzi najdete v tomto článku ve verzi .NET 9.

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

Statické doručování prostředků v aplikacích na straně Blazor serveru

Obsluha statických prostředků se spravuje pomocí konvencí koncového bodu směrování nebo middlewaru popsaného v následující tabulce.

Funkce rozhraní API Verze .NET Popis
Mapování konvencí koncového bodu směrování statických prostředků MapStaticAssets .NET 9 nebo novější Optimalizuje doručování statických prostředků klientům.
Middleware statických souborů UseStaticFiles Všechny verze .NET Obsluhuje statické prostředky klientům bez optimalizace mapových statických prostředků, ale užitečné pro některé úlohy, které mapují statické prostředky, nejsou schopné spravovat.

Nakonfigurujte mapování statických prostředků voláním MapStaticAssets kanálu zpracování požadavků aplikace, který provádí následující:

Mapování statických prostředků funguje kombinací procesů sestavení a publikování za účelem shromáždění informací o statických prostředcích v aplikaci. Tyto informace využívá knihovna modulu runtime k efektivnímu poskytování statických prostředků do prohlížečů.

Mapování statických prostředků může ve většině situací nahradit UseStaticFiles . Statické prostředky mapy jsou však optimalizované pro obsluhu prostředků ze známých umístění v aplikaci v době sestavení a publikování. Pokud aplikace obsluhuje prostředky z jiných umístění, jako jsou disky nebo vložené prostředky, UseStaticFiles by se měly použít.

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

Mapové statické prostředky poskytují následující výhody, které nejsou při volání UseStaticFilesdostupné:

  • Komprese času sestavení pro všechny prostředky v aplikaci, včetně JavaScriptu (JS) a šablon stylů, ale s výjimkou prostředků obrázků a písem, které jsou už komprimované. Komprese Gzip (Content-Encoding: gz) se používá při vývoji. Při publikování se používá komprese Gzip s Brotli (Content-Encoding: br).
  • Otisk prstu pro všechny prostředky v době sestavení pomocí řetězce s kódováním Base64 hodnoty hash SHA-256 obsahu každého souboru. Tím se zabrání opakovanému použití staré verze souboru, i když je starý soubor uložen v mezipaměti. Otisky prstů jsou prostředky uloženy do mezipaměti pomocí immutable direktivy, což vede k tomu, že prohlížeč nikdy nebude požadovat prostředek znovu, dokud se nezmění. Pro prohlížeče, které direktivu immutable nepodporují, se přidá direktivamax-age.
    • I když prostředek není otiskem prstu, pro každý statický prostředek se vygeneruje obsah ETags pomocí hodnoty hash otisku prstu ETag souboru. Tím se zajistí, že prohlížeč stáhne jenom soubor, pokud se změní jeho obsah (nebo se soubor poprvé stáhne).
    • Interně Blazor mapuje fyzické prostředky na otisky prstů, což aplikaci umožňuje:
      • Vyhledejte automaticky generované Blazor prostředky, jako Razor jsou komponenty s oborem CSS pro Blazorfunkci izolace CSS a JS prostředky popsané v JS mapách importu.
      • Vygenerujte <head> značky odkazů v obsahu stránky pro předběžné načtení prostředků.
  • Během vývojového testování sady Visual Studio Opětovné načítání za provozu:
    • Informace o integritě se z prostředků odeberou, aby nedocházelo k problémům při změně souboru během běhu aplikace.
    • Statické prostředky nejsou uložené v mezipaměti, aby se zajistilo, že prohlížeč vždy načte aktuální obsah.

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

  • Blazor vytvoří koncový bod pro zveřejnění kolekce prostředků jako JS modulu.
  • Adresa URL se vygeneruje do textu požadavku jako trvalý stav součásti při vykreslení komponenty WebAssembly na stránku.
  • Během spouštění WebAssembly načte adresu URL, naimportuje modul a zavolá funkci, Blazor 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.

Mapové statické prostředky neposkytují funkce pro minifikace ani jiné transformace souborů. Minifikace se obvykle zpracovává vlastním kódem nebo nástroji třetích stran.

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

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

Doručování prostředků pomocí konvencí koncového bodu směrování statických prostředků mapování

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

Prostředky se doručují prostřednictvím ComponentBase.Assets vlastnosti, která přeloží adresu URL otisku prstu pro daný prostředek. V následujícím příkladu jsou bootstrap, Blazor šablona stylů aplikace projektu (app.css) a šablona stylů CSS (založená na oboru názvů BlazorSampleaplikace) propojeny v kořenové komponentě, obvykle komponenta App (Components/App.razor):

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"]" />

Import map

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

Komponenta Import Map (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).

razor 
<ImportMap />

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

Následující příklady ukazují vlastní definice mapování importu a mapování importu, které vytvoří.

Základní mapování importu:

C# 
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:

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

Mapování importu s vymezeným oborem:

C# 
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:

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

Import mapy s integritou:

C# 
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:

JSON 
{
  "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.

Naimportujte mapu vytvořenou z mapované ResourceAssetCollection statické prostředky na odpovídající jedinečné adresy URL:

C# 
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:

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

Nakonfigurujte Middleware statického souboru tak, aby klientům sloužil statickým prostředkům 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 rozhraním .NET 8 Blazor se statické soubory architektury, jako je skript, obsluhují prostřednictvím statického middlewaru Blazor souborů. V .NET 8 nebo novějších Blazor se statické soubory architektury mapují pomocí směrování koncového bodu a statický middleware se už nepoužívá.

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í <HeadContent> komponent 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 přijetí .NET 8 nebo novější doporučujeme aktualizovat hostované Blazor WebAssembly aplikace na Blazor Web Appverzi 8.

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 .Client projektu vrácení Blazor WebAssembly statického Blazor Web App prostředku zpět na výchozí hodnoty, aby se projekt chová 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 Appwebassembly část aplikace je logická čá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.

Statické soubory v jiných prostředíchDevelopment

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

Při místním spuštění aplikace jsou statické webové prostředky povoleny pouze v Development prostředí. Pokud chcete povolit statické soubory pro jiná prostředí než Development při místním vývoji a testování (například Staging), zavolejte UseStaticWebAssets WebApplicationBuilder v Program souboru.

Upozornění

Zavolejte UseStaticWebAssets přesné prostředí, aby se zabránilo aktivaci funkce v produkčním prostředí, protože obsluhuje soubory z jiných umístění na disku než z projektu, pokud je volána v produkčním prostředí. Příklad v této části kontroluje Staging prostředí voláním IsStaging.

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

Předpona pro Blazor WebAssembly prostředky

Tato část se týká Blazor Web Apps.

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

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

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

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

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

Základní cesta statického webového prostředku

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

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

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

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

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ý symbol Moniker (TFM) cílového rozhraní (například net6.0).

<StaticWebAssetBasePath> Pokud vlastnost v samostatné Blazor WebAssembly aplikaci nastaví publikovanou cestu statického prostředku na app1, kořenová cesta k aplikaci v publikovaném výstupu je /app1.

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

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

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

V předchozím příkladu {TFM} je zástupný symbol Moniker (TFM) cílového rozhraní (například net6.0).

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ů architektury (_framework prostředků složek), do kořenové cesty (/) v publikovaném výstupu. Vlastnost <StaticWebAssetBasePath> zadaná v souboru projektu (.csproj) nastaví základní cestu k jiné než kořenové cestě:

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

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

Bez nastavení <StaticWebAssetBasePath> vlastnosti se klientská aplikace hostovaného řešení nebo samostatné aplikace publikuje na následujících cestách:

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

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

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

XML 
<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 Více hostovaných aplikací ASP.NET CoreBlazor WebAssembly. Tato vlastnost je také efektivní v samostatných Blazor WebAssembly aplikacích.

V předchozíchpříkladch {TFM} net6.0

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 jiným StaticFileOptionssouborem nebo ho FileExtensionContentTypeProvider nakonfigurovat, 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. Obor názvů pro následující rozhraní API je Microsoft.AspNetCore.StaticFiles.

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

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

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

app.UseStaticFiles();

  • StaticFileOptions Předat přímo do UseStaticFiles Program souboru:

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

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

Pokud chcete vytvořit další mapování souborů s jiným StaticFileOptionssouborem nebo ho FileExtensionContentTypeProvider nakonfigurovat, 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:

    C# 
    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 použijte UseStaticFiles Program dvě volání:

    • 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 .
    C# 
    using Microsoft.AspNetCore.StaticFiles;

...

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

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

  • Pokud chcete spustit vlastní middleware statického souboru, můžete se vyhnout narušení poskytování služeb _framework/blazor.server.js MapWhen :

    C# 
    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 Apps.

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 Program serveru přidejte následující using příkaz:

C# 
using Microsoft.Extensions.FileProviders;

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

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

Ve značkě Home komponenty aplikace (Home.razor) odkazujte na obrázek se značkou <img> :

razor 
<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ý {ALT TEXT} symbol je alternativní text obrázku.

Spustit aplikaci.

Další materiály