ambienti ASP.NET Core Blazor

Questo articolo illustra come configurare e leggere l'ambiente in un'appBlazor.

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 i test, la gestione temporanea e gli ambienti di produzione, pubblicare e distribuire sempre l'app. Puoi usare qualsiasi schema di denominazione dell'ambiente che desideri per le app pubblicate, ma usa sempre nomi di file di impostazione dell'app con maiuscole e minuscole del segmento di ambiente che corrisponde esattamente al nome dell'ambiente. Per la gestione temporanea, usare "Staging" (maiuscola "S") come nome dell'ambiente e assegnare al file di impostazioni dell'app la corrispondenza (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: usare uno degli approcci descritti in Usare più ambienti in ASP.NET Core per le app generali ASP.NET Core.
• Blazor Web App o autonomo Blazor WebAssembly: Blazor avviare la configurazione
• Autonomo Blazor WebAssembly: blazor-environment intestazione
• Blazor Web Appo autonomo Blazor WebAssembly: servizio app Azure

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. L'intestazione imposta l'ambiente quando WebAssemblyHost viene creato nel file lato Program client (WebAssemblyHostBuilder.CreateDefault).

Per un'app autonoma Blazor WebAssembly in esecuzione in locale, il server di sviluppo aggiunge l'intestazione blazor-environment .

Per l'esecuzione locale dell'app in fase di sviluppo, per impostazione predefinita l'app è l'ambiente Development . La pubblicazione dell'app usa per impostazione predefinita l'ambiente in Production.

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

Nell'esempio seguente viene avviato Blazor nell'ambiente Staging se il nome host include 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, vedere ASP.NET Struttura del progetto CoreBlazor.

Nota

Per Blazor Web Appquanto riguarda l'impostazione della webAssemblyenvironment>proprietà nella Blazor.start configurazione, è consigliabile associare l'ambiente lato server all'ambiente impostato nella environment proprietà . 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.

Blazor WebAssembly autonomo:

<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, vedere ASP.NET Struttura del progetto CoreBlazor.

L'uso della proprietà esegue l'override environment dell'ambiente impostato dall'intestazioneblazor-environment.

L'approccio precedente imposta l'ambiente del client senza modificare il blazor-environment valore dell'intestazione, né modifica la registrazione della console del progetto server dell'ambiente di avvio per un Blazor Web App oggetto che ha adottato il rendering WebAssembly interattivo globale.

Per registrare l'ambiente nella console in un progetto autonomo Blazor WebAssembly o nel .Client progetto di un Blazor Web App, inserire il codice C# seguente nel Program file dopo WebAssemblyHost la creazione di WebAssemblyHostBuilder.CreateDefault e prima della riga che compila ed esegue il progetto (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.

Impostare l'ambiente lato client tramite l'intestazione

Blazor WebAssembly le app possono impostare l'ambiente con l'intestazione blazor-environment .

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>

Nota

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.

Anche se il Blazor framework rilascia il nome dell'intestazione in tutte le lettere minuscole (blazor-environment), è possibile usare tutte le maiuscole e minuscole desiderate. Ad esempio, è supportato un nome di intestazione che maiuscola ogni parola (Blazor-Environment).

Impostare l'ambiente per il servizio app Azure

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

Per un'app sul lato server, impostare l'ambiente tramite un'impostazione ASPNETCORE_ENVIRONMENT dell'app in Azure:

1. Verificare che la combinazione di maiuscole e minuscole dei segmenti di ambiente nei nomi dei file delle impostazioni dell'app corrisponda esattamente al nome dell'ambiente. 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. Nel portale di Azure per lo slot di distribuzione dell'ambiente impostare l'ambiente con l'impostazione dell'appASPNETCORE_ENVIRONMENT. Per un'app denominata BlazorAzureAppSample, il servizio app slot di staging è denominato BlazorAzureAppSample/Staging. Per la Staging configurazione dello slot, creare un'impostazione dell'app per ASPNETCORE_ENVIRONMENT con il valore Staging. L'impostazione dello slot di distribuzione è abilitata per l'impostazione.

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

Quando l'app viene caricata nel browser, la raccolta di intestazioni di risposta per blazor.boot.json indica che il valore dell'intestazione blazor-environment è Staging.

Le impostazioni dell'app dal appsettings.{ENVIRONMENT}.json file vengono caricate dall'app, dove il {ENVIRONMENT} segnaposto è l'ambiente dell'app. Nell'esempio precedente le impostazioni del appsettings.Staging.json file vengono caricate.

Leggere l'ambiente in un'app Blazor WebAssembly

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

ReadEnvironment.razor:

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

<h1>Environment example</h1>

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

Leggere il lato client dell'ambiente in un Blazor Web App

Supponendo che il prerendering non sia disabilitato per un componente o per l'app, un componente nel .Client progetto viene pre-predefinito nel server. Poiché il server non dispone di un servizio registrato IWebAssemblyHostEnvironment , non è possibile inserire il servizio e usare i metodi e le proprietà dell'estensione dell'ambiente host dell'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>();

A questo punto, il IWebAssemblyHostEnvironment servizio può essere inserito in un componente WebAssembly interattivo o automatico interattivo e usato come illustrato nella sezione Leggi l'ambiente in un'appBlazor WebAssembly.

L'esempio precedente può dimostrare che è possibile avere un ambiente server diverso rispetto all'ambiente client, che non è consigliato e può causare risultati arbitrari. Quando si imposta l'ambiente in un Blazor Web App, è consigliabile trovare le corrispondenze con gli ambienti server e .Client di progetto. Si consideri lo scenario seguente in un'app di test:

• Implementare la proprietà di ambiente lato client (webassembly) con l'ambiente Staging tramite Blazor.start. Per un esempio, vedere la sezione Impostare l'ambiente lato client tramite la configurazione di avvio.
• Non modificare il file sul lato Properties/launchSettings.json server. Lasciare la sezione con la environmentVariables ASPNETCORE_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

Quando il componente viene riabilitare solo un secondo o due versioni successive, dopo il download del Blazor bundle e il runtime .NET WebAssembly viene attivato, i valori cambiano per riflettere che il client opera nell'ambiente Staging nel 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 altre informazioni, vedere la sezione Sui servizi lato client non è possibile risolvere durante la prerendering dell'articolo Modalità di rendering, che viene visualizzato più avanti nella Blazor documentazione.

Leggere l'ambiente lato client durante l'avvio

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

Nel file Program:

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

I metodi di estensione seguenti forniti tramite WebAssemblyHostEnvironmentExtensions consentono di controllare l'ambiente corrente per Developmenti nomi di ambiente , ProductionStaging, e 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
• Blazorrepository GitHub di esempi () (dotnet/blazor-samplescome scaricare)