Ospitare e distribuire ASP.NET Core Blazor

Questo articolo illustra come ospitare e distribuire le app Blazor.

Pubblicazione dell'app

Le app vengono pubblicate per la distribuzione nella configurazione per il rilascio.

Visual Studio

1. Selezionare il comando Pubblica {APPLICATION} dal menu Compila , in cui il {APPLICATION} segnaposto il nome dell'app.
2. Selezionare la destinazione di pubblicazione. Per pubblicare in locale, selezionare Cartella.
3. Accettare il percorso predefinito nel campo Scegliere una cartella oppure specificarne uno diverso. Seleziona il pulsante Publish.

CLI .NET

Usare il comando dotnet publish per pubblicare l'app con una configurazione per il rilascio:

dotnet publish -c Release

La pubblicazione dell'app attiva un ripristino delle dipendenze del progetto e compila il progetto prima di creare gli asset per la distribuzione. Come parte del processo di compilazione, vengono rimossi gli assembly e i metodi non usati per ridurre le dimensioni del download e i tempi di caricamento dell'app.

Posizioni di pubblicazione:

• Blazor Web App: l'app viene pubblicata nella cartella /bin/Release/{TARGET FRAMEWORK}/publish. Distribuire il contenuto della cartella publish nell'host.
• Blazor WebAssembly: l'app viene pubblicata nella cartella bin\Release\net8.0\browser-wasm\publish\. Per distribuire l'app come sito statico, copiare il contenuto della cartella wwwroot nell'host del sito statico.

{TARGET FRAMEWORK} Nel percorso precedente è presente il framework di destinazione , ad esempio net8.0.

IIS

Per ospitare un'app Blazor in IIS, vedere le risorse seguenti:

• Hosting IIS
  • Pubblicare un'app ASP.NET Core in IIS
  • Host ASP.NET Core in Windows con IIS
• Ospitare e distribuire ASP.NET app lato Blazor server Core: app server in esecuzione in IIS, incluso IIS con macchine virtuali (Macchine virtuali VM) che eseguono il sistema operativo Windows e app Azure Servizio.
• Ospitare e distribuire ASP.NET CoreBlazor WebAssembly: include indicazioni aggiuntive per Blazor WebAssembly le app ospitate in IIS, tra cui hosting di siti statici, file personalizzatiweb.config, riscrittura url, app secondarie, compressione e Archiviazione di Azure hosting di file statici.
• Hosting di applicazioni secondarie IIS
  • Seguire le indicazioni nella sezione Percorso di base dell'app per l'app Blazor prima di pubblicare l'app. Gli esempi usano un percorso di base dell'app di /CoolApp e illustrano come ottenere il percorso di base dalle impostazioni dell'app o da altri provider di configurazione.
  • Seguire le indicazioni sulla configurazione dell'applicazione secondaria in Configurazione avanzata. Il percorso della cartella dell'app secondaria nel sito radice diventa il percorso virtuale dell'app secondaria. Per un percorso di base dell'app di /CoolApp, l'app Blazor viene inserita in una cartella denominata CoolApp nel sito radice e l'app secondaria assume un percorso virtuale di /CoolApp.

La condivisione di un pool di app tra app ASP.NET Core non è supportata, nemmeno per le app Blazor. Usare un pool di app per ogni app in caso di hosting con IIS ed evitare l'uso delle directory virtuali di IIS per ospitare più app.

Percorso di base dell'app

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

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.

Background

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

• Posizioni assolute che includono uno schema (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

• Percorsi relativi che contengono 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.

Esistono tre origini di collegamenti relativi alle Blazor app di base ASP.NET:

• 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.

Esistono due approcci per affrontare la sfida di risolvere correttamente i collegamenti relativi:

• Eseguire il mapping delle risorse in modo dinamico usando il documento su cui è stato eseguito il rendering come radice.
• Impostare un percorso di base coerente per il documento ed eseguire il mapping delle risorse in tale percorso di base.

La prima opzione è più complessa e non è l'approccio più tipico, perché rende la navigazione diversa per ogni documento. Si consideri l'esempio seguente per il rendering di una pagina /Something/Else:

• Sottoposto a rendering in /Admin/B/C/, viene eseguito il rendering della pagina con un percorso di /Admin/B/C/Something/Else.
• Sottoposto a rendering in /Admin/D/E/, il rendering della pagina viene eseguito nello stesso percorso di /Admin/B/C/Something/Else.

Nel primo approccio, il routing offre IDynamicEndpointMetadata e MatcherPolicy, che in combinazione possono essere la base per implementare una soluzione completamente dinamica che determina in fase di esecuzione il modo in cui le richieste vengono instradate.

Per la seconda opzione, ovvero l'approccio consueto adottato, l'app imposta il percorso di base nel documento ed esegue il mapping degli endpoint server ai percorsi sotto la base. Le linee guida seguenti adottano questo approccio.

Lato server Blazor

Eseguire il mapping dell'hub SignalR di un'app lato Blazor server passando il percorso a MapBlazorHub nel Program file:

app.MapBlazorHub("base/path");

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 middleware diramata. 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.UseEndpoints(endpoints => endpoints.MapBlazorHub());
});

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 Router componente gestisce lo spostamento interno.

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

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

Nota

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 lato Blazor server usare uno degli approcci seguenti:

  • 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 UsePathBase prima 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 Usare più ambienti in ASP.NET Core. Per altre informazioni sui percorsi e l'hosting di Blazor base delle app, vedere<base href="/" /> o alternativa tag di base per Blazor l'integrazione MVC (dotnet/aspnetcore #43191).

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

  <base href="/CoolApp/">
  

  La barra finale è obbligatoria.

Nota

Quando si usa WebApplication (vedere Eseguire la migrazione da ASP.NET Core 5.0 a 6.0), app.UseRouting deve essere chiamato dopo UsePathBase in modo che il middleware di routing possa osservare il percorso modificato prima delle route corrispondenti. In caso contrario, le route vengono associate prima che il percorso venga riscritto da UsePathBase come descritto negli articoli Ordinamento del middleware e Routing.

Non anteporre collegamenti in tutta l'app con una barra. 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 (/):

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

Non anteporre collegamenti relativi a Gestione navigazione con una barra. Evitare l'uso di un separatore di segmento di percorso o usare la notazione del percorso relativo dot-slash (./) (Navigation è un elemento inserito 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 di hosting non IIS e proxy inverso, potrebbe essere necessaria una configurazione aggiuntiva del middleware di file statico:

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

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 di base del percorso quando si esegue l'app in locale, eseguire il dotnet watch comando (o dotnet run) dalla directory dell'app con 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",

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

Per altre informazioni sul launchSettings.json file, vedere Usare più ambienti in ASP.NET Core. Per altre informazioni sui percorsi e l'hosting di Blazor base delle app, vedere<base href="/" /> o alternativa tag di base per Blazor l'integrazione MVC (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'app lato Blazor server caricare il percorso di base dalla configurazione nel <head> contenuto:

@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 seguente prima nella pipeline di elaborazione delle richieste dell'app (Program.cs) subito dopo la WebApplicationBuilder compilazione (builder.Build()). Nell'esempio seguente viene usata la chiave AppBasePathdi configurazione :

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

In un'app lato Blazor WebAssembly client:

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

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

• Specificare il percorso di base dell'app tramite un HeadContent componente nel App componente (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 /radice .

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 ulteriori informazioni, vedi le seguenti risorse:

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

Configurazione Blazor ServerMapFallbackToPage

Questa sezione si applica solo alle Blazor Server app. MapFallbackToPage non è supportato in Blazor Web Apps e Blazor WebAssembly nelle app.

Negli scenari in cui un'app richiede un'area separata con risorse personalizzate e componenti di Razor:

• Creare una cartella all'interno della cartella Pages dell'app per conservare le risorse. Ad esempio, una sezione amministratore di un'app viene creata in una nuova cartella denominata Admin (Pages/Admin).

• Creare una pagina radice (_Host.cshtml) per l'area. Ad esempio, creare un file Pages/Admin/_Host.cshtml dalla pagina radice principale dell'app (Pages/_Host.cshtml). Non fornire una direttiva @page nella pagina _Host di Admin.

• Aggiungere un layout alla cartella dell'area (ad esempio, Pages/Admin/_Layout.razor). Nel layout dell'area separata impostare il valore href del tag <base> in modo che corrisponda alla cartella dell'area (ad esempio, <base href="/Admin/" />). Per scopi dimostrativi, aggiungere ~/ alle risorse statiche nella pagina. Ad esempio:

  • ~/css/bootstrap/bootstrap.min.css
  • ~/css/site.css
  • ~/BlazorSample.styles.css (lo spazio dei nomi dell'app di esempio è BlazorSample)
  • ~/_framework/blazor.server.js (script Blazor)

• Se l'area deve avere la propria cartella degli asset statici, aggiungere la cartella e specificarne la posizione nel middleware dei file statici in Program.cs (ad esempio, app.UseStaticFiles("/Admin/wwwroot")).

• I componenti di Razor vengono aggiunti alla cartella dell'area. Aggiungere almeno un componente Index alla cartella dell'area con la direttiva @page corretta per l'area. Ad esempio, aggiungere un file Pages/Admin/Index.razor basato sul file Pages/Index.razor predefinito dell'app. Indicare l'area Admin come modello di route all'inizio del file (@page "/admin"). Aggiungi ulteriori componenti come necessario. Ad esempio, Pages/Admin/Component1.razor con una direttiva @page e un modello di route @page "/admin/component1.

• In Program.cs chiamare MapFallbackToPage per il percorso della richiesta dell'area immediatamente prima del percorso della pagina radice di fallback alla pagina _Host:

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

Distribuzione

Per indicazioni sulla distribuzione, vedere gli argomenti seguenti:

• Ospitare e distribuire ASP.NET Core Blazor WebAssembly
• Ospitare e distribuire ASP.NET app sul lato Blazor server Core