Sdílet prostřednictvím


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

Poznámka:

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

Upozorňující

Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v tématu .NET a .NET Core Zásady podpory. Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

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 ve verzi .NET 8 tohoto článku.

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

Middleware statického prostředku

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

Obsluha statických prostředků se spravuje některým ze dvou middlewarů popsaných v následující tabulce.

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

Nakonfigurujte middleware mapovat statické prostředky voláním MapStaticAssets kanálu zpracování požadavků aplikace, který provádí následující kroky:

MapStaticAssets funguje kombinováním procesů sestavení a publikování, které shromažďují informace 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čů.

MapStaticAssets může nahradit UseStaticFiles ve většině situací. MapStaticAssets Je ale 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.

MapStaticAssets poskytuje následující výhody, které nejsou při volání UseStaticFilesk dispozici:

  • 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.

Middleware Map Static Assets neposkytuje 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, které MapStaticAssets nemůžou zpracovat:

Využívání prostředků pomocí middlewaru mapového statického souboru

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

Prostředky se využívají 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 Blazor šablony šablony projektu propojeny šablony šablony stylů (app.css) a šablona stylů CSS 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["BlazorWeb-CSharp.styles.css"]" />

Import map

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

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

<ImportMap />

Pokud vlastní komponenta ImportMapDefinition není přiřazená ImportMap , vygeneruje se mapa importu 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:

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"
  }
}

Mapování importu s vymezeným oborem:

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.

Naimportujte mapu vytvořenou z mapované ResourceAssetCollection statické prostředky na 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"
  }
}

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 Webová aplikace @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 Webová aplikace {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řechodu na .NET 8 nebo novější doporučujeme aktualizovat hostované Blazor WebAssembly aplikace na Blazor Web Apps.

Režim projektu statického webového assetu

Tato část se týká .Client projektu Blazor webové aplikace.

Požadované <StaticWebAssetProjectMode>Default</StaticWebAssetProjectMode> nastavení v .Client projektu webové aplikace vrátí Blazor WebAssembly chování statických Blazor prostředků 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 webovou aplikaci, kde je část aplikace WebAssembly 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) nebo odebrání vlastnosti z .Client projektu není podporována.<StaticWebAssetProjectMode>

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 ve výchozím nastavení 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.

Upozorňující

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.

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

Předpona pro Blazor WebAssembly prostředky

Tato část platí pro 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.

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:

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í.

Ve výchozím nastavení 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ě:

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

<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í.

Ve výchozím nastavení 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ě:

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

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

    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:

    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:

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

    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:

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čkě Home komponenty aplikace (Home.razor) odkazujte na obrázek se značkou <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ý {ALT TEXT} symbol je alternativní text obrázku.

Spustit aplikaci.

Další materiály