Dela via

Statiska filer i ASP.NET Core

Note

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

Warning

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 aktuella utgåvan, se .NET 9-versionen av den här artikeln.

Important

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 aktuella utgåvan, se .NET 9-versionen av den här artikeln.

Statiska filer, även kallade statiska resurser, är sådana filer i en ASP.NET Core-app som inte genereras dynamiskt. De skickas istället direkt till klienter på begäran, till exempel HTML-, CSS-, bild- och JavaScript-filer.

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.

Om du vill aktivera hantering av statiska filer i ASP.NET Core anropar du MapStaticAssets.

Som standard lagras statiska filer i projektets webbrotkatalog . Standardkatalogen är {CONTENT ROOT}/wwwroot, där {CONTENT ROOT} platshållaren är appens innehållsrot. Endast filer i wwwroot-mappen kan adresseras, så du behöver inte bekymra dig om resten av koden.

Endast filer med specifika filnamnstillägg som mappas till medietyper som stöds behandlas som statiska webbtillgångar.

Statiska webbtillgångar identifieras under byggfasen och optimeras med innehållsbaserad fingeravtrycksteknik för att förhindra återanvändning av gamla filer. Tillgångar komprimeras också för att minska tiden för tillgångsleverans.

Under körning exponeras de identifierade statiska webbtillgångarna som slutpunkter med HTTP-huvuden, såsom cachelagringshuvuden och huvuden för innehållstyp. En tillgång hanteras en gång tills filen ändras eller webbläsaren rensar cacheminnet. Rubrikerna ETag, Last-Modifiedoch Content-Type anges. Webbläsaren hindras från att använda inaktuella tillgångar när en app har uppdaterats.

Leverans av statiska tillgångar baseras på slutpunktsroutning, så det fungerar med andra slutpunktsmedvetna funktioner, till exempel auktorisering. Den är utformad för att fungera med alla användargränssnittsramverk, inklusive Blazor, Razor Pages och MVC.

Map Static Assets ger följande fördelar:

  • 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- och Brotli-komprimering (Content-Encoding: br) används båda 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.

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.

Om du vill aktivera hantering av statiska filer i ASP.NET Core anropar du UseStaticFiles.

Som standard lagras statiska filer i projektets webbrotkatalog . Standardkatalogen är {CONTENT ROOT}/wwwroot, där {CONTENT ROOT} platshållaren är appens innehållsrot. Endast filer i wwwroot-mappen kan adresseras, så du behöver inte bekymra dig om resten av koden.

Vid körning returneras statiska webbtillgångar av Static File Middleware när de begärs med tillgångsändring och innehållstyphuvuden som tillämpas. Rubrikerna ETag, Last-Modifiedoch Content-Type anges.

Static File Middleware möjliggör statisk filservering och används av en app när UseStaticFiles den anropas i appens pipeline för bearbetning av begäranden. Filer levereras från sökvägen som anges i IWebHostEnvironment.WebRootPath eller WebRootFileProvider, vilket som standard är webbrotmappen, vanligtvis wwwroot.

Du kan också hantera statiska webbtillgångar från refererade projekt och paket.

Ändra webbrotkatalogen

Använd metoden UseWebRoot om du vill ändra webbrooten. Mer information finns i översikten över grunderna i ASP.NET Core.

Förhindra publicering av filer i wwwroot med projektobjektet i projektfilen.<Content> I följande exempel förhindras publicering av innehåll i wwwroot/local och dess underkataloger:

<ItemGroup>
  <Content Update="wwwroot\local\**\*.*" CopyToPublishDirectory="Never" />
</ItemGroup>

Metoden CreateBuilder anger innehållsroten till den aktuella katalogen:

var builder = WebApplication.CreateBuilder(args);

Metoden CreateDefaultBuilder anger innehållsroten till den aktuella katalogen:

Host.CreateDefaultBuilder(args)

I pipelinen för bearbetning av begäranden efter anropet till UseHttpsRedirectionanropar du MapStaticAssets i appens pipeline för bearbetning av begäranden för att aktivera servering av statiska filer från appens webbrot:

app.MapStaticAssets();

I pipelinen för bearbetning av begäranden efter anropet till UseHttpsRedirectionanropar du UseStaticFiles i appens pipeline för bearbetning av begäranden för att aktivera servering av statiska filer från appens webbrot:

app.UseStaticFiles();

Statiska filer är tillgängliga via en sökväg i förhållande till webrooten.

Så här kommer du åt en avbildning på wwwroot/images/favicon.png:

  • URL-format: https://{HOST}/images/{FILE NAME}
    • Platshållaren {HOST} är värden.
    • Platshållaren {FILE NAME} är filnamnet.
  • Exempel
    • Absolut URL: https://localhost:5001/images/favicon.png
    • Rootrelativ URL: images/favicon.png

I en Blazor app images/favicon.png läser du in ikonbilden (favicon.png) från appens wwwroot/images mapp:

<link rel="icon" type="image/png" href="images/favicon.png" />

I Razor Pages- och MVC-appar pekar tilde-tecknet ~ på webbroten. I följande exempel ~/images/favicon.png läser du in ikonbilden (favicon.png) från appens wwwroot/images mapp:

<link rel="icon" type="image/png" href="~/images/favicon.png" />

Kortslut pipelinen för mellanprogram

För att undvika att köra hela mellanprogramvarupipelinen efter att en statisk tillgång har matchats, vilket är beteendet hos UseStaticFiles, anropar du ShortCircuit på MapStaticAssets. Anropet ShortCircuit kör omedelbart slutpunkten och returnerar svaret, vilket förhindrar att andra mellanprogram körs för begäranden om statiska tillgångar:

app.MapStaticAssets().ShortCircuit();

Kontrollera cachelagring av statiska filer under utveckling

När du kör i utvecklingsmiljön, till exempel under Visual Studio Hot Reload-utvecklingstestning, överordnar ramverket cachehuvuden för att förhindra att webbläsare cachar statiska filer. Detta säkerställer att den senaste versionen av filer används när filer ändras, vilket undviker problem med inaktuellt innehåll. I produktion anges rätt cache-header, vilket gör att webbläsare kan cache:a statiska resurser som förväntat.

Om du vill inaktivera det här beteendet anger du EnableStaticAssetsDevelopmentCaching till true i appinställningsfilen för utvecklingsmiljön (appsettings.Development.json).

Statiska filer i icke-Development miljöer

När du kör en app lokalt aktiveras endast statiska webbtillgångar i utvecklingsmiljön. Om du vill aktivera statiska filer för andra miljöer än Utveckling under lokal utveckling och testning (till exempel i Staging-miljön) ska du anropa UseStaticWebAssets på WebApplicationBuilder.

Warning

Anropa UseStaticWebAssets den exakta miljön för att förhindra aktivering av funktionen i produktion, eftersom den hanterar filer från separata platser på en annan disk än från projektet. Exemplet i det här avsnittet söker efter stagingmiljön med IsStaging.

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

Hantera filer utanför webbrotkatalogen via IWebHostEnvironment.WebRootPath

När IWebHostEnvironment.WebRootPath är inställt på en annan mapp än wwwrootvisas följande standardbeteenden:

  • I utvecklingsmiljön hanteras statiska tillgångar från wwwroot om tillgångar med samma namn finns i båda wwwroot och en annan mapp tilldelad till WebRootPath.
  • Dubbletter av statiska tillgångar hanteras från WebRootPath-mappen i andra miljöer än utveckling.

Överväg att skapa en webbapp från den tomma webbmallen:

  • Innehåller en fil Index.html i wwwroot och wwwroot-custom.
  • Filen Program har uppdaterats för att ange WebRootPath = "wwwroot-custom".
var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    WebRootPath = "wwwroot-custom"
});

Som standard för begäranden till /:

  • I utvecklingsmiljön returneras wwwroot/Index.html.
  • I alla miljöer, utom utveckling, returneras wwwroot-custom/Index.html.

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

  • Ta bort duplicerade namngivna tillgångar i wwwroot.

  • Ange ASPNETCORE_ENVIRONMENT i Properties/launchSettings.json till vilket värde som helst utom Development.

  • Inaktivera statiska webbtillgångar genom att ställa in <StaticWebAssetsEnabled> till false i appens projektfil. VARNING: Om du inaktiverar statiska webbtillgångar inaktiveras Razor klassbibliotek.

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

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

Följande kod uppdaterar WebRootPath till ett värde som inte är ett utvecklingsvärde (Staging), vilket säkerställer att duplicerat innehåll returneras från wwwroot-custom istället för från wwwroot.

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    EnvironmentName = Environments.Staging,
    WebRootPath = "wwwroot-custom"
});

Mellanprogram för statisk fil

Med Static File Middleware möjliggörs statisk filservering i specifika scenarier med statiska filer, vanligtvis utöver konventionerna för att kartlägga routning av statiska resurspunkter (MapStaticAssets).

Static File Middleware ingår i bearbetning av begäranden när UseStaticFiles anropas i appens pipeline för bearbetning av begäranden, vanligtvis efter att Map Static Assets-slutpunktskonventioner (MapStaticAssets) har lagts till.

Map Static Assets-slutpunktskonventioner används i appar som riktar sig mot .NET 9 eller senare. Static File Middleware måste användas i appar som riktar in sig på versioner av .NET före .NET 9.

Static File Middleware hanterar statiska filer, men ger inte samma optimeringsnivå som map static assets-slutpunktskonventioner. Funktionerna för komprimering och identifiering i Map Static Assets Endpoint Conventions är inte tillgängliga när man endast förlitar sig på Static File Middleware.

Slutpunktkonventionerna är optimerade för att leverera resurser som appen har kännedom om vid körningstid. Om appen hanterar tillgångar från andra platser, till exempel disk eller inbäddade resurser, ska Static File Middleware användas.

Följande funktioner som beskrivs i den här artikeln stöds med Static File Middleware men inte med Map Static Assets-slutpunktskonventioner:

Hantera filer utanför webbrotkatalogen via UseStaticFiles

Överväg följande kataloghierarki med statiska filer som finns utanför appens webbrot i en mapp med namnet ExtraStaticFiles:

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

En begäran kan komma åt red-rose.jpg genom att konfigurera en ny instans av Static File Middleware:

Namnområden för följande API:

using Microsoft.Extensions.FileProviders;

I pipelinen för bearbetning av begäran efter det befintliga anropet till antingen MapStaticAssets (.NET 9 eller senare) eller UseStaticFiles (.NET 8 eller tidigare):

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(builder.Environment.ContentRootPath, "ExtraStaticFiles")),
    RequestPath = "/static-files"
});

I föregående kod ExtraStaticFiles exponeras kataloghierarkin offentligt via static-files URL-segmentet. En begäran till https://{HOST}/StaticFiles/images/red-rose.jpg, där {HOST} platshållaren är värden, hanterar red-rose.jpg filen.

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

<img src="static-files/images/red-rose.jpg" alt="A red rose" />

I föregående exempel stöds tilde-slash-notation i Razor Sid- och MVC-vyer (src="~/StaticFiles/images/red-rose.jpg"), inte för Razor komponenter i Blazor appar.

Hantera filer från flera platser

Vägledningen i det här avsnittet 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.

Överväg följande markering som visar en företagslogotyp:

<img src="~/logo.png" asp-append-version="true" alt="Company logo">

Utvecklaren har för avsikt att använda hjälpverktyget för bildtaggen för att lägga till en version och hantera filen från en anpassad plats, en mapp med namnet ExtraStaticFiles.

I följande exempel anropas MapStaticAssets för att hantera filer från wwwroot och UseStaticFiles för att hantera filer från ExtraStaticFiles:

I pipelinen för bearbetning av begäran efter det befintliga anropet till antingen MapStaticAssets (.NET 9 eller senare) eller UseStaticFiles (.NET 8 eller tidigare):

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

I följande exempel anropas UseStaticFiles två gånger för att hantera filer från både wwwroot och ExtraStaticFiles.

I pipelinen för bearbetning av begäranden efter det befintliga anropet till UseStaticFiles:

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

Med hjälp av föregående kod ExtraStaticFiles/logo.png visas filen. Hjälpen för bildtaggen (AppendVersion) tillämpas dock inte eftersom Tag Helper är beroende av WebRootFileProvider, som inte har uppdaterats för att inkludera mappen ExtraStaticFiles.

Följande kod uppdaterar WebRootFileProvider för att inkludera ExtraStaticFiles mappen med hjälp av en CompositeFileProvider. På så sätt kan hjälpverktyget för bildtaggen tillämpa en version på ExtraStaticFiles bilder i mappen.

Namnområde för följande API:

using Microsoft.Extensions.FileProviders;

I pipelinen för bearbetning av begäran före det befintliga anropet till MapStaticAssets (.NET 9 eller senare) eller UseStaticFiles (.NET 8 eller tidigare):

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

var compositeProvider = new CompositeFileProvider(webRootProvider, newPathProvider);

app.Environment.WebRootFileProvider = compositeProvider;

UseStaticFiles och UseFileServer är som standard inställda på att filprovidern 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. Mer information finns i UseStaticFiles som fortfarande behövs med UseFileServer för wwwroot (dotnet/AspNetCore.Docs #15578).

Ange HTTP-svarshuvuden

Använd StaticFileOptions för att ange HTTP-svarshuvuden. Förutom att konfigurera Static File Middleware för att hantera statiska filer anger Cache-Control följande kod rubriken till 604 800 sekunder (en vecka).

Namnområden för följande API:

using Microsoft.AspNetCore.Http;

I pipelinen för bearbetning av begäran efter det befintliga anropet till antingen MapStaticAssets (.NET 9 eller senare) eller UseStaticFiles (.NET 8 eller tidigare):

app.UseStaticFiles(new StaticFileOptions
{
    OnPrepareResponse = ctx =>
    {
        ctx.Context.Response.Headers.Append(
            "Cache-Control", "public, max-age=604800");
    }
});

Stor samling tillgångar

När du hanterar stora samlingar av tillgångar, som anses vara cirka 1 000 eller fler tillgångar, rekommenderar vi att du använder en bundler för att minska det slutliga antalet tillgångar som hanteras av appen eller kombinera MapStaticAssets med UseStaticFiles.

MapStaticAssets läser ivrigt in de förberäknade metadata som samlas in under byggprocessen för resurserna för att stödja komprimering, cachelagring och fingeravtryck. De här funktionerna kostar mer minnesanvändning av appen. För tillgångar som används ofta är det vanligtvis värt kostnaderna. För tillgångar som inte används ofta kanske kompromissen inte är värd kostnaderna.

Om du inte använder paketering rekommenderar vi att du kombinerar MapStaticAssets med UseStaticFiles. I följande exempel visas metoden.

I projektfilen (.csproj) används MSBuild-egenskapen StaticWebAssetEndpointExclusionPattern för att filtrera slutpunkter från det slutliga manifestet för MapStaticAssets. Exkluderade filer hanteras av UseStaticFiles och drar inte nytta av komprimering, cachelagring eller fingerprinting.

När du anger värdet för StaticWebAssetEndpointExclusionPatternbehåller du $(StaticWebAssetEndpointExclusionPattern) för att behålla ramverkets standardundantagsmönster. Lägg till ytterligare mönster i en semikolonavgränsad lista.

I följande exempel lägger exkluderings-patten till de statiska filerna i lib/icons mappen, som representerar en hypotetisk uppsättning ikoner:

<StaticWebAssetEndpointExclusionPattern>
  $(StaticWebAssetEndpointExclusionPattern);lib/icons/**
</StaticWebAssetEndpointExclusionPattern>

Efter bearbetning av HTTPS Redirection Middleware (app.UseHttpsRedirection();) i Program filen:

app.UseStaticFiles();

app.UseAuthorization();

app.MapStaticAssets();

Auktorisering av statisk fil

När en app antar en reservauktoriseringsprincip krävs auktorisering för alla begäranden som inte uttryckligen anger en auktoriseringsprincip, inklusive begäranden om statiska filer efter att Auktorisering mellanprogram bearbetar begäranden. Tillåt anonym åtkomst till statiska filer genom att tillämpa AllowAnonymousAttribute på slutpunktsverktyget för statiska filer:

app.MapStaticAssets().Add(endpointBuilder => 
    endpointBuilder.Metadata.Add(new AllowAnonymousAttribute()));

När en app antar en reservauktoriseringsprincip krävs auktorisering för alla begäranden som inte uttryckligen anger en auktoriseringsprincip, inklusive begäranden om statiska filer efter att Auktorisering mellanprogram bearbetar begäranden. Mallarna ASP.NET Core tillåter anonym åtkomst till statiska filer genom att anropa UseStaticFiles innan du anropar UseAuthorization. De flesta appar följer det här mönstret. När mellanprogrammet för statisk fil 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 webbroten (vanligtvis wwwroot), är offentligt tillgängliga.

Så här hanterar du statiska filer baserat på auktorisering:

  • Bekräfta att appen anger principen för reservautentisering för att kräva autentiserade användare.
  • Lagra den statiska filen utanför appens webbrot.
  • När du har anropat UseAuthorization ska du anropa UseStaticFiles och ange sökvägen till mappen med statiska filer utanför webbroten.

Namnområden för följande API:

using Microsoft.AspNetCore.Authorization;
using Microsoft.Extensions.FileProviders;

Tjänstregistrering:

builder.Services.AddAuthorization(options =>
{
    options.FallbackPolicy = new AuthorizationPolicyBuilder()
        .RequireAuthenticatedUser()
        .Build();
});

I pipelinen för bearbetning av begäran efter anropet till UseAuthorization:

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(builder.Environment.ContentRootPath, "SecureStaticFiles")),
    RequestPath = "/static-files"
});

Namnområden för följande API:

using Microsoft.AspNetCore.Authorization;
using Microsoft.Extensions.FileProviders;

I Startup.ConfigureServices:

services.AddAuthorization(options =>
{
    options.FallbackPolicy = new AuthorizationPolicyBuilder()
        .RequireAuthenticatedUser()
        .Build();
});

I Startup.Configure efter anropet till UseAuthorization:

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(env.ContentRootPath, "SecureStaticFiles")),
    RequestPath = "/static-files"
});

I föregående kod kräver reservauktoriseringsprincipen autentiserade användare. Slutpunkter, till exempel kontroller och Razor Sidor, som anger sina egna auktoriseringskrav använder inte fall-back-auktoriseringsprincipen. Till exempel använder Razor sidor, kontrollanter eller åtgärdsmetoder med [AllowAnonymous] eller [Authorize(PolicyName="MyPolicy")] det använda auktoriseringsattributet i stället för reservauktoriseringspolicyn.

RequireAuthenticatedUser lägger till DenyAnonymousAuthorizationRequirement till den aktuella instansen, vilket framtvingar att den aktuella användaren autentiseras.

Statisk tillgångar som lagras i appens webbrot är offentligt tillgängliga eftersom standard-middleware för statiska filer (UseStaticFiles) anropas före UseAuthorization. Statiska tillgångar i SecureStaticFiles mappen kräver autentisering.

En alternativ metod för att hantera filer baserat på auktorisering är att:

  • Lagra filerna utanför webbroten och alla kataloger som är tillgängliga för Static File Middleware.
  • Hantera filerna via en åtgärdsmetod som auktorisering tillämpas på och returnera ett FileResult objekt.

Från en Razor sida (Pages/BannerImage.cshtml.cs):

public class BannerImageModel : PageModel
{
    private readonly IWebHostEnvironment _env;

    public BannerImageModel(IWebHostEnvironment env) => _env = env;

    public PhysicalFileResult OnGet()
    {
        var filePath = Path.Combine(
            _env.ContentRootPath, "SecureStaticFiles", "images", "red-rose.jpg");

        return PhysicalFile(filePath, "image/jpeg");
    }
}

Från en styrenhet (Controllers/HomeController.cs):

[Authorize]
public IActionResult BannerImage()
{
    var filePath = Path.Combine(
        _env.ContentRootPath, "SecureStaticFiles", "images", "red-rose.jpg");

    return PhysicalFile(filePath, "image/jpeg");
}

Föregående metod kräver en sida eller slutpunkt per fil.

Följande vägslutpunktsexempel returnerar filer för autentiserade användare.

I filen Program:

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("AuthenticatedUsers", b => b.RequireAuthenticatedUser());
});

...

app.MapGet("/files/{fileName}", IResult (string fileName) => 
{
    var filePath = GetOrCreateFilePath(fileName);

    if (File.Exists(filePath))
    {
        return TypedResults.PhysicalFile(filePath, fileName);
    }

    return TypedResults.NotFound("No file found with the supplied file name");
})
.WithName("GetFileByName")
.RequireAuthorization("AuthenticatedUsers");

Följande exempel på routningsslutpunkt laddar upp filer för autentiserade användare i administratörsrollen ("admin").

I filen Program:

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("AdminsOnly", b => b.RequireRole("admin"));
});

...

// IFormFile uses memory buffer for uploading. For handling large 
// files, use streaming instead. See the *File uploads* article
// in the ASP.NET Core documentation:
// https://free.blessedness.top/aspnet/core/mvc/models/file-uploads
app.MapPost("/files", async (IFormFile file, LinkGenerator linker, 
    HttpContext context) =>
{
    // Don't rely on the value in 'file.FileName', as it's only metadata that can 
    // be manipulated by the end-user. Consider the 'Utilities.IsFileValid' method 
    // that takes an 'IFormFile' and validates its signature within the 
    // 'AllowedFileSignatures'.

    var fileSaveName = Guid.NewGuid().ToString("N") + 
        Path.GetExtension(file.FileName);
    await SaveFileWithCustomFileName(file, fileSaveName);

    context.Response.Headers.Append("Location", linker.GetPathByName(context, 
        "GetFileByName", new { fileName = fileSaveName}));

    return TypedResults.Ok("File Uploaded Successfully!");
})
.RequireAuthorization("AdminsOnly");

I Startup.ConfigureServices:

services.AddAuthorization(options =>
{
    options.AddPolicy("AuthenticatedUsers", b => b.RequireAuthenticatedUser());
});

I Startup.Configure:

app.MapGet("/files/{fileName}", IResult (string fileName) => 
{
    var filePath = GetOrCreateFilePath(fileName);

    if (File.Exists(filePath))
    {
        return TypedResults.PhysicalFile(filePath, fileName);
    }

    return TypedResults.NotFound("No file found with the supplied file name");
})
.WithName("GetFileByName")
.RequireAuthorization("AuthenticatedUsers");

Följande kod laddar upp filer för autentiserade användare i administratörsrollen ("admin").

I Startup.ConfigureServices:

services.AddAuthorization(options =>
{
    options.AddPolicy("AdminsOnly", b => b.RequireRole("admin"));
});

I Startup.Configure:

// IFormFile uses memory buffer for uploading. For handling large 
// files, use streaming instead. See the *File uploads* article
// in the ASP.NET Core documentation:
// https://free.blessedness.top/aspnet/core/mvc/models/file-uploads
app.MapPost("/files", async (IFormFile file, LinkGenerator linker, 
    HttpContext context) =>
{
    // Don't rely on the value in 'file.FileName', as it's only metadata that can 
    // be manipulated by the end-user. Consider the 'Utilities.IsFileValid' method 
    // that takes an 'IFormFile' and validates its signature within the 
    // 'AllowedFileSignatures'.

    var fileSaveName = Guid.NewGuid().ToString("N") + 
        Path.GetExtension(file.FileName);
    await SaveFileWithCustomFileName(file, fileSaveName);

    context.Response.Headers.Append("Location", linker.GetPathByName(context, 
        "GetFileByName", new { fileName = fileSaveName}));

    return TypedResults.Ok("File Uploaded Successfully!");
})
.RequireAuthorization("AdminsOnly");

Katalogbläddring

Katalogbläddring tillåter kataloglistning inom angivna kataloger.

Katalogbläddring är inaktiverat som standard av säkerhetsskäl. Mer information finns i Säkerhetsöverväganden för statiska filer.

Aktivera katalogbläddring med följande API:

I följande exempel:

  • En images mapp i appens rot innehåller bilder för katalogbläddring.
  • Begärandesökvägen för att bläddra bland bilderna är /DirectoryImages.
  • Om du anropar UseStaticFiles och ställer in FileProvider av StaticFileOptions så att du kan visa webbläsarlänkar till de enskilda filerna.

Namnområden för följande API:

using Microsoft.AspNetCore.StaticFiles;
using Microsoft.Extensions.FileProviders;

Tjänstregistrering:

builder.Services.AddDirectoryBrowser();

I pipelinen för bearbetning av begäran efter det befintliga anropet till antingen MapStaticAssets (.NET 9 eller senare) eller UseStaticFiles (.NET 8 eller tidigare):

var fileProvider = new PhysicalFileProvider(
    Path.Combine(builder.Environment.WebRootPath, "images"));
var requestPath = "/DirectoryImages";

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = fileProvider,
    RequestPath = requestPath
});

app.UseDirectoryBrowser(new DirectoryBrowserOptions
{
    FileProvider = fileProvider,
    RequestPath = requestPath
});

Namnområden för följande API:

using Microsoft.Extensions.FileProviders;
using System.IO;

I Startup.ConfigureServices:

services.AddDirectoryBrowser();

I Startup.Configure efter det befintliga anropet till UseStaticFiles:

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(env.WebRootPath, "images")),
    RequestPath = "/DirectoryImages"
});

app.UseDirectoryBrowser(new DirectoryBrowserOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(env.WebRootPath, "images")),
    RequestPath = "/DirectoryImages"
});

Föregående kod tillåter katalogbläddring i mappen wwwroot/images med hjälp av URL:en https://{HOST}/DirectoryImages med länkar till varje fil och mapp, där platshållaren {HOST} representerar värden.

AddDirectoryBrowser lägger till tjänster som krävs av katalogbläddringsmellanprogram, inklusive HtmlEncoder. Dessa tjänster kan läggas till av andra anrop, till exempel AddRazorPages, men vi rekommenderar att du anropar AddDirectoryBrowser för att säkerställa att tjänsterna läggs till.

Hantera standarddokument

Om du anger en standardsida får besökare en startpunkt på en webbplats. Om du vill hantera en standardfil från wwwroot utan att begärande-URL:en måste innehålla filens namn anropar UseDefaultFiles du metoden.

UseDefaultFiles är en URL-omskrivare som inte serverar filen. I pipelinen för bearbetning av begäran före det befintliga anropet till antingen MapStaticAssets (.NET 9 eller senare) eller UseStaticFiles (.NET 8 eller tidigare):

app.UseDefaultFiles();

Med UseDefaultFilessöker begäranden till en mapp i wwwroot efter:

  • default.htm
  • default.html
  • index.htm
  • index.html

Den första filen som hittades i listan hanteras som om begäran innehöll filens namn. Webbläsarens URL fortsätter att återspegla den begärda URI:n.

Följande kod ändrar standardfilnamnet till default-document.html:

var options = new DefaultFilesOptions();
options.DefaultFileNames.Clear();
options.DefaultFileNames.Add("default-document.html");
app.UseDefaultFiles(options);

Kombinera statiska filer, standarddokument och katalogbläddring

UseFileServer kombinerar funktionerna i UseStaticFiles, UseDefaultFilesoch eventuellt UseDirectoryBrowser.

I pipelinen för bearbetning av begäran efter det befintliga anropet till antingen MapStaticAssets (.NET 9 eller senare) eller UseStaticFiles (.NET 8 eller tidigare) anropar du UseFileServer för att aktivera servering av statiska filer och standardfilen:

app.UseFileServer();

Katalogbläddring är inte aktiverat för föregående exempel.

Följande kod möjliggör servering av statiska filer, standardfilen och katalogbläddring.

Tjänstregistrering:

builder.Services.AddDirectoryBrowser();

I pipelinen för bearbetning av begäranden efter det befintliga anropet till UseStaticFiles:

app.UseFileServer(enableDirectoryBrowsing: true);

I Startup.ConfigureServices:

services.AddDirectoryBrowser();

I Startup.Configure efter det befintliga anropet till UseStaticFiles:

app.UseFileServer(enableDirectoryBrowsing: true);

För värdadressen (/) UseFileServer returnerar standard-HTML-dokumentet före standardsidan Razor (Pages/Index.cshtml) eller MVC-standardvyn (Home/Index.cshtml).

Överväg följande kataloghierarki:

  • wwwroot
    • css
    • images
    • js
  • ExtraStaticFiles
    • images
      • logo.png
    • default.html

Följande kod möjliggör servering av statiska filer, standardfilen och katalogbläddring av ExtraStaticFiles.

Namnområden för följande API:

using Microsoft.Extensions.FileProviders;

Tjänstregistrering:

builder.Services.AddDirectoryBrowser();

I pipelinen för bearbetning av begäranden efter det befintliga anropet till UseStaticFiles:

app.UseFileServer(new FileServerOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(builder.Environment.ContentRootPath, "ExtraStaticFiles")),
    RequestPath = "/static-files",
    EnableDirectoryBrowsing = true
});

Namnområden för följande API:

using Microsoft.Extensions.FileProviders;
using System.IO;

I Startup.ConfigureServices:

services.AddDirectoryBrowser();

I Startup.Configure efter det befintliga anropet till UseStaticFiles:

app.UseFileServer(new FileServerOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(env.ContentRootPath, "ExtraStaticFiles")),
    RequestPath = "/static-files",
    EnableDirectoryBrowsing = true
});

AddDirectoryBrowser måste anropas när EnableDirectoryBrowsing egenskapsvärdet är true.

Med hjälp av föregående filhierarki och kod matchar URL:er enligt följande tabell ( {HOST} platshållaren är värden).

URI Svarsfil
https://{HOST}/static-files/images/logo.png ExtraStaticFiles/images/logo.png
https://{HOST}/static-files ExtraStaticFiles/default.html

Om det inte finns någon fil med standardnamn i ExtraStaticFiles-katalogen returnerar https://{HOST}/static-files kataloglistan med klickbara länkar, där platshållaren {HOST} är värd.

UseDefaultFiles och UseDirectoryBrowser utför en omdirigering på klientsidan från mål-URI:n utan en avslutande / till mål-URI:n med en avslutande /. Till exempel från https://{HOST}/static-files (ingen avslutande /) till https://{HOST}/static-files/ (innehåller en avslutande /). Relativa URL:er i ExtraStaticFiles katalogen är ogiltiga utan ett avslutande snedstreck (/) om inte RedirectToAppendTrailingSlash alternativet DefaultFilesOptions används.

Mappa filnamnstillägg till MIME-typer

Note

Vägledning som gäller för Blazor appar finns i ASP.NET Core statiska filerBlazor.

Använd FileExtensionContentTypeProvider.Mappings för att lägga till eller ändra filnamnstillägg till MIME-innehållstypmappningar. I följande exempel mappas flera filnamnstillägg till kända MIME-typer. Tillägget .rtf ersätts och .mp4 tas bort:

using Microsoft.AspNetCore.StaticFiles;
using Microsoft.Extensions.FileProviders;

...

// Set up custom content types - associating file extension to MIME type
var provider = new FileExtensionContentTypeProvider();
// Add new mappings
provider.Mappings[".myapp"] = "application/x-msdownload";
provider.Mappings[".htm3"] = "text/html";
provider.Mappings[".image"] = "image/png";
// Replace an existing mapping
provider.Mappings[".rtf"] = "application/x-msdownload";
// Remove MP4 videos
provider.Mappings.Remove(".mp4");

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

När du har flera alternativ för statiska filer att konfigurera kan du ange providern med hjälp av StaticFileOptions:

var provider = new FileExtensionContentTypeProvider();

...

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

app.UseStaticFiles();

I Startup.Configure:

using Microsoft.AspNetCore.StaticFiles;
using Microsoft.Extensions.FileProviders;
using System.IO;

...

// Set up custom content types - associating file extension to MIME type
var provider = new FileExtensionContentTypeProvider();
// Add new mappings
provider.Mappings[".myapp"] = "application/x-msdownload";
provider.Mappings[".htm3"] = "text/html";
provider.Mappings[".image"] = "image/png";
// Replace an existing mapping
provider.Mappings[".rtf"] = "application/x-msdownload";
// Remove MP4 videos
provider.Mappings.Remove(".mp4");

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(env.WebRootPath, "images")),
    RequestPath = "/images",
    ContentTypeProvider = provider
});

app.UseDirectoryBrowser(new DirectoryBrowserOptions
{
    FileProvider = new PhysicalFileProvider(
        Path.Combine(env.WebRootPath, "images")),
    RequestPath = "/images"
});

Mer information finns i MIME-innehållstyper.

Innehållstyper som inte är standard

Static File Middleware förstår nästan 400 kända filinnehållstyper. Om användaren begär en fil med en okänd filtyp skickar Static File Middleware begäran till nästa mellanprogram i pipelinen. Om inget mellanprogram hanterar begäran returneras ett 404 Hittades inte svar. Om katalogbläddring är aktiverat visas en länk till filen i en kataloglista.

Följande kod gör det möjligt att hantera okända innehållstyper och renderar den okända filen som en bild:

app.UseStaticFiles(new StaticFileOptions
{
    ServeUnknownFileTypes = true,
    DefaultContentType = "image/png"
});

Med föregående kod returneras en begäran om en fil med en okänd innehållstyp som en bild.

Warning

Att aktivera ServeUnknownFileTypes är en säkerhetsrisk. Den är inaktiverad som standard och dess användning rekommenderas inte. Mappa filnamnstillägg till MIME-typer är ett säkrare alternativ till att hantera filer med tillägg som inte är standard.

Ange ett anpassat manifest för statiska filer

Om staticAssetsManifestPath är null används IHostEnvironment.ApplicationName för att hitta manifestet. Du kan också ange en fullständig sökväg till manifestfilen. Om en relativ sökväg används söker ramverket efter filen i AppContext.BaseDirectory.

Säkerhetsöverväganden för statiska filer

Warning

UseDirectoryBrowser och UseStaticFiles kan läcka hemligheter. Vi rekommenderar starkt att du inaktiverar katalogbläddring i produktion. Granska noggrant vilka kataloger som är aktiverade via UseStaticFiles eller UseDirectoryBrowser. Hela katalogen och dess underkataloger blir offentligt tillgängliga. Lagra filer som är lämpliga för att betjäna allmänheten i en dedikerad katalog, till exempel <content_root>/wwwroot. Avgränsa dessa filer från MVC-vyer, Razor sidor, konfigurationsfiler osv.

  • URL:er för innehåll som exponeras med UseDirectoryBrowser och UseStaticFiles omfattas av skiftlägeskänsligheten och teckenbegränsningarna för det underliggande filsystemet. Windows är till exempel skiftlägesokänsligt, men macOS och Linux är det inte.

  • ASP.NET Core-appar som finns i IIS använder ASP.NET Core Module för att vidarebefordra alla begäranden till appen, inklusive statiska filbegäranden. Den statiska IIS-filhanteraren används inte och har ingen chans att hantera begäranden.

  • Slutför följande steg i IIS-hanteraren för att ta bort den statiska IIS-filhanteraren på server- eller webbplatsnivå:

    1. Gå till funktionen Moduler.
    2. Välj StaticFileModule i listan.
    3. Klicka på Ta bort i sidofältet Åtgärder.

Warning

Om den statiska IIS-filhanteraren är aktiverad och ASP.NET Core Module har konfigurerats felaktigt, hanteras statiska filer. Detta inträffar till exempel om web.config filen inte har distribuerats.

  • Placera kodfiler, inklusive .cs och .cshtml, utanför appprojektets webbrot. Därför skapas en logisk separation mellan appens innehåll på klientsidan och serverbaserad kod. Detta förhindrar att kod på serversidan läcker ut.

MSBuild-egenskaper

Följande tabeller visar msBuild-egenskaper och metadatabeskrivningar för statiska filer.

Fastighet Description
EnableDefaultCompressedItems Aktiverar standardkomprimering: inkludera/exkludera mönster.
CompressionIncludePatterns Semikolonavgränsad lista över filmönster som ska ingå för komprimering.
CompressionExcludePatterns Semikolonavgränsad lista över filmönster som ska undantas från komprimering.
EnableDefaultCompressionFormats Aktiverar standardkomprimeringsformat (Gzip och Brotli).
BuildCompressionFormats Komprimeringsformat som ska användas under bygget.
PublishCompressionFormats Komprimeringsformat som ska användas under publiceringen.
DisableBuildCompression Inaktiverar komprimering under bygget.
CompressDiscoveredAssetsDuringBuild Komprimerar identifierade tillgångar under bygget.
BrotliCompressionLevel Komprimeringsnivå för Brotli-algoritmen.
StaticWebAssetBuildCompressAllAssets Komprimerar alla resurser under byggprocessen, inte bara resurser som identifieras eller beräknas under en byggprocess.
StaticWebAssetPublishCompressAllAssets Komprimerar alla tillgångar vid utgivning, inte bara tillgångar som upptäcks eller beräknas under en kompilering.
Fastighet Description
StaticWebAssetBasePath Grundläggande URL-sökväg för alla tillgångar i ett bibliotek.
StaticWebAssetsFingerprintContent Aktiverar fingeravtryck för innehåll för cache-busting.
StaticWebAssetFingerprintingEnabled Aktiverar fingeravtrycksfunktionen för statiska webbtillgångar.
StaticWebAssetsCacheDefineStaticWebAssetsEnabled Aktiverar cachelagring för statiska webbtillgångsdefinitioner.
StaticWebAssetEndpointExclusionPattern Mönster för exkludering av slutpunkter.
Artikelgrupp Description Metainformation
StaticWebAssetContentTypeMapping Mappar filmönster till innehållstyper och cachehuvuden för slutpunkter. Pattern, Cache
StaticWebAssetFingerprintPattern Definierar mönster för att tillämpa fingeravtryck på statiska webbtillgångar för cachelagring. Pattern, Expression

Metadatabeskrivningar:

  • Pattern: Ett globmönster som används för att matcha filer. För StaticWebAssetContentTypeMappingmatchar den filer för att fastställa deras innehållstyp (till exempel *.js för JavaScript-filer). För StaticWebAssetFingerprintPatternidentifierar den filer med flera tillägg som kräver särskild fingeravtrycksbehandling (till exempel *.lib.module.js).

  • Cache: Anger Cache-Control rubrikvärdet för den matchade innehållstypen. Detta styr webbläsarens cachelagringsbeteende (till exempel max-age=3600, must-revalidate för mediefiler).

  • Expression: Definierar hur fingeravtrycket infogas i filnamnet. Standardvärdet är #[.{FINGERPRINT}], vilket infogar fingeravtrycket ({FINGERPRINT} platshållare) före förlängningen.

I följande exempel mappas bitmappsfilmönstret (.bmp) till image/bmp innehållstypen med {CACHE HEADER} platshållaren som representerar Cache-Control rubriken som ska användas för slutpunkter som inte har fingeravtryck:

<ItemGroup>
  <StaticWebAssetContentTypeMapping Include="image/bmp" Cache="{CACHE HEADER}" Pattern="*.bmp" />
</ItemGroup>

Konfigurationsalternativ för körtid

I följande tabell beskrivs konfigurationsalternativ för körningstid.

Konfigurationsnyckel Description
ReloadStaticAssetsAtRuntime Möjliggör hotladdning av statiska resurser under utvecklingstid: serverar ändrade webbrotsfiler (wwwroot) (beräknar om ETag och komprimerar om det behövs) istället för förutbestämda manifestversioner. Standardvärdet är endast aktiverat när du hanterar ett byggmanifest om det inte uttryckligen anges.
DisableStaticAssetNotFoundRuntimeFallback När true används, inaktiverar det den återställningsslutpunkt som hanterar nyligen tillagda filer som inte finns i byggmanifestet. När false är närvarande eller saknas, använder en fil-existeringskontrollerad {**path} reservmetod (GET/HEAD) en varning och levererar filen med en beräknad ETag.
EnableStaticAssetsDevelopmentCaching När true bevaras de ursprungliga Cache-Control rubrikerna på tillgångsbeskrivningar. När false är närvarande eller frånvarande skrivs Cache-Control-rubriker om till no-cache för att undvika aggressiv klientcachelagring under utveckling.
EnableStaticAssetsDevelopmentIntegrity När true, behåller integritetsegenskaper på tillgångsbeskrivningar. När false är frånvarande, tar det bort integritetsegenskapen för att förhindra felmatchningar när filer ändras under utvecklingen.

Ytterligare resurser