Sdílet prostřednictvím

Statické soubory v ASP.NET Core

Note

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

Warning

Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v zásadách podpory .NET a .NET Core. Aktuální verzi tohoto článku najdete ve verzi .NET 9.

Statické soubory, označované také jako statické prostředky, jsou soubory aplikace ASP.NET Core, které se negenerují dynamicky. Místo toho jsou poskytovány přímo klientům na vyžádání, jako jsou soubory HTML, CSS, obrázky a JavaScript.

Pokud chcete pokyny k Blazor statickým souborům, které doplňují nebo nahrazují pokyny v tomto článku, přečtěte si téma ASP.NET Core Blazor statické soubory.

Pokud chcete povolit zpracování statických souborů v ASP.NET Core, zavolejte MapStaticAssets.

Ve výchozím nastavení se statické soubory ukládají do webového kořenového adresáře projektu. Výchozí adresář je {CONTENT ROOT}/wwwroot, kde je zástupný prvek {CONTENT ROOT}kořen obsahu aplikace. Pouze soubory ve složce wwwroot budou adresovatelné, takže se nemusíte starat o zbytek kódu.

Statické webové prostředky jsou považovány za pouze soubory s konkrétními příponami souborů spojené s podporovanými typy médií.

Statické webové prostředky jsou zjištěny v době sestavení a optimalizovány pomocí otisku prstu založeného na obsahu, aby se zabránilo opakovanému použití starých souborů. Prostředky se také komprimují, aby se zkrátila doba jejich doručení.

Zjištěné statické webové prostředky se za běhu zveřejňují jako koncové body s použitými hlavičkami HTTP, jako jsou hlavičky ukládání do mezipaměti a hlavičky typu obsahu. Prostředek se podává jednou, dokud se soubor nezmění nebo prohlížeč vymaže jeho mezipaměť. Jsou nastaveny hlavičky ETag, Last-Modified a Content-Type. Prohlížeči je znemožněno používat zastaralé prostředky po aktualizaci aplikace.

Doručování statických prostředků je založené na směrování koncových bodů, takže funguje s dalšími funkcemi pracujícími s koncovými body, jako je autorizace. Je navržená tak, aby fungovala se všemi architekturami uživatelského rozhraní, včetně Blazor, Razor Pages a MVC.

Statické zdroje pro mapování poskytují následující výhody:

  • Komprese při sestavení pro všechny prostředky v aplikaci, včetně JavaScriptu (JS) a šablon stylů, ale kromě obrázků a písem, které jsou již komprimované. komprese Gzip (Content-Encoding: gz) se používá při vývoji. Při publikování se používají komprese Gzip a Brotli (Content-Encoding: br).
  • Označování všech prostředků při sestavování s použitím Base64-kódovaného řetězce SHA-256 hashe 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. Prostředky s otisky prstů jsou uloženy do mezipaměti pomocí direktivy immutable, což vede k tomu, že prohlížeč již prostředek nepožaduje, dokud se nezmění. Pro prohlížeče, které nepodporují direktivu immutable, se přidá max-age direktiva.
    • I když prostředek nemá otisk prstu, pro každý statický prostředek se generuje obsah založený na ETags pomocí hash otisku prstu souboru jako hodnoty ETag. Tím se zajistí, že prohlížeč stáhne jenom soubor, pokud se změní jeho obsah (nebo se soubor poprvé stáhne).
    • Rámec interně mapuje fyzické prostředky na jejich otisky prstů, což aplikaci umožňuje:
      • Vyhledejte automaticky generované prostředky, jako je komponent Razor s omezeným dosahem CSS pro izolaci CSS funkce Blazor a prostředky JS popsané import mapami JS.
      • Vygenerujte odkazové tagy v obsahové části <head> stránky za účelem předběžného načtení prostředků.

Mapové statické prostředky neposkytují funkce pro minifikace ani jiné transformace souborů. Minifikace se obvykle zpracovává vlastním kódem nebo nástroji třetích stran.

Pokud chcete povolit zpracování statických souborů v ASP.NET Core, zavolejte UseStaticFiles.

Ve výchozím nastavení se statické soubory ukládají do webového kořenového adresáře projektu. Výchozí adresář je {CONTENT ROOT}/wwwroot, kde je zástupný prvek {CONTENT ROOT}kořen obsahu aplikace. Pouze soubory ve složce wwwroot budou adresovatelné, takže se nemusíte starat o zbytek kódu.

Za běhu vrátí statický webový prostředek middleware statického souboru, pokud se požaduje s úpravami prostředků a použitými hlavičkami typu obsahu. Jsou nastaveny hlavičky ETag, Last-Modified a Content-Type.

Middleware pro statické soubory umožňuje obsluhu statických souborů a používá ji aplikace, když je volána v procesním řetězci požadavků aplikace. Soubory se obsluhují z cesty zadané v IWebHostEnvironment.WebRootPath nebo WebRootFileProvider, která standardně odpovídá webové kořenové složce, obvykle wwwroot.

Můžete také obsluhovat statické webové prostředky z odkazovaných projektů a balíčků.

Změna webového kořenového adresáře

Tuto metodu UseWebRoot použijte, pokud chcete změnit kořenový adresář webu. Další informace najdete v tématu ASP.NET Základní přehled.

Zabránit publikování souborů v wwwroot pomocí <Content> položky projektu v souboru projektu. Následující příklad brání publikování obsahu ve wwwroot/local a jeho podadresářích:

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

Metoda CreateBuilder nastaví kořen obsahu na aktuální adresář:

var builder = WebApplication.CreateBuilder(args);

Metoda CreateDefaultBuilder nastaví kořen obsahu na aktuální adresář:

Host.CreateDefaultBuilder(args)

V kanálu zpracování požadavků po volání UseHttpsRedirection zavolejte MapStaticAssets v kanálu zpracování požadavků aplikace k umožnění obsluhování statických souborů z webového kořenového adresáře aplikace:

app.MapStaticAssets();

V kanálu zpracování požadavků po volání UseHttpsRedirection zavolejte UseStaticFiles v kanálu zpracování požadavků aplikace k umožnění obsluhování statických souborů z webového kořenového adresáře aplikace:

app.UseStaticFiles();

Statické soubory jsou přístupné prostřednictvím cesty relativní k kořenovému adresáři webu.

Přístup k obrázku wwwroot/images/favicon.pngna adrese:

  • Formát adresy URL: https://{HOST}/images/{FILE NAME}
    • Zástupný symbol {HOST} je hostitel.
    • Zástupný {FILE NAME} symbol je název souboru.
  • Příklady
    • Absolutní adresa URL: https://localhost:5001/images/favicon.png
    • Relativní adresa URL kořenového adresáře: images/favicon.png

Blazor V aplikaci images/favicon.png načte obrázek ikony (favicon.png) ze složky aplikacewwwroot/images:

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

V aplikacích Pages a MVC znak Razor tilda odkazuje na webový kořen. V následujícím příkladu ~/images/favicon.png načte obrázek ikony (favicon.png) ze složky aplikace wwwroot/images :

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

Přeskočit middleware vrstvu

Aby se zabránilo spuštění celého kanálu middlewaru po spárování statického UseStaticFiles prostředku, což je toto chování, volejte ShortCircuit na MapStaticAssets. Volání ShortCircuit okamžitě spustí koncový bod a vrátí odpověď, což brání spuštění jiného middlewaru pro požadavky na statické prostředky:

app.MapStaticAssets().ShortCircuit();

Řízení ukládání statických souborů do mezipaměti během vývoje

Když běží ve vývojovém prostředí, například během vývojového testování Visual Studio Hot Reload, rámec přepíše hlavičky mezipaměti, aby zabránil prohlížečům v ukládání statických souborů do mezipaměti. To pomáhá zajistit, aby se při změně souborů používala nejnovější verze souborů, aby nedocházelo k problémům se zastaralým obsahem. V produkčním prostředí jsou nastaveny správné hlavičky mezipaměti, což umožňuje prohlížečům ukládat statické prostředky do mezipaměti podle očekávání.

Pokud chcete toto chování zakázat, nastavte EnableStaticAssetsDevelopmentCaching na true v souboru nastavení aplikace pro vývojové prostředí (appsettings.Development.json).

Statické soubory v jiných prostředíchDevelopment

Při místním spuštění aplikace jsou statické webové prostředky povoleny pouze ve vývojovém prostředí. Pokud chcete povolit statické soubory pro jiná prostředí než pro Vývoj během místního vývoje a testování (například v přípravném prostředí), zavolejte UseStaticWebAssets na WebApplicationBuilder.

Warning

Pro zavolání UseStaticWebAssets na konkrétní prostředí je potřeba, aby se funkce neaktivovala v produkci, protože soubory jsou obsluhovány z jiných umístění na disku než z projektu. Příklad v této části kontroluje stagingové prostředí pomocí IsStaging.

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

Obsluha souborů mimo webový kořenový adresář prostřednictvím IWebHostEnvironment.WebRootPath

Pokud IWebHostEnvironment.WebRootPath je nastavena na jinou složku než wwwroot, zobrazí se následující výchozí chování:

  • Ve vývojovém prostředí jsou statické prostředky podávány z wwwroot, pokud se prostředky se stejným názvem nachází ve složkách wwwroot a zároveň v jiné složce přiřazené WebRootPath.
  • V jakémkoli jiném prostředí než ve vývoji jsou duplicitní statické prostředky obsluhovány ze složky WebRootPath.

Představte si webovou aplikaci vytvořenou z prázdné webové šablony:

  • Index.html Obsahující soubor v wwwroot a wwwroot-custom.
  • Soubor Program je aktualizován tak, aby nastavil WebRootPath = "wwwroot-custom".
var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    WebRootPath = "wwwroot-custom"
});

Ve výchozím nastavení u požadavků na /:

  • Ve vývojovém prostředí se vrátí wwwroot/Index.html.
  • V jakémkoli jiném prostředí než vývojovém se vrátí wwwroot-custom/Index.html.

Pokud chcete zajistit, aby aktiva z wwwroot-custom byla vždy dostupná, použijte jeden z následujících způsobů:

  • Odstraňte prostředky se stejnými názvy v wwwroot.

  • Nastavit ASPNETCORE_ENVIRONMENT v Properties/launchSettings.json na libovolnou hodnotu kromě Development.

  • Zakažte statické webové prostředky nastavením <StaticWebAssetsEnabled> na false v souboru projektu aplikace. VAROVÁNÍ: Zakázání statických webových prostředků znemožňuje funkčnost Razor knihoven tříd.

  • Do souboru projektu přidejte následující KÓD XML:

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

Následující kód aktualizuje WebRootPath na hodnotu, která není určená pro vývoj (Staging), což zaručuje, že duplicitní obsah bude vrácen z wwwroot-custom místo wwwroot.

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

Middleware statického souboru

Middleware statických souborů umožňuje poskytování statických souborů v konkrétních scénářích, obvykle se používá vedle konvencí směrování koncových bodů mapování statických prostředků (MapStaticAssets).

Middleware pro statické soubory je zahrnuto do zpracování požadavků, když je UseStaticFiles voláno v kanálu zpracování požadavků aplikace, obvykle po přidání konvencí koncového bodu pro mapování statických prostředků (MapStaticAssets).

Konvence koncových bodů pro statické prostředky se používají v aplikacích, které cílí na rozhraní .NET 9 nebo novější. Middleware pro statické soubory se musí používat v aplikacích, které mají cílit na verze .NET před verzí .NET 9.

Middleware pro statické soubory obsluhuje statické soubory, ale neposkytuje stejnou úroveň optimalizace jako konvence koncových bodů pro statické prostředky Map. Funkce komprese a fingerprintování konvencí koncových bodů pro mapové statické prostředky nejsou k dispozici, pokud se spoléháte pouze na Middleware statických souborů.

Konvence koncových bodů jsou optimalizované pro poskytování prostředků, které aplikace je schopna rozeznat za běhu. Pokud aplikace obsluhuje prostředky z jiných umístění, jako jsou disky nebo vložené prostředky, mělo by se použít middleware pro statické soubory.

V middlewaru pro statické soubory se podporují následující funkce, které jsou popsány v tomto článku, ale ne s konvencemi koncových bodů mapování statických souborů.

Obsluha souborů mimo webový kořenový adresář prostřednictvím UseStaticFiles

Zvažte následující hierarchii adresářů se statickými soubory umístěnými mimo webovou kořenovou složku aplikace ve složce s názvem ExtraStaticFiles:

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

Požadavek může získat přístup red-rose.jpg konfigurací nové instance middlewaru statického souboru:

Jmenné prostory pro následující rozhraní API:

using Microsoft.Extensions.FileProviders;

V kanálu zpracování požadavků po existujícím volání buď MapStaticAssets (.NET 9 nebo novější), nebo UseStaticFiles (.NET 8 nebo starší):

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

V předchozím kódu ExtraStaticFiles se hierarchie adresářů veřejně zveřejní prostřednictvím static-files segmentu adresy URL. Požadavek na https://{HOST}/StaticFiles/images/red-rose.jpg, kde {HOST} je zástupce hostitele, zpracovává red-rose.jpg soubor.

Následující odkazy na označení ExtraStaticFiles/images/red-rose.jpg:

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

V předchozím příkladu je v zobrazeních Pages a MVC podporována Razor notace tilda-slash (src="~/StaticFiles/images/red-rose.jpg"), nikoli pro Razor komponenty v Blazor aplikacích.

Obsluha souborů z více umístění

Pokyny v této části platí pro Razor aplikace Pages a MVC. Pokyny vztahující se k Blazor Web Apps najdete v tématu Blazor.

Představte si následující značky, které zobrazují logo společnosti:

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

Vývojář hodlá použít Image Tag Helper k přidání verze a poskytování souboru z vlastního umístění, složky s názvem ExtraStaticFiles.

Následující příklad volá MapStaticAssets k obsluhování souborů z wwwroot a UseStaticFiles k obsluhování souborů z ExtraStaticFiles:

V kanálu zpracování požadavků po existujícím volání buď MapStaticAssets (.NET 9 nebo novější), nebo UseStaticFiles (.NET 8 nebo starší):

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

Následující příklad volá UseStaticFiles dvakrát, aby obsluhoval soubory z adresářů wwwroot a ExtraStaticFiles.

V kanálu zpracování požadavků po existujícím volání UseStaticFiles:

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

Pomocí předchozího kódu ExtraStaticFiles/logo.png se soubor zobrazí. Pomocník Image Tag Helper (AppendVersion) se ale neuplatní, protože závisí na WebRootFileProvider, který nebyl aktualizován, aby zahrnoval složku ExtraStaticFiles.

Následující kód aktualizuje WebRootFileProvider tak, aby zahrnoval složku ExtraStaticFiles pomocí CompositeFileProvider. To umožňuje Image Tag Helperu použít verzi pro obrázky ve složce ExtraStaticFiles.

Namespace pro následující rozhraní API:

using Microsoft.Extensions.FileProviders;

V kanálu zpracování požadavků před existujícím voláním MapStaticAssets (.NET 9 nebo novější) nebo UseStaticFiles (.NET 8 nebo starší):

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 a UseFileServer ve výchozím nastavení odkazují na zprostředkovatele souborů ukazujícího na wwwroot. Další instance UseStaticFiles a UseFileServer mohou být poskytovány s jinými poskytovateli souborů, aby obsluhovaly soubory z jiných umístění. Další informace naleznete v tématu UseStaticFiles je stále vyžadováno s UseFileServer pro wwwroot (dotnet/AspNetCore.Docs #15578).

Nastavení hlaviček odpovědí HTTP

Slouží StaticFileOptions k nastavení hlaviček odpovědi HTTP. Kromě konfigurace statického middlewaru pro obsluhu statických souborů nastaví následující kód hlavičkuCache-Control na 604 800 sekund (jeden týden).

Jmenné prostory pro následující rozhraní API:

using Microsoft.AspNetCore.Http;

V kanálu zpracování požadavků po existujícím volání buď MapStaticAssets (.NET 9 nebo novější), nebo UseStaticFiles (.NET 8 nebo starší):

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

Rozsáhlá kolekce prostředků

Při práci s velkými kolekcemi prostředků, které se považují za přibližně 1 000 nebo více prostředků, doporučujeme použít bundler ke snížení konečného počtu prostředků, které aplikace obsluhuje, nebo kombinovat MapStaticAssets s UseStaticFiles.

MapStaticAssets Dychtivě načte předem vypočítaná metadata zachycená během procesu sestavení prostředků, aby podporovala kompresi, ukládání do mezipaměti a otisk prstu. Tyto funkce mají náklady na větší využití paměti aplikací. U aktiv, ke kterým se často přistupuje, obvykle stojí za ty náklady. U aktiv, ke kterým se přistupuje zřídka, nemusí stát vyvážení nákladů za to.

Pokud nepoužíváte sdružování, doporučujeme kombinovat MapStaticAssets s UseStaticFiles. Následující příklad ukazuje přístup.

V souboru projektu .csproj se vlastnost MSBuild StaticWebAssetEndpointExclusionPattern používá k filtrování koncových bodů z konečného manifestu pro MapStaticAssets. Vyloučené soubory jsou obsluhovány UseStaticFiles a nemají prospěch z komprese, ukládání do mezipaměti a otisků prstů.

Při nastavování hodnoty StaticWebAssetEndpointExclusionPattern zachovejte $(StaticWebAssetEndpointExclusionPattern) výchozí vzor vyloučení frameworku. Do seznamu odděleného středníkem přidejte další vzory.

V následujícím příkladu přidá patten vyloučení statické soubory do lib/icons složky, což představuje hypotetickou dávku ikon:

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

Po zpracování middlewaru pro přesměrování HTTPS (app.UseHttpsRedirection();) v souboru Program:

app.UseStaticFiles();

app.UseAuthorization();

app.MapStaticAssets();

Statická autorizace souborů

Když aplikace přijme záložní zásady autorizace, vyžaduje se autorizace pro všechny požadavky, které explicitně nezadávají zásady autorizace, včetně požadavků na statické soubory, poté, co middleware pro autorizaci zpracuje žádosti. Umožněte anonymní přístup ke statickým souborům aplikováním AllowAnonymousAttribute na endpoint builder pro statické soubory.

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

Když aplikace přijme záložní zásady autorizace, vyžaduje se autorizace pro všechny požadavky, které explicitně nezadávají zásady autorizace, včetně požadavků na statické soubory, poté, co middleware pro autorizaci zpracuje žádosti. Šablony ASP.NET Core umožňují anonymní přístup ke statickým souborům voláním UseStaticFiles před voláním UseAuthorization. Většina aplikací tento vzor dodržuje. Pokud je middleware pro statický soubor zavolán před autorizačním middlewarem:

  • Na statické soubory se neprovádí žádné kontroly autorizace.
  • Statické soubory obsluhované middlewarem statických souborů, jako jsou například webové kořenové adresáře (obvykle wwwroot), jsou veřejně přístupné.

Obsluha statických souborů na základě autorizace:

Jmenné prostory pro následující rozhraní API:

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

Registrace služby:

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

V potrubí zpracování požadavků po volání UseAuthorization:

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

Jmenné prostory pro následující rozhraní API:

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

V Startup.ConfigureServices:

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

V Startup.Configure po volání UseAuthorization

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

V kódu uvedeném výše vyžaduje záložní autorizační politika ověřené uživatele. Koncové body, jako jsou kontrolery a Razor stránky, které určují vlastní požadavky na autorizaci, nepoužívají záložní zásady autorizace. Například Razor Stránky, kontrolery nebo metody akcí s [AllowAnonymous] nebo [Authorize(PolicyName="MyPolicy")] používají aplikovaný autorizační atribut místo záložní autorizační politiky.

RequireAuthenticatedUser přidá DenyAnonymousAuthorizationRequirement do aktuální instance, která vynucuje ověření aktuálního uživatele.

Statické prostředky uložené ve webovém kořenovém adresáři aplikace jsou veřejně přístupné, protože výchozí statický souborový middleware (UseStaticFiles) se volá před UseAuthorization. Statické prostředky ve SecureStaticFiles složce vyžadují autentizaci.

Alternativním přístupem k poskytování souborů na základě autorizace je:

  • Ukládejte soubory mimo kořenový adresář webu a jakýkoli adresář přístupný statickému middlewaru.
  • Soubory můžete obsluhovat pomocí metody akce, na kterou se použije autorizace, a vrátit FileResult objekt.

Razor Ze stránky (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");
    }
}

Z kontroleru (Controllers/HomeController.cs):

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

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

Předchozí přístup vyžaduje stránku nebo koncový bod pro každý soubor.

Následující příklad koncového bodu trasy vrátí soubory pro ověřené uživatele.

V souboru 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");

Následující příklad koncového bodu trasy nahraje soubory pro ověřené uživatele v roli správce ("admin").

V souboru 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://learn.microsoft.com/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");

V Startup.ConfigureServices:

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

V 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");

Následující kód nahraje soubory pro ověřené uživatele v roli správce ("admin").

V Startup.ConfigureServices:

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

V 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://learn.microsoft.com/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");

Procházení adresářů

Procházení adresářů umožňuje výpis adresářů v zadaných adresářích.

Procházení adresářů je ve výchozím nastavení zakázané z bezpečnostních důvodů. Další informace najdete v tématu Důležité informace o zabezpečení statických souborů.

Povolte procházení adresářů pomocí následujícího rozhraní API:

V následujícím příkladu:

  • Složka images v kořenovém adresáři aplikace obsahuje obrázky pro procházení adresáře.
  • Cesta požadavku pro procházení obrázků je /DirectoryImages.
  • Volání UseStaticFiles a nastavení FileProviderStaticFileOptions umožňuje zobrazení odkazů prohlížeče na jednotlivé soubory.

Jmenné prostory pro následující rozhraní API:

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

Registrace služby:

builder.Services.AddDirectoryBrowser();

V kanálu zpracování požadavků po existujícím volání buď MapStaticAssets (.NET 9 nebo novější), nebo UseStaticFiles (.NET 8 nebo starší):

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

Jmenné prostory pro následující rozhraní API:

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

V Startup.ConfigureServices:

services.AddDirectoryBrowser();

Za Startup.Configure stávajícím voláním na 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"
});

Předchozí kód umožňuje procházení obsahu složky wwwroot/images pomocí adresy URL https://{HOST}/DirectoryImages, s odkazy na každý soubor a složku, kde zástupný prvek {HOST} představuje hostitele.

AddDirectoryBrowser přidává služby vyžadované middlewarem procházení adresářů, včetně HtmlEncoder. Tyto služby mohou být přidány jinými voláními, například AddRazorPages, ale doporučujeme volat AddDirectoryBrowser , aby se zajistilo přidání služeb.

Obsluha výchozích dokumentů

Nastavení výchozí stránky poskytuje návštěvníkům výchozí bod na webu. Pokud chcete zobrazit výchozí soubor z wwwroot bez nutnosti uvádět název souboru v URL požadavku, zavolejte metodu UseDefaultFiles.

UseDefaultFiles je přepisovač URL, který soubor nepodává. V potrubí zpracování požadavků před existujícím voláním na buď MapStaticAssets (.NET 9 nebo novější) nebo UseStaticFiles (.NET 8 nebo starší):

app.UseDefaultFiles();

S UseDefaultFiles žádostmi do složky wwwroot vyhledáváme:

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

První soubor nalezený ze seznamu se obsluhuje, jako by požadavek obsahoval název souboru. Adresa URL prohlížeče bude i nadále odrážet požadovaný identifikátor URI.

Následující kód změní výchozí název souboru na default-document.html:

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

Kombinování statických souborů, výchozích dokumentů a procházení adresářů

UseFileServer kombinuje funkce UseStaticFiles, UseDefaultFilesa volitelně UseDirectoryBrowser.

V kanálu zpracování požadavků, po existujícím volání buď MapStaticAssets (.NET 9 nebo novější), nebo UseStaticFiles (.NET 8 nebo starší), je třeba zavolat UseFileServer, aby bylo možné obsluhovat statické soubory a výchozí soubor.

app.UseFileServer();

Pro předchozí příklad není povolené procházení adresářů.

Následující kód umožňuje obsluhu statických souborů, výchozí soubor a procházení adresářů.

Registrace služby:

builder.Services.AddDirectoryBrowser();

V kanálu zpracování požadavků po existujícím volání UseStaticFiles:

app.UseFileServer(enableDirectoryBrowsing: true);

V Startup.ConfigureServices:

services.AddDirectoryBrowser();

Za Startup.Configure stávajícím voláním na UseStaticFiles:

app.UseFileServer(enableDirectoryBrowsing: true);

Pro adresu hostitele (/) UseFileServer vrátí výchozí dokument HTML před výchozí Razor stránkou (Pages/Index.cshtml) nebo výchozím zobrazením MVC (Home/Index.cshtml).

Zvažte následující hierarchii adresářů:

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

Následující kód umožňuje obsluhu statických souborů, výchozí soubor a procházení ExtraStaticFilesadresáře .

Jmenné prostory pro následující rozhraní API:

using Microsoft.Extensions.FileProviders;

Registrace služby:

builder.Services.AddDirectoryBrowser();

V kanálu zpracování požadavků po existujícím volání UseStaticFiles:

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

Jmenné prostory pro následující rozhraní API:

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

V Startup.ConfigureServices:

services.AddDirectoryBrowser();

Za Startup.Configure stávajícím voláním na UseStaticFiles:

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

AddDirectoryBrowser musí být zavolána, pokud je hodnota vlastnosti EnableDirectoryBrowsingtrue.

Pomocí předchozí hierarchie souborů a kódu se adresy URL přeloží, jak je uvedeno v následující tabulce (zástupný symbol {HOST} je hostitel).

identifikátor URI Soubor odpovědi
https://{HOST}/static-files/images/logo.png ExtraStaticFiles/images/logo.png
https://{HOST}/static-files ExtraStaticFiles/default.html

Pokud v ExtraStaticFiles adresáři neexistuje žádný výchozí pojmenovaný soubor, https://{HOST}/static-files vrátí seznam adresářů s odkazy, na které lze kliknout, kde {HOST} zástupný symbol je hostitel.

UseDefaultFiles a UseDirectoryBrowser provádějí přesměrování na straně klienta z cílového URI bez koncového / na cílový URI s koncovým /. Například od https://{HOST}/static-files (bez koncového /) do https://{HOST}/static-files/ (včetně koncového /). Relativní adresy URL v adresáři ExtraStaticFiles jsou neplatné bez koncového lomítka (/), pokud RedirectToAppendTrailingSlash není použita možnost DefaultFilesOptions .

Mapování přípon souborů na typy MIME

Note

Pokyny, které platí pro Blazor aplikace, najdete v části ASP.NET Core Blazor statické soubory.

Použijte FileExtensionContentTypeProvider.Mappings k přidání nebo úpravě přípony souboru pro mapování typů obsahu MIME. V následujícím příkladu je několik přípon souborů mapováno na známé typy MIME. Rozšíření .rtf se nahradí a .mp4 odebere se:

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

Pokud máte několik možností statického souboru ke konfiguraci, můžete alternativně nastavit poskytovatele pomocí StaticFileOptions:

var provider = new FileExtensionContentTypeProvider();

...

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

app.UseStaticFiles();

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

Další informace najdete v tématu Typy obsahu MIME.

Nestandardní typy obsahu

Middleware statického souboru rozumí téměř 400 známým typům obsahu souboru. Pokud uživatel požádá o soubor s neznámým typem souboru, middleware pro statické soubory předá požadavek do dalšího middlewaru v řetězci. Pokud požadavek nezpracuje žádný middleware, vrátí se odpověď 404 Nenalezena . Pokud je povolené procházení adresářů, zobrazí se v seznamu adresářů odkaz na soubor.

Následující kód umožňuje obsluhovat neznámé typy obsahu a vykreslit neznámý soubor jako obrázek:

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

V předchozím kódu se jako obrázek vrátí požadavek na soubor s neznámým typem obsahu.

Warning

Povolení ServeUnknownFileTypes je bezpečnostní riziko. Ve výchozím nastavení je zakázaný a jeho použití se nedoporučuje. Mapování přípon souborů na typy MIME poskytuje bezpečnější alternativu k poskytování souborů s nestandardními příponami.

Zadání vlastního manifestu statických souborů

Pokud staticAssetsManifestPath je null, IHostEnvironment.ApplicationName slouží k vyhledání manifestu. Případně zadejte úplnou cestu k souboru manifestu. Pokud se použije relativní cesta, rozhraní vyhledá soubor v AppContext.BaseDirectory.

Důležité informace o zabezpečení statických souborů

Warning

UseDirectoryBrowser a UseStaticFiles mohou odhalit tajemství. Zakázání procházení adresářů v produkčním prostředí se důrazně doporučuje. Pečlivě zkontrolujte, které adresáře jsou povoleny prostřednictvím UseStaticFiles nebo UseDirectoryBrowser. Celý adresář a jeho podadresáři jsou veřejně přístupné. Ukládat soubory vhodné pro poskytování veřejnosti ve vyhrazeném adresáři, například <content_root>/wwwroot. Tyto soubory oddělte od zobrazení MVC, Razor stránek, konfiguračních souborů atd.

  • Adresy URL pro obsah vystavený s UseDirectoryBrowser a UseStaticFiles podléhají rozlišování velkých a malých písmen a omezení znaků souborového systému. Windows například nerozlišuje malá a velká písmena, ale macOS a Linux nejsou.

  • ASP.NET aplikace Core hostované ve službě IIS používají modul ASP.NET Core k předávání všech požadavků do aplikace, včetně požadavků na statické soubory. Obslužná rutina statického souboru služby IIS se nepoužívá a nemá šanci zpracovat požadavky.

  • Pomocí následujících kroků ve Správci služby IIS odeberte obslužnou rutinu statického souboru služby IIS na úrovni serveru nebo webu:

    1. Přejděte na funkci Moduly .
    2. V seznamu vyberte StaticFileModule .
    3. Na bočním panelu Akcí klikněte na Odebrat.

Warning

Pokud je povolená obslužná rutina statického souboru služby IIS a ASP.NET Core modul je nesprávně nakonfigurovaný, obsluhují se statické soubory. K tomu dochází například v případě, že web.config soubor není nasazený.

  • Umístěte soubory kódu, včetně .cs a .cshtml, mimo webovou kořenovou složku projektu aplikace. Logické oddělení se proto vytvoří mezi obsahem na straně klienta aplikace a serverovým kódem. Tím zabráníte úniku kódu na straně serveru.

Vlastnosti nástroje MSBuild

Následující tabulky ukazují statické soubory MSBuild vlastnosti a popisy metadat.

Vlastnictví Description
EnableDefaultCompressedItems Umožňuje výchozí vzory pro zahrnutí/vyloučení při kompresi.
CompressionIncludePatterns Seznam vzorů souborů oddělených středníkem, které se mají zahrnout pro kompresi.
CompressionExcludePatterns Seznam vzorů souborů oddělený středníkem, které se mají vyloučit z komprese.
EnableDefaultCompressionFormats Povolí výchozí formáty komprese (Gzip a Brotli).
BuildCompressionFormats Formáty komprese, které se mají použít při sestavování.
PublishCompressionFormats Formáty komprese, které se mají použít při publikování.
DisableBuildCompression Zakáže kompresi během sestavování.
CompressDiscoveredAssetsDuringBuild Komprimuje objevené prostředky během sestavování.
BrotliCompressionLevel Úroveň komprese pro Brotli algoritmus.
StaticWebAssetBuildCompressAllAssets Komprimuje všechny prostředky během sestavování, nejen zjištěné nebo vypočítané prostředky během sestavení.
StaticWebAssetPublishCompressAllAssets Komprimuje všechny prostředky během publikování, nejen zjištěné nebo vypočítané prostředky během sestavení.
Vlastnictví Description
StaticWebAssetBasePath Základní cesta URL pro všechny prostředky v knihovně.
StaticWebAssetsFingerprintContent Umožňuje otisky obsahu pro ukládání do mezipaměti.
StaticWebAssetFingerprintingEnabled Povolí funkci otisku prstu pro statické webové prostředky.
StaticWebAssetsCacheDefineStaticWebAssetsEnabled Umožňuje ukládání do mezipaměti pro definice statických webových prostředků.
StaticWebAssetEndpointExclusionPattern Model vyloučení koncových bodů
Sk. položek Description Metadatové informace
StaticWebAssetContentTypeMapping Mapuje vzory souborů na typy obsahu a hlavičky mezipaměti pro koncové body. Pattern, Cache
StaticWebAssetFingerprintPattern Definuje vzory pro použití otisků prstů na statické webové prostředky pro rušení mezipaměti. Pattern, Expression

Popisy metadat:

  • Pattern: Vzor globu používaný ke shodě souborů. Pro StaticWebAssetContentTypeMapping se shoduje se soubory, aby určil jejich typ obsahu (například *.js pro soubory JavaScript). Identifikuje soubory s více příponami StaticWebAssetFingerprintPattern, které vyžadují speciální zpracování otisků (například *.lib.module.js).

  • Cache: Určuje Cache-Control hodnotu záhlaví pro odpovídající typ obsahu. To řídí chování prohlížeče při ukládání do mezipaměti (například max-age=3600, must-revalidate u mediálních souborů).

  • Expression: Definuje, jak se otisk prstu vloží do názvu souboru. Výchozí hodnota je #[.{FINGERPRINT}], která vloží otisk prstu ({FINGERPRINT} zástupný symbol) před příponu.

Následující příklad mapuje vzor rastrového souboru (.bmp) na image/bmp typ obsahu se {CACHE HEADER} zástupným symbolem představujícím Cache-Control záhlaví, které se má použít pro koncové body bez otisku prstu:

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

Možnosti konfigurace modulu runtime

Následující tabulka popisuje možnosti konfigurace modulu runtime.

Konfigurační klíč Description
ReloadStaticAssetsAtRuntime Umožňuje opětovné načítání statických prostředků během vývoje: zpracovává upravené soubory webového kořenového adresáře (wwwroot) (přepočítá ETag, rekomprimuje v případě potřeby) místo verzí manifestu během sestavení. Výchozí nastavení je povolené pouze při poskytování manifestu sestavení, pokud není explicitně nastaveno.
DisableStaticAssetNotFoundRuntimeFallback Když truepotlačí záložní koncový bod, který obsluhuje nově přidané soubory, které nejsou přítomné v manifestu sestavení. Pokud false není přítomen, záložní kontrola existence souboru {**path} (GET/HEAD) zaznamená upozornění a obsluhuje soubor s vypočítaným ETag.
EnableStaticAssetsDevelopmentCaching Pokud true zachová původní Cache-Control hlavičky na popisovačích aktiva. Pokud false chybí nebo zcela chybí, přepisuje Cache-Control hlavičky na no-cache k zabránění agresivnímu ukládání klientů do mezipaměti během vývoje.
EnableStaticAssetsDevelopmentIntegrity Když true, zachová vlastnosti integrity u deskriptorů prostředků. Pokud false nebo chybí, odebere všechny vlastnosti integrity, aby se zabránilo neshodám při změně souborů během vývoje.

Dodatečné zdroje

  • Last updated on