ambienti ASP.NET Core Blazor

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. Puoi usare qualsiasi schema di denominazione dell'ambiente che desideri per le app pubblicate, ma usa sempre i nomi dei file di impostazione dell'app rispettando la distinzione tra maiuscole e minuscole del segmento dell'ambiente che corrisponde esattamente al nome dell'ambiente. 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 o Blazor Server: usare uno degli approcci descritti in ambienti di runtime di ASP.NET Core per le applicazioni ASP.NET Core generali.
• Qualsiasi Blazor app: Blazor avviare la configurazione
• Autonomo Blazor WebAssembly: <WasmApplicationEnvironmentName> proprietà

Nel client per un Blazor Web App, l'ambiente viene determinato dal server tramite un commento HTML che gli sviluppatori non interagiscono con:

<!--Blazor-WebAssembly:{"environmentName":"Development", ...}-->

Per un'app autonoma Blazor WebAssembly, impostare l'ambiente con la proprietà MSBuild <WasmApplicationEnvironmentName> nel file di progetto dell'app (.csproj). L'esempio seguente imposta l'ambiente Staging :

<WasmApplicationEnvironmentName>Staging</WasmApplicationEnvironmentName>

Gli ambienti predefiniti sono Development per la compilazione e Production per la pubblicazione.

Esistono diversi approcci per l'impostazione dell'ambiente in un'app autonoma Blazor WebAssembly durante le operazioni di compilazione/pubblicazione e un approccio per l'avvio o l'esecuzione di un'app nel client:

• Impostare il valore della proprietà quando dotnet build o dotnet publish viene eseguito. L'esempio seguente imposta l'ambiente su Staging quando viene pubblicata un'app:

  dotnet publish -p:WasmApplicationEnvironmentName=Staging
  

• Impostare la proprietà durante la compilazione o la pubblicazione in base alla configurazione dell'app in Visual Studio. I gruppi di proprietà seguenti possono essere usati nel file di progetto dell'app o in qualsiasi file di configurazione di pubblicazione (.pubxml). Aggiungere altri gruppi di proprietà per altre configurazioni di compilazione in uso.

  <PropertyGroup Condition="'$(Configuration)' == 'Debug'">
    <WasmApplicationEnvironmentName>Development</WasmApplicationEnvironmentName>
  </PropertyGroup>
  
  <PropertyGroup Condition="'$(Configuration)' == 'Release'">
    <WasmApplicationEnvironmentName>Production</WasmApplicationEnvironmentName>
  </PropertyGroup>
  

• L'ambiente può essere impostato in base all'uso di un profilo di pubblicazione. Nell'esempio seguente la prima condizione imposta l'ambiente su Development quando non viene usato alcun profilo di pubblicazione (si applica alle operazioni di compilazione e pubblicazione senza profilo), mentre la seconda condizione copre l'impostazione dell'ambiente su Production quando viene usato un profilo di pubblicazione:

  <PropertyGroup Condition="'$(PublishProfile)' == ''">
    <WasmApplicationEnvironmentName>Development</WasmApplicationEnvironmentName>
  </PropertyGroup>
  
  <PropertyGroup Condition="'$(PublishProfile)' != ''">
    <WasmApplicationEnvironmentName>Production</WasmApplicationEnvironmentName>
  </PropertyGroup>
  

• Creare un endpoint API Web personalizzato lato server. L'app autonoma Blazor WebAssembly richiede il proprio ambiente dall'API Web all'avvio dell'app o su richiesta mentre è in esecuzione. Il valore deve essere passato a WebAssemblyStartOptions o con withApplicationEnvironment.

  Annotazioni

  In genere, i collegamenti della documentazione alla sorgente di riferimento .NET caricano il ramo predefinito del repository, che rappresenta lo sviluppo corrente per la versione successiva di .NET. Per selezionare un tag per una versione specifica, utilizzare il menu a tendina Seleziona rami o tag. Per ulteriori informazioni, vedere Come selezionare un tag di versione del codice sorgente di ASP.NET Core (dotnet/AspNetCore.Docs #26205).

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

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

Nell'esempio seguente Blazor inizia 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, consultare la struttura del progetto Blazor.

Annotazioni

Per Blazor Web App che impostano la proprietà webAssembly>environment nella configurazione Blazor.start, è consigliabile associare l'ambiente lato server all'ambiente impostato sulla proprietà environment. In caso contrario, la prerendering sul server opera 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 ASP.NET Ambienti di runtime di base.

Un 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, consultare la struttura del progetto Blazor.

Per registrare l'ambiente nella console in un'app autonoma Blazor WebAssembly o nel progetto .Client di un Blazor Web App, inserire il codice C# seguente nel file Program dopo la creazione di WebAssemblyHost e prima della riga che compila ed esegue il progetto (WebAssemblyHostBuilder.CreateDefault):

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

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

Leggere l'ambiente nell'app Blazor WebAssembly

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>

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 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. Per altre informazioni e un'implementazione di esempio, vedere la sezione Implementazione del servizio personalizzato nel server dell'articolo Prerendering , disponibile più avanti nella Blazor documentazione.

Leggere l'ambiente lato client durante l'avvio

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
• ASP.NET Core ambienti di runtime
• Blazor esempi di repository GitHub (dotnet/blazor-samples) (come scaricare)