bassökväg för ASP.NET Core-app Blazor

I den här artikeln beskrivs appbassökvägen i ASP.NET Core-appar Blazor , inklusive konfigurationsvägledning.

Den basvägen för appen är appens rot-URL-väg. För att routning i Blazor appar ska lyckas krävs ramverkskonfiguration för alla rot-URL-sökvägar som inte är vid standardappens bassökväg /.

Överväg följande ASP.NET Core-app och Blazor underapp:

• ASP.NET Core-appen heter MyApp:
  • Appen finns fysiskt på d:/MyApp.
  • Begäranden tas emot på https://www.contoso.com/{MYAPP RESOURCE}.
• En Blazor app med namnet CoolApp är en underapp för MyApp:
  • Underappen finns fysiskt på d:/MyApp/CoolApp.
  • Begäranden tas emot på https://www.contoso.com/CoolApp/{COOLAPP RESOURCE}.

Utan att ange ytterligare konfiguration för CoolApphar underappen i det här scenariot ingen kunskap om var den finns på servern. Appen kan till exempel inte konstruera rätt relativa URL:er till sina resurser utan att veta att den finns på den relativa URL-sökvägen /CoolApp/. Det här scenariot gäller även i olika värd- och omvända proxyscenarier när en app inte finns på en rot-URL-sökväg.

Bakgrund

En ankartaggs mål (href) kan bestå av en av två slutpunkter:

• Absoluta platser som innehåller ett schema (standardvärdet för sidans schema om det utelämnas), värd, port och sökväg eller bara ett snedstreck (/) följt av sökvägen.

  Exempel: https://example.com/a/b/c eller /a/b/c

• Relativa platser som bara innehåller en sökväg och inte börjar med ett snedstreck (/). Dessa löses i förhållande till den aktuella dokument-URL:en eller <base>-taggens värde, om det anges.

  Exempel: a/b/c

Förekomsten av ett avslutande snedstreck (/) i en konfigurerad appbassökväg är viktig för att beräkna bassökvägen för appens URL:er. https://example.com/a har till exempel en bassökväg för https://example.com/, medan https://example.com/a/ med ett avslutande snedstreck har en bassökväg för https://example.com/a.

För källor till länkar som avser Blazor i ASP.NET Core-appar:

Om du återger en Blazor app från olika dokument (till exempel /Admin/B/C/ och /Admin/D/E/) måste du ta hänsyn till appens bassökväg, eller så är bassökvägen annorlunda när appen renderas i varje dokument och resurserna hämtas från fel URL:er.

Det finns två sätt att hantera utmaningen att lösa relativa länkar korrekt:

• Mappa resurserna dynamiskt med det dokument som de renderades på som rot.
• Ange en konsekvent bassökväg för dokumentet och mappa resurserna under den bassökvägen.

Det första alternativet är mer komplicerat och är inte den mest typiska metoden, eftersom det gör navigeringen olika för varje dokument. Överväg följande exempel för att återge en sida /Something/Else:

• Renderad under /Admin/B/C/, renderas sidan med en sökväg av /Admin/B/C/Something/Else.
• Renderas under /Admin/D/E/renderas sidan på samma sökväg för /Admin/B/C/Something/Else.

Under den första metoden erbjuder routning IDynamicEndpointMetadata och MatcherPolicy, vilket i kombination kan vara grunden för att implementera en helt dynamisk lösning som vid körning avgör hur begäranden dirigeras.

För det andra alternativet, som är den vanliga metoden, anger appen bassökvägen i dokumentet och mappar serverslutpunkterna till sökvägar under basen. Följande vägledning använder den här metoden.

Blazor på serversidan

Mappa SignalR-hubben för en Blazor-app på serversidan genom att ange sökvägen till MapBlazorHub i filen Program.

app.MapBlazorHub("base/path");

Fördelen med att använda MapBlazorHub är att du kan mappa mönster, till exempel "{tenant}" och inte bara konkreta vägar.

Du kan också mappa SignalR hubben när appen finns i en virtuell mapp med en förgrening av middleware-pipeline. I följande exempel hanteras begäranden till /base/path/ av hubben Blazor från SignalR.

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

Konfigurera taggen <base> enligt vägledningen i avsnittet Konfigurera appens bassökväg.

Fristående Blazor WebAssembly

I en fristående Blazor WebAssembly app konfigureras endast taggen <base> enligt riktlinjerna i avsnittet Konfigurera appens bassökväg.

Konfigurera appens bassökväg

Om du vill ställa in konfigurationen för Blazor-appens bassökväg för https://www.contoso.com/CoolApp/ska du ange :s appbaskväg (<base>), som också kallas den relativa rotsökvägen.

Genom att konfigurera appbassökvägen kan en komponent som inte finns i rotkatalogen konstruera URL:er i förhållande till appens rotsökväg. Komponenter på olika nivåer i katalogstrukturen kan skapa länkar till andra resurser på platser i hela appen. Appens bassökväg används också för att intercepta valda hyperlänkar där målet för länken href finns inom URI-utrymmet för appens bassökväg. Komponenten Router hanterar den interna navigeringen.

Placera taggen <base> i <head> markering (plats för <head> innehåll) före alla element med attributvärden som är URL:er, till exempel href attribut för <link> element.

• I en Blazor app på serversidan använder du antingen av följande metoder:

  • Alternativ 1: Använd taggen <base> för att ange appens bassökväg (plats för <head> innehåll):

    <base href="/CoolApp/">
    

    Det avslutande snedstrecket krävs.

  • Alternativ 2: Anropa UsePathBaseförsta i appens pipeline för bearbetning av begäranden (Program.cs) omedelbart efter att WebApplicationBuilder har skapats (builder.Build()) för att konfigurera bassökvägen för alla följande mellanprogram som interagerar med begärandesökvägen:

    app.UsePathBase("/CoolApp");
    

    Anrop av UsePathBase rekommenderas när du även vill köra appen Blazor Server lokalt. Ange till exempel start-URL:en i Properties/launchSettings.json:

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

    Den {PORT}-platshållaren i det föregående exemplet är porten som matchar den säkra porten i den applicationUrl-konfigurationssökvägen. I följande exempel visas den fullständiga startprofilen för en app på 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"
    }
    

    Mer information om filen finns i launchSettings.jsonASP.NET Core-körningsmiljöer. Mer information om Blazor appbassökvägar och -värd finns i <base href="/" /> eller bastaggalternativ för Blazor MVC-integrering (dotnet/aspnetcore #43191).

• Fristående Blazor WebAssembly (wwwroot/index.html):

  <base href="/CoolApp/">
  

  Det avslutande snedstrecket krävs.

Prefixa inte länkar i hela appen med ett snedstreck. Undvik antingen att använda en sökvägssegmentavgränsare eller använd punkt-snedstreck (./) för relativ sökvägs notation.

• ❌ felaktig: <a href="/account">
• ✔️ korrekt: <a href="account">
• ✔️ korrekt: <a href="./account">

I Blazor WebAssembly webb-API-förfrågningar med HttpClient-tjänstenska du kontrollera att JSON-hjälpare (HttpClientJsonExtensions) inte lägger ett prefix på URL:er med ett snedstreck (/):

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

Prefixa inte Navigeringshanteraren relativa länkar med ett snedstreck. Undvik antingen att använda en sökvägssegmentavgränsare eller använd punkt-snedstreck (./) relativ sökvägs notation (Navigation är en inmatad NavigationManager):

• ❌ felaktig: Navigation.NavigateTo("/other");
• ✔️ korrekt: Navigation.NavigateTo("other");
• ✔️ korrekt: Navigation.NavigateTo("./other");

I vanliga konfigurationer för Azure/IIS-värdtjänster krävs vanligtvis ingen ytterligare konfiguration. I vissa värd- och omvända proxyvärdsscenarier som inte använder IIS kan ytterligare konfiguration av statisk mellanprogramvara behövas.

• Så här hanterar du statiska filer korrekt (till exempel app.UseStaticFiles("/CoolApp");).
• För att betjäna skriptet Blazor (_framework/blazor.*.js). Mer information finns i ASP.NET Core Blazor statiska filer.

För en Blazor WebAssembly app med en icke-rotrelativ URL-sökväg (till exempel <base href="/CoolApp/">) kan appen inte hitta sina resurser när den körs lokalt. För att lösa det här problemet under lokal utveckling och testning kan du ange ett argument för sökvägsbasen som matchar värdet href för taggen <base> vid körning. Ta inte med ett avslutande snedstreck. Om du vill skicka sökvägsbasargumentet när du kör appen lokalt kör du kommandot dotnet watch (eller dotnet run) från appens katalog med alternativet --pathbase:

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

För en Blazor WebAssembly-app med en relativ URL-sökväg på /CoolApp/ (<base href="/CoolApp/">) är kommandot:

dotnet watch --pathbase=/CoolApp

Om du föredrar att konfigurera appens startprofil för att ange pathbase automatiskt i stället för manuellt med dotnet watch (eller dotnet run), anger du egenskapen commandLineArgs i Properties/launchSettings.json. Följande konfigurerar även start-URL:en (launchUrl):

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

Använd CoolApp som exempel:

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

Antingen genom att använda dotnet watch (eller dotnet run) med alternativet --pathbase, eller genom en startprofilkonfiguration som anger bassökvägen, svarar appen Blazor WebAssembly lokalt på http://localhost:port/CoolApp.

Mer information om filen finns i launchSettings.jsonASP.NET Core-körningsmiljöer. Mer information om Blazor appbassökvägar och -värd finns i <base href="/" /> eller bastaggalternativ för Blazor MVC-integrering (dotnet/aspnetcore #43191).

Hämta appens bassökväg från konfigurationen

Följande vägledning beskriver hur du hämtar sökvägen för taggen <base> från en appinställningsfil för olika miljöer.

Lägg till appens inställningsfil i appen. Följande exempel är för den Staging miljön (appsettings.Staging.json):

{
  "AppBasePath": "staging/"
}

I en Blazor app på serversidan läser du in bassökvägen från konfigurationen i <head> innehåll:

@inject IConfiguration Config

...

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

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

Om det inte finns något konfigurationsvärde att läsa in, till exempel i icke-stagingmiljöer, löses föregående href till rotsökvägen /.

Exemplen i det här avsnittet fokuserar på att tillhandahålla appens bassökväg från appinställningar, men metoden för att läsa sökvägen från IConfiguration är giltig för alla konfigurationsleverantörer. Mer information finns i följande resurser:

• ASP.NET Core Blazor konfiguration
• Konfiguration i ASP.NET Core