Statische Blazor-Dateien in ASP.NET Core

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

Allgemeine Informationen über die Bereitstellung statischer Dateien mit den Routing-Endpunkt-Konventionen von Map Static Assets finden Sie unter Map static files in ASP.NET Core, bevor Sie diesen Artikel lesen.

Bereitstellung statischer Ressourcen in serverseitigen Blazor Apps

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

Merkmal	Programmierschnittstelle (API)	.NET-Version	Beschreibung
Routing-Endpunkt-Konventionen für statische Assets zuordnen	MapStaticAssets	.NET 9 oder höher	Optimiert die Bereitstellung statischer Objekte an Clients.
Middleware für statische Dateien	UseStaticFiles	Alle .NET-Versionen	Liefert statische Assets an Clients ohne die Optimierungen von Map Static Assets, aber nützlich für einige Aufgaben, die Map Static Assets nicht bewältigen kann.

Map Static Assets kann UseStaticFiles in den meisten Situationen ersetzen. Map Static Assets ist jedoch dafür optimiert, die Assets zum Zeitpunkt der Erstellung und Veröffentlichung an bekannten Stellen in der App bereitzustellen. 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 auch Aufrufe von UseBlazorFrameworkFiles in Apps, die Blazor WebAssembly Frameworkdateien bereitstellen, und das explizite Aufrufen von UseBlazorFrameworkFiles in einer Blazor Web App Datei ist nicht erforderlich, da die API beim Aufrufen von AddInteractiveWebAssemblyComponents automatisch aufgerufen wird.

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

• Blazor erstellt einen Endpunkt, um die Ressourcenaufstellung als Modul JS 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 unter einer menschenlesbaren URL (_framework/resource-collection.js) bereitgestellt, sodass JS Zugang zur Ressourcensammlung für die erweiterte Navigation oder die Implementierung von Features anderer Frameworks und Drittanbieterkomponenten hat.

Static File Middleware (UseStaticFiles) ist in den folgenden Situationen nützlich, die Map Static Assets (MapStaticAssets) nicht bewältigen können:

• Bereitstellen von Dateien vom Datenträger, die nicht Teil des Build- oder Veröffentlichungsprozesses sind, z. B. Dateien, die dem Anwendungsordner während oder nach der Bereitstellung hinzugefügt wurden.
• 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.

Assets mit Map Static Assets Routing-Endpunktkonventionen liefern

Dieser Abschnitt gilt für serverseitige Blazor-Apps.

Assets werden über die Eigenschaft ComponentBase.Assets geliefert, die die URL mit Fingerabdruck für ein bestimmtes Asset auflöst. Im folgenden Beispiel werden Bootstrap, das Stylesheet der Projektvorlagen-App (Blazor) und das app.css (basierend auf dem Namespace einer App) in einer Stammkomponente verknüpft, in der Regel die BlazorSample Komponente (App):Components/App.razor

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

ImportMap-Komponente

Dieser Abschnitt gilt für Blazor Web Apps, die MapRazorComponents aufrufen.

Die ImportMap Komponente (ImportMap) stellt ein Importzuordnungselement (<script type="importmap"></script>) dar, das die Zuordnung für Modulskripte definiert. Die Komponente Import Map wird im <head>-Inhalt der Stammkomponente platziert, normalerweise der App-Komponente (Components/App.razor).

<ImportMap />

Wenn einer Importkarte-Komponente kein benutzerdefinierter ImportMapDefinition zugewiesen ist, wird die Importkarte basierend auf den Ressourcen der App generiert.

Hinweis

ImportMapDefinition Instanzen sind teuer zu erstellen, daher wird empfohlen, sie beim Erstellen einer zusätzlichen Instanz zwischenzuspeichern.

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

Grundlegende Importkarte:

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"
  }
}

Scoped Import Map:

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"
    }
  }
}

Karte 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 Sie Import Map-Definitionen (ImportMapDefinition) mit ImportMapDefinition.Combine.

Importieren Sie eine Karte, die aus einer ResourceAssetCollection erstellt wurde und statische Assets 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"
  }
}

Karte „Verstöße gegen die Content Security Policy (CSP)“ importieren

Dieser Abschnitt gilt für Blazor Web Apps, die MapRazorComponents aufrufen.

Die ImportMap-Komponente wird als Inline-Tag <script> gerendert, was gegen eine strenge Inhaltssicherheitsrichtlinie (Content Security Policy, CSP) verstößt, die die default-src- oder script-src-Richtlinie festlegt.

Beispiele für die Behandlung der Richtlinienverletzung mit Subresource Integrity (SRI) oder einer kryptografischen Nonce finden Sie unter Beheben von CSP-Verstößen mit Subresource Integrity (SRI) oder einer Nonce.

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	href-Wert	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	href-Wert	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	href-Wert	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.

Das Veröffentlichen der App platziert die statischen Assets der App, einschließlich der Blazor-Framework-Dateien (_framework-Ordner-Assets), im Stammverzeichnis (/) in der veröffentlichten Ausgabe. Die in der Projektdatei (<StaticWebAssetBasePath>) angegebene .csproj-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 {TFM}-Platzhalter der Zielframeworkmoniker (TFM).

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 {TFM}-Platzhalter der Zielframeworkmoniker (TFM).

Dateizuordnungen und Optionen für statische Dateien

Dieser Abschnitt gilt für serverseitige statische Dateien.

Verwenden Sie FileExtensionContentTypeProvider der folgenden Ansätze, um zusätzliche Dateizuordnungen mit einem StaticFileOptions zu erstellen oder andere 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

Die Anweisungen in diesem Abschnitt gelten nur für Blazor Web App.

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.
• In der Program-Datei des Serverprojekts führen Sie Folgendes vor dem Aufrufen von UseStaticFiles aus:
  • Erstellen Sie einen PhysicalFileProvider mit dem Pfad zu den statischen Ressourcen.
  • Erstellen Sie aus dem CompositeFileProvider und dem WebRootFileProvider einen PhysicalFileProvider. 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

• ASP.NET Core-App-Basispfad Blazor
• Vermeiden der Dateierfassung in einem Routenparameter