ASP.NET Core Blazor statiska filer

2025-09-17

Anmärkning

Det här är inte den senaste versionen av den här artikeln. För den nuvarande utgåvan, se .NET 9-versionen av den här artikeln .

Varning

Den här versionen av ASP.NET Core stöds inte längre. Mer information finns i .NET och .NET Core Support Policy. För den nuvarande utgåvan, se .NET 9-versionen av den här artikeln .

Viktigt!

Den här informationen gäller en förhandsversionsprodukt som kan ändras avsevärt innan den släpps kommersiellt. Microsoft lämnar inga garantier, uttryckliga eller underförstådda, med avseende på den information som tillhandahålls här.

För den nuvarande utgåvan, se .NET 9-versionen av den här artikeln .

I den här artikeln beskrivs Blazor appkonfiguration för hantering av statiska filer.

Allmän information om hur du hanterar statiska filer med map-slutpunktskonventioner för routning av statiska tillgångar finns i Statiska filer i ASP.NET Core innan du läser den här artikeln.

Förinstallerade Blazor statiska tillgångar i ramverket

I Blazor Web Apps förladdas statiska ramverksresurser automatiskt med hjälp av Link headers, vilket gör att webbläsaren kan förladda resurser innan den första sidan hämtas och renderas.

I fristående Blazor WebAssembly appar schemaläggs ramverkstillgångar för högprioriterade nedladdningar och cachelagring tidigt i bearbetning av webbläsarsidor index.html när:

Egenskapen OverrideHtmlAssetPlaceholders MSBuild i appens projektfil (.csproj) är inställd på true:

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

Följande <link>-element som innehåller rel="preload" finns i innehållet av <head>wwwroot/index.html:
```
<link rel="preload" id="webassembly" />
```

Leverans av statiska tillgångar i Blazor appar på serversidan

Hantering av statiska tillgångar hanteras antingen av routningsslutpunktskonventioner eller ett mellanprogram som beskrivs i följande tabell.

Egenskap	API (applikationsprogrammeringsgränssnitt)	.NET-version	Beskrivning
Mappa slutpunktskonventioner för routning av statiska tillgångar	MapStaticAssets	.NET 9 eller senare	Optimerar leveransen av statiska tillgångar till klienter.
Mellanprogram för statisk fil	UseStaticFiles	Alla .NET-versioner	Hanterar statiska tillgångar till klienter utan optimering av map static assets men användbart för vissa uppgifter som Map Static Assets inte kan hantera.

Map Static Assets kan ersätta UseStaticFiles i de flesta situationer. Map Static Assets är dock optimerat för att leverera tillgångarna från kända platser i appen vid bygg- och publiceringstillfället. Om appen hanterar tillgångar från andra platser, till exempel disk eller inbäddade resurser, bör UseStaticFiles användas.

Map Static Assets (MapStaticAssets) ersätter även anropande UseBlazorFrameworkFiles i appar som hanterar Blazor WebAssembly framework-filer och att uttryckligen anropa UseBlazorFrameworkFiles i en Blazor Web App är inte nödvändigt eftersom API:et anropas automatiskt när AddInteractiveWebAssemblyComponentsanropas .

När interaktiva webassembly- eller interaktiva autoåtergivningslägen är aktiverade:

Blazor skapar en slutpunkt för att exponera resurssamlingen som en JS modul.
URL:en skickas till huvudinnehållet i begäran som ihållande komponenttillstånd när en WebAssembly-komponent renderas på sidan.
Under WebAssembly-start hämtar Blazor URL:en, importerar modulen och anropar en funktion för att hämta tillgångssamlingen och rekonstruera den i minnet. URL:en är specifik för innehållet och cachelagras för alltid, så den här kostnaden betalas bara en gång per användare tills appen uppdateras.
Resurssamlingen exponeras också på en läsbar URL (_framework/resource-collection.js), så JS har åtkomst till resurssamlingen för förbättrad navigering eller för att implementera funktioner i andra ramverk och komponenter från tredje part.

Static File Middleware (UseStaticFiles) är användbart i följande situationer som Map Static Assets (MapStaticAssets) inte kan hantera:

Hantera filer från diskar som inte ingår i bygg- eller publiceringsprocessen, till exempel filer som lagts till i programmappen under eller efter distributionen.
Tillämpa ett sökvägsprefix på Blazor WebAssembly statiska tillgångsfiler, som beskrivs i avsnittet Prefix för Blazor WebAssembly tillgångar.
Konfigurering av filkopplingar för tillägg till specifika innehållstyper och inställning av alternativ för statiska filer, som beskrivs i avsnittet Filkopplingar och alternativ för statiska filer.

Mer information finns i Statiska filer i ASP.NET Core.

Leverera tillgångar med konventioner för routingändpunkt för statiska kartresurser

Det här avsnittet gäller för Blazor appar på serversidan.

Tillgångar levereras via ComponentBase.Assets-egenskapen, som uppslår den fingeravtrycksbaserade URL:en för en viss tillgång. I följande exempel är Bootstrap, Blazor-projektmallens appformatmall (app.css) och CSS-isoleringsformatmallen (baserat på en apps namnområde BlazorSample) länkade i en rotkomponent, vanligtvis den App komponenten (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` komponent

Det här avsnittet gäller för Blazor Web Apps som anropar MapRazorComponents.

Komponenten ImportMap (ImportMap) representerar ett importkarteelement (<script type="importmap"></script>) som definierar importkartan för modulskript. Komponenten Importkarta placeras i innehållet av <head> i rotkomponenten, vanligtvis komponenten App (Components/App.razor).

<ImportMap />

Om en anpassad ImportMapDefinition inte har tilldelats en importkarta komponent genereras importkartan baserat på appens resurser.

Anmärkning

ImportMapDefinition instanser är dyra att skapa, så vi rekommenderar att du cachelagrar dem när du skapar ytterligare en instans.

I följande exempel visas anpassade importkartdefinitioner och de importkartor som de skapar.

Grundläggande importkarta:

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

Föregående kod resulterar i följande importkarta:

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

Avgränsad importkarta:

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

Föregående kod resulterar i följande importkarta:

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

Importera karta med integritet:

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

Föregående kod resulterar i följande importkarta:

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

Kombinera importkartdefinitioner (ImportMapDefinition) med ImportMapDefinition.Combine.

Importera karta som skapats från en ResourceAssetCollection som mappar statiska tillgångar till motsvarande unika URL:er:

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

Föregående kod resulterar i följande importkarta:

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

Överträdelser av innehållssäkerhetspolicyn (CSP) i importkartor

Det här avsnittet gäller för Blazor Web Apps som anropar MapRazorComponents.

Komponenten ImportMap återges som en infogad <script>-tagg, vilket strider mot en strikt CSP(Content Security Policy) som anger default-src- eller script-src-direktivet.

Exempel på hur du hanterar principöverträdelsen med Subresource Integrity (SRI) eller en kryptografisk nonce finns i Lösa CSP-överträdelser med Subresource Integrity (SRI) eller en nonce.

Konfigurera Static File Middleware för att hantera statiska tillgångar till klienter genom att anropa UseStaticFiles i appens pipeline för bearbetning av begäranden. Mer information finns i Statiska filer i ASP.NET Core.

I versioner före .NET 8 hanteras statiska Blazor ramverksfiler, till exempel skriptet Blazor, via Static File Middleware. I .NET 8 eller senare mappas Blazor ramverks statiska filer med hjälp av slutpunktsroutning och Static File Middleware används inte längre.

Identifiera klient-side statiska resurser i fristående Blazor WebAssembly-appar

I fristående Blazor WebAssembly appar under byggnation/publicering ersätter ramverket platshållare med index.html värden som beräknas under kompilering till fingeravtryck av statiska tillgångar för klientsideåtergivning. Ett fingeravtryck placeras i skriptfilens blazor.webassembly.js namn och en importkarta genereras för andra .NET-tillgångar.

Följande konfiguration måste finnas i filen för wwwwoot/index.html en fristående Blazor WebAssembly app för att kunna använda fingeravtryck:

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

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

</html>

I projektfilen (.csproj) är egenskapen <OverrideHtmlAssetPlaceholders> inställd på true:

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

När importer löses för JavaScript-interop använder webbläsaren importkartan för att lösa fingeravtrycksfiler.

Alla skript i index.html med fingeravtrycksmarkören fingeravtryckas av ramverket. En skriptfil med namnet scripts.js i appens mapp tas till exempel med fingeravtryck genom att lägga till wwwroot/js före filnamnstillägget #[.{fingerprint}] (.js):

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

Fingeravtrycka statiska resurser på klientsidan i Blazor Web Apps

För återgivning på klientsidan (CSR) i Blazor Web Apps (interaktiva auto- eller interaktiva WebAssembly-återgivningslägen) aktiveras fingerprinting på serversidan genom att använda konventioner för kartläggning av statiska tillgångars routing-endpoints (), MapStaticAssets-komponent och ImportMap-egenskapen (). Mer information finns i Statiska filer i ASP.NET Core.

Om du vill ta fingeravtryck på ytterligare JavaScript-moduler för CSR använder du <StaticWebAssetFingerprintPattern> objektet i appens projektfil (.csproj). I följande exempel läggs ett fingeravtryck till för alla filer som tillhandahålls .mjs av utvecklare i appen:

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

När importer löses för JavaScript-interop använder webbläsaren importkartan för att lösa fingeravtrycksfiler.

Sammanfattning av statiska filformat `<link>href`

Det här avsnittet gäller för alla .NET-versioner och Blazor appar.

Följande tabeller sammanfattar statiska filer <link>href format efter .NET-version.

Information om platsen för <head> innehåll där statiska fillänkar finns finns i ASP.NET Core Blazor projektstruktur. Statiska tillgångslänkar kan också anges med hjälp av <HeadContent> komponenter i enskilda Razor komponenter.

Information om platsen för <head> innehåll där statiska fillänkar finns finns i ASP.NET Core Blazor projektstruktur.

.NET 9 eller senare

Apptyp	`href` värde	Exempel
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" />`
Fristående Blazor WebAssembly	`{PATH}`	`<link rel="stylesheet" href="css/app.css" />` `<link href="_content/ComponentLib/styles.css" rel="stylesheet" />`

.NET 8.x

Apptyp	`href` värde	Exempel
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" />`
Fristående Blazor WebAssembly	`{PATH}`	`<link rel="stylesheet" href="css/app.css" />` `<link href="_content/ComponentLib/styles.css" rel="stylesheet" />`

.NET 7.x eller tidigare

Apptyp	`href` värde	Exempel
Blazor Server†	`{PATH}`	`<link href="css/site.css" rel="stylesheet" />` `<link href="_content/ComponentLib/styles.css" rel="stylesheet" />`
Värd 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 stöds i .NET 8 eller senare men är inte längre en projektmall efter .NET 7.
‡Vi rekommenderar att du uppdaterar värdbaserade Blazor WebAssembly appar till Blazor Web Appnär du använder .NET 8 eller senare.

Projektläge för statisk webbtillgång

Detta avsnitt är tillämpbart på .Client-projektet i ett Blazor Web App.

Den obligatoriska inställningen <StaticWebAssetProjectMode>Default</StaticWebAssetProjectMode> i .Client projektet för en Blazor Web App återställer Blazor WebAssembly statiska tillgångsbeteenden tillbaka till standardvärdena, så att projektet fungerar som en del av det värdbaserade projektet. Blazor WebAssembly SDK (Microsoft.NET.Sdk.BlazorWebAssembly) konfigurerar statiska webbtillgångar på ett specifikt sätt för att arbeta i "fristående" läge med en server som helt enkelt förbrukar utdata från biblioteket. Det här passar inte för en Blazor Web App, där WebAssembly-delen av appen är en logisk del av värden och bör fungera mer som ett bibliotek. Projektet exponerar till exempel inte stilpaketet (till exempel BlazorSample.Client.styles.css) och tillhandahåller istället bara värdprogrammet med projektbunten, så att värdprogrammet kan inkludera det i sitt eget stilpaket.

Det går inte att ändra värdet (Default) för <StaticWebAssetProjectMode> eller ta bort egenskapen från .Client projektet.

Prefix för Blazor WebAssembly tillgångar

Det här avsnittet gäller för Blazor Web Apps.

Använd slutpunktsalternativet WebAssemblyComponentsEndpointOptions.PathPrefix för att ange den sökvägssträng som anger prefixet för Blazor WebAssembly tillgångar. Sökvägen måste motsvara ett refererat Blazor WebAssembly programprojekt.

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

I föregående exempel är platshållaren {PATH PREFIX} sökvägsprefixet och måste börja med ett snedstreck (/).

I följande exempel är sökvägsprefixet inställt på /path-prefix:

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

Basväg för statiska webbresurser

Det här avsnittet gäller fristående Blazor WebAssembly appar.

När appen publiceras placeras appens statiska resurser, inklusive Blazor frameworkfiler (_framework mappresurser), på rotvägen (/) i det publicerade resultatet. Egenskapen <StaticWebAssetBasePath> som anges i projektfilen (.csproj) ställer in basvägen till en sökväg som inte är en rot.

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

I det föregående exemplet är {PATH} platsenhållaren sökvägen.

Utan att ange egenskapen <StaticWebAssetBasePath> publiceras en fristående app på /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/.

I föregående exempel {TFM} är platshållaren Target Framework Moniker (TFM).

Om egenskapen <StaticWebAssetBasePath> i en fristående Blazor WebAssembly-app anger den publicerade statiska resurssökvägen som app1, är rotsökvägen till appen i det publicerade resultatet /app1.

I den fristående Blazor WebAssembly appens projektfil (.csproj):

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

Sökvägen till den fristående appen Blazor WebAssembly i publicerade utdata är /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/.

I föregående exempel {TFM} är platshållaren Target Framework Moniker (TFM).

Det här avsnittet gäller fristående Blazor WebAssembly appar och värdbaserade Blazor WebAssembly lösningar.

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

I det föregående exemplet är {PATH} platsenhållaren sökvägen.

Utan att ange egenskapen <StaticWebAssetBasePath> publiceras klientappen för en värdbaserad lösning eller en fristående app på följande sökvägar:

I Server-projektet för en värdbaserad Blazor WebAssembly-lösning: /BlazorHostedSample/Server/bin/Release/{TFM}/publish/wwwroot/
I en fristående Blazor WebAssembly app: /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/

Om egenskapen <StaticWebAssetBasePath> i Client-projektet för en värdbaserad Blazor WebAssembly-app eller i en fristående Blazor WebAssembly-app anger den publicerade statiska resursens sökväg till app1, är rotsökvägen till appen i publicerade utdata /app1.

I Client-appens projektfil (.csproj) eller den fristående Blazor WebAssembly appens projektfil (.csproj):

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

I publicerat resultat:

Sökväg till klientappen i Server-projektet för den värdbaserade Blazor WebAssembly lösningen: /BlazorHostedSample/Server/bin/Release/{TFM}/publish/wwwroot/app1/
Sökväg till en fristående Blazor WebAssembly-applikation: /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/

Egenskapen <StaticWebAssetBasePath> används oftast för att styra sökvägarna till publicerade statiska tillgångar för flera Blazor WebAssembly appar i en enda värdbaserad distribution. Mer information finns i Flera värdbaserade ASP.NET Core Blazor WebAssembly-appar. Egenskapen är också effektiv i fristående Blazor WebAssembly appar.

I de föregående exemplen är {TFM} platshållaren Target Framework Moniker (TFM).

Filmappningar och inställningar för statiska filer

Det här avsnittet gäller statiska filer på serversidan.

För att skapa ytterligare filmappar med en FileExtensionContentTypeProvider eller konfigurera andra StaticFileOptions, använd ett av följande tillvägagångssätt. I följande exempel är {EXTENSION}-platshållaren filtillägget och {CONTENT TYPE}-platshållaren innehållstypen.

Konfigurera alternativ via dependency injection (DI) i Program-filen med hjälp av StaticFileOptions:
```
using Microsoft.AspNetCore.StaticFiles;

...

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

builder.Services.Configure<StaticFileOptions>(options =>
{
    options.ContentTypeProvider = provider;
});
```
Den här metoden konfigurerar samma filprovider som används för att hantera Blazor-skriptet. Se till att den anpassade konfigurationen inte påverkar Blazor-skriptet. Ta till exempel inte bort mappningen för JavaScript-filer genom att konfigurera providern med provider.Mappings.Remove(".js").
Använd två anrop till UseStaticFiles i filen Program:
- Konfigurera den anpassade filprovidern i det första anropet med StaticFileOptions.
- Det andra mellanprogrammet hanterar Blazor-skriptet, som använder standardkonfigurationen för statiska filer som tillhandahålls av Blazor ramverket.
```
using Microsoft.AspNetCore.StaticFiles;

...

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

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

Du kan undvika störningar vid distribution av _framework/blazor.server.js med hjälp av MapWhen för att genomföra ett anpassat statisk fil-mellanprogram:

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

Hantera filer från flera platser

Vägledningen i denna del gäller endast Blazor Web Apps.

Så här hanterar du filer från flera platser med en CompositeFileProvider:

Lägg till namnområdet för Microsoft.Extensions.FileProviders överst i Program fil i serverprojektet.
I serverprojektets Program-fil innan anropet till UseStaticFiles:
- Skapa en PhysicalFileProvider med sökvägen till de statiska resurserna.
- Skapa en CompositeFileProvider från WebRootFileProvider och PhysicalFileProvider. Tilldela den sammansatta filprovidern tillbaka till appens WebRootFileProvider.

Exempel:

Skapa en ny mapp i serverprojektet med namnet AdditionalStaticAssets. Placera en bild i mappen.

Lägg till följande using-instruktion överst i serverprojektets Program-fil:

using Microsoft.Extensions.FileProviders;

Lägg till följande kod i serverprojektets Program-fil innan anropet till UseStaticFiles:

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

I appens Home-komponent (Home.razor) -markering refererar du till bilden med en <img> tagg:

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

I föregående exempel:

Platshållaren {IMAGE FILE NAME} är namnet på bildfilen. Du behöver inte ange ett sökvägssegment om bildfilen finns i roten i mappen AdditionalStaticAssets.
Platshållaren {ALT TEXT} är bildens alternativa text.

Kör appen.

Ytterligare resurser

Feedback

Var den här sidan till hjälp?

Dela via

ASP.NET Core Blazor statiska filer

Förinstallerade Blazor statiska tillgångar i ramverket

Leverans av statiska tillgångar i Blazor appar på serversidan

Leverera tillgångar med konventioner för routingändpunkt för statiska kartresurser

ImportMap komponent

Överträdelser av innehållssäkerhetspolicyn (CSP) i importkartor

Identifiera klient-side statiska resurser i fristående Blazor WebAssembly-appar

Fingeravtrycka statiska resurser på klientsidan i Blazor Web Apps

Sammanfattning av statiska filformat <link>href

.NET 9 eller senare

.NET 8.x

.NET 7.x eller tidigare

Projektläge för statisk webbtillgång

Prefix för Blazor WebAssembly tillgångar

Basväg för statiska webbresurser

Filmappningar och inställningar för statiska filer

Hantera filer från flera platser

Ytterligare resurser

Feedback

Ytterligare resurser

`ImportMap` komponent

Sammanfattning av statiska filformat `<link>href`