ASP.NET Core ambienti di runtime

ASP.NET Core configura il comportamento dell'app in base all'ambiente di runtime, che in genere riflette dove è in esecuzione l'app.

Le app vengono in genere eseguite nell'ambiente di sviluppo durante lo sviluppo locale e i test nel computer di uno sviluppatore con un set di comportamenti configurati. Al contrario, vengono eseguiti nell'ambiente di produzione quando vengono distribuiti in un server con un set diverso di comportamenti configurati. È possibile usare un numero qualsiasi di ambienti aggiuntivi, ad esempio l'ambiente di gestione temporanea fornito dal framework per la gestione temporanea di un'app prima della distribuzione dinamica o di altri ambienti creati dagli sviluppatori.

Questo articolo descrive gli ambienti di runtime delle app, come usare l'ambiente per controllare il comportamento dell'app e come impostare l'ambiente.

Per Blazor indicazioni per gli ambienti, che aggiunge o sostituisce le linee guida in questo articolo, vedere Blazor principali.

Environments

Anche se l'ambiente può essere qualsiasi valore stringa, i valori di ambiente seguenti vengono forniti dal framework:

• Development
• Staging
• Production

L'ambiente di produzione è configurato per ottimizzare la sicurezza, le prestazioni e l'affidabilità delle app. Le impostazioni e la configurazione comuni per sviluppatori che differiscono dall'ambiente di sviluppo includono:

• Abilitazione della memorizzazione nella cache.
• Creazione di bundle e minimizzazione delle risorse lato client, insieme alla possibilità di gestirle da una rete CDN.
• Disabilitazione delle pagine di errore di diagnostica e abilitazione di pagine di errore amichevoli.
• Abilitazione della registrazione e del monitoraggio della produzione. Ad esempio, la registrazione è abilitata per Azure Application Insights.

L'ultima impostazione dell'ambiente letta dall'app determina l'ambiente dell'app. L'ambiente dell'app non può essere modificato durante l'esecuzione dell'app.

Registrazione

L'output nella shell di comando all'avvio di un'app in esecuzione indica l'ambiente dell'app. Nell'esempio seguente l'app è in esecuzione nell'ambiente di staging.

info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Staging

Variabili di ambiente che determinano l'ambiente di runtime

Per determinare l'ambiente di runtime, ASP.NET Core legge dalle variabili di ambiente seguenti:

• DOTNET_ENVIRONMENT
• ASPNETCORE_ENVIRONMENT

Quando si usa WebApplication, il valore ha la DOTNET_ENVIRONMENT precedenza su ASPNETCORE_ENVIRONMENT. Quando si usa WebHost, ASPNETCORE_ENVIRONMENT ha la precedenza.

Se le DOTNET_ENVIRONMENT variabili di ambiente e ASPNETCORE_ENVIRONMENT non sono impostate, l'ambiente di produzione è l'ambiente predefinito.

In Windows e macOS i nomi delle variabili di ambiente non fanno distinzione tra maiuscole e minuscole. Le variabili di ambiente Linux fanno distinzione tra maiuscole e minuscole.

Controllare l'esecuzione del codice in base all'ambiente

Usare WebApplicationBuilder.Environment o WebApplication.Environment per aggiungere servizi o middleware in modo condizionale a seconda dell'ambiente corrente.

Il codice seguente nel file dell'app Program :

• Usa WebApplication.Environment per distinguere l'ambiente.
• Chiama UseExceptionHandler, che aggiunge il middleware gestore delle eccezioni alla pipeline di elaborazione delle richieste per gestire le eccezioni.
• Chiama UseHsts, che aggiunge il middleware HSTS per applicare l'intestazioneStrict-Transport-Security.

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

L'esempio precedente controlla l'ambiente corrente per la pipeline di elaborazione delle richieste. Per controllare l'ambiente corrente durante la configurazione dei servizi, usare builder.Environment anziché app.Environment.

All'interno dell'app, IHostEnvironment fornisce informazioni generali sull'ambiente di hosting dell'app e la IHostEnvironment.EnvironmentName proprietà indica l'ambiente corrente dell'app.

Controllo contenuto renderizzato

Inserire IHostEnvironment in un componente di Razor sottoposto a rendering del server e usare i metodi di estensione del servizio e la proprietà EnvironmentName per determinare l'ambiente per il rendering del contenuto.

@inject IHostEnvironment Env

@if (Env.IsDevelopment())
{
    <div>The environment is Development.</div>
}

@if (!Env.IsDevelopment())
{
    <div>The environment isn't Development.</div>
}

@if (Env.IsStaging() || Env.EnvironmentName == "Testing")
{
    <div>The environment is either Staging or Testing.</div>
}

Per Blazor Web Appi componenti che richiedono l'ambiente per controllare il rendering lato client, vedere Prerender ASP.NET Componenti principaliRazor.

Impostare l'ambiente in un terminale dei comandi quando l'app viene eseguita (dotnet run)

Utilizza l'opzione-e|--environment per impostare l'ambiente:

dotnet run -e Staging

Impostare l'ambiente con il file delle impostazioni di avvio (launchSettings.json)

L'ambiente per lo sviluppo locale può essere impostato nel Properties\launchSettings.json file del progetto. I valori di ambiente impostati in launchSettings.json hanno la precedenza sui valori impostati dall'ambiente di sistema.

Ecco il file launchSettings.json:

• Viene usato solo nel computer di sviluppo locale.
• Non viene distribuito quando l'app viene pubblicata.
• Può contenere più profili, ognuno dei quali configura un ambiente diverso.

L'esempio seguente imposta l'ambiente di gestione temporanea per il https profilo di avvio usando la ASPNETCORE_ENVIRONMENT variabile di ambiente:

"https": {
  "commandName": "Project",
  "dotnetRunMessages": true,
  "launchBrowser": true,
  "applicationUrl": "https://localhost:7205",
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "Staging"
  }
}

In Visual Studio esistono due approcci per impostare l'ambiente tramite profili di avvio:

• Premere ALT+INVIO o selezionare Proprietà dopo aver fatto clic con il pulsante destro del mouse sul progetto in Esplora soluzioni. Selezionare Debug>generale, quindi selezionare il collegamento Apri l'interfaccia utente dei profili di avvio di debug .

• Con il progetto selezionato in Esplora soluzioni, selezionare {PROJECT NAME} Debug Properties (Proprietà di debug) dal menu Debug , dove il {PROJECT NAME} segnaposto è un nome di progetto.

Gli approcci precedenti aprono la finestra di dialogo Avvia profili in cui è possibile modificare le impostazioni delle variabili di ambiente nel launchSettings.json file. È possibile che le modifiche apportate ai profili di progetto abbiano effetto solo dopo il riavvio del server Web. Kestrel deve essere riavviato prima di poter rilevare le modifiche apportate al relativo ambiente.

I profili possono essere selezionati nell'interfaccia utente di Visual Studio accanto al pulsante Start (■).

Quando una soluzione contiene più progetti, impostare solo l'ambiente per il progetto di avvio.

In alternativa, usa il comando dotnet run con l'opzione -lp|--launch-profile impostata come nome del profilo. Questo approccio supporta solo i profili di avvio in base al Project comando .

dotnet run -lp "https"

Quando si usa Visual Studio Code con C# Dev Kit per Visual Studio Code (Introduzione a C# in VS Code), i profili di avvio vengono prelevati dal file dell'app launchSettings.json .

Se C# Dev Kit non viene usato, impostare la ASPNETCORE_ENVIRONMENT variabile di ambiente nella .vscode/launch.jsonenv sezione insieme a qualsiasi altra variabile di ambiente impostata nella sezione :

"env": {
    "ASPNETCORE_ENVIRONMENT": "Staging",
    ...
},

Il .vscode/launch.json file viene usato solo da Visual Studio Code.

Impostare l'ambiente con una variabile di ambiente

Spesso è utile impostare un ambiente specifico per il test con una variabile di ambiente o un'impostazione della piattaforma. Se l'ambiente non è impostato, per impostazione predefinita viene usato l'ambiente di produzione, che disabilita la maggior parte delle funzionalità di debug. Il metodo per l'impostazione dell'ambiente dipende dal sistema operativo.

Servizio app di Azure

Le app distribuite nel servizio app di Azure adottano l'ambiente di produzione per impostazione predefinita.

Per impostare la ASPNETCORE_ENVIRONMENT variabile di ambiente, vedere le risorse seguenti nella documentazione di Azure:

• Configurare un'app del Servizio App
• Configurare gli ambienti di gestione temporanea nel servizio app di Azure

Servizio app di Azure riavvia automaticamente l'app dopo l'aggiunta, la modifica o l'eliminazione di un'impostazione dell'app.

Impostare la variabile di ambiente per un processo

Per impostare la ASPNETCORE_ENVIRONMENT variabile di ambiente per la sessione corrente (shell dei comandi) quando l'app viene avviata usando dotnet run, usare i comandi seguenti. Dopo aver impostato la variabile di ambiente, l'app viene avviata senza un profilo di avvio usando l'opzione --no-launch-profile .

1. Nella shell dei comandi impostare la variabile di ambiente usando l'approccio appropriato per il sistema operativo.

2. Eseguire il dotnet run comando senza usare un profilo di avvio:

   dotnet run --no-launch-profile
   

Quando si usa PowerShell, i passaggi precedenti possono essere combinati nei due comandi seguenti. L'esempio seguente imposta l'ambiente di gestione temporanea:

$Env:ASPNETCORE_ENVIRONMENT = "Staging"
dotnet run --no-launch-profile

Impostare la variabile di ambiente a livello globale

Usare le indicazioni appropriate per il sistema operativo per impostare la ASPNETCORE_ENVIRONMENT variabile di ambiente.

Quando la ASPNETCORE_ENVIRONMENT variabile di ambiente viene impostata a livello globale, viene applicata per il dotnet run comando in qualsiasi shell dei comandi aperta dopo l'impostazione del valore. I valori di ambiente impostati dai profili di avvio nel file launchSettings.json eseguono l'override dei valori impostati per l'ambiente di sistema.

Impostare l'ambiente per le app distribuite in IIS

Per impostare la ASPNETCORE_ENVIRONMENT variabile di ambiente con il web.config file, vedere web.config file.

Per impostare la variabile di ambiente nella distribuzione su IIS, includere la <EnvironmentName> proprietà nel profilo di pubblicazione (con estensione pubxml) o nel file di progetto. Nell'esempio seguente, l'ambiente viene impostato su web.config per l'ambiente di gestione temporanea quando il progetto viene pubblicato.

<PropertyGroup>
  <EnvironmentName>Staging</EnvironmentName>
</PropertyGroup>

Per impostare la variabile di ambiente ASPNETCORE_ENVIRONMENT per un'app in esecuzione in un pool di applicazioni isolato (supportato in IIS 10.0 o versione successiva), vedere Variabili di ambiente <variabiliDiAmbiente>. Quando la ASPNETCORE_ENVIRONMENT variabile di ambiente è impostata per un pool di applicazioni, il relativo valore esegue l'override di un'impostazione a livello di sistema.

Quando si ospita un'app in IIS e si aggiunge o si modifica la ASPNETCORE_ENVIRONMENT variabile di ambiente, usare uno degli approcci seguenti per rendere effettivo il nuovo valore per l'esecuzione delle app:

• Eseguire net stop was /y seguito da net start w3svc in una shell dei comandi.
• Riavviare il server.

Docker

Impostare l'ambiente dell'app usando uno degli approcci descritti in questa sezione.

Usare un Dockerfile

Impostare la ASPNETCORE_ENVIRONMENT variabile di ambiente all'interno del Dockerfile usando l'istruzione ENV :

ENV ASPNETCORE_ENVIRONMENT=Staging

Usare Docker Compose

Per le app multiservizio gestite con Docker Compose, definire ASPNETCORE_ENVIRONMENT le variabili di ambiente all'interno del docker-compose.yml file:

version: "3.9"
services:
  web:
    build: .
    ports:
      - "8000:5000"
    environment:
      - ASPNETCORE_ENVIRONMENT=Staging
      - API_KEY=...

Un ambiente impostato in fase di esecuzione con Docker Compose esegue l'override di un ambiente impostato dal Dockerfile.

Usare il docker run comando

Quando si esegue il contenitore Docker con il docker run comando , impostare la ASPNETCORE_ENVIRONMENT variabile di ambiente con l'opzione -e|--env :

docker run -e ASPNETCORE_ENVIRONMENT=Staging aspnet_core_image

Un ambiente impostato in fase di esecuzione con docker run esegue l'override di un ambiente impostato dal Dockerfile.

File di ambiente Docker

Impostare la ASPNETCORE_ENVIRONMENT variabile di ambiente usando un file di ambiente Docker (.env).

env_variables.env:

ASPNETCORE_ENVIRONMENT=Staging

Caricare il file con l'opzione --env-file durante l'esecuzione del comando docker run.

docker run --env-file ./env_variables.env aspnet_core_image

Un ambiente impostato in fase di esecuzione con docker run esegue l'override di un ambiente impostato dal Dockerfile.

Impostare l'ambiente nel codice di avvio dell'app

Per impostare l'ambiente nel codice, usare WebApplicationOptions.EnvironmentName durante la creazione di WebApplicationBuilder, come illustrato nell'esempio seguente:

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    EnvironmentName = Environments.Staging
}); 

Caricare la configurazione in base all'ambiente

Per caricare la configurazione in base all'ambiente, vedere Configurazione in ASP.NET Core.

Accedere all'ambiente da una Startup classe

L'uso di una Startup classe (Startup.cs) con i metodi Configure e ConfigureServices era necessario prima del rilascio di .NET 6 e rimane supportato.

Inserire IWebHostEnvironment nel costruttore Startup per controllare l'esecuzione del codice. Questo approccio è utile quando l'app richiede la configurazione del codice di avvio solo per pochi ambienti con differenze minime di codice per ogni ambiente.

Nell'esempio seguente l'ambiente viene mantenuto nel _env campo e controlla l'esecuzione del codice in base all'ambiente dell'app:

public class Startup
{
    private readonly IWebHostEnvironment _env;

    public Startup(IWebHostEnvironment env)
    {
        _env = env;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            ...
        }
        else if (_env.IsStaging())
        {
            ...
        }
        else
        {
            ...
        }
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            ...
        }
        else
        {
            ...
        }

        ...
    }
}

Classe specifica dell'ambiente Startup

Un'app può definire più classi Startup per ambienti diversi con la convenzione di denominazione Startup{EnvironmentName}, dove il segnaposto {ENVIRONMENT NAME} è il nome dell'ambiente.

La classe il cui suffisso di nome corrisponde all'ambiente corrente ha la priorità. Se non viene trovata una classe Startup{EnvironmentName} corrispondente, viene usata la classe Startup.

Per implementare classi basate sull'ambiente Startup , creare tutte Startup{EnvironmentName} le classi necessarie e una classe di fallback Startup :

public class StartupDevelopment
{
    ...
}

public class StartupProduction
{
    ...
}

public class Startup
{
    ...
}

Dove viene creato il generatore host, chiamare HostingAbstractionsWebHostBuilderExtensions.UseStartup, che accetta un nome di assembly per caricare la classe corretta Startup :

public static IHostBuilder CreateHostBuilder(string[] args)
{
    var assemblyName = typeof(Startup).GetTypeInfo().Assembly.FullName;

    return Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup(assemblyName);
        });
}

Metodi di classe specifici dell'ambiente Startup

I metodi Configure e ConfigureServices supportano versioni specifiche dell'ambiente nella forma Configure{ENVIRONMENT NAME} e Configure{ENVIRONMENT NAME}Services, dove il segnaposto {ENVIRONMENT NAME} è il nome dell'ambiente. Se non viene trovato un nome di ambiente corrispondente per i metodi denominati, viene usato rispettivamente il ConfigureServices metodo o Configure .

public void ConfigureDevelopmentServices(IServiceCollection services)
{
    ...
}

public void ConfigureStagingServices(IServiceCollection services)
{
    ...
}

public void ConfigureProductionServices(IServiceCollection services)
{
    ...
}

public void ConfigureServices(IServiceCollection services)
{
    ...
}

Risorse aggiuntive

• Visualizzare o scaricare il codice di esempio (procedura per il download)
• Avvio dell'app in ASP.NET Core
• Configurazione in ASP.NET Core
• Ambienti di ASP.NET Core Blazor