ASP.NET Core ambienti di runtime

Note

Questa non è la versione più recente di questo articolo. Per la versione corrente, vedere la versione .NET 10 di questo articolo.

Warning

Questa versione di ASP.NET Core non è più supportata. Per altre informazioni, vedere i criteri di supporto di .NET e .NET Core. Per la versione corrente, vedere la versione .NET 9 di questo articolo.

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:

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.

DOTNET_ENVIRONMENT
ASPNETCORE_ENVIRONMENT quando viene chiamato il WebApplication.CreateBuilder metodo . I modelli di progetto dell'app Web core ASP.NET chiamano WebApplication.CreateBuilder. Il valore esegue l'override ASPNETCORE_ENVIRONMENT di DOTNET_ENVIRONMENT.

DOTNET_ENVIRONMENT
ASPNETCORE_ENVIRONMENT quando ConfigureWebHostDefaults viene chiamato . I modelli di progetto dell'app Web core ASP.NET chiamano ConfigureWebHostDefaults. Il valore esegue l'override ASPNETCORE_ENVIRONMENT di DOTNET_ENVIRONMENT.

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.

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

Il codice seguente in Startup.Configure:

Inserisce IWebHostEnvironment in Startup.Configure per adattare il codice all'ambiente. Questo approccio è utile quando l'app richiede solo la regolazione Startup.Configure per alcuni ambienti con differenze minime di codice per ogni ambiente. Quando esistono molte differenze di codice per ogni ambiente, è consigliabile usare l'accesso all'ambiente da una Startup classe, descritta più avanti in questo articolo.
Chiama UseDeveloperExceptionPage quando ASPNETCORE_ENVIRONMENT è impostato su Development. La chiamata aggiunge middleware che acquisisce le eccezioni e genera risposte di errore HTML.
Chiama UseExceptionHandler quando il valore di ASPNETCORE_ENVIRONMENT è impostato su Production, Stagingo Testing. La chiamata aggiunge il middleware gestore di eccezioni alla pipeline per la gestione delle eccezioni.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    if (env.IsProduction() || env.IsStaging() || env.IsEnvironment("Testing"))
    {
        app.UseExceptionHandler("/Error");
    }

    ...
}

L'esempio precedente controlla l'ambiente corrente durante la compilazione della pipeline di richiesta. Per controllare l'ambiente corrente in Startup.ConfigureServices durante la configurazione dei servizi, inserire IWebHostEnvironment nella Startup classe invece di inserirlo Startup.Configure in e usare il servizio inserito per determinare l'ambiente in Startup.ConfigureServices e Startup.Configure.

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:

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 .

Nella shell dei comandi impostare la variabile di ambiente usando l'approccio appropriato per il sistema operativo.
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
});

Chiamare UseEnvironment quando si compila l'host. Per altre informazioni, vedere Host generico .NET in ASP.NET Core.

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

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-09-19

Condividi tramite

ASP.NET Core ambienti di runtime

Environments

Registrazione

Variabili di ambiente che determinano l'ambiente di runtime

Controllare l'esecuzione del codice in base all'ambiente

Controllo contenuto renderizzato

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

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

Impostare l'ambiente con una variabile di ambiente

Servizio app di Azure

Impostare la variabile di ambiente per un processo

Impostare la variabile di ambiente a livello globale

Impostare l'ambiente per le app distribuite in IIS

Docker

Usare un Dockerfile

Usare Docker Compose

Usare il docker run comando

File di ambiente Docker

Impostare l'ambiente nel codice di avvio dell'app

Caricare la configurazione in base all'ambiente

Accedere all'ambiente da una Startup classe

Classe specifica dell'ambiente Startup

Metodi di classe specifici dell'ambiente Startup

Risorse aggiuntive

Commenti e suggerimenti

Risorse aggiuntive

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

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

Usare il `docker run` comando

Accedere all'ambiente da una `Startup` classe

Classe specifica dell'ambiente `Startup`

Metodi di classe specifici dell'ambiente `Startup`