Freigeben über

Statische Dateien in ASP.NET Core

Note

Dies ist nicht die neueste Version dieses Artikels. Die aktuelle Version finden Sie in der .NET 9-Version dieses Artikels.

Warning

Diese Version von ASP.NET Core wird nicht mehr unterstützt. Weitere Informationen finden Sie in der .NET- und .NET Core-Supportrichtlinie. Die aktuelle Version finden Sie in der .NET 9-Version dieses Artikels.

Important

Diese Informationen beziehen sich auf ein Vorabversionsprodukt, das vor der kommerziellen Freigabe möglicherweise noch wesentlichen Änderungen unterliegt. Microsoft gibt keine Garantie, weder ausdrücklich noch impliziert, hinsichtlich der hier bereitgestellten Informationen.

Die aktuelle Version finden Sie in der .NET 9-Version dieses Artikels.

Statische Dateien, auch als statische Ressourcen bezeichnet, sind Dateien eine ASP.NET Core-App, die nicht dynamisch generiert werden. Stattdessen werden sie direkt an Clients auf Anfrage bereitgestellt, z. B. HTML-, CSS-, Bild- und JavaScript-Dateien.

Informationen zu statischen Blazor-Dateien, die die Informationen in diesem Artikel ergänzen oder ersetzen, finden Sie unter Statische Blazor-Dateien in ASP.NET Core.

Rufen Sie MapStaticAssets auf, um die statische Dateibehandlung in ASP.NET Core zu aktivieren.

Standardmäßig werden statische Dateien im Webstammverzeichnis des Projekts gespeichert. Das Standardverzeichnis ist {CONTENT ROOT}/wwwroot, wobei der {CONTENT ROOT} Platzhalter der Inhaltsstamm der App ist. Nur Dateien im Ordner "wwwroot" können adressierbar sein, daher müssen Sie sich keine Gedanken über den Rest Ihres Codes machen.

Nur Dateien mit bestimmten Dateierweiterungen, die unterstützten Medientypen zugeordnet sind, werden als statische Webressourcen behandelt.

Statische Webressourcen werden zur Erstellungszeit erkannt und mithilfe inhaltsbasierter Fingerabdrucks optimiert, um die Wiederverwendung alter Dateien zu verhindern. Ressourcen werden auch komprimiert , um die Bereitstellungszeit von Ressourcen zu reduzieren.

Zur Laufzeit werden die ermittelten statischen Webressourcen als Endpunkte mit angewendeten HTTP-Headern verfügbar gemacht, z. B. Cache-Header und Content-Type-Header. Ein Objekt wird einmal bereitgestellt, bis sich die Datei ändert oder der Browser den Cache löscht. Die Kopfzeilen ETag, Last-Modified und Content-Type werden festgelegt. Der Browser wird daran gehindert, veraltete Ressourcen zu verwenden, nachdem eine App aktualisiert wurde.

Die Bereitstellung statischer Ressourcen basiert auf dem Endpunktrouting, sodass sie mit anderen endpunktfähigen Features wie autorisierung funktioniert. Sie ist für alle UI-Frameworks geeignet, einschließlich Blazor, Razor Pages und MVC.

Statische Karten-Assets bieten die folgenden Vorteile:

  • Komprimierung zur Buildzeit für alle Ressourcen in der App, einschließlich JavaScript (JS) und Stylesheets, jedoch ohne Bild- und Schriftartressourcen, die bereits komprimiert sind. Gzip (Content-Encoding: gz) Komprimierung wird während der Entwicklung verwendet. Gzip und Brotli (Content-Encoding: br) Komprimierung werden beide während der Veröffentlichung verwendet.
  • Fingerabdruck für alle Objekte zur Erstellungszeit mit einer base64-codierten Zeichenfolge des SHA-256-Hashs der einzelnen Dateiinhalte. Dadurch wird verhindert, dass eine alte Version einer Datei erneut verwendet wird, auch wenn die alte Datei zwischengespeichert wird. Fingerabdrücke werden mithilfe der immutable-Direktivezwischengespeichert, was dazu führt, dass der Browser die Ressource nie erneut anfordert, bis sie geändert wird. Für Browser, die die immutable-Direktive nicht unterstützen, wird eine max-age Direktive hinzugefügt.
    • Selbst wenn eine Ressource nicht mit einem Fingerabdruck versehen ist, werden inhaltsbasierte ETags für jede statische Ressource mithilfe des Fingerabdruckhashes der Datei als ETag-Wert generiert. Dadurch wird sichergestellt, dass der Browser nur eine Datei herunterlädt, wenn sich der Inhalt ändert (oder die Datei zum ersten Mal heruntergeladen wird).
    • Intern ordnet das Framework physische Objekte ihren Fingerabdrücken zu, sodass die App:
      • Suchen Sie automatisch generierte Ressourcen, z. B. ein auf Razor-Komponenten bezogenes CSS für das Blazor-CSS-Isolationsfeature und JS-Ressourcen, die durch JS-Importzuordnungen beschrieben werden.
      • Generieren Sie Link-Tags im <head>-Inhalt der Seite, um Ressourcen vorab zu laden.

Statische Assets einer Karte bieten keine Funktionen zur Minifizierung oder andere Dateitransformationen. Die Minimierung wird in der Regel durch benutzerdefinierten Code oder Tools von Drittanbietern behandelt.

Rufen Sie UseStaticFiles auf, um die statische Dateibehandlung in ASP.NET Core zu aktivieren.

Standardmäßig werden statische Dateien im Webstammverzeichnis des Projekts gespeichert. Das Standardverzeichnis ist {CONTENT ROOT}/wwwroot, wobei der {CONTENT ROOT} Platzhalter der Inhaltsstamm der App ist. Nur Dateien im Ordner "wwwroot" können adressierbar sein, daher müssen Sie sich keine Gedanken über den Rest Ihres Codes machen.

Zur Laufzeit werden statische Webressourcen von der statischen Datei-Middleware zurückgegeben, wenn Modifikation der Ressourcen und Inhaltstyp-Header angewendet werden. Die Kopfzeilen ETag, Last-Modified und Content-Type werden festgelegt.

Static File Middleware ermöglicht statische Dateibereitstellung und wird von einer App verwendet, wenn UseStaticFiles sie in der Anforderungsverarbeitungspipeline der App aufgerufen wird. Dateien werden von dem in IWebHostEnvironment.WebRootPath oder WebRootFileProvider angegebenen Pfad bereitgestellt. Standardmäßig wird der Webstammordner verwendet, in der Regel wwwroot.

Sie können auch statische Webressourcen aus referenzierten Projekten und Paketen bereitstellen.

Ändern des Webstammverzeichnisses

Verwenden Sie die UseWebRoot Methode, wenn Sie den Webstamm ändern möchten. Weitere Informationen finden Sie unter ASP.NET Core Fundamentals Overview.

Verhindern Sie das Veröffentlichen von Dateien in wwwroot mithilfe des <Content> Projektelements in der Projektdatei. Im folgenden Beispiel wird verhindert, dass Inhalte in wwwroot/local und ihren Unterverzeichnissen veröffentlicht werden:

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

Die Methode CreateBuilder legt das Inhaltsstammverzeichnis auf das aktuelle Verzeichnis fest:

var builder = WebApplication.CreateBuilder(args);

Die Methode CreateDefaultBuilder legt das Inhaltsstammverzeichnis auf das aktuelle Verzeichnis fest:

Host.CreateDefaultBuilder(args)

Rufen Sie UseHttpsRedirection in der Anforderungsverarbeitungspipeline auf und anschließend MapStaticAssets, um die Bereitstellung statischer Dateien aus dem Webstamm der App zu ermöglichen:

app.MapStaticAssets();

Rufen Sie UseHttpsRedirection in der Anforderungsverarbeitungspipeline auf und anschließend UseStaticFiles, um die Bereitstellung statischer Dateien aus dem Webstamm der App zu ermöglichen:

app.UseStaticFiles();

Auf statische Dateien kann über einen Pfad relativ zum Webstammverzeichnis zugegriffen werden.

Greifen Sie auf ein Bild zu unter wwwroot/images/favicon.png:

  • URL-Format: https://{HOST}/images/{FILE NAME}
    • Der {HOST} Platzhalter ist der Host.
    • Der {FILE NAME} Platzhalter ist der Dateiname.
  • Beispiele
    • Absolute URL: https://localhost:5001/images/favicon.png
    • Relative Stamm-URL: images/favicon.png

In einer Blazor-App lädt images/favicon.png das Symbolbild (favicon.png) aus dem wwwroot/images-Ordner der App.

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

In Razor Seiten- und MVC-Apps zeigt das Tildezeichen ~ auf den Webstamm. Im folgenden Beispiel ~/images/favicon.png wird das Symbolbild (favicon.png) aus dem Ordner der App wwwroot/images geladen:

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

Umgehen der Middleware-Pipeline

Um zu vermeiden, dass die gesamte Middleware-Pipeline ausgeführt wird, nachdem eine statische Ressource abgeglichen wurde, was das Verhalten von UseStaticFiles ist, rufen Sie ShortCircuit auf MapStaticAssets auf. Durch das Aufrufen von ShortCircuit wird der Endpunkt sofort ausgeführt und die Antwort zurückgegeben, wodurch verhindert wird, dass andere Middleware für statische Datenanforderungen ausgeführt wird.

app.MapStaticAssets().ShortCircuit();

Steuern der zwischenspeicherung statischer Dateien während der Entwicklung

Wenn sie in der Entwicklungsumgebung ausgeführt werden, z. B. während der Testphase der Visual Studio Hot Reload-Entwicklung , überschreibt das Framework Cacheheader, um zu verhindern, dass Browser statische Dateien zwischenspeichern. Dadurch wird sichergestellt, dass die neueste Version von Dateien verwendet wird, wenn Dateien geändert werden, sodass Probleme mit veralteten Inhalten vermieden werden. In der Produktion werden die richtigen Cacheheader festgelegt, sodass Browser statische Objekte erwartungsgemäß zwischenspeichern können.

Um dieses Verhalten zu deaktivieren, setzen Sie EnableStaticAssetsDevelopmentCaching auf true in der App-Einstellungsdatei (appsettings.Development.json) der Entwicklungsumgebung fest.

Statische Dateien in Nicht-Development-Umgebungen

Bei der lokalen Ausführung einer App sind statische Webressourcen nur in der Entwicklungsumgebung aktiviert. Um statische Dateien während der lokalen Entwicklung und Tests für andere Umgebungen als die Entwicklungsumgebung zu aktivieren (z. B. für die Staging-Umgebung), rufen Sie UseStaticWebAssets auf dem WebApplicationBuilder auf.

Warning

Rufen Sie UseStaticWebAssets die genaue Umgebung auf, um zu verhindern, dass das Feature in der Produktion aktiviert wird, da es Dateien von separaten Speicherorten auf einem anderen Datenträger als vom Projekt bedient. Im Beispiel in diesem Abschnitt wird die Staging-Umgebung mit IsStaging geprüft.

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

Bereitstellen von Dateien außerhalb des Webstammverzeichnisses über IWebHostEnvironment.WebRootPath

Wenn IWebHostEnvironment.WebRootPath auf einen anderen Ordner als wwwroot festgelegt ist, treten die folgenden Standardverhaltensweisen auf:

  • In der Entwicklungsumgebung werden statische Assets bereitgestellt von wwwroot, wenn sich Dateien mit demselben Namen sowohl in wwwroot als auch in einem anderen Ordner befinden, der WebRootPath zugewiesen ist.
  • In allen anderen Umgebungen als der Entwicklung werden doppelte statische Dateien aus dem WebRootPath Ordner bereitgestellt.

Betrachten Sie eine Web-App, die aus der leeren Webvorlage erstellt wurde:

  • Sie enthält eine Datei Index.html in wwwroot und wwwroot-custom.
  • Die Program Datei wird aktualisiert, um WebRootPath = "wwwroot-custom" festzulegen.
var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    WebRootPath = "wwwroot-custom"
});

Standardmäßig gelten für Anforderungen an /:

  • In der Entwicklungsumgebung wird wwwroot/Index.html zurückgegeben.
  • In allen Umgebungen außer der Entwicklungsumgebung wird wwwroot-custom/Index.html zurückgegeben.

Um sicherzustellen, dass Ressourcen wwwroot-custom immer zurückgegeben werden, verwenden Sie einen der folgenden Ansätze:

  • Löschen doppelt benannter Objekte in wwwroot.

  • Legen Sie ASPNETCORE_ENVIRONMENT in Properties/launchSettings.json auf einen beliebigen anderen Wert als Development fest.

  • Deaktivieren Sie statische Webressourcen, indem Sie in der Projektdatei der App von <StaticWebAssetsEnabled> auf false ändern. WARNUNG: Durch das Deaktivieren statischer Webressourcen werden KlassenbibliothekenRazor deaktiviert.

  • Fügen Sie der Projektdatei den folgenden XML-Code hinzu:

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

Der folgende Code aktualisiert WebRootPath auf einen Nicht-Entwicklungswert (Staging), was garantiert, dass doppelte Inhalte von wwwroot-custom anstelle von wwwroot zurückgegeben werden.

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

Middleware für statische Dateien

Static File Middleware ermöglicht die Bereitstellung statischer Dateien in bestimmten Szenarien, üblicherweise zusätzlich zu den Routingkonventionen für den Endpunkt für statische Ressourcen (MapStaticAssets).

Statische Datei-Middleware wird in die Anforderungsverarbeitung einbezogen, wenn UseStaticFiles im Anforderungsverarbeitungspipeline der App aufgerufen wird, typischerweise nachdem Konventionen für den Map Static Assets-Endpunkt (MapStaticAssets) hinzugefügt wurden.

Endpunktkonventionen für Map Static Assets werden in Apps verwendet, die auf .NET 9 oder höher abzielen. Static File Middleware muss in Apps verwendet werden, die auf .NET-Versionen vor .NET 9 abzielen.

Static File Middleware dient zur Bereitstellung von statischen Dateien, bietet jedoch nicht das gleiche Maß an Optimierung wie die Map Static Assets-Endpunktkonventionen. Die Buildzeitkomprimierungs- und Fingerabdruck-Features der Endpunktkonventionen für statische Kartenressourcen sind nicht verfügbar, wenn sie nur auf die Static File Middleware verwendet werden.

Die Endpunktkonventionen sind für die Bereitstellung von Ressourcen optimiert, die die App zur Laufzeit kennen kann. Wenn die App Ressourcen von anderen Speicherorten wie Datenträger oder eingebetteten Ressourcen bedient, sollte statische Datei-Middleware verwendet werden.

Die folgenden Features, die in diesem Artikel behandelt werden, werden mit Static File Middleware unterstützt, jedoch nicht mit Endpunktkonventionen für die Zuordnung statischer Assets.

Bereitstellen von Dateien außerhalb des Webstammverzeichnisses über UseStaticFiles

Betrachten Sie die folgende Verzeichnishierarchie mit statischen Dateien, die sich außerhalb des Webstamms der App befinden, in einem Ordner mit dem Namen ExtraStaticFiles:

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

Eine Anforderung kann auf red-rose.jpg zugreifen, indem eine neue Instanz von Static File Middleware konfiguriert wird.

Namespaces für die folgende API:

using Microsoft.Extensions.FileProviders;

In der Anforderungsverarbeitungspipeline nach dem vorhandenen Aufruf von entweder MapStaticAssets (.NET 9 oder höher) oder UseStaticFiles (.NET 8 oder früher):

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

Im vorherigen Code wird die ExtraStaticFiles Verzeichnishierarchie über das static-files URL-Segment öffentlich verfügbar gemacht. Eine Anfrage an https://{HOST}/StaticFiles/images/red-rose.jpg, bei der der Platzhalter {HOST} der Host ist, liefert die red-rose.jpg Datei aus.

Folgendes Markup verweist auf ExtraStaticFiles/images/red-rose.jpg:

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

Im vorherigen Beispiel wird tilde-slash notation in Razor Seiten- und MVC-Ansichten (src="~/StaticFiles/images/red-rose.jpg") und nicht für Razor Komponenten in Blazor Apps unterstützt.

Bereitstellen von Dateien aus mehreren Speicherorten

Die Anleitungen in diesem Abschnitt gelten für Razor Seiten und MVC-Apps. Anleitungen, die für Blazor Web App gelten, finden Sie unter Statische Dateien in ASP.NET Core-Blazor.

Beachten Sie das folgende Markup, das ein Firmenlogo anzeigt:

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

Der Entwickler beabsichtigt, das Imagetag-Hilfsprogramm zu verwenden, um eine Version anzufügen und die Datei an einem benutzerdefinierten Speicherort zu bedienen, einem Ordner mit dem Namen ExtraStaticFiles.

Im folgenden Beispiel werden MapStaticAssets zum Bereitstellen von Dateien aus wwwroot und UseStaticFiles zum Bereitstellen von Dateien aus ExtraStaticFiles verwendet.

In der Anforderungsverarbeitungspipeline nach dem vorhandenen Aufruf von entweder MapStaticAssets (.NET 9 oder höher) oder UseStaticFiles (.NET 8 oder früher):

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

Im folgenden Beispiel wird UseStaticFiles zweimal aufgerufen, um Dateien sowohl aus wwwroot als auch aus ExtraStaticFiles bereitzustellen.

In der Anforderungsverarbeitungspipeline nach dem vorhandenen Aufruf von UseStaticFiles:

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

Mit dem vorherigen Code wird die ExtraStaticFiles/logo.png Datei angezeigt. Das Bildtag-Hilfsprogramm (AppendVersion) wird jedoch nicht angewendet, da das Tag-Hilfsprogramm von WebRootFileProvider abhängt, welches nicht aktualisiert wurde, um den ExtraStaticFiles Ordner einzuschließen.

Der folgende Code fasst den WebRootFileProvider ein, um den ExtraStaticFiles-Ordner mithilfe eines CompositeFileProvider einzuschließen. Dies ermöglicht es dem Bild-Tag-Hilfsprogramm, eine Version auf die Bilder im ExtraStaticFiles-Ordner anzuwenden.

Namespace für die folgende API:

using Microsoft.Extensions.FileProviders;

In der Anforderungsverarbeitungspipeline vor dem vorhandenen Aufruf von MapStaticAssets (.NET 9 oder höher) oder UseStaticFiles (.NET 8 oder früher):

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;

Bei UseStaticFiles und UseFileServer zeigt der Dateianbieter standardmäßig auf wwwroot. Weitere Instanzen von UseStaticFiles und UseFileServer können mit anderen Dateianbietern bereitgestellt werden, um Dateien von anderen Speicherorten bereitzustellen. Weitere Informationen finden Sie unter UseStaticFiles, das weiterhin in Verbindung mit UseFileServer für wwwroot benötigt wird (dotnet/AspNetCore.Docs #15578).

Festlegen von HTTP-Antwortheadern

Verwenden Sie StaticFileOptions, um HTTP-Antwortheader festzulegen. Neben der Konfiguration der Middleware für statische Dateien legt der folgende Code den Cache-Control Header auf 604.800 Sekunden (eine Woche) fest.

Namespaces für die folgende API:

using Microsoft.AspNetCore.Http;

In der Anforderungsverarbeitungspipeline nach dem vorhandenen Aufruf von entweder MapStaticAssets (.NET 9 oder höher) oder UseStaticFiles (.NET 8 oder früher):

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

Große Sammlung von Assets

Beim Umgang mit großen Sammlungen von Assets, die als rund 1.000 oder mehr Assets gelten, empfehlen wir die Verwendung eines Bundlers, um die endgültige Anzahl der von der App bereitgestellten Assets zu reduzieren oder MapStaticAssets mit UseStaticFiles zu kombinieren.

MapStaticAssets lädt bereitwillig die vorkompilierten Metadaten, die während des Buildprozesses für die Ressourcen erfasst wurden, um Komprimierung, Caching und Fingerprinting zu unterstützen. Diese Features werden durch die App zu einem höheren Speicherverbrauch führen. Für Ressourcen, auf die häufig zugegriffen wird, lohnen sich die Kosten in der Regel. Für Ressourcen, auf die nicht häufig zugegriffen wird, ist der Kompromiss möglicherweise nicht die Kosten wert.

Wenn Sie keine Bündelung verwenden, empfehlen wir, MapStaticAssets mit UseStaticFiles zu kombinieren. Im folgenden Beispiel wird der Ansatz veranschaulicht.

In der Projektdatei (.csproj) wird die StaticWebAssetEndpointExclusionPattern MSBuild-Eigenschaft verwendet, um Endpunkte aus dem endgültigen Manifest für MapStaticAssets herauszufiltern. Ausgeschlossene Dateien werden von UseStaticFiles bedient und profitieren nicht von Komprimierung, Zwischenspeicherung und Fingerprinting.

Beim Festlegen des Werts StaticWebAssetEndpointExclusionPattern sollten Sie $(StaticWebAssetEndpointExclusionPattern) beibehalten, um das standardmäßige Ausschlussmuster des Frameworks zu bewahren. Fügen Sie in einer durch Semikolons getrennten Liste zusätzliche Muster hinzu.

Im folgenden Beispiel fügt das Ausschlussmuster die statischen Dateien im lib/icons Ordner hinzu, die einen hypothetischen Satz von Symbolen darstellen.

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

Nach der VERARBEITUNG der HTTPS-Umleitungs-Middleware (app.UseHttpsRedirection();) in der Program Datei:

app.UseStaticFiles();

app.UseAuthorization();

app.MapStaticAssets();

Autorisierung statischer Dateien

Wenn eine App eine Fallbackautorisierungsrichtlinie einnimmt, ist die Autorisierung für alle Anforderungen erforderlich, die keine explizite Autorisierungsrichtlinie angeben, einschließlich Anforderungen für statische Dateien, nachdem Autorisierungs-Middleware Anforderungen verarbeitet hat. Anonymen Zugriff auf statische Dateien zulassen, indem Sie den Endpunkt-Generator für statische Dateien anwenden AllowAnonymousAttribute :

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

Wenn eine App eine Fallbackautorisierungsrichtlinie einnimmt, ist die Autorisierung für alle Anforderungen erforderlich, die keine explizite Autorisierungsrichtlinie angeben, einschließlich Anforderungen für statische Dateien, nachdem Autorisierungs-Middleware Anforderungen verarbeitet hat. Die ASP.NET Core-Vorlagen ermöglichen anonymen Zugriff auf statische Dateien, indem UseStaticFiles vor UseAuthorization aufgerufen wird. Die meisten Apps folgen diesem Muster. Wenn die Middleware für statische Dateien vor der Autorisierungsmiddleware aufgerufen wird, gilt Folgendes:

  • In den statischen Dateien werden keine Autorisierungsüberprüfungen durchgeführt.
  • Statische Dateien, die von der Static File Middleware bereitgestellt werden, wie das Webstammverzeichnis (in der Regel wwwroot), sind öffentlich zugänglich.

So stellen Sie statische Dateien basierend auf Autorisierung bereit:

  • Vergewissern Sie sich, dass die App die Fallbackautorisierungsrichtlinie so festlegt, dass authentifizierte Benutzer erforderlich sind.
  • Speichern Sie die statische Datei außerhalb des Webstamms der App.
  • Rufen Sie UseAuthorization auf und anschließend UseStaticFiles, indem Sie den Pfad zum Ordner mit statischen Dateien außerhalb des Webstamms angeben.

Namespaces für die folgende API:

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

Dienstregistrierung:

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

In der Anforderungsverarbeitungspipeline nach dem Aufruf von UseAuthorization:

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

Namespaces für die folgende API:

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

In Startup.ConfigureServices:

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

Im Startup.Configure Anschluss an den Anruf an UseAuthorization:

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

Im vorherigen Code erfordert die Fallbackautorisierungsrichtlinie authentifizierte Benutzer. Endpunkte wie Controller und Razor Seiten, die ihre eigenen Autorisierungsanforderungen angeben, verwenden nicht die Fallbackautorisierungsrichtlinie. Beispielsweise verwenden Razor Seiten, Controller oder Aktionsmethoden mit [AllowAnonymous] oder [Authorize(PolicyName="MyPolicy")] das angewendete Autorisierungsattribut anstelle der Fallback-Autorisierungsrichtlinie.

RequireAuthenticatedUser fügt der aktuellen Instanz DenyAnonymousAuthorizationRequirement hinzu. Dadurch wird die Authentifizierung des aktuellen Benutzers erzwungen.

Statische Objekte, die im Webstamm der App gespeichert sind, sind öffentlich zugänglich, da die standardmäßige Static File Middleware (UseStaticFiles) vor UseAuthorizationaufgerufen wird. Statische Objekte im SecureStaticFiles Ordner erfordern eine Authentifizierung.

Eine Alternative zum Bereitstellen von Dateien basierend auf Autorisierung ist folgendes Verfahren:

  • Speichern Sie die Dateien außerhalb des Webstamms und jedes Verzeichnis, auf das die Middleware für statische Dateien zugreifen kann.
  • Dienen Sie die Dateien über eine Aktionsmethode, auf die die Autorisierung angewendet wird, und geben Sie ein FileResult Objekt zurück.

Von einer Razor Seite (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");
    }
}

Von einem Controller (Controllers/HomeController.cs):

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

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

Für den vorherigen Ansatz ist eine Seite oder ein Endpunkt pro Datei erforderlich.

Im folgenden Routenendpunktbeispiel werden Dateien für authentifizierte Benutzer zurückgegeben.

In der Program-Datei:

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

Im folgenden Routenendpunktbeispiel werden Dateien für authentifizierte Benutzer in der Administratorrolle ("admin") hochgeladen.

In der Program-Datei:

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

In Startup.ConfigureServices:

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

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

Der folgende Code lädt Dateien für authentifizierte Benutzer in der Administratorrolle hoch ("admin").

In Startup.ConfigureServices:

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

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

Verzeichnisbrowsen

Die Verzeichnissuche ermöglicht die Verzeichnisauflistung in angegebenen Verzeichnissen.

Die Verzeichnissuche ist aus Sicherheitsgründen standardmäßig deaktiviert. Weitere Informationen finden Sie unter Sicherheitsüberlegungen für statische Dateien.

Aktivieren Sie das Verzeichnisbrowsen mit der folgenden API:

Im folgenden Beispiel:

  • Ein images Ordner im Stammverzeichnis der App enthält Bilder zum Durchsuchen von Verzeichnissen.
  • Der Anforderungspfad zum Durchsuchen der Bilder lautet /DirectoryImages.
  • Durch das Aufrufen von UseStaticFiles und das Festlegen von FileProvider wird das Anzeigen von StaticFileOptions-Browserlinks zu den einzelnen Dateien ermöglicht.

Namespaces für die folgende API:

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

Dienstregistrierung:

builder.Services.AddDirectoryBrowser();

In der Anforderungsverarbeitungspipeline nach dem vorhandenen Aufruf von entweder MapStaticAssets (.NET 9 oder höher) oder UseStaticFiles (.NET 8 oder früher):

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

Namespaces für die folgende API:

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

In Startup.ConfigureServices:

services.AddDirectoryBrowser();

Nach dem bestehenden Aufruf von Startup.Configure in 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"
});

Der vorangehende Code ermöglicht das Verzeichnisbrowsen des wwwroot/images Ordners mithilfe der URL https://{HOST}/DirectoryImages mit Links zu jeder Datei und jedem Ordner, wobei der {HOST} Platzhalter der Host ist.

AddDirectoryBrowser fügt Dienste hinzu, die von der Middleware für das Verzeichnisbrowsen erforderlich sind, einschließlich HtmlEncoder. Diese Dienste können durch andere Aufrufe wie AddRazorPages hinzugefügt werden, aber wir empfehlen, AddDirectoryBrowser aufzurufen, um sicherzustellen, dass die Dienste hinzugefügt werden.

Bereitstellen von Standarddokumenten

Durch das Festlegen einer Standardseite wird Besuchern ein Ausgangspunkt auf einer Website bereitgestellt. Rufen Sie die Methode auf, um eine Standarddatei von wwwroot bereitzustellen, ohne dass die Anforderungs-URL den Dateinamen enthalten muss.

UseDefaultFiles ist ein URL-Rewriter, der die Datei nicht verarbeiten kann. In der Anforderungsverarbeitungspipeline vor dem vorhandenen Aufruf von entweder MapStaticAssets (.NET 9 oder höher) oder UseStaticFiles (.NET 8 oder früher):

app.UseDefaultFiles();

Bei UseDefaultFiles werden bei Anforderungen an einen Ordner in wwwroot folgende Dateien durchsucht:

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

Die erste in der Liste gefundene Datei wird bereitgestellt, als wäre die Anforderung im Dateinamen enthalten. Die Browser-URL spiegelt weiterhin den angeforderten URI wider.

Mit dem folgenden Code wird der Standarddateiname in default-document.html geändert:

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

Kombinieren statischer Dateien, Standarddokumente und Verzeichnisbrowsen

In UseFileServer werden die Funktionen von UseStaticFiles, UseDefaultFiles und (optional) UseDirectoryBrowser miteinander kombiniert.

Rufen Sie in der Anforderungsverarbeitungspipeline nach dem vorhandenen Aufruf entweder von MapStaticAssets (.NET 9 oder höher) oder UseStaticFiles (.NET 8 oder früher) UseFileServer auf, um die Bereitstellung statischer Dateien und der Standarddatei zu aktivieren.

app.UseFileServer();

Das Verzeichnisbrowsen ist für das vorherige Beispiel nicht aktiviert.

Der folgende Code ermöglicht die Bereitstellung statischer Dateien, der Standarddatei und des Verzeichnisbrowsens.

Dienstregistrierung:

builder.Services.AddDirectoryBrowser();

In der Anforderungsverarbeitungspipeline nach dem vorhandenen Aufruf von UseStaticFiles:

app.UseFileServer(enableDirectoryBrowsing: true);

In Startup.ConfigureServices:

services.AddDirectoryBrowser();

Nach dem bestehenden Aufruf von Startup.Configure in UseStaticFiles:

app.UseFileServer(enableDirectoryBrowsing: true);

Gibt für die Hostadresse (/) UseFileServer das STANDARD-HTML-Dokument vor der Standardseite Razor (Pages/Index.cshtml) oder der MVC-Standardansicht (Home/Index.cshtml) zurück.

Betrachten Sie die folgende Verzeichnishierarchie:

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

Der folgende Code ermöglicht die Bereitstellung statischer Dateien, der Standarddatei und des Verzeichnisbrowsens von ExtraStaticFiles.

Namespaces für die folgende API:

using Microsoft.Extensions.FileProviders;

Dienstregistrierung:

builder.Services.AddDirectoryBrowser();

In der Anforderungsverarbeitungspipeline nach dem vorhandenen Aufruf von UseStaticFiles:

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

Namespaces für die folgende API:

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

In Startup.ConfigureServices:

services.AddDirectoryBrowser();

Nach dem bestehenden Aufruf von Startup.Configure in UseStaticFiles:

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

AddDirectoryBrowser muss aufgerufen werden, wenn der EnableDirectoryBrowsing-Eigenschaftswert true lautet.

Unter Verwendung der vorherigen Dateihierarchie und des vorangehenden Codes werden URLs wie in der folgenden Tabelle dargestellt aufgelöst (der Platzhalter {HOST} ist der Host).

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

Wenn keine standardmäßig benannte Datei im ExtraStaticFiles Verzeichnis vorhanden ist, https://{HOST}/static-files wird der Verzeichniseintrag mit klickbaren Links zurückgegeben, wobei der {HOST} Platzhalter der Host ist.

UseDefaultFiles und UseDirectoryBrowser führen eine clientseitige Umleitung vom Ziel-URI ohne angehängten / zum Ziel-URI mit angehängtem / durch. Beispiel: von https://{HOST}/static-files (keine nachgestellten /) bis https://{HOST}/static-files/ (enthält einen nachgestellten /). Relative URLs innerhalb des Verzeichnisses ExtraStaticFiles sind ohne nachgestellten Schrägstrich (/) ungültig, es sei denn, die Option RedirectToAppendTrailingSlash von DefaultFilesOptions wird verwendet.

Zuordnen von Dateierweiterungen zu MIME-Typen

Note

Anleitungen, die für Blazor Apps gelten, finden Sie unter ASP.NET Core Blazor static files.

Verwenden Sie FileExtensionContentTypeProvider.Mappings, um Dateierweiterungen zu Zuordnungen von MIME-Inhaltstypen hinzuzufügen oder zu ändern. Im folgenden Beispiel werden mehrere Dateierweiterungen bekannten MIME-Typen zugeordnet. Die .rtf Erweiterung wird ersetzt und .mp4 entfernt:

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

Wenn Sie mehrere Optionen zur Konfiguration statischer Dateien haben, können Sie alternativ den Anbieter mithilfe von StaticFileOptions festlegen.

var provider = new FileExtensionContentTypeProvider();

...

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

app.UseStaticFiles();

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

Weitere Informationen finden Sie unter MIME-Inhaltstypen.

Inhaltstypen, die vom Standard abweichen

Die Middleware für statische Dateien erkennt fast 400 bekannte Dateiinhaltstypen. Wenn ein Benutzer eine Datei mit einem unbekannten Dateityp anfordert, übergibt die Middleware für statische Dateien die Anforderung an die nächste Middleware in der Pipeline. Wenn keine Middleware die Anforderung verarbeitet, wird die Meldung 404 Nicht gefunden zurückgegeben. Wenn die Verzeichnissuche aktiviert ist, wird ein Link zur Datei in einer Verzeichnisliste angezeigt.

Der folgende Code ermöglicht die Bereitstellung unbekannter Inhaltstypen und rendert die unbekannte Datei als Bild:

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

Mit dem vorangehenden Code wird eine Anforderung für eine Datei mit unbekanntem Inhaltstyp als Image zurückgegeben.

Warning

Die Aktivierung von ServeUnknownFileTypes stellt ein Sicherheitsrisiko dar. Diese Eigenschaft ist standardmäßig deaktiviert, von einer Verwendung wird abgeraten. Die Zuordnung von Dateierweiterungen zu MIME-Typen bietet eine sicherere Alternative zur Bereitstellung von Dateien mit nicht standardmäßigen Erweiterungen.

Bereitstellen eines benutzerdefinierten Manifests für statische Dateien

Wenn staticAssetsManifestPathnull ist, wird IHostEnvironment.ApplicationName verwendet, um das Manifest zu lokalisieren. Alternativ können Sie einen vollständigen Pfad zur Manifestdatei angeben. Wenn ein relativer Pfad verwendet wird, sucht das Framework nach der Datei in der AppContext.BaseDirectory.

Sicherheitsüberlegungen für statische Dateien

Warning

UseDirectoryBrowser und UseStaticFiles können Geheimnisse preisgeben. Eine Deaktivierung der Verzeichnissuche in der Produktionsumgebung wird dringend empfohlen. Überprüfen Sie sorgfältig, welche Verzeichnisse über UseStaticFiles oder UseDirectoryBrowser aktiviert wurden. Das gesamte Verzeichnis und die zugehörigen Unterverzeichnisse werden öffentlich zugänglich gemacht. Speichern Sie Dateien, die für eine Bereitstellung in der Öffentlichkeit geeignet sind, in einem dafür vorgesehenen Verzeichnis wie z.B. <content_root>/wwwroot. Trennen Sie diese Dateien von MVC-Ansichten, Razor Pages, Konfigurationsdateien usw.

  • Die URLs für Inhalte, die mit UseDirectoryBrowser und UseStaticFiles verfügbar gemacht wurden, unterliegen der Groß-/Kleinschreibung und den Zeichenbeschränkungen des zugrunde liegenden Dateisystems. Bei Windows wird die Groß-/Kleinschreibung beispielsweise nicht beachtet, jedoch bei macOS und Linux.

  • In IIS gehostete ASP.NET Core-Apps leiten über das ASP.NET Core-Modul alle Anforderungen an die App weiter, darunter die Anforderungen von statischen Dateien. Der IIS-Handler für statische Dateien wird nicht verwendet und hat keine Möglichkeit, Anforderungen zu verarbeiten.

  • Führen Sie im IIS-Manager die folgenden Schritte aus, um den statischen IIS-Dateihandler auf Server- oder Website-Ebene zu entfernen:

    1. Navigieren Sie zum Feature Module.
    2. Wählen Sie StaticFileModule aus der Liste aus.
    3. Klicken Sie in der Randleiste Aktionen auf Entfernen.

Warning

Wenn der statische IIS-Dateihandler aktiviert ist und das ASP.NET Core-Modul falsch konfiguriert wurde, werden statische Dateien bereitgestellt. Dies geschieht beispielsweise, wenn die web.config Datei nicht bereitgestellt wird.

  • Platzieren Sie Codedateien einschließlich .cs und .cshtml außerhalb des Webstammverzeichnisses des App-Projekts. Aus diesem Grund wird eine logische Trennung zwischen den clientseitigen Inhalten der App und dem serverbasierten Code erschaffen. Dadurch wird verhindert, dass serverseitiger Code aufgedeckt wird.

MSBuild-Eigenschaften

In den folgenden Tabellen sind die MSBuild-Eigenschaften und Metadatenbeschreibungen der statischen Dateien dargestellt.

Eigentum Description
EnableDefaultCompressedItems Aktiviert standardkomprimierungs-Include-/Exclude-Muster.
CompressionIncludePatterns Durch Semikolons getrennte Liste von Dateimustern, die für die Komprimierung eingeschlossen werden sollen.
CompressionExcludePatterns Durch Semikolons getrennte Liste von Dateimustern, die von der Komprimierung ausgeschlossen werden sollen.
EnableDefaultCompressionFormats Aktiviert Standardkomprimierungsformate (Gzip und Brotli).
BuildCompressionFormats Komprimierungsformate, die während des Builds verwendet werden sollen.
PublishCompressionFormats Komprimierungsformate, die während der Veröffentlichung verwendet werden sollen.
DisableBuildCompression Deaktiviert die Komprimierung während des Builds.
CompressDiscoveredAssetsDuringBuild Komprimiert ermittelte Objekte während des Builds.
BrotliCompressionLevel Komprimierungsebene für den Brotli-Algorithmus.
StaticWebAssetBuildCompressAllAssets Komprimiert alle Ressourcen während des Builds, nicht nur während eines Builds ermittelte oder berechnete Ressourcen.
StaticWebAssetPublishCompressAllAssets Komprimiert alle Ressourcen während der Veröffentlichung, nicht nur die während eines Builds ermittelten oder berechneten Ressourcen.
Eigentum Description
StaticWebAssetBasePath Basis-URL-Pfad für alle Objekte in einer Bibliothek.
StaticWebAssetsFingerprintContent Aktiviert das Fingerabdrucken von Inhalten für das Cache-Busting.
StaticWebAssetFingerprintingEnabled Aktiviert das Fingerabdruckfeature für statische Webressourcen.
StaticWebAssetsCacheDefineStaticWebAssetsEnabled Aktiviert das Zwischenspeichern für statische Webobjektdefinitionen.
StaticWebAssetEndpointExclusionPattern Muster für das Ausschließen von Endpunkten.
Artikelgruppe Description Metadaten
StaticWebAssetContentTypeMapping Ordnet Dateimuster den Inhaltstypen und Cache-Headern von Endpunkten zu. Pattern, Cache
StaticWebAssetFingerprintPattern Definiert Muster zum Anwenden von Fingerabdrücken auf statische Webressourcen zum Cache-Busting. Pattern, Expression

Metadatenbeschreibungen:

  • Pattern: Ein Globmuster, das zum Abgleichen von Dateien verwendet wird. Für StaticWebAssetContentTypeMapping durchsucht es Dateien, um ihren Inhaltstyp zu bestimmen (zum Beispiel *.js für JavaScript-Dateien). Es identifiziert Multierweiterungsdateien, wie zum Beispiel StaticWebAssetFingerprintPattern, die eine spezielle Fingerabdruckbehandlung erfordern (z. B. *.lib.module.js).

  • Cache: Gibt den Cache-Control Headerwert für den übereinstimmenen Inhaltstyp an. Dadurch wird das Verhalten der Browserzwischenspeicherung (z. B max-age=3600, must-revalidate . für Mediendateien) gesteuert.

  • Expression: Definiert, wie der Fingerabdruck in den Dateinamen eingefügt wird. Der Standardwert ist #[.{FINGERPRINT}], der den Fingerabdruck ({FINGERPRINT} Platzhalter) vor der Erweiterung einfügt.

Das folgende Beispiel ordnet das Bitmapdateimuster (.bmp) dem image/bmp Inhaltstyp zu, mit dem Platzhalter {CACHE HEADER}, der den Header darstellt, der für Endpunkte ohne Fingerabdruck verwendet werden soll.

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

Laufzeitkonfigurationsoptionen

In der folgenden Tabelle werden die Laufzeitkonfigurationsoptionen beschrieben.

Konfigurationsschlüssel Description
ReloadStaticAssetsAtRuntime Ermöglicht das Hot-Reloading von statischen Assets während der Entwicklungszeit: Es werden geänderte Web-Stammdateien wwwroot (neu berechnet und bei Bedarf neu komprimiert) anstelle der Build-Zeit-Manifestversionen bereitgestellt. Wird standardmäßig nur bei der Bereitstellung eines Buildmanifests aktiviert, es sei denn, es wird explizit festgelegt.
DisableStaticAssetNotFoundRuntimeFallback Wenn true unterdrückt wird, wird der Fallback-Endpunkt deaktiviert, der neu hinzugefügte Dateien bedient, die nicht im Buildmanifest vorhanden sind. Wenn false oder nicht vorhanden ist, protokolliert ein geprüftes {**path} Fallback (GET/HEAD) eine Warnung und liefert die Datei mit einem berechneten ETag aus.
EnableStaticAssetsDevelopmentCaching Wenn true, behält die ursprünglichen Cache-Control Header für Objektdeskriptoren bei. Wenn false fehlt oder nicht vorhanden ist, werden Cache-Control-Header zu no-cache umgeschrieben, um eine aggressive Clientzwischenspeicherung während der Entwicklung zu vermeiden.
EnableStaticAssetsDevelopmentIntegrity Wenn truedie Integritätseigenschaften für Objektdeskriptoren beibehalten werden. Wenn false nicht vorhanden ist oder fehlt, werden alle Integritätseigenschaften entfernt, um Konflikte zu verhindern, wenn Dateien während der Entwicklung geändert werden.

Weitere Ressourcen