Mappa statiska filer i ASP.NET Core

Av Rick Anderson

Statiska filer, som HTML, CSS, bilder och JavaScript, är resurser som en ASP.NET Core-app som standard levereras direkt till klienter.

Vägledning för Blazor statiska filer, som lägger till eller ersätter vägledningen i den här artikeln, finns i ASP.NET Core Blazor statiska filer.

Hantera statiska filer

Statiska filer lagras i projektets webbrotskatalog. Standardkatalogen är {content root}/wwwroot, men den kan ändras med metoden UseWebRoot. Mer information finns i Innehållsrot och webbrot.

Metoden CreateBuilder anger innehållsroten till den aktuella katalogen:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.MapStaticAssets();

app.UseAuthorization();

app.MapDefaultControllerRoute().WithStaticAssets();
app.MapRazorPages().WithStaticAssets();

app.Run();

Statista filer är tillgängliga via en sökväg relativt till webbroten. Till exempel innehåller projektmallarna för webbapplikation flera mappar i mappen wwwroot.

• wwwroot
  • css
  • js
  • lib

Överväg en app med filen wwwroot/images/MyImage.jpg. URI-formatet för att komma åt en fil i mappen images är https://<hostname>/images/<image_file_name>. Till exempel https://localhost:5001/images/MyImage.jpg

Mappa slutpunktskonventioner för routning av statiska tillgångar (MapStaticAssets)

För att skapa högpresterande webbappar krävs att leveransen av resurser optimeras till webbläsaren. Möjliga optimeringar med MapStaticAssets inkluderar:

• Hantera en viss tillgång en gång tills filen ändras eller webbläsaren rensar cacheminnet. Ange rubrikerna ETag och Last-Modified .
• Förhindra att webbläsaren använder gamla eller inaktuella tillgångar när en app har uppdaterats. Ange senaste ändrade-huvudet.
• Konfigurera rätt cachehuvuden.
• Använd caching middleware.
• Hantera komprimerade versioner av tillgångarna när det är möjligt. Den här optimeringen omfattar inte minifiering.
• Använd en CDN för att tillhandahålla resurserna närmare användaren.
• Fingeravtryckstillgångar för att förhindra återanvändning av gamla versioner av filer.

MapStaticAssets:

• Integrerar den information som samlas in om statiska webbtillgångar under bygg- och publiceringsprocessen med ett körningsbibliotek som bearbetar den här informationen för att optimera filservering till webbläsaren.
• Är routningsslutpunktskonventioner som optimerar leveransen av statiska tillgångar i en app. Den är utformad för att fungera med alla användargränssnittsramverk, inklusive Blazor, Razor Pages och MVC.

MapStaticAssets jämfört med UseStaticFiles

MapStaticAssets finns i ASP.NET Core i .NET 9.0 och senare. UseStaticFiles måste användas i versioner före .NET 9.0.

UseStaticFiles hanterar statiska filer, men den ger inte samma optimeringsnivå som MapStaticAssets. MapStaticAssets är optimerad för att betjäna resurser som är kända av appen under körning. Om appen hanterar tillgångar från andra platser, till exempel disk eller inbäddade resurser, bör UseStaticFiles användas.

Map Static Assets ger följande fördelar som inte är tillgängliga när du anropar UseStaticFiles:

• Komprimering under kompileringstiden för alla resurser i appen, inklusive JavaScript (JS) och formatmallar, men exklusive bild- och teckensnittsresurser som redan är komprimerade. Gzip-komprimering (Content-Encoding: gz) används under utveckling. Gzip med Brotli-komprimering (Content-Encoding: br) används under publiceringen.
• Fingeravtryckning för alla resurser vid byggtidpunkt med en Base64-kodad sträng av SHA-256-hashen för varje fils innehåll. Detta förhindrar återanvändning av en gammal version av en fil, även om den gamla filen cachelagras. Tillgångar med fingeravtryck cachelagras med immutable-direktivet, vilket resulterar i att webbläsaren aldrig begär resursen igen förrän den ändras. För webbläsare som inte stöder immutable direktivet läggs ett max-age direktiv till.
  • Även om en resurs inte är fingeravtrycksmarkerad genereras innehållsbaserade ETags för varje statisk resurs med filens fingeravtryckshash som ETag värde. Detta säkerställer att webbläsaren endast laddar ned en fil om dess innehåll ändras (eller om filen laddas ned för första gången).
  • Internt mappar ramverket fysiska tillgångar till deras fingeravtryck, vilket gör att appen kan:
    • Hitta automatiskt genererade resurser, till exempel komponentavgränsat Razor CSS för funktionen för BlazorCSS-isolering och JS resurser som beskrivs i JS importkartor.
    • Generera länktaggar i <head> innehållet på sidan för att förinläsa resurser.
• Under Visual Studio Hot Reload utvecklingstestning:
  • Integritetsinformation tas bort från tillgångarna för att undvika problem när en fil ändras medan appen körs.
  • Statiska tillgångar cachelagras inte för att säkerställa att webbläsaren alltid hämtar aktuellt innehåll.

Map Static Assets tillhandahåller inte funktioner för minifiering eller andra filtransformeringar. Minifiering hanteras vanligtvis av anpassad kod eller verktyg från tredje part.

Följande funktioner stöds med UseStaticFiles men inte med MapStaticAssets:

• Att hantera filer från diskar eller inbäddade resurser eller andra platser
• Serva filer utanför webbroot
• Ange HTTP-svarshuvuden
• Katalogbläddring
• Tillhandahålla standarddokument
• FileExtensionContentTypeProvider
• Hantera filer från flera platser
• Att hantera filer från diskar eller inbäddade resurser eller andra platser
• Leverera filer utanför webbroten
• Ange HTTP-svarshuvuden
• Katalogbläddring
• Tillhandahålla standarddokument
• FileExtensionContentTypeProvider
• Hantera filer från flera platser

Servera filer i webbens rotkatalog

Standardmallarna för webbappar anropar metoden MapStaticAssets i Program.cs, som gör att statiska filer kan hanteras:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.MapStaticAssets();

app.UseAuthorization();

app.MapDefaultControllerRoute().WithStaticAssets();
app.MapRazorPages().WithStaticAssets();

app.Run();

Den parameterlösa MapStaticAssets-metodens överbelastning markerar filerna i webbroten som tillgängliga. Följande markering refererar till wwwroot/images/MyImage.jpg:

<img src="~/images/MyImage.jpg" class="img" alt="My image" />

I den föregående markeringen pekar tilde-tecknet ~ på webbplatsens rot .

Tillhandahålla filer utanför webrooten

Överväg en kataloghierarki där de statiska filer som ska hanteras finns utanför webbroten:

• wwwroot
  • css
  • images
  • js
• MyStaticFiles
  • images
    • red-rose.jpg

En begäran kan komma åt red-rose.jpg-fil genom att konfigurera det statiska mellanprogrammet på följande sätt:

using Microsoft.Extensions.FileProviders;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();

app.UseStaticFiles();    //Serve files from wwwroot
app.UseStaticFiles(new StaticFileOptions
 {
     FileProvider = new PhysicalFileProvider(
            Path.Combine(builder.Environment.ContentRootPath, "MyStaticFiles")),
     RequestPath = "/StaticFiles"
 });

app.UseAuthorization();

app.MapDefaultControllerRoute().WithStaticAssets();
app.MapRazorPages().WithStaticAssets();

app.Run();

I föregående kod exponeras MyStaticFiles kataloghierarki offentligt via StaticFiles URI-segment. En begäran om att https://<hostname>/StaticFiles/images/red-rose.jpg hanterar red-rose.jpg-filen.

Följande markering refererar till MyStaticFiles/images/red-rose.jpg:

<img src="~/StaticFiles/images/red-rose.jpg" class="img" alt="A red rose" />

Information om hur du hanterar filer från flera platser finns i Hantera filer från flera platser.

Ange HTTP-svarshuvuden

Ett StaticFileOptions objekt kan användas för att ange HTTP-svarshuvuden. Förutom att konfigurera betjäning av statiska filer från webbroten, anger följande kod Cache-Control-huvudet:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();

 var cacheMaxAgeOneWeek = (60 * 60 * 24 * 7).ToString();
 app.UseStaticFiles(new StaticFileOptions
 {
     OnPrepareResponse = ctx =>
     {
         ctx.Context.Response.Headers.Append(
              "Cache-Control", $"public, max-age={cacheMaxAgeOneWeek}");
     }
 });

app.UseAuthorization();

app.MapDefaultControllerRoute().WithStaticAssets();
app.MapRazorPages().WithStaticAssets();

app.Run();

Föregående kod gör statiska filer offentligt tillgängliga i den lokala cachen i en vecka.

Auktorisering av statisk fil

ASP.NET Core-mallarna anropar MapStaticAssets innan de anropar UseAuthorization. De flesta appar följer det här mönstret. När MapStaticAssets anropas före mellanprogrammet för auktorisering:

• Inga auktoriseringskontroller utförs på de statiska filerna.
• Statiska filer som hanteras av Static File Middleware, till exempel de under wwwroot, är offentligt tillgängliga.

Information om hur du hanterar statiska filer baserat på auktorisering finns i Statisk filauktorisering.

Hantera filer från flera platser

Överväg följande Razor sida som visar /MyStaticFiles/image3.png-filen:

@page

<p> Test /MyStaticFiles/image3.png</p>

<img src="~/image3.png" class="img" asp-append-version="true" alt="Test">

UseStaticFiles och UseFileServer är standardinställda till filprovidern som pekar på wwwroot. Ytterligare instanser av UseStaticFiles och UseFileServer kan tillhandahållas med andra filleverantörer för att hantera filer från andra platser. I följande exempel anropas UseStaticFiles två gånger för att hantera filer från både wwwroot och MyStaticFiles:

app.UseStaticFiles();
app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(builder.Environment.ContentRootPath, "MyStaticFiles"))
});

Använd föregående kod:

• Filen /MyStaticFiles/image3.png visas på skärmen.
• Image Tag HelpersAppendVersion tillämpas inte eftersom Tag Helpers är beroende av WebRootFileProvider. WebRootFileProvider har inte uppdaterats för att inkludera mappen MyStaticFiles.

Följande kod uppdaterar WebRootFileProvider, vilket möjliggör att Image Tag Helper kan erbjuda en versionering:

var webRootProvider = new PhysicalFileProvider(builder.Environment.WebRootPath);
var newPathProvider = new PhysicalFileProvider(
  Path.Combine(builder.Environment.ContentRootPath, "MyStaticFiles"));

var compositeProvider = new CompositeFileProvider(webRootProvider,
                                                  newPathProvider);

// Update the default provider.
app.Environment.WebRootFileProvider = compositeProvider;

app.MapStaticAssets();

Anteckning

Föregående metod gäller för Razor Pages- och MVC-appar. Vägledning som gäller för Blazor Web Apps finns i ASP.NET Core Blazor statiska filer.

Hantera filer utanför wwwroot genom att uppdatera IWebHostEnvironment.WebRootPath

När IWebHostEnvironment.WebRootPath är inställt på en annan mapp än wwwroot:

• I utvecklingsmiljön hanteras statiska tillgångar i både wwwroot och de uppdaterade IWebHostEnvironment.WebRootPath från wwwroot.
• I andra miljöer än utveckling hanteras dubbletter av statiska tillgångar från den uppdaterade mappen IWebHostEnvironment.WebRootPath.

Överväg att skapa en webbapp med den tomma webbmallen:

• Innehåller en Index.html-fil i wwwroot och wwwroot-custom.

• Med den följande uppdaterade Program.cs-filen som konfigurerar WebRootPath = "wwwroot-custom":

  var builder = WebApplication.CreateBuilder(new WebApplicationOptions
  {
      Args = args,
      // Look for static files in "wwwroot-custom"
      WebRootPath = "wwwroot-custom"
  });
  
  var app = builder.Build();
  
  app.UseDefaultFiles();
  app.MapStaticAssets();
  
  app.Run();
  

I den föregående koden görs förfrågningar till /:

• I utvecklingsmiljön returnerar wwwroot/Index.html
• I alla miljöer förutom utvecklingsmiljön returnera wwwroot-custom/Index.html

Använd någon av följande metoder för att säkerställa att tillgångar från wwwroot-custom returneras:

• Ta bort duplicerade namngivna tillgångar i wwwroot.

• Ställ in "ASPNETCORE_ENVIRONMENT" i Properties/launchSettings.json till vilket värde som helst utom "Development".

• Inaktivera statiska webbtillgångar helt genom att ange <StaticWebAssetsEnabled>false</StaticWebAssetsEnabled> i projektfilen. VARNING: Inaktivering av statiska webbtillgångar inaktiverar Razor klassbibliotek.

• Lägg till följande XML i projektfilen:

  <ItemGroup>
      <Content Remove="wwwroot\**" />
  </ItemGroup>
  

Följande kod uppdaterar IWebHostEnvironment.WebRootPath till ett värde som inte är för utvecklingsbruk, vilket säkerställer att duplicerat innehåll returneras från wwwroot-custom i stället för wwwroot:

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    // Examine Hosting environment: logging value
    EnvironmentName = Environments.Staging,
    WebRootPath = "wwwroot-custom"
});

var app = builder.Build();

app.Logger.LogInformation("ASPNETCORE_ENVIRONMENT: {env}",
      Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT"));

app.Logger.LogInformation("app.Environment.IsDevelopment(): {env}",
      app.Environment.IsDevelopment().ToString());

app.UseDefaultFiles();
app.MapStaticAssets();

app.Run();

Ytterligare resurser

• Visa eller ladda ned exempelkod (hur du laddar ned)
• Mellanprogram
• Introduktion till ASP.NET Core
• ASP.NET Core Blazor filuppladdningar
• ASP.NET Core Blazor nedladdning av filer