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:
- Nastaví hlavičky ETag a Naposledy změněné .
- Nastaví hlavičky ukládání do mezipaměti.
- Používá middleware ukládání do mezipaměti.
- Pokud je to možné, obsluhuje komprimované statické prostředky.
- Pracuje se službou Content Delivery Network (CDN) (například Azure CDN) a obsluhuje statické prostředky aplikace blíže k uživateli.
- Minifies the app's static assets.
- Otisky prstů prostředků , aby se zabránilo opakovanému použití starých verzí souborů.
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é direktivuimmutable
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 prstuETag
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ů.
- I když prostředek není otiskem prstu, pro každý statický prostředek se vygeneruje obsah
- 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:
- Použití předpony cesty u Blazor WebAssembly statických souborů assetů, které jsou popsány v části Předpona pro Blazor WebAssembly prostředky .
- Konfigurace mapování souborů přípon na konkrétní typy obsahu a nastavení statických možností souborů, které jsou popsány v části Mapování souborů a možnosti statického souboru .
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á.
Souhrn statických formátů souborů <link>
href
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 app1
k 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.
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řidejte obor názvů Microsoft.Extensions.FileProviders na začátek
Program
souboru projektu serveru. - V souboru projektu
Program
serveru před voláním:UseStaticFiles- Vytvořte cestu PhysicalFileProvider ke statickým prostředkům.
- Vytvořte z CompositeFileProvider a WebRootFileProvider na kartě PhysicalFileProvider. Přiřaďte zprostředkovatele složeného souboru zpět k aplikaci WebRootFileProvider.
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žceAdditionalStaticAssets
, nemusíte zadávat segment cesty. - Zástupný
{ALT TEXT}
symbol je alternativní text obrázku.
Spustit aplikaci.