Hosten und Bereitstellen von ASP.NET Core Blazor

In diesem Artikel wird erläutert, wie Sie Blazor-Apps hosten und bereitstellen.

Veröffentlichen der App

Apps werden für die Bereitstellung in Releasekonfigurationen veröffentlicht.

dotnet publish -c Release

Das Veröffentlichen einer App löst eine Wiederherstellung der Abhängigkeiten des Projekts aus und erstellt das Projekt, bevor die Objekte für die Bereitstellung erstellt werden. Im Rahmen des Buildprozesses werden nicht verwendete Methoden und Assemblys entfernt, um die Downloadgröße und Ladezeiten von Apps zu reduzieren.

Veröffentlichungsspeicherorte:

Der Abschnitt {TARGET FRAMEWORK} in den vorherigen Pfaden steht für das Zielframework (z. B. net8.0).

IIS

Informationen zum Hosten einer Blazor-App in IIS finden Sie in den folgenden Ressourcen:

• IIS-Hosting
  • Veröffentlichen einer ASP.NET Core-App in IIS
  • Hosten von ASP.NET Core unter Windows mit IIS
• Hosten und Bereitstellen von serverseitigen ASP.NET Core Blazor-Apps: Server-Apps, die in IIS ausgeführt werden, einschließlich IIS mit virtuellen Azure-Computern (Virtual Machines, VMs) unter dem Windows-Betriebssystem und mit Azure App Service.
• Hosten und Bereitstellen von ASP.NET Core Blazor WebAssembly: Enthält zusätzliche Anleitungen für Blazor WebAssembly-Apps, die in IIS gehostet werden. Dies schließt das Hosten statischer Websites, benutzerdefinierte Dateien vom Typ web.config, URL-Umschreibung, untergeordnete Apps, Komprimierung und das Hosten statischer Dateien von Azure Storage ein.
• IIS-Hosting untergeordneter Anwendungen
  • Befolgen Sie die Anleitungen im Abschnitt Basispfad einer App für die Blazor-App, bevor Sie die App veröffentlichen. In den Beispielen wird der App-Basispfad /CoolApp verwendet und gezeigt, wie Sie den Basispfad aus App-Einstellungen oder anderen Konfigurationsanbietern abrufen.
  • Folgen Sie der Anleitung zum Konfigurieren untergeordneter Anwendungen unter Erweiterte Konfiguration. Der Ordnerpfad der untergeordneten App unter der Stammwebsite wird zum virtuellen Pfad der untergeordneten App. Bei einem App-Basispfad wie /CoolApp wird die Blazor-App in einem Ordner mit dem Namen CoolApp unter der Stammwebsite platziert, und die untergeordnete App verwendet einen virtuellen Pfad (/CoolApp).

Das Freigeben eines App-Pools zwischen ASP.NET Core-Apps wird nicht unterstützt, auch nicht für Blazor-Apps. Verwenden Sie beim Hosten mit IIS einen App-Pool pro App, und vermeiden Sie die Verwendung der virtuellen IIS-Verzeichnisse zum Hosten mehrerer Apps.

Basispfad einer App

Der Basispfad einer App beschreibt den URL-Stammpfad der App. Erfolgreiches Routing in Blazor-Apps erfordert eine Frameworkkonfiguration für alle Stamm-URL-Pfade, die sich nicht im Standard-App-Basispfad / befinden.

Betrachten Sie die folgende ASP.NET Core-App und die untergeordnete Blazor-App:

• Die ASP.NET Core-App heißt MyApp:
  • Die App befindet sich physisch unter d:/MyApp.
  • Anforderungen werden über https://www.contoso.com/{MYAPP RESOURCE} empfangen.
• Eine Blazor-App mit dem Namen CoolApp ist die untergeordnete App von MyApp:
  • Die untergeordnete App befindet sich physisch unter d:/MyApp/CoolApp.
  • Anforderungen werden über https://www.contoso.com/CoolApp/{COOLAPP RESOURCE} empfangen.

Wenn keine zusätzlichen Konfiguration für CoolApp festgelegt wird, weiß die untergeordnete App in diesem Szenario nicht, wo sie sich auf dem Server befindet. Beispielsweise kann die App keine richtigen relativen URLs zu ihren Ressourcen erstellen, ohne zu wissen, dass sie sich unter dem relativen URL-Pfad /CoolApp/ befindet. Das gilt auch in verschiedenen Hosting- und Reverseproxyszenarios, wenn eine App nicht unter einem URL-Stammpfad gehostet wird.

Hintergrund

Das Ziel eines Ankertags (href) kann mit einem von zwei Endpunkten erstellt werden:

• Absolute Speicherorte, die ein Schema (ohne Angabe wird standardmäßig das Schema der Seite verwendet), einen Host, einen Port und einen Pfad enthalten, oder nur ein Schrägstrich (/) gefolgt vom Pfad.

  Beispiel: https://example.com/a/b/c oder /a/b/c

• Relative Speicherorte, die nur einen Pfad enthalten und nicht mit einem Schrägstrich (/) beginnen. Diese werden relativ zur aktuellen Dokument-URL oder relativ zum Wert des <base>-Tags aufgelöst (sofern angegeben).

  Beispiel: a/b/c

Das Vorhandensein eines nachgestellten Schrägstrichs (/) in einem konfigurierten App-Basispfad ist wichtig, um den Basispfad für URLs der App zu berechnen. Beispielsweise hat https://example.com/a den Basispfad https://example.com/, während https://example.com/a/ mit einem nachgestellten Schrägstrich den Basispfad https://example.com/a hat.

Es gibt drei Linkquellen, die sich auf Blazor in ASP.NET Core-Apps beziehen:

Wenn Sie eine Blazor-App aus verschiedenen Dokumenten rendern (z. B. /Admin/B/C/ und /Admin/D/E/), müssen Sie den App-Basispfad berücksichtigen. Andernfalls unterscheidet sich der Basispfad, wenn die App in den einzelnen Dokumenten gerendert wird, und die Ressourcen werden von den falschen URLs abgerufen.

Es gibt zwei Ansätze für die korrekte Auflösung relativer Links:

• Dynamisches Zuordnen der Ressourcen, wobei das Dokument, auf dessen Grundlage sie gerendert wurden, als Stamm verwendet wird
• Festlegen eines konsistenten Basispfads für das Dokument und Zuordnen der Ressourcen unter diesem Basispfad

Die erste Option ist komplizierter und nicht der gängigste Ansatz, da die Navigation für jedes Dokument unterschiedlich ist. Betrachten Sie das folgende Beispiel zum Rendern der Seite /Something/Else:

• Beim Rendern unter /Admin/B/C/ wird die Seite mit dem Pfad /Admin/B/C/Something/Else gerendert.
• Beim Rendern unter /Admin/D/E/ wird die Seite unter dem gleichen Pfad (also /Admin/B/C/Something/Else) gerendert.

Beim ersten Ansatz liefert das Routing IDynamicEndpointMetadata und MatcherPolicy. Die Kombination aus beidem kann die Basis für die Implementierung einer vollständig dynamischen Lösung sein, die zur Laufzeit bestimmt, wie Anforderungen weitergeleitet werden.

Die zweite Option ist die übliche Vorgehensweise. Hierbei legt die App den Basispfad im Dokument fest und ordnet die Serverendpunkte Pfaden unter der Basis zu. Dieser Ansatz wird in den folgenden Anleitungen verwendet.

Serverseitige Blazor-App

Ordnen Sie den SignalR-Hub einer serverseitigen Blazor-App zu, indem Sie den Pfad zu MapBlazorHub in der Program-Datei übergeben:

app.MapBlazorHub("base/path");

Der Vorteil der Verwendung von MapBlazorHub ist, dass Sie Muster wie "{tenant}" und nicht nur konkrete Pfade zuordnen können.

Sie können den SignalR-Hub auch zuordnen, wenn sich die App in einem virtuellen Ordner mit einer verzweigten Middleware-Pipeline befindet. Im folgenden Beispiel werden Anforderungen an/base/path/ vom SignalR-Hub von Blazor behandelt:

app.Map("/base/path/", subapp => {
    subapp.UsePathBase("/base/path/");
    subapp.UseRouting();
    subapp.UseEndpoints(endpoints => endpoints.MapBlazorHub());
});

Konfigurieren Sie das Tag <base> gemäß der Anleitung im Abschnitt Konfigurieren des Basispfads der App.

Eigenständige Blazor WebAssembly-App

In einer eigenständigen Blazor WebAssembly-App wird nur das Tag <base> gemäß der Anleitung im Abschnitt Konfigurieren des Basispfads der App konfiguriert.

Konfigurieren des Basispfads der App

Um die Konfiguration für den Basispfad der Blazor App bereitzustellen, legen Sie den App-Basispfad (<base>) fest, der auch als relativer Stammpfad bezeichnet https://www.contoso.com/CoolApp/wird.

Durch Konfigurieren des Basispfads der App kann eine Komponente, die sich nicht im Stammverzeichnis befindet, URLs relativ zum Stammpfad der App erstellen. Komponenten auf verschiedenen Verzeichnisstrukturebenen können Links zu anderen Ressourcen an Speicherorten in der gesamten App erstellen. Ferner wird der Basispfad der App verwendet, um ausgewählte Hyperlinks abzufangen, bei denen sich das href-Ziel des Links innerhalb des URI-Raums für den Basispfad der App befindet. Die Router-Komponente verarbeitet die interne Navigation.

Platzieren Sie das <base> Tag im <head> Markup (Speicherort des <head> Inhalts) vor Allen Elementen mit Attributwerten, die URLs sind, z. B. die href Attribute von <link> Elementen.

• Verwenden Sie in einer serverseitigen Blazor-App einen der folgenden Ansätze:

  • Option 1: Verwenden Sie das Tag <base>, um den Basispfad der App (Speicherort von <head>-Inhalten) festzulegen:

    <base href="/CoolApp/">
    

    Der nachstehende Schrägstrich ist erforderlich.

  • Option 2: Rufen Sie UsePathBase zuerst in der Anforderungsverarbeitungspipeline der App (Program.cs) auf, und zwar unmittelbar nach der Erstellung von WebApplicationBuilder (builder.Build()), um den Basispfad für ggf. folgende Middleware zu konfigurieren, die mit dem Anforderungspfad interagiert:

    app.UsePathBase("/CoolApp");
    

    Das Aufrufen von UsePathBase wird empfohlen, wenn Sie die Blazor Server-App auch lokal ausführen möchten. Geben Sie die Start-URL beispielsweise in Properties/launchSettings.json an:

    "launchUrl": "https://localhost:{PORT}/CoolApp",
    

    Der Platzhalter {PORT} im vorherigen Beispiel ist der Port, der dem sicheren Port im Konfigurationspfad applicationUrl entspricht. Das folgende Beispiel zeigt das vollständige Startprofil für eine App an Port 7279:

    "BlazorSample": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7279;http://localhost:5279",
      "launchUrl": "https://localhost:7279/CoolApp",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
    }
    

    Weitere Informationen zur Datei launchSettings.json finden Sie im Artikel Verwenden von mehreren Umgebungen in ASP.NET Core. Weitere Informationen zu Blazor-App-Basispfaden und zum Hosting finden Sie unter <base href="/" /> or base-tag alternative for Blazor MVC integration (dotnet/aspnetcore #43191).

• Eigenständige Blazor WebAssembly-App (wwwroot/index.html):

  <base href="/CoolApp/">
  

  Der nachstehende Schrägstrich ist erforderlich.

Stellen Sie den Links in der App keinen Schrägstrich voran. Vermeiden Sie entweder die Verwendung eines Pfadsegmenttrennzeichens, oder verwenden Sie eine relative Pfadnotation mit einem Punkt und einem Schrägstrich (./):

• ❌ Falsch: <a href="/account">
• ✔️ Richtig: <a href="account">
• ✔️ Richtig: <a href="./account">

In Blazor WebAssembly-Web-API-Anfragen mit dem HttpClient-Dienst muss sichergestellt werden, dass JSON-Hilfsprogramme (HttpClientJsonExtensions) den URLs keinen Schrägstrich (/) voranstellen:

• ❌ Falsch: var rsp = await client.GetFromJsonAsync("/api/Account");
• ✔️ Richtig: var rsp = await client.GetFromJsonAsync("api/Account");

Stellen Sie Navigationsmanager relativen Links keinen Schrägstrich voran. Vermeiden Sie entweder die Verwendung eines Pfadsegmenttrennzeichens, oder verwenden Sie einen Punkt und einen Schrägstrich (./) für eine relative Pfadnotation (Navigation ist ein eingefügtes NavigationManager-Element):

• ❌ Falsch: Navigation.NavigateTo("/other");
• ✔️ Richtig: Navigation.NavigateTo("other");
• ✔️ Richtig: Navigation.NavigateTo("./other");

In der Regel ist beim Azure- oder IIS-Hosting keine zusätzliche Konfiguration erforderlich. Beim Hosting ohne IIS oder beim Reverseproxyhosting kann eine zusätzliche Konfiguration der Middleware für statische Dateien erforderlich sein, um Folgendes zu erreichen:

• Korrektes Bereitstellen statischer Dateien (z. B. app.UseStaticFiles("/CoolApp");)
• Zum Bereitstellen des Blazor-Skripts (_framework/blazor.*.js). Weitere Informationen finden Sie unter Blazor in ASP.NET Core: statische Dateien.

Bei einer Blazor WebAssembly-App mit einem relativen URL-Pfad, der nicht zum Stammverzeichnis führt (z. B. <base href="/CoolApp/">), werden die Ressourcen der App nicht gefunden, wenn die App lokal ausgeführt wird. Um dieses Problem bei der lokalen Entwicklung und bei Tests zu beheben, können Sie ein Pfadbasis-Argument bereitstellen, das dem href-Wert des <base>-Tags zur Laufzeit entspricht. Fügen Sie keinen nachgestellten Schrägstrich ein. Führen Sie den Befehl dotnet watch (oder dotnet run) aus dem Verzeichnis der App mit der Option --pathbase aus, um das Basispfadargument beim lokalen Ausführen der App zu übergeben:

dotnet watch --pathbase=/{RELATIVE URL PATH (no trailing slash)}

Für eine Blazor WebAssembly-App mit einem relativen URL-Pfad von /CoolApp/ (<base href="/CoolApp/">) lautet der Befehl wie folgt:

dotnet watch --pathbase=/CoolApp

Wenn Sie das Startprofil der App so konfigurieren möchten, dass pathbase automatisch und nicht manuell mit dotnet watch (oder dotnet run) angegeben wird, legen Sie die commandLineArgs-Eigenschaft in Properties/launchSettings.json fest. Im Folgenden wird auch die Start-URL konfiguriert (launchUrl):

"commandLineArgs": "--pathbase=/{RELATIVE URL PATH (no trailing slash)}",
"launchUrl": "{RELATIVE URL PATH (no trailing slash)}",

Verwenden Sie CoolApp als Beispiel:

"commandLineArgs": "--pathbase=/CoolApp",
"launchUrl": "CoolApp",

Verwenden Sie entweder dotnet watch (oder dotnet run) mit der Option --pathbase oder eine Startprofilkonfiguration, die den Basispfad festlegt. Die Blazor WebAssembly-App reagiert lokal unter http://localhost:port/CoolApp.

Weitere Informationen zur Datei launchSettings.json finden Sie im Artikel Verwenden von mehreren Umgebungen in ASP.NET Core. Weitere Informationen zu Blazor-App-Basispfaden und zum Hosting finden Sie unter <base href="/" /> or base-tag alternative for Blazor MVC integration (dotnet/aspnetcore #43191).

Abrufen des App-Basispfads aus der Konfiguration

Im folgenden Leitfaden wird erläutert, wie Sie den Pfad für das <base>-Tag aus einer App-Einstellungsdatei für verschiedene Umgebungen abrufen.

Fügen Sie der App die App-Einstellungsdatei hinzu. Das folgende Beispiel gilt für die Staging-Umgebung (appsettings.Staging.json):

{
  "AppBasePath": "staging/"
}

Laden Sie in einer serverseitigen Blazor-App den Basispfad aus der Konfiguration in <head> Inhalt:

@inject IConfiguration Config

...

<head>
    ...
    <base href="/@(Config.GetValue<string>("AppBasePath"))" />
    ...
</head>

app.UsePathBase($"/{app.Configuration.GetValue<string>("AppBasePath")}");

Wenn kein Konfigurationswert geladen werden soll, z. B. in Nicht-Staging-Umgebungen, wird die vorangehende href in den Stammpfad / aufgelöst.

Die Beispiele in diesem Abschnitt konzentrieren sich auf die Bereitstellung des App-Basispfads aus den App-Einstellungen, aber der Ansatz zum Lesen des Pfads aus IConfiguration ist für jeden Konfigurationsanbieter gültig. Weitere Informationen finden Sie in den folgenden Ressourcen:

• Blazor-Konfiguration in ASP.NET Core
• Konfiguration in ASP.NET Core

Blazor ServerMapFallbackToPage-Konfiguration

Dieser Abschnitt gilt nur für Blazor Server-Apps. MapFallbackToPage wird in Blazor Web Apps und Blazor WebAssembly-Apps nicht unterstützt.

Falls eine App einen separaten Bereich mit benutzerdefinierten Ressourcen und Razor-Komponenten erfordert:

• Erstellen Sie im Ordner Pages der App einen Ordner für die Ressourcen. Der Administratorbereich einer App wird beispielsweise in einem Ordner namens Admin (Pages/Admin) erstellt.

• Erstellen Sie eine Stammseite (_Host.cshtml) für den Bereich. Erstellen Sie beispielsweise eine Pages/Admin/_Host.cshtml-Datei aus der Hauptstammseite der App (Pages/_Host.cshtml). Geben Sie auf der _Host-Seite für Administrator*innen keine @page-Anweisung an.

• Fügen Sie dem Ordner des Bereichs ein Layout hinzu (z. B. Pages/Admin/_Layout.razor). Legen Sie das <base>-Tag href im Layout für den separaten Bereich so fest, dass es mit dem Ordner des Bereichs übereinstimmt (z. B. <base href="/Admin/" />). Fügen Sie zu Demonstrationszwecken ~/ zu den statischen Ressourcen auf der Seite hinzu. Beispiel:

  • ~/css/bootstrap/bootstrap.min.css
  • ~/css/site.css
  • ~/BlazorSample.styles.css (der Namespace der Beispiel-App lautet BlazorSample)
  • ~/_framework/blazor.server.js (Blazor-Skript)

• Wenn der Bereich über einen eigenen Ordner für statische Ressourcen verfügen soll, fügen Sie einen Ordner hinzu, und geben Sie dessen Speicherort in der Middleware für statische Dateien in Program.cs (z. B. app.UseStaticFiles("/Admin/wwwroot")) an.

• Razor-Komponenten werden dem Ordner des Bereichs hinzugefügt. Fügen Sie dem Bereichsordner mindestens eine Index-Komponente mit der richtigen @page-Anweisung für den Bereich hinzu. Fügen Sie beispielsweise eine Pages/Admin/Index.razor-Datei hinzu, die auf der Pages/Index.razor-Standarddatei der App basiert. Geben Sie den Bereich Admin als Routenvorlage am Anfang der Datei an (@page "/admin"). Fügen Sie bei Bedarf zusätzliche Komponenten hinzu. Geben Sie beispielsweise Pages/Admin/Component1.razor mit einer @page-Anweisung und der Routenvorlage @page "/admin/component1 an.

• Rufen Sie in Program.cs die Methode MapFallbackToPage für den Anforderungspfad des Bereichs unmittelbar vor dem Pfad der Fallbackstammseite auf die _Host-Seite auf:

  ...
  app.UseRouting();
  
  app.MapBlazorHub();
  app.MapFallbackToPage("~/Admin/{*clientroutes:nonfile}", "/Admin/_Host");
  app.MapFallbackToPage("/_Host");
  
  app.Run();
  

Bereitstellung

Anleitungen für die Bereitstellung finden Sie in folgenden Themen:

• Hosten und Bereitstellen von in ASP.NET CoreBlazor WebAssembly
• Hosten und Bereitstellen von serverseitigen ASP.NET Core Blazor-Apps