ASP.NET Core-App-Basispfad Blazor

In diesem Artikel wird der App-Basispfad in ASP.NET Core-Apps Blazor erläutert, einschließlich Konfigurationsanleitungen.

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.

Für die Quellen von Links, 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 Blazor-Hub von SignalR 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 (https://www.contoso.com/CoolApp/)<base>auch als relativer Stammpfad bezeichnet 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 den <base>-Tag im <head>-Markup (Speicherort des <head>-Inhalts) vor allen Elementen mit Attributwerten, die URLs sind, wie die href-Attribute der <link>-Elemente.

• 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 UsePathBasezuerst 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 launchSettings.json Datei finden Sie unter ASP.NET Core-Laufzeitumgebungen. 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 launchSettings.json Datei finden Sie unter ASP.NET Core-Laufzeitumgebungen. 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:

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