Percorso di base dell'app ASP.NET Core Blazor

Questo articolo illustra il percorso di base dell'app nelle app di base ASP.NET Core Blazor , incluse le linee guida per la configurazione.

Il percorso di base dell'app è il percorso URL radice dell'app. Il routing efficace nelle Blazor app richiede la configurazione del framework per qualsiasi percorso URL radice che non si trova nel percorso di base predefinito dell'app /.

Si considerino l'app ASP.NET Core e l'app secondaria Blazor seguenti:

• L'app ASP.NET Core è denominata MyApp:
  • L'app si trova fisicamente in d:/MyApp.
  • Le richieste vengono ricevute all'indirizzo https://www.contoso.com/{MYAPP RESOURCE}.
• Un'app Blazor denominata CoolApp è una sotto-app di MyApp:
  • L'app secondaria si trova fisicamente in d:/MyApp/CoolApp.
  • Le richieste vengono ricevute all'indirizzo https://www.contoso.com/CoolApp/{COOLAPP RESOURCE}.

Senza specificare una configurazione aggiuntiva per CoolApp, l'app secondaria in questo scenario non conosce in alcun modo dove si trova nel server. L'app, ad esempio, non può costruire URL relativi corretti alle risorse senza sapere che si trova nel percorso URL relativo /CoolApp/. Questo scenario si applica anche in diversi scenari di hosting e proxy inverso quando un'app non è ospitata in un percorso URL radice.

Sfondo

La destinazione di un tag di ancoraggio (href) può essere composta con uno dei due endpoint seguenti:

• Posizioni assolute che includono uno schema (che prevede per impostazione predefinita lo schema della pagina se omesso), host, porta e percorso o solo una barra (/) seguita dal percorso.

  Esempi: https://example.com/a/b/c o /a/b/c

• Posizioni relative che comprendono solo un percorso e non iniziano con una barra (/). Questi vengono risolti in relazione all'URL del documento corrente o al <base> valore del tag, se specificato.

  Esempio: a/b/c

La presenza di una barra finale (/) in un percorso di base dell'app configurato è significativa per calcolare il percorso di base per gli URL dell'app. Ad esempio, https://example.com/a ha un percorso di base di https://example.com/, mentre https://example.com/a/ con una barra finale ha un percorso di base di https://example.com/a.

Per le fonti dei collegamenti relativi a Blazor nelle app ASP.NET Core:

• Gli URL nei Razor componenti (.razor) sono in genere relativi.
• Gli URL negli script, ad esempio gli Blazor script (blazor.*.js), sono relativi al documento.

Se si esegue il rendering di un'app Blazor da documenti diversi (ad esempio, /Admin/B/C/ e /Admin/D/E/), è necessario prendere in considerazione il percorso di base dell'app oppure il percorso di base è diverso quando l'app esegue il rendering in ogni documento e le risorse vengono recuperate dagli URL errati.

Scegliere una delle strategie seguenti per assicurarne la corretta risoluzione dei collegamenti relativi:

• Eseguire il mapping di risorse in modo dinamico usando il documento su cui è stato eseguito il rendering come radice. Ciò richiede la logica di routing personalizzata (ad esempio, IDynamicEndpointMetadata o un MatcherPolicy) ed è in genere riservata ai siti altamente dinamici.

• Stabilire un percorso di base coerente per il documento ed eseguire il mapping di tutte le risorse dell'app sotto tale percorso. Configurare il tag <base> literal nella pagina host sia per le app lato server Blazor che per le app Blazor WebAssembly (o scenari che utilizzano sempre un valore fisso).

La parte restante di questo articolo è incentrata sull'implementazione di un percorso di base coerente.

Il lato server Blazor

Eseguire il mapping dell'hub SignalR di un'app lato Blazor server passando il percorso a MapBlazorHub nel Program file. Il percorso hub predefinito Blazor è /_blazore l'esempio seguente imposta il percorso di base dell'hub predefinito su base/path:

app.MapBlazorHub("base/path/_blazor");

Il vantaggio dell'uso MapBlazorHub è che è possibile mappare modelli, ad esempio "{tenant}" e non solo percorsi concreti.

È anche possibile eseguire il mapping dell'hub SignalR quando l'app si trova in una cartella virtuale con una pipeline di middleware ramificata. Nell'esempio seguente le richieste a /base/path/ vengono gestite dall'hub Blazordi SignalR :

app.Map("/base/path", subapp => {
    subapp.UsePathBase("/base/path");
    subapp.UseRouting();
	  subapp.UseAntiforgery();
    subapp.UseEndpoints(endpoints => {
        endpoints.MapBlazorHub("/base/path/_blazor");
        endpoints.MapStaticAssets();
		    endpoints.MapRazorComponents<App>()
				.AddInteractiveServerRenderMode();
	});
});

Annotazioni

Il percorso predefinito Blazor dell'hub è /_blazor.

Configurare il <base> tag, in base alle indicazioni nella sezione Configurare il percorso di base dell'app.

Autonomo Blazor WebAssembly

In un'app autonoma Blazor WebAssembly , solo il <base> tag è configurato, in base alle indicazioni nella sezione Configurare il percorso di base dell'app.

Configurare il percorso di base dell'app

Per fornire la configurazione per il Blazor percorso di base dell'app di https://www.contoso.com/CoolApp/, impostare il percorso di base dell'app (<base>), detto anche percorso radice relativo.

Configurando il percorso di base dell'app, un componente che non si trova nella directory radice può costruire URL relativi al percorso radice dell'app. I componenti in diversi livelli della struttura di directory possono creare collegamenti ad altre risorse in varie posizioni in tutta l'app. Il percorso di base dell'app viene anche usato per intercettare i collegamenti ipertestuali selezionati in cui la destinazione del collegamento href si trova all'interno dello spazio URI del percorso di base dell'app. Il componente Router gestisce la navigazione interna.

Posizionare il tag <base> nel markup <head> (posizionedel contenuto <head>) prima di qualsiasi elemento con valori di attributo che sono URL, come gli attributi href degli elementi <link>.

In molti scenari di hosting, il percorso URL relativo per l'app è la radice dell'app. In questi casi predefiniti, il percorso base dell'URL relativo dell'app è / configurato come <base href="/" /> nel contenuto <head>.

Annotazioni

In alcuni scenari di hosting, ad esempio GitHub Pages e app secondarie IIS, il percorso di base dell'app deve essere impostato sul percorso URL relativo del server dell'app.

• In un'app sul lato server Blazor si usi l'approccio seguente:

• Opzione 1: usare il tag per impostare il <base> percorso di base dell'app (posizione del <head> contenuto):

  <base href="/CoolApp/">
  

  La barra finale è obbligatoria.

• Opzione 2: Chiamare UsePathBaseprima nella pipeline di elaborazione delle richieste dell'app (Program.cs) subito dopo la WebApplicationBuilder compilazione (builder.Build()) per configurare il percorso di base per qualsiasi middleware seguente che interagisce con il percorso della richiesta:

  app.UsePathBase("/CoolApp");
  

  La chiamata a UsePathBase è consigliata anche quando si vuole eseguire l'app Blazor Server in locale. Ad esempio, specificare l'URL di avvio in Properties/launchSettings.json:

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

  Il segnaposto {PORT} nell'esempio precedente è la porta corrispondente alla porta protetta nel percorso di configurazione applicationUrl. L'esempio seguente mostra il profilo di avvio completo per un'app sulla porta 7279:

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

  Per altre informazioni sul launchSettings.json file, vedere ASP.NET Ambienti di runtime core. Per ulteriori informazioni sui percorsi base delle app e sull'hosting di Blazor, consultare <base href="/" /> o l'alternativa al tag base per l'integrazione MVC di Blazor (dotnet/aspnetcore #43191).

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

  <base href="/CoolApp/">
  

  La barra obliqua finale è obbligatoria.

Annotazioni

Quando si usa WebApplication (vedere Eseguire la migrazione da ASP.NET Core in .NET 5 a .NET 6), app.UseRouting è necessario chiamare dopo UsePathBase in modo che il middleware di routing possa osservare il percorso modificato prima della corrispondenza delle route. In caso contrario, le route vengono confrontate prima che il percorso venga riscritto da UsePathBase come descritto in ASP.NET Core Middleware e Routing in ASP.NET Core.

Non anteporre collegamenti in tutta l'applicazione con una barra obliqua. Evitare l'uso di un separatore segmento di percorso o usare la notazione del percorso relativo punto-barra (./):

• ❌ Non corretto: <a href="/account">
• ✔️ Corretto: <a href="account">
• ✔️ Corretto: <a href="./account">

Nelle Blazor WebAssembly richieste API Web con il HttpClient servizio, verificare, che gli helper JSON (HttpClientJsonExtensions) non prefissino gli URL con una barra obliqua (/):

• ❌ Non corretto: var rsp = await client.GetFromJsonAsync("/api/Account");
• ✔️ Corretto: var rsp = await client.GetFromJsonAsync("api/Account");

Non anteporre Navigation Manager ai link relativi con una barra in avanti. Evitare l'uso di un separatore di segmento di percorso oppure usare la notazione del percorso relativo punto e barra (./) (Navigation è un elemento iniettato NavigationManager):

• ❌ Non corretto: Navigation.NavigateTo("/other");
• ✔️ Corretto: Navigation.NavigateTo("other");
• ✔️ Corretto: Navigation.NavigateTo("./other");

Nelle configurazioni tipiche per l'hosting di Azure/IIS, in genere non sono necessarie configurazioni aggiuntive. In alcuni scenari dell'hosting non-IIS e del proxy inverso, potrebbe essere necessaria una configurazione aggiuntiva del Middleware per file statici.

• Per gestire correttamente i file statici , ad esempio app.UseStaticFiles("/CoolApp");.
• Per gestire lo Blazor script (_framework/blazor.*.js). Per ulteriori informazioni, vedere ASP.NET Core Blazor file statici.

Per un'app Blazor WebAssembly con un percorso URL relativo non radice (ad esempio, <base href="/CoolApp/">), l'app non riesce a trovare le relative risorse quando viene eseguita in locale. Per risolvere questo problema durante sviluppo e test locali, è possibile specificare un argomento base del percorso corrispondente al valore href del tag <base> in fase di esecuzione. Non includere una barra finale. Per passare l'argomento base del percorso quando si esegue l'app in locale, eseguire il comando dotnet watch (o dotnet run) dalla directory dell'app utilizzando l'opzione --pathbase.

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

Per un'app Blazor WebAssembly con il percorso URL relativo /CoolApp/ (<base href="/CoolApp/">), il comando è:

dotnet watch --pathbase=/CoolApp

Se si preferisce configurare il profilo di avvio dell'app per specificare automaticamente pathbase anziché manualmente con dotnet watch (o dotnet run), impostare la commandLineArgs proprietà in Properties/launchSettings.json. Il codice seguente configura anche l'URL di avvio (launchUrl):

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

Uso di CoolApp come esempio:

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

Usando dotnet watch (oppure dotnet run) con l'opzione --pathbase o una configurazione del profilo di avvio che imposta il percorso di base, l'app Blazor WebAssembly risponde localmente all'indirizzo http://localhost:port/CoolApp.

Per altre informazioni sul launchSettings.json file, vedere ASP.NET Ambienti di runtime core. Per ulteriori informazioni sui percorsi base e l'hosting dell'app Blazor, vedere <base href="/" />o tag di base alternativa per l'integrazione MVC di Blazor (dotnet/aspnetcore #43191).

Ottenere il percorso di base dell'app dalla configurazione

Le indicazioni seguenti illustrano come ottenere il percorso del <base> tag da un file di impostazioni dell'app per ambienti diversi.

Aggiungere il file delle impostazioni dell'app all'app. L'esempio seguente è relativo all'ambiente Staging (appsettings.Staging.json):

{
  "AppBasePath": "staging/"
}

In un'applicazione lato Blazor server, carica il percorso base dalla configurazione nel contenuto <head>:

@inject IConfiguration Config

...

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

In alternativa, un'app lato server può ottenere il valore dalla configurazione per UsePathBase. Inserire il codice primo nella pipeline di elaborazione delle richieste dell'app (Program.cs) subito dopo che WebApplicationBuilder è costruito (builder.Build()). Nell'esempio seguente viene usata la chiave AppBasePathdi configurazione :

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

In un'app Blazor WebAssembly lato client:

• Rimuovere il <base> tag da wwwroot/index.html:

  - <base href="..." />
  

• Specificare il percorso di base dell'app tramite un HeadContent componente nel componente App (App.razor):

  @inject IConfiguration Config
  
  ...
  
  <HeadContent>
      <base href="/@(Config.GetValue<string>("AppBasePath"))" />
  </HeadContent>
  

Se non è presente alcun valore di configurazione da caricare, ad esempio, in ambienti non di staging, il precedente href viene risolto nel percorso principale /.

Gli esempi di questa sezione sono incentrati sulla fornitura del percorso di base dell'app dalle impostazioni dell'app, ma l'approccio di lettura del percorso da IConfiguration è valido per qualsiasi provider di configurazione. Per altre informazioni, vedere le risorse seguenti:

• Configurazione Blazor di ASP.NET Core
• La configurazione in ASP.NET Core