ASP.NET Core Blazor environments

Questo articolo spiega come configurare e leggere l'ambiente in un'applicazione.

Quando si esegue un'app in locale, per impostazione predefinita l'ambiente è Development. Quando l'app viene pubblicata, per impostazione predefinita l'ambiente è Production.

È consigliabile usare le convenzioni seguenti:

• Usare sempre il nome dell'ambiente "Development" per lo sviluppo locale. Questo perché il framework ASP.NET Core prevede esattamente questo nome durante la configurazione dell'app e degli strumenti per le esecuzioni di sviluppo locale di un'app.

• Per gli ambienti di test, staging e produzione, pubblica e distribuisci sempre l'app. You can use any environment naming scheme that you wish for published apps, but always use app setting file names with casing of the environment segment that exactly matches the environment name. Per l'ambiente di staging, usare "Staging" (maiuscola "S") come nome dell'ambiente e assegnare al file di impostazioni dell'app un nome che corrisponda (appsettings.Staging.json). Per la produzione, usare "Production" (maiuscola "P") come nome dell'ambiente e assegnare al file di impostazioni dell'app la corrispondenza (appsettings.Production.json).

Impostare l'ambiente

L'ambiente viene impostato usando uno degli approcci seguenti:

• Blazor Web App or Blazor Server: Use any of the approaches described in Use multiple environments in ASP.NET Core for general ASP.NET Core apps.
• Any Blazor app:
  • Blazor start configuration
  • Servizio app di Azure
• Blazor WebAssembly: Blazor-Environment header

Nel client per un Blazor Web App, l'ambiente viene determinato dal server tramite un middleware che comunica l'ambiente al browser tramite un'intestazione denominata Blazor-Environment. The header sets the environment when the WebAssemblyHost is created in the client-side Program file (WebAssemblyHostBuilder.CreateDefault).

Per un'app autonoma Blazor WebAssembly in esecuzione in locale, il server di sviluppo aggiunge l'intestazione Blazor-Environment con il nome dell'ambiente ottenuto dall'ambiente host. L'ambiente host imposta l'ambiente attraverso la variabile di ambiente ASPNETCORE_ENVIRONMENT stabilita dal file del progetto Properties/launchSettings.json. Il valore predefinito della variabile di ambiente in un progetto creato dal modello di Blazor WebAssembly progetto è Development. For more information, see the Set the client-side environment via header section.

Per l'esecuzione locale dell'app in fase di sviluppo, l'app utilizza l'ambiente Development per impostazione predefinita. Publishing the app defaults the environment to Production.

Impostare l'ambiente lato client tramite la configurazione di avvio Blazor.

The following example starts Blazor in the Staging environment if the hostname includes localhost. In caso contrario, l'ambiente è impostato sul valore predefinito.

Blazor Web App:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  if (window.location.hostname.includes("localhost")) {
    Blazor.start({
      webAssembly: {
        environment: "Staging"
      }
    });
  } else {
    Blazor.start();
  }
</script>

Nell'esempio precedente il {BLAZOR SCRIPT} segnaposto è il percorso dello script e il Blazor nome del file. Per la posizione dello script, consultare la struttura del progetto Blazor.

Annotazioni

For Blazor Web Apps that set the webAssembly>environment property in Blazor.start configuration, it's wise to match the server-side environment to the environment set on the environment property. In caso contrario, la prerendering sul server funzionerà in un ambiente diverso rispetto al rendering sul client, con effetti arbitrari. Per indicazioni generali sull'impostazione dell'ambiente per un Blazor Web App, vedere Usare più ambienti in ASP.NET Core.

Standalone Blazor WebAssembly:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  if (window.location.hostname.includes("localhost")) {
    Blazor.start({
      environment: "Staging"
    });
  } else {
    Blazor.start();
  }
</script>

Nell'esempio precedente il {BLAZOR SCRIPT} segnaposto è il percorso dello script e il Blazor nome del file. Per la posizione dello script, consultare la struttura del progetto Blazor.

Using the environment property overrides the environment set by the Blazor-Environment header.

The preceding approach sets the client's environment without changing the Blazor-Environment header's value, nor does it change the server project's console logging of the startup environment for a Blazor Web App that has adopted global Interactive WebAssembly rendering.

To log the environment to the console in either a standalone Blazor WebAssembly app or the .Client project of a Blazor Web App, place the following C# code in the Program file after the WebAssemblyHost is created with WebAssemblyHostBuilder.CreateDefault and before the line that builds and runs the project (await builder.Build().RunAsync();):

Console.WriteLine(
    $"Client Hosting Environment: {builder.HostEnvironment.Environment}");

Per altre informazioni sull'avvio di Blazor, vedere Avvio di ASP.NET Core Blazor.

Set the client-side environment via header

Blazor WebAssembly le app possono impostare l'ambiente con l'intestazione Blazor-Environment . In particolare, l'intestazione della risposta deve essere impostata nel _framework/blazor.boot.json file, ma non c'è alcun problema nell'impostare l'intestazione nelle risposte del file server per altre Blazor richieste di file o per l'intera Blazor distribuzione.

Although the Blazor framework issues the header name in kebab case with mixed letter case (Blazor-Environment), you're welcome to use all-lower or all-upper kebab case (blazor-environment, BLAZOR-ENVIRONMENT).

Per le esecuzioni di sviluppo locale con Blazor il server di sviluppo predefinito, è possibile controllare il valore dell'intestazione Blazor-Environment impostando il valore della variabile d'ambiente ASPNETCORE_ENVIRONMENT nel file del progetto Properties/launchSettings.json. Quando si esegue localmente con il server di sviluppo, l'ordine di precedenza per determinare l'ambiente dell'app è Blazor.start configuration (environment key)>Blazor-Environment response header (blazor.boot.json file) >ASPNETCORE_ENVIRONMENT environment variable (launchSettings.json). Non è possibile usare l'approccio della ASPNETCORE_ENVIRONMENT variabile di ambiente (launchSettings.json) per un'app distribuita Blazor WebAssembly . La tecnica funziona solo con il server di sviluppo nelle esecuzioni locali dell'app.

IIS

Nell'esempio seguente per IIS, l'intestazione personalizzata (Blazor-Environment) viene aggiunta al file pubblicato web.config . Il web.config file si trova nella bin/Release/{TARGET FRAMEWORK}/publish cartella, dove il {TARGET FRAMEWORK} segnaposto è il framework di destinazione:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    ...
    <httpProtocol>
      <customHeaders>
        <add name="Blazor-Environment" value="Staging" />
      </customHeaders>
    </httpProtocol>
  </system.webServer>
</configuration>

Annotazioni

Per usare un file personalizzato web.config per IIS che non viene sovrascritto quando l'app viene pubblicata nella publish cartella, vedere Ospitare e distribuire ASP.NET Core Blazor WebAssembly con IIS.

Nginx

Per i server Nginx, usare la add_header direttiva da ngx_http_headers_module:

http {
    server {
        ...
        location / {
            ...
            add_header Blazor-Environment "Staging";
        }
    }
}

Per altre informazioni, vedere le risorse seguenti:

• Documentazione di Nginx
• Ospitare e distribuire ASP.NET Core Blazor WebAssembly con Nginx

Apache

Per i server Apache, usare la Header direttiva del mod_headers modulo:

<VirtualHost *:80>
    ...
    Header set Blazor-Environment "Staging"
    ...
</VirtualHost>

Per altre informazioni, vedere le risorse seguenti:

• Documentazione di Apache (cercare la versione più recente per "mod_headers")
• Ospitare e distribuire ASP.NET Core Blazor WebAssembly con Apache

Impostare l'ambiente per il servizio app di Azure

Per un'app autonomaBlazor WebAssembly, è possibile impostare l'ambiente manualmente tramite la configurazione di avvio o l'intestazioneBlazor-Environment.

For a server-side app, set the environment via an ASPNETCORE_ENVIRONMENT app setting in Azure:

1. Confirm that the casing of environment segments in app settings file names match their environment name casing exactly. Ad esempio, il nome file delle impostazioni dell'app corrispondente per l'ambiente Staging è appsettings.Staging.json. Se il nome del file è appsettings.staging.json (minuscolo "s"), il file non si trova e le impostazioni nel file non vengono usate nell'ambiente Staging .

2. Per la distribuzione di Visual Studio, verificare che l'app sia distribuita nello slot di distribuzione corretto. Per un'app denominata BlazorAzureAppSample, l'app viene distribuita nello Staging slot di distribuzione.

3. In the Azure portal for the environment's deployment slot, set the environment with the ASPNETCORE_ENVIRONMENT app setting. For an app named BlazorAzureAppSample, the staging App Service Slot is named BlazorAzureAppSample/Staging. For the Staging slot's configuration, create an app setting for ASPNETCORE_ENVIRONMENT with a value of Staging. Deployment slot setting is enabled for the setting.

Quando richiesto in un browser, l'app BlazorAzureAppSample/Staging viene caricata nell'ambiente Staging in https://blazorazureappsample-staging.azurewebsites.net.

When the app is loaded in the browser, the response header collection for blazor.boot.json indicates that the Blazor-Environment header value is Staging.

App settings from the appsettings.{ENVIRONMENT}.json file are loaded by the app, where the {ENVIRONMENT} placeholder is the app's environment. Nell'esempio precedente le impostazioni del appsettings.Staging.json file vengono caricate.

Read the environment in a Blazor WebAssembly app

Ottenere l'ambiente dell'app in un componente inserendo IWebAssemblyHostEnvironment e leggendo la proprietà Environment.

ReadEnvironment.razor:

@page "/read-environment"
@using Microsoft.AspNetCore.Components.WebAssembly.Hosting
@inject IWebAssemblyHostEnvironment Env

<h1>Environment example</h1>

<p>Environment: @Env.Environment</p>

Read the environment client-side in a Blazor Web App

Supponendo che il prerendering non sia disabilitato per un componente o per l'app, un componente del progetto .Client viene prerenderizzato sul server. Poiché il server non dispone di un servizio registrato IWebAssemblyHostEnvironment, non è possibile iniettare il servizio e utilizzare i metodi e le proprietà dell'estensione dell'ambiente host relativi all'implementazione del servizio durante il prerendering del server. L'inserimento del servizio in un componente Interactive WebAssembly o Interactive Auto genera l'errore di runtime seguente:

There is no registered service of type 'Microsoft.AspNetCore.Components.WebAssembly.Hosting.IWebAssemblyHostEnvironment'.

Per risolvere questo problema, creare un'implementazione del servizio personalizzata per IWebAssemblyHostEnvironment nel server. Aggiungere la classe seguente al progetto server.

ServerHostEnvironment.cs:

using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
using Microsoft.AspNetCore.Components;

public class ServerHostEnvironment(IWebHostEnvironment env, NavigationManager nav) : 
    IWebAssemblyHostEnvironment
{
    public string Environment => env.EnvironmentName;
    public string BaseAddress => nav.BaseUri;
}

Nel file del progetto server Program registrare il servizio:

builder.Services.TryAddScoped<IWebAssemblyHostEnvironment, ServerHostEnvironment>();

At this point, the IWebAssemblyHostEnvironment service can be injected into an interactive WebAssembly or interactive Auto component and used as shown in the Read the environment in a Blazor WebAssembly app section.

L'esempio precedente può dimostrare che è possibile avere un ambiente server diverso rispetto all'ambiente client, che non è consigliato e può causare risultati arbitrari. When setting the environment in a Blazor Web App, it's best to match server and .Client project environments. Si consideri lo scenario seguente in un'app di test:

• Implement the client-side (webassembly) environment property with the Staging environment via Blazor.start. Per un esempio, vedere la sezione Impostare l'ambiente lato client tramite la configurazione di avvio .
• Don't change the server-side Properties/launchSettings.json file. Lasciare la sezione con la environmentVariablesASPNETCORE_ENVIRONMENT variabile di ambiente impostata su Development.

È possibile visualizzare il valore della modifica della IWebAssemblyHostEnvironment.Environment proprietà nell'interfaccia utente.

Quando il prerendering si verifica nel server, il rendering del componente viene eseguito nell'ambiente Development :

Environment: Development

When the component is rerendered just a second or two later, after the Blazor bundle is downloaded and the .NET WebAssembly runtime activates, the values change to reflect that the client is operating in the Staging environment on the client:

Environment: Staging

Nell'esempio precedente viene illustrato il motivo per cui è consigliabile impostare l'ambiente server in modo che corrisponda all'ambiente client per distribuzioni di sviluppo, test e produzione.

Per ulteriori informazioni, consultare la sezione Problemi di risoluzione dei servizi lato client durante la prerenderizzazione dell'articolo Modalità di rendering, che appare più avanti nella documentazione.

Read the client-side environment during startup

Durante l'avvio, WebAssemblyHostBuilder espone IWebAssemblyHostEnvironment tramite la proprietà HostEnvironment, che abilita la logica specifica dell'ambiente nel codice del costruttore host.

Nel file Program:

if (builder.HostEnvironment.Environment == "Custom")
{
    ...
};

I seguenti metodi di estensione, forniti tramite WebAssemblyHostEnvironmentExtensions, consentono di controllare l'ambiente corrente per Development, Production, Staging e nomi di ambiente personalizzati.

• IsDevelopment
• IsProduction
• IsStaging
• IsEnvironment

Nel file Program:

if (builder.HostEnvironment.IsStaging())
{
    ...
};

if (builder.HostEnvironment.IsEnvironment("Custom"))
{
    ...
};

La IWebAssemblyHostEnvironment.BaseAddress proprietà può essere usata durante l'avvio quando il NavigationManager servizio non è disponibile.

Risorse aggiuntive

• Avvio di ASP.NET Core Blazor
• Usare più ambienti in ASP.NET Core
• Blazor samples GitHub repository (dotnet/blazor-samples) (how to download)