basispad voor ASP.NET Core-app Blazor

In dit artikel wordt het basispad van de app in ASP.NET Core-apps Blazor uitgelegd, inclusief configuratierichtlijnen.

Het basispad van de app is het root-URL-pad van de app. Voor geslaagde routering in Blazor-apps is frameworkconfiguratie vereist voor elk hoofd-URL-pad dat zich niet op het standaard-app-basispad bevindt /.

Houd rekening met de volgende ASP.NET Core-app en Blazor sub-app:

• De ASP.NET Core-app heeft de naam MyApp:
  • De app bevindt zich fysiek op d:/MyApp.
  • Aanvragen worden ontvangen op https://www.contoso.com/{MYAPP RESOURCE}.
• Een Blazor-app met de naam CoolApp is een sub-app van MyApp:
  • De sub-app bevindt zich fysiek op d:/MyApp/CoolApp.
  • Aanvragen worden ontvangen op https://www.contoso.com/CoolApp/{COOLAPP RESOURCE}.

Zonder aanvullende configuratie voor CoolAppop te geven, heeft de sub-app in dit scenario geen kennis van waar deze zich op de server bevindt. De app kan bijvoorbeeld geen juiste relatieve URL's maken voor de resources zonder te weten dat deze zich bevindt op het relatieve URL-pad /CoolApp/. Dit scenario is ook van toepassing in verschillende scenario's voor hosting en omgekeerde proxy wanneer een app niet wordt gehost op een hoofd-URL-pad.

Achtergrond

De bestemming van een ankertag (href) kan worden samengesteld met een van de twee eindpunten:

• Absolute locaties die een schema bevatten (standaard ingesteld op het schema van de pagina als het wordt weggelaten), host, poort, en pad of alleen een schuine streep (/) gevolgd door het pad.

  Voorbeelden: https://example.com/a/b/c of /a/b/c

• Relatieve locaties die alleen een pad bevatten en niet beginnen met een slash (/). Deze worden omgezet ten opzichte van de URL van het huidige document of de waarde van de <base>-tag, indien opgegeven.

  Voorbeeld: a/b/c

De aanwezigheid van een afsluitende slash (/) in een geconfigureerd app-basispad is belangrijk om het basispad voor URL's van de app te berekenen. https://example.com/a heeft bijvoorbeeld een basispad van https://example.com/, terwijl https://example.com/a/ met een afsluitende slash een basispad van https://example.com/aheeft.

Voor de bronnen van koppelingen die betrekking hebben op Blazor in ASP.NET Core-apps:

Als u een Blazor-app uit verschillende documenten weergeeft (bijvoorbeeld /Admin/B/C/ en /Admin/D/E/), moet u rekening houden met het basispad van de app of het basispad verschilt wanneer de app in elk document wordt weergegeven en de resources worden opgehaald uit de verkeerde URL's.

Er zijn twee manieren om de uitdaging aan te pakken om relatieve koppelingen correct op te lossen:

• Wijs de resources dynamisch toe door het document waarop ze werden weergegeven als basis te gebruiken.
• Stel een consistent basispad in voor het document en wijs de resources onder dat basispad toe.

De eerste optie is ingewikkelder en is niet de meest gebruikelijke benadering, omdat het navigatie voor elk document anders maakt. Bekijk het volgende voorbeeld voor het weergeven van een pagina /Something/Else:

• Weergegeven onder /Admin/B/C/, wordt de pagina weergegeven met een pad van /Admin/B/C/Something/Else.
• Onder /Admin/D/E/wordt de pagina weergegeven op hetzelfde pad van /Admin/B/C/Something/Else.

Onder de eerste benadering biedt routering IDynamicEndpointMetadata en MatcherPolicy, die in combinatie de basis kan zijn voor het implementeren van een volledig dynamische oplossing die tijdens runtime bepaalt hoe aanvragen worden gerouteerd.

Voor de tweede optie, de gebruikelijke benadering, stelt de app het basispad in het document in en wijst de servereindpunten toe aan paden onder de basis. In de volgende richtlijnen wordt deze aanpak gebruikt.

Blazor aan de serverzijde

Wijs de SignalR hub van een Blazor-app aan de serverzijde toe door het pad door te geven naar MapBlazorHub in het Program bestand:

app.MapBlazorHub("base/path");

Het voordeel van het gebruik van MapBlazorHub is dat u patronen kunt toewijzen, zoals "{tenant}" en niet alleen concrete paden.

U kunt de SignalR-hub ook toewijzen wanneer de app zich in een virtuele map bevindt met een vertakte middleware-pijplijn. In het volgende voorbeeld worden aanvragen voor /base/path/ verwerkt door de Blazor-hub van SignalR:

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

Configureer de <base>-tag volgens de richtlijnen in de Het basispad van de app configureren sectie.

Zelfstandige Blazor WebAssembly

In een zelfstandige Blazor WebAssembly-app wordt alleen de <base>-tag geconfigureerd volgens de richtlijnen in de sectie Het basispad van de app configureren.

Het basispad voor de app configureren

Als u configuratie wilt opgeven voor het basispad van de Blazor-app van https://www.contoso.com/CoolApp/, stelt u het app-basispad (<base>)in, dat ook wel het relatieve hoofdpad wordt genoemd.

Door het basispad van de app te configureren, kan een onderdeel dat zich niet in de hoofdmap bevindt URL's samenstellen ten opzichte van het hoofdpad van de app. Onderdelen op verschillende niveaus van de mapstructuur kunnen koppelingen maken naar andere resources op locaties in de app. Het basispad van de app wordt ook gebruikt om geselecteerde hyperlinks te onderscheppen waarbij het href doel van de koppeling zich binnen de URI-ruimte van het basispad van de app bevindt. Het Router onderdeel verwerkt de interne navigatie.

Plaats de <base> tag in <head> markeringen (locatie van <head> inhoud) vóór elementen met kenmerkwaarden die URL's zijn, zoals de href kenmerken van <link> elementen.

• Gebruik in een Blazor-app aan de serverzijde van de volgende methoden:

  • Optie 1: gebruik de <base>-tag om het basispad van de app in te stellen (locatie van <head> inhoud):

    <base href="/CoolApp/">
    

    De afsluitende slash is vereist.

  • Optie 2: roep UsePathBaseeerste aan in de aanvraagverwerkingspijplijn van de app (Program.cs) direct nadat de WebApplicationBuilder is gebouwd (builder.Build()) om het basispad te configureren voor de volgende middleware die communiceert met het aanvraagpad:

    app.UsePathBase("/CoolApp");
    

    Het aanroepen van UsePathBase wordt aanbevolen wanneer u de Blazor Server-app ook lokaal wilt uitvoeren. Geef bijvoorbeeld de start-URL op in Properties/launchSettings.json:

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

    De tijdelijke aanduiding {PORT} in het vorige voorbeeld is de poort die overeenkomt met de beveiligde poort in het applicationUrl configuratiepad. In het volgende voorbeeld ziet u het volledige startprofiel voor een app op poort 7279:

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

    Zie launchSettings.json voor meer informatie over het bestand. Voor meer informatie over Blazor basispaden en hosting, zie <base href="/" /> of een basistag-alternatief voor Blazor MVC-integratie (dotnet/aspnetcore #43191).

• Zelfstandige Blazor WebAssembly (wwwroot/index.html):

  <base href="/CoolApp/">
  

  De afsluitende slash is vereist.

Voeg geen voorvoegselkoppelingen toe in de app met een slash. Vermijd het gebruik van een scheidingsteken voor padsegmenten of gebruik een punt-slash (./) voor relatieve padnotatie.

• ❌ Onjuist: <a href="/account">
• ✔️ Juist: <a href="account">
• ✔️ Juist: <a href="./account">

Controleer in Blazor WebAssembly web-API-aanvragen met de HttpClient-serviceof JSON-helpers (HttpClientJsonExtensions) geen forward slash toevoegen aan URL's (/):

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

Voeg geen voorvoegsel toe Navigatiebeheer relatieve koppelingen met een slash. Vermijd het gebruik van een padsegmentscheidingsteken of gebruik een punt-slash (./) voor relatieve padnotatie (Navigation is een geïnjecteerde NavigationManager).

• ❌ Onjuist: Navigation.NavigateTo("/other");
• ✔️ Juist: Navigation.NavigateTo("other");
• ✔️ Juist: Navigation.NavigateTo("./other");

In typische configuraties voor Azure/IIS-hosting is doorgaans geen aanvullende configuratie vereist. In sommige scenario's voor niet-IIS-hosting en omgekeerde proxyhosting is mogelijk aanvullende configuratie van statische bestands-middleware vereist:

• Statische bestanden correct verwerken (bijvoorbeeld app.UseStaticFiles("/CoolApp");).
• Het Blazor-script (_framework/blazor.*.js) serveren. Zie ASP.NET Core Blazor statische bestandenvoor meer informatie.

Voor een Blazor WebAssembly-app met een niet-hoofd-RELATIEF URL-pad (bijvoorbeeld <base href="/CoolApp/">), kan de app de resources niet vinden wanneer deze lokaalwordt uitgevoerd. Als u dit probleem wilt oplossen tijdens het ontwikkelen en testen, kunt u tijdens runtime een padbasis opgeven argument dat overeenkomt met de href waarde van de <base>-tag. Neem geen afsluitende slash op. Als u het padbasisargument wilt doorgeven wanneer u de app lokaal uitvoert, voert u de opdracht dotnet watch (of dotnet run) uit vanuit de map van de app met de optie --pathbase:

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

Voor een Blazor WebAssembly-app met een relatief URL-pad van /CoolApp/ (<base href="/CoolApp/">), is de opdracht:

dotnet watch --pathbase=/CoolApp

Als u het startprofiel van de app liever configureert om de pathbase automatisch op te geven in plaats van handmatig met dotnet watch (of dotnet run), stelt u de eigenschap commandLineArgs in Properties/launchSettings.jsonin. Hieronder wordt ook de start-URL (launchUrl) geconfigureerd:

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

Gebruik CoolApp als voorbeeld:

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

Met behulp van dotnet watch (of dotnet run) met de optie --pathbase of een startprofielconfiguratie waarmee het basispad wordt ingesteld, reageert de Blazor WebAssembly app lokaal op http://localhost:port/CoolApp.

Zie launchSettings.json voor meer informatie over het bestand. Voor meer informatie over Blazor basispaden en hosting, zie <base href="/" /> of een basistag-alternatief voor Blazor MVC-integratie (dotnet/aspnetcore #43191).

Het basispad van de app ophalen uit de configuratie

In de volgende richtlijnen wordt uitgelegd hoe u het pad voor de <base>-tag ophaalt uit een app-instellingenbestand voor verschillende omgevingen.

Voeg het app-instellingenbestand toe aan de app. Het volgende voorbeeld is voor de Staging-omgeving (appsettings.Staging.json):

{
  "AppBasePath": "staging/"
}

Laad in een Blazor-app aan de serverzijde het basispad uit de configuratie in <head> inhoud:

@inject IConfiguration Config

...

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

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

Als er geen configuratiewaarde is om te laden, bijvoorbeeld in niet-faseringsomgevingen, wordt de voorgaande href omgezet in het hoofdpad /.

De voorbeelden in deze sectie richten zich op het opgeven van het basispad van de app vanuit app-instellingen, maar de benadering van het lezen van het pad uit IConfiguration is geldig voor elke configuratieprovider. Zie de volgende bronnen voor meer informatie:

• ASP.NET Core Blazor-configuratie
• Configuratie in ASP.NET Core