Statische Blazor-Dateien in ASP.NET Core

In diesem Artikel wird die Konfiguration der Blazor-App zum Bereitstellen statischer Dateien beschrieben.

Bereitstellung statischer Ressourcen in serverseitigen Blazor Apps

Die Bereitstellung statischer Objekte wird entweder durch Routingendpunktkonventionen oder eine in der folgenden Tabelle beschriebene Middleware verwaltet.

Funktion	API	.NET-Version	Beschreibung
Zuordnen von Endpunktkonventionen für das Routing statischer Objekte	MapStaticAssets	.NET 9 oder höher	Optimiert die Bereitstellung statischer Objekte an Clients.
Middleware für statische Dateien	UseStaticFiles	Alle .NET-Versionen	Dient statischen Ressourcen an Clients, ohne die Optimierungen von statischen Kartenobjekten, aber nützlich für einige Aufgaben, die statische Ressourcen zuordnen, nicht in der Lage ist, zu verwalten.

Konfigurieren Sie statische Kartenressourcen, indem Sie die Anforderungsverarbeitungspipeline der App aufrufen MapStaticAssets , die Folgendes ausführt:

• Legt die Kopfzeilen ETag und Last-Modified fest.
• Legt Zwischenspeicherungsheader fest.
• Verwendet Zwischenspeicherungs-Middleware.
• Dient, wenn möglich, komprimierten statischen Ressourcen.
• Arbeitet mit einem CDN (Content Delivery Network) (z. B. Azure CDN ) zusammen, um die statischen Ressourcen der App näher an den Benutzer zu bedienen.
• Fingerabdruckobjekte, um zu verhindern, dass alte Versionen von Dateien wiederverwendet werden.

Statische Objekte zuordnen, indem Erstellungs- und Veröffentlichungsprozesse kombiniert werden, um Informationen zu den statischen Ressourcen in der App zu sammeln. Diese Informationen werden von der Laufzeitbibliothek verwendet, um die statischen Objekte effizient für Browser bereitzustellen.

Statische Objekte zuordnen können in den meisten Situationen ersetzt werden UseStaticFiles . Statische Kartenobjekte sind jedoch für die Bereitstellung der Objekte aus bekannten Speicherorten in der App zur Erstellung und Veröffentlichung optimiert. Wenn die App Ressourcen von anderen Speicherorten bereitstellt, z. B. von der Festplatte oder von eingebetteten Ressourcen, sollte UseStaticFiles verwendet werden.

Die Zuordnung statischer Objekte (MapStaticAssets) ersetzt Aufrufe UseBlazorFrameworkFiles in Apps, die Frameworkdateien bereitstellen Blazor WebAssembly , und das explizite Aufrufen UseBlazorFrameworkFiles in einer Blazor Web App Datei ist nicht erforderlich, da die API beim Aufrufen AddInteractiveWebAssemblyComponentsautomatisch aufgerufen wird.

Statische Kartenressourcen bieten die folgenden Vorteile, die beim Aufrufen UseStaticFilesnicht verfügbar sind:

• Buildzeitkomprimierung für alle Objekte 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 mit Brotli (Content-Encoding: br) Komprimierung wird 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 Direktive zwischengespeichert, was dazu führt, dass der Browser die Ressource nie wieder anfordert, bis sie geändert wird. Für Browser, welche die immutable-Direktive nicht unterstützen, wird eine max-age-Direktive hinzugefügt.
  • Selbst wenn ein Objekt nicht mit Fingerabdruck versehen ist, werden inhaltsbasierte ETags für jede statische Ressource mithilfe des Fingerabdruckhashs 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 Blazor ihren Fingerabdrücken physische Ressourcen zu, sodass die App Folgendes kann:
    • Suchen Sie automatisch generierte Blazor-Ressourcen, z. B. Razor-CSS-Komponentenbereich für die CSS-Isolationsfeatures von Blazor und JS-Ressourcen, die durch JS Importieren von Karten beschrieben werden.
    • Generieren Sie Linktags im <head>-Inhalt der Seite, um Ressourcen vorab zu laden.
• Während der Testphase der Hot Reload-Entwicklung von Visual Studio:
  • Integritätsinformationen werden aus den Ressourcen entfernt, um Probleme zu vermeiden, wenn eine Datei geändert wird, während die App ausgeführt wird.
  • Statische Objekte werden nicht zwischengespeichert, um sicherzustellen, dass der Browser immer aktuelle Inhalte abruft.

Wenn interaktive WebAssembly- oder interaktive Auto-Rendermodi aktiviert sind:

• Erstellt Blazor einen Endpunkt, um die Ressourcenauflistung als JS-Modul verfügbar zu machen.
• Die URL wird als permanenter Komponentenstatus an den Textkörper der Anforderung ausgegeben, wenn eine WebAssembly-Komponente in der Seite gerendert wird.
• Während des WebAssembly-Starts ruft Blazor die URL ab, importiert das Modul und ruft eine Funktion auf, um die Objektauflistung abzurufen und im Arbeitsspeicher zu rekonstruieren. Die URL ist spezifisch für den Inhalt und wird für immer zwischengespeichert, sodass dieser Aufwand nur einmal pro Benutzer erforderlich ist, bis die App aktualisiert ist.
• Die Ressourcensammlung wird auch bei einer lesbaren URL (_framework/resource-collection.js) verfügbar gemacht, hat also JS-Zugriff auf die Ressourcensammlung für die erweiterte Navigation oder die Implementierung von Features anderer Frameworks und Drittanbieterkomponenten.

Statische Kartenobjekte bieten keine Features für die Minimierung oder andere Dateitransformationen. Die Minimierung wird in der Regel durch benutzerdefinierten Code oder Tools von Drittanbietern behandelt.

Static File Middleware (UseStaticFiles) ist in den folgenden Situationen nützlich, die statische Objekte (MapStaticAssets) nicht verarbeiten können:

• Anwenden eines Pfadpräfixes auf Blazor WebAssembly statische Objektdateien, die im Abschnitt Präfix für Blazor WebAssembly-Ressourcen behandelt werden.
• Konfigurieren von Dateizuordnungen von Erweiterungen zu bestimmten Inhaltstypen und Festlegen statischer Dateioptionen, die im Abschnitt Dateizuordnungen und statische Dateioptionen behandelt werden.

Weitere Informationen finden Sie unter Statische Dateien in ASP.NET Core.

Bereitstellen von Ressourcen mit Endpunktkonventionen für das Zuordnen statischer Objekte

Dieser Abschnitt gilt für serverseitige Blazor-Apps.

Ressourcen werden über die ComponentBase.Assets Eigenschaft übermittelt, wodurch die fingerabdruckierte URL für ein bestimmtes Objekt aufgelöst wird. Im folgenden Beispiel werden Bootstrap, das Stylesheet der Projektvorlagen-App (app.css) und das CSS-Isolations-Stylesheet (basierend auf dem Namespace BlazorSampleeiner App) in einer Stammkomponente verknüpft, in der Regel die App Komponente (Components/App.razor):Blazor

<link rel="stylesheet" href="@Assets["bootstrap/bootstrap.min.css"]" />
<link rel="stylesheet" href="@Assets["app.css"]" />
<link rel="stylesheet" href="@Assets["BlazorSample.styles.css"]" />

Importieren von Karten

Dieser Abschnitt gilt für serverseitige Blazor-Apps.

Die Importzuordnungskomponente (ImportMap) stellt ein Importzuordnungselement (<script type="importmap"></script>) dar, das die Importzuordnung für Modulskripts definiert. Die Importzuordnungskomponente wird in <head> Den Inhalt der Stammkomponente eingefügt, in der Regel die App Komponente (Components/App.razor).

<ImportMap />

Wenn einer Importzuordnungskomponente keine Benutzerdefinierte ImportMapDefinition zugewiesen ist, wird die Importzuordnung basierend auf den Ressourcen der App generiert.

Die folgenden Beispiele veranschaulichen benutzerdefinierte Importzuordnungsdefinitionen und die von ihnen erstellten Importzuordnungen.

Grundlegende Importzuordnung:

new ImportMapDefinition(
    new Dictionary<string, string>
    {
        { "jquery", "https://cdn.example.com/jquery.js" },
    },
    null,
    null);

Der voranstehende Code führt zu der folgenden Importzuordnung:

{
  "imports": {
    "jquery": "https://cdn.example.com/jquery.js"
  }
}

Bereichsbezogene Importzuordnung:

new ImportMapDefinition(
    null,
    new Dictionary<string, IReadOnlyDictionary<string, string>>
    {
        ["/scoped/"] = new Dictionary<string, string>
        {
            { "jquery", "https://cdn.example.com/jquery.js" },
        }
    },
    null);

Der voranstehende Code führt zu der folgenden Importzuordnung:

{
  "scopes": {
    "/scoped/": {
      "jquery": "https://cdn.example.com/jquery.js"
    }
  }
}

Zuordnung mit Integrität importieren:

new ImportMapDefinition(
    new Dictionary<string, string>
    {
        { "jquery", "https://cdn.example.com/jquery.js" },
    },
    null,
    new Dictionary<string, string>
    {
        { "https://cdn.example.com/jquery.js", "sha384-abc123" },
    });

Der voranstehende Code führt zu der folgenden Importzuordnung:

{
  "imports": {
    "jquery": "https://cdn.example.com/jquery.js"
  },
  "integrity": {
    "https://cdn.example.com/jquery.js": "sha384-abc123"
  }
}

Kombinieren von Importzuordnungsdefinitionen (ImportMapDefinition) mit ImportMapDefinition.Combine.

Importiert eine Zuordnung, die aus einem ResourceAssetCollection-Objekt erstellt wurde, das statische Objekte ihren entsprechenden eindeutigen URLs zuordnet:

ImportMapDefinition.FromResourceCollection(
    new ResourceAssetCollection(
    [
        new ResourceAsset(
            "jquery.fingerprint.js",
            [
                new ResourceAssetProperty("integrity", "sha384-abc123"),
                new ResourceAssetProperty("label", "jquery.js"),
            ])
    ]));

Der voranstehende Code führt zu der folgenden Importzuordnung:

{
  "imports": {
    "./jquery.js": "./jquery.fingerprint.js"
  },
  "integrity": {
    "jquery.fingerprint.js": "sha384-abc123"
  }
}

In Versionen vor .NET 8 werden statische Blazor-Frameworkdateien wie das Blazor-Skript über Static File Middleware bereitgestellt. Ab .NET 8 werden statische Blazor-Frameworkdateien mithilfe von Endpunktrouting zugeordnet, und Static File Middleware wird nicht mehr verwendet.

Zusammenfassung statischer Dateiformate <link> href

Dieser Abschnitt gilt für alle .NET-Versionen und Blazor-Apps.

In den folgenden Tabellen sind statische Dateiformate <link> href nach .NET-Version zusammengefasst.

Informationen zum Speicherort <head>-Inhalts, an dem statische Dateilinks platziert werden, finden Sie unter ASP.NET Core Blazor Projektstruktur. Statische Objektverbindungen können auch mithilfe von <HeadContent>-Komponenten in einzelnen Razor-Komponenten bereitgestellt werden.

.NET 9 oder höher

App-Typ	Wert vom Typ href	Beispiele
Blazor Web App	@Assets["{PATH}"]	<link rel="stylesheet" href="@Assets["app.css"]" /> <link href="@Assets["_content/ComponentLib/styles.css"]" rel="stylesheet" />
Blazor Server†	@Assets["{PATH}"]	<link href="@Assets["css/site.css"]" rel="stylesheet" /> <link href="@Assets["_content/ComponentLib/styles.css"]" rel="stylesheet" />
Eigenständige Blazor WebAssembly-App	{PATH}	<link rel="stylesheet" href="css/app.css" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />

.NET 8.x

App-Typ	Wert vom Typ href	Beispiele
Blazor Web App	{PATH}	<link rel="stylesheet" href="app.css" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />
Blazor Server†	{PATH}	<link href="css/site.css" rel="stylesheet" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />
Eigenständige Blazor WebAssembly-App	{PATH}	<link rel="stylesheet" href="css/app.css" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />

.NET 7.x oder früher

App-Typ	Wert vom Typ href	Beispiele
Blazor Server†	{PATH}	<link href="css/site.css" rel="stylesheet" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />
Gehostet Blazor WebAssembly‡	{PATH}	<link href="css/app.css" rel="stylesheet" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />
Blazor WebAssembly	{PATH}	<link href="css/app.css" rel="stylesheet" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />

†Blazor Server wird in .NET 8 oder höher unterstützt, ist aber nach .NET 7 keine Projektvorlage mehr.
‡Es wird empfohlen, gehostete Blazor WebAssembly-Apps bei der Übernahme von .NET 8 oder höher auf Blazor Web Apps zu aktualisieren.

Statischer Webobjekt-Projektmodus

Dieser Abschnitt bezieht sich auf das .Client-Projekt einer Blazor Web App.

Die erforderliche Einstellung <StaticWebAssetProjectMode>Default</StaticWebAssetProjectMode> im .Client-Projekt eines Blazor Web App setzt das Verhalten für statische Assets von Blazor WebAssembly auf die Standardwerte zurück, sodass sich das Projekt als Teil des gehosteten Projekts verhält. Das Blazor WebAssembly SDK (Microsoft.NET.Sdk.BlazorWebAssembly) konfiguriert statische Webobjekte auf eine bestimmte Weise, um im „eigenständigen“ Modus mit einem Server zu arbeiten, der einfach die Ausgaben aus der Bibliothek verwendet. Dies ist nicht für eine Blazor Web App geeignet, wo der WebAssembly-Teil der App ein logischer Teil des Hosts ist und sich eher wie eine Bibliothek verhält. Beispielsweise macht das Projekt das Formatvorlagenbundle (z. B. BlazorSample.Client.styles.css) nicht verfügbar und stellt stattdessen nur den Host mit dem Projektbundle bereit, sodass der Host es in ein eigenes Formatvorlagenbundle aufnehmen kann.

Das Ändern des Wertes (Default) von <StaticWebAssetProjectMode> oder das Entfernen der Eigenschaft aus dem .Client-Projekt wird nicht unterstützt.

Statische Dateien in Nicht-Development-Umgebungen

Dieser Abschnitt gilt für serverseitige statische Dateien.

Wenn eine App lokal ausgeführt wird, werden statische Web-Assets nur in der Development-Umgebung aktiviert. Um statische Dateien für andere Umgebungen als Development während der lokalen Entwicklung und bei lokalen Tests (z. B. Staging) zu aktivieren, rufen Sie UseStaticWebAssets für WebApplicationBuilder in der Program-Datei auf.

Warnung

Rufen Sie UseStaticWebAssets auf, um die genaue Umgebung zu erhalten. So können Sie die Aktivierung des Features in der Produktion verhindern, da Dateien von anderen Speicherorten auf dem Datenträger, die vom Projekt abweichen getrennt werden, wenn der Aufruf in einer Produktionsumgebung erfolgt. Im Beispiel in diesem Abschnitt wird die Staging-Umgebung durch Aufrufen von IsStaging überprüft.

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

Präfix für Blazor WebAssembly Ressourcen

Dieser Abschnitt gilt für Blazor Web Apps.

Mit der WebAssemblyComponentsEndpointOptions.PathPrefix-Endpunktoption können Sie die Pfadzeichenfolge festlegen, die das Präfix für Blazor WebAssembly-Ressourcen angibt. Der Pfad muss einem Referenzanwendungsprojekt Blazor WebAssembly entsprechen.

endpoints.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode(options => 
        options.PathPrefix = "{PATH PREFIX}");

Im vorherigen Beispiel ist der {PATH PREFIX} Platzhalter das Pfadpräfix und muss mit einem Schrägstrich (/) beginnen.

Im folgenden Beispiel wird das Pfadpräfix auf /path-prefixfestgelegt:

endpoints.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode(options => 
        options.PathPrefix = "/path-prefix");

Basispfad der statischen Webressource

Dieser Abschnitt gilt für eigenständige Blazor WebAssembly-Apps.

Durch die Veröffentlichung der App werden die statischen Assets der App, einschließlich der Blazor Framework-Dateien (_framework Ordner-Assets), im Stammverzeichnis (/) der veröffentlichten Ausgabe abgelegt. Die in der Projektdatei (.csproj) angegebene <StaticWebAssetBasePath>-Eigenschaft legt den Basispfad auf einen Nicht-Stammpfad fest:

<PropertyGroup>
  <StaticWebAssetBasePath>{PATH}</StaticWebAssetBasePath>
</PropertyGroup>

Im vorherigen Beispiel entspricht der {PATH}-Platzhalter dem Pfad.

Ohne Festlegen der <StaticWebAssetBasePath>-Eigenschaft wird eine eigenständige App unter /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/ veröffentlicht.

Im vorherigen Beispiel ist der Platzhalter {TFM} der Zielframeworkmoniker (Target Framework Moniker (TFM)) (z. B. net6.0).

Wenn die <StaticWebAssetBasePath>-Eigenschaft in einer eigenständigen Blazor WebAssembly-App den Pfad zu veröffentlichten statischen Ressourcen auf app1 festlegt, ist /app1 der Stammpfad zur App in der veröffentlichten Ausgabe.

In der Projektdatei der eigenständigen Blazor WebAssembly-App (.csproj):

<PropertyGroup>
  <StaticWebAssetBasePath>app1</StaticWebAssetBasePath>
</PropertyGroup>

In der veröffentlichten Ausgabe lautet der Pfad zur eigenständigen Blazor WebAssembly-App: /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/.

Im vorherigen Beispiel ist der Platzhalter {TFM} der Zielframeworkmoniker (Target Framework Moniker (TFM)) (z. B. net6.0).

Dateizuordnungen und Optionen für statische Dateien

Dieser Abschnitt gilt für serverseitige statische Dateien.

Verwenden Sie einen der folgenden Ansätze, um zusätzliche Dateizuordnungen mit einem FileExtensionContentTypeProvider zu erstellen oder andere StaticFileOptions zu konfigurieren. In den folgenden Beispielen ist der Platzhalter {EXTENSION} die Dateierweiterung und der Platzhalter {CONTENT TYPE} der Inhaltstyp. Der Namespace für die folgende API lautet Microsoft.AspNetCore.StaticFiles.

• Konfigurieren Sie Optionen über die Dependency Injection (DI) in der Program-Datei mithilfe von StaticFileOptions:

  var provider = new FileExtensionContentTypeProvider();
  provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";
  
  builder.Services.Configure<StaticFileOptions>(options =>
  {
      options.ContentTypeProvider = provider;
  });
  
  app.UseStaticFiles();
  

• Übergeben Sie StaticFileOptions direkt an UseStaticFiles in der Program-Datei:

  var provider = new FileExtensionContentTypeProvider();
  provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";
  
  app.UseStaticFiles(new StaticFileOptions { ContentTypeProvider = provider });
  

Bereitstellen von Dateien aus mehreren Speicherorten

Der Leitfaden in diesem Abschnitt gilt nur für Blazor Web Apps.

So stellen Sie mit einem CompositeFileProvider Dateien aus mehreren Speicherorten bereit:

• Fügen Sie den Namespace für Microsoft.Extensions.FileProviders am Anfang der Program-Datei des Serverprojekts hinzu.
• Führen Sie in der Program-Datei des Serverprojekts Folgendes vor dem Aufrufen von UseStaticFiles aus:
  • Erstellen Sie mit dem Pfad zu den statischen Ressourcen einen PhysicalFileProvider.
  • Erstellen Sie aus dem WebRootFileProvider und dem PhysicalFileProvider einen CompositeFileProvider. Weisen Sie den Verbunddateianbieter wieder dem WebRootFileProvider der App zu.

Beispiel:

Erstellen Sie im Serverprojekt einen neuen Ordner mit dem Namen AdditionalStaticAssets. Legen Sie ein Bild im Ordner ab.

Fügen Sie die folgende using-Anweisung am Anfang der Program-Datei des Serverprojekts hinzu:

using Microsoft.Extensions.FileProviders;

Fügen Sie in der Program-Datei des Serverprojekts vor dem Aufrufen von UseStaticFiles den folgenden Code hinzu:

var secondaryProvider = new PhysicalFileProvider(
    Path.Combine(builder.Environment.ContentRootPath, "AdditionalStaticAssets"));
app.Environment.WebRootFileProvider = new CompositeFileProvider(
    app.Environment.WebRootFileProvider, secondaryProvider);

Verweisen Sie im Markup der Home-Komponente (Home.razor) der App auf das Bild mit einem <img>-Tag:

<img src="{IMAGE FILE NAME}" alt="{ALT TEXT}" />

Im vorherigen Beispiel:

• Der Platzhalter {IMAGE FILE NAME} ist der Bilddateiname. Es muss kein Pfadsegment angegeben werden, wenn sich die Bilddatei im Stammverzeichnis des Ordners AdditionalStaticAssets befindet.
• Der Platzhalter {ALT TEXT} ist der Alternativtext des Bilds.

Führen Sie die App aus.

Zusätzliche Ressourcen

• Basispfad einer App
• Vermeiden der Dateierfassung in einem Routenparameter