Bereitstellen statischer Dateien in ASP.NET Core Apps

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

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

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

Statische Webressourcen werden zur Erstellungszeit erkannt und mithilfe eines inhaltsbasierten 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.
• Fingerabdrücke für alle Ressourcen zur Buildzeit mit einer Base64-codierten Zeichenfolge des SHA-256-Hashes jedes Dateiinhalts. 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.

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

Zur Laufzeit werden statische Webressourcen von der Middleware für statische Dateien zurückgegeben, wenn sie mit Modifikation der Ressource und angewendeten Inhaltstyp-Headern angefordert werden. Die Kopfzeilen ETag, Last-Modified und Content-Type werden festgelegt.

Die Middleware für statische Dateien ermöglicht die Bereitstellung statischer Dateien und wird von einer App verwendet, wenn UseStaticFiles in der Anforderungs­verarbeitungspipeline 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.

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 in der Anforderungsverarbeitungspipeline nach dem Aufruf UseHttpsRedirectionauf MapStaticAssets , um die Bereitstellung statischer Dateien aus dem Webstamm der App zu aktivieren:

app.MapStaticAssets();

Rufen Sie in der Anforderungsverarbeitungspipeline nach dem Aufruf UseHttpsRedirectionauf UseStaticFiles , um die Bereitstellung statischer Dateien aus dem Webstamm der App zu aktivieren:

app.UseStaticFiles();

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 Anforderungen zu statischen Ressourcen ausgeführt wird.

app.MapStaticAssets().ShortCircuit();

Steuern der zwischenspeicherung statischer Dateien während der Entwicklung

Wenn sie in der Development Umgebung ausgeführt werden, z. B. beim Testen der Visual Studio Hot Reload-Entwicklung , überschreibt das Framework Cacheheader, um zu verhindern, dass Browser statische Dateien zwischenspeichern. Dieses Verhalten trägt dazu bei, sicherzustellen, dass die neueste Version von Dateien verwendet wird, wenn Dateien geändert werden und Probleme mit veralteten Inhalten vermieden werden. In der Produktion legt das Framework die richtigen Cacheheader fest, sodass Browser statische Ressourcen wie erwartet zwischenspeichern können.

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

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

Wenn Sie IWebHostEnvironment.WebRootPath auf einen anderen Ordner als wwwroot festlegen, zeigt die App die folgenden Standardverhaltensweisen:

• In der Development Umgebung werden statische Assets von wwwroot bereitgestellt, wenn Assets mit demselben Namen sowohl in wwwroot als auch in einem anderen Ordner, der WebRootPath zugewiesen ist, vorhanden sind.
• In einer anderen Umgebung als Developmentwerden doppelte statische Objekte 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 /:

• Development wird in der wwwroot/Index.html Umgebung zurückgegeben.
• In jeder Umgebung außer Development 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 <StaticWebAssetsEnabled> auf false festlegen. 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

Die Middleware für statische Dateien ermöglicht die Bereitstellung statischer Dateien in bestimmten Szenarien für statische Dateien, in der Regel zusätzlich zu den Endpunktroutingkonventionen für Map Static Assets (MapStaticAssets).

Binden Sie die Middleware für statische Dateien in die Anforderungsverarbeitung ein, wenn Sie UseStaticFiles in der Anforderungsverarbeitungspipeline der App aufrufen, in der Regel nachdem Sie Endpunktkonventionen für das Zuordnen statischer Assets (MapStaticAssets) hinzugefügt haben.

Verwenden Sie in Apps, die auf .NET 9 oder höher abzielen, die Endpunktkonventionen von Map Static Assets. Verwenden Sie statische Datei-Middleware in Apps, die auf Versionen von .NET vor .NET 9 abzielen.

Die Middleware für statische Dateien stellt statische Dateien bereit, bietet jedoch nicht den gleichen Optimierungsgrad wie die Endpunktkonventionen von Map Static Assets für statische Ressourcen. Die Features für die Komprimierung zur Buildzeit und das Fingerprinting der Endpunktkonventionen von Map Static Assets sind nicht verfügbar, wenn Sie sich nur auf Middleware für statische Dateien verlassen.

Die Endpunktkonventionen sind für die Bereitstellung von Ressourcen optimiert, die von der App zur Laufzeit bekannt sind. Wenn die App Ressourcen von anderen Speicherorten wie Datenträger oder eingebetteten Ressourcen bedient, verwenden Sie statische Datei-Middleware.

Die folgenden in diesem Artikel beschriebenen Funktionen werden von der Middleware für statische Dateien unterstützt, jedoch nicht von den Endpunktkonventionen von Map Static Assets:

• Bereitstellen von Dateien außerhalb des Webstammverzeichnisses
• Festlegen von HTTP-Antwortheadern
• Bereitstellen von Dateien von Datenträgern, eingebetteten Ressourcen oder anderen Speicherorten
• Verzeichnisbrowsen
• Bereitstellen von Standarddokumenten (mit MapStaticAssets, erfordert einen Aufruf an UseStaticFiles)
• Kombinieren statischer Dateien, Standarddokumente und Verzeichnisbrowsen
• Zuordnen von Dateierweiterungen zu MIME-Typen
• Bereitstellen nicht standardmäßiger Inhaltstypen

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 aktualisiert den WebRootFileProvider, 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;

Manifest statischer Ressourcen

MapStaticAssets liefert Assets aus einem statischen Asset-Manifest, anstatt das Webstammverzeichnis zur Laufzeit zu scannen. Das Manifest wird zur Build- und Veröffentlichungszeit generiert und erfasst die für die App ermittelten statischen Webressourcen zusammen mit Metadaten wie Inhaltsfingerprints, Content-Type-Headern, Cacheheadern und den vorab berechneten komprimierten Darstellungen (Gzip und Brotli). Zur Laufzeit MapStaticAssets liest das Manifest, registriert einen Endpunkt für jede Ressource und liefert die optimierten Antworten.

Der Buildprozess generiert das Manifest im Buildausgabeverzeichnis. Der Dateiname basiert auf dem Assemblynamen des Projekts (z. B. {ASSEMBLY NAME}.staticwebassets.endpoints.json, wobei der Platzhalter {ASSEMBLY NAME} dem MSBuild-Wert AssemblyName der App entspricht). Informationen zum Bereitstellen eines Manifests von einem anderen Speicherort finden Sie im Abschnitt " Bereitstellen eines benutzerdefinierten Manifests für statische Dateien ".

Da MapStaticAssets nur die im Manifest aufgeführten Assets bereitstellt, werden keine Dateien bereitgestellt, die nicht Teil des Manifests sind. Dateien sind nicht Teil des Manifests, wenn sie:

• Außerhalb des Web-Stammverzeichnisses zur Erstellungszeit, wie beispielsweise Dateien, die von der Festplatte bereitgestellt werden, eingebettete Ressourcen oder eine benutzerdefinierte WebRootPath, das zur Laufzeit festgelegt wird.
• Aus dem Manifest mit der StaticWebAssetEndpointExclusionPattern MSBuild-Eigenschaft ausgeschlossen (siehe den Abschnitt Große Sammlung von Ressourcen).

Um Dateien bereitzustellen, die nicht im Manifest enthalten sind, rufen Sie UseStaticFiles auf, wodurch Dateien zur Laufzeit direkt aus dem Webstamm bereitgestellt werden. Dies ist auch der Grund, warum das Ausliefern von Standarddokumenten mit MapStaticAssets einen Aufruf von UseStaticFiles erfordert.

Integrieren von buildgenerierten Dateien in statische Webressourcen

Buildtools wie TypeScript-Compiler und JavaScript-Bundler erzeugen häufig Dateien während des Builds. Um diese generierten Dateien mit dem Fingerprinting, der Komprimierung und dem Caching bereitzustellen, die MapStaticAssets bietet, müssen sie während des Builds als statische Webressourcen erkannt werden. Generierte Dateien werden in der Regel außerhalb des Webstamms (wwwroot) gespeichert und von der Quellcodeverwaltung ausgeschlossen, sodass sie standardmäßig nicht als statische Webressourcen erkannt werden. Nur Dateien, die beim Auflösen statischer Webressourcen während des Builds als unter wwwroot befindlich ermittelt werden, werden dem Manifest für statische Ressourcen hinzugefügt und von MapStaticAssets bereitgestellt. Dateien, die in <Content> eingebunden sind (z. B. mit einem Link-Element und einem wwwroot), werden ebenfalls einbezogen, auch wenn die Quelldatei außerhalb von wwwroot gespeichert ist.

Um buildgenerierte Dateien als statische Webressourcen einzuschließen, verwenden Sie eine der folgenden Ansätze.

Verknüpfen generierter Dateien mit dem Webstamm

Fügen Sie ein <Content> Element mit einem Link hinzu, das jede generierte Datei unter wwwroot ablegt. Eine Datei, die in wwwroot verknüpft ist, wird von der Pipeline für statische Webressourcen erkannt und von MapStaticAssets mit Fingerprinting, Komprimierung und Caching bereitgestellt, obwohl die Quelldatei außerhalb von wwwroot gespeichert ist.

Im folgenden Beispiel erzeugt ein Buildschritt main.js in einem generated-Ordner, und der <Content>-Eintrag bindet die Datei in wwwroot ein:

<ItemGroup>
  <Content Include="generated\main.js" Link="wwwroot\main.js"
    CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

Die generierte Datei muss vorhanden sein, wenn der Buildprozess statische Webressourcen auflöst.

Verwenden Sie ein JavaScript-Projekt für komplexe Build-Pipelines

Verwenden Sie für einen komplexen JavaScript- oder TypeScript-Clientbuild ein separates JavaScript-Projekt, das die Clientressourcen mit dem JavaScript-Projektsystem erstellt (das Microsoft.VisualStudio.JavaScript.Sdk MSBuild SDK und eine .esproj Projektdatei). Verweisen Sie auf das JavaScript-Projekt aus der ASP.NET Core-App, sodass die Ausgabe als statische Webressourcen verwendet wird. Ein Beispiel finden Sie in der Microsoft.FluentUI.AspNetCore.Components.Assets.esproj Projektdatei (microsoft/fluentui-blazor GitHub Repository).

Wenn eine App eine Fallbackautorisierungsrichtlinie einnimmt, erfordert sie eine Autorisierung für Anforderungen, die von Autorisierungs-Middleware verarbeitet werden, wenn keine Richtlinie aus Autorisierungsmetadaten erstellt wird. Diese Anforderung umfasst Anforderungen für statische Objekte, die als Endpunkte zugeordnet sind. Um anonymen Zugriff auf statische Ressourcen zu ermöglichen, wenden Sie AllowAnonymousAttribute auf den Endpunktersteller an:

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

Wenn eine App eine Fallbackautorisierungsrichtlinie einnimmt, ist die Autorisierung für Anforderungen erforderlich, die von Autorisierungs-Middleware verarbeitet werden, wenn keine Richtlinie aus Autorisierungsmetadaten erstellt wird. 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 statische Datei-Middleware vor der Autorisierungs-Middleware aufgerufen wird:

• In den statischen Dateien werden keine Autorisierungsüberprüfungen durchgeführt.
• Statische Dateien, die von der Middleware für statische Dateien bereitgestellt werden, z. B. solche im Webstamm (in der Regel wwwroot), sind öffentlich zugänglich.

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

In Startup.Configure im Anschluss an den Anruf an UseAuthorization:

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

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

Mit dem folgenden Code werden Dateien für authentifizierte Benutzer in der Administratorrolle (admin) hochgeladen.

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

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

In Startup.Configure im Anschluss an den Aufruf an 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"
});

AddDirectoryBrowser fügt Dienste hinzu, die von der Middleware für das Verzeichnisbrowsen erforderlich sind, einschließlich HtmlEncoder. Diese Dienste werden möglicherweise durch andere Aufrufe hinzugefügt, wie z. B. AddRazorPages. Rufen Sie jedoch AddDirectoryBrowser auf, um sicherzustellen, dass die Dienste hinzugefügt werden.

Da MapStaticAssets Ressourcen, die während des Builds über Endpunktrouting ermittelt werden, bereitstellt, werden Standarddokumente nicht von selbst bereitgestellt. Rufen Sie UseDefaultFiles auf, um die Anforderung umzuschreiben, gefolgt von UseStaticFiles, um die umgeschriebene Anforderung für das Standarddokument bereitzustellen:

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

In der Anforderungsverarbeitungspipeline vor dem vorhandenen Aufruf von UseStaticFiles:

app.UseDefaultFiles();

Dienstregistrierung:

builder.Services.AddDirectoryBrowser();

In der Anforderungsverarbeitungspipeline nach dem vorhandenen Aufruf von UseStaticFiles:

app.UseFileServer(enableDirectoryBrowsing: true);

In Startup.ConfigureServices:

services.AddDirectoryBrowser();

In Startup.Configure im Anschluss an den Aufruf an UseStaticFiles:

app.UseFileServer(enableDirectoryBrowsing: true);

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

In Startup.Configure im Anschluss an den Aufruf an UseStaticFiles:

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

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 Konfigurationsoptionen für statische Dateien haben, können Sie den Anbieter alternativ mit 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"
});

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 Sie einen relativen Pfad verwenden, sucht das Framework nach der Datei in der AppContext.BaseDirectory.

MSBuild-Eigenschaften

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

Im folgenden Beispiel werden JavaScript-Dateien von der Komprimierung ausgeschlossen:

<PropertyGroup>
  <CompressionExcludePatterns>$(CompressionExcludePatterns);**\*.js</CompressionExcludePatterns>
</PropertyGroup>

So deaktivieren Sie die Komprimierung statischer Ressourcen vollständig:

<PropertyGroup>
  <CompressionEnabled>false</CompressionEnabled>
</PropertyGroup>

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). Für StaticWebAssetFingerprintPattern identifiziert es Multierweiterungsdateien, die eine spezielle Fingerabdruckbehandlung erfordern (z. B. *.lib.module.js).

• Cache: Gibt den Cache-Control Headerwert für den übereinstimmenen Inhaltstyp an. Dieser Wert steuert das Cache-Verhalten des Browsers (zum Beispiel max-age=3600, must-revalidate für Mediendateien).

• Priority: Steuert die Rangfolge, wenn mehrere StaticWebAssetContentTypeMapping Elemente mit derselben Datei übereinstimmen. Höhere numerische Werte haben Vorrang vor niedrigeren Werten. Priority ist erforderlich.

• 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.

Im folgenden Beispiel wird das Bitmapdateimuster (.bmp) dem image/bmp-Inhaltstyp zugeordnet, wobei der Platzhalter {CACHE HEADER} den Cache-Control-Header darstellt, der für Endpunkte ohne Fingerabdruck verwendet werden soll.

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

Laufzeitkonfigurationsoptionen

In der folgenden Tabelle werden die Laufzeitkonfigurationsoptionen beschrieben.