Usare più ambienti in ASP.NET CoreUse multiple environments in ASP.NET Core

Di Rick AndersonBy Rick Anderson

ASP.NET Core configura il comportamento dell'app in base all'ambiente di runtime e tramite una variabile di ambiente.ASP.NET Core configures app behavior based on the runtime environment using an environment variable.

Visualizzare o scaricare il codice di esempio (procedura per il download)View or download sample code (how to download)

AmbientiEnvironments

ASP.NET Core legge la variabile di ambiente ASPNETCORE_ENVIRONMENT all'avvio dell'app e ne archivia il valore in IHostingEnvironment.EnvironmentName.ASP.NET Core reads the environment variable ASPNETCORE_ENVIRONMENT at app startup and stores the value in IHostingEnvironment.EnvironmentName. La variabile ASPNETCORE_ENVIRONMENT può essere impostata su qualsiasi valore, ma il framework supporta tre valori: Development, Staging e Production.You can set ASPNETCORE_ENVIRONMENT to any value, but three values are supported by the framework: Development, Staging, and Production. Se la variabile ASPNETCORE_ENVIRONMENT non viene impostata, il valore predefinito è Production.If ASPNETCORE_ENVIRONMENT isn't set, it defaults to Production.

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

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

    app.UseStaticFiles();
    app.UseMvc();
}

Il codice precedente:The preceding code:

L'helper per tag di ambiente usa il valore di IHostingEnvironment.EnvironmentName per includere o escludere il markup nell'elemento:The Environment Tag Helper uses the value of IHostingEnvironment.EnvironmentName to include or exclude markup in the element:

<environment include="Development">
    <div>&lt;environment include="Development"&gt;</div>
</environment>
<environment exclude="Development">
    <div>&lt;environment exclude="Development"&gt;</div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>
        &lt;environment include="Staging,Development,Staging_2"&gt;
    </div>
</environment>

In Windows e macOS le variabili di ambiente e i relativi valori non applicano la distinzione tra maiuscole e minuscole.On Windows and macOS, environment variables and values aren't case sensitive. In Linux le variabili di ambiente e i relativi valori applicano la distinzione tra maiuscole e minuscole per impostazione predefinita.Linux environment variables and values are case sensitive by default.

SviluppoDevelopment

L'ambiente di sviluppo può abilitare funzionalità che non devono essere esposte nell'ambiente di produzione.The development environment can enable features that shouldn't be exposed in production. Ad esempio i modelli ASP.NET Core abilitano la pagina delle eccezioni per gli sviluppatori nell'ambiente di sviluppo.For example, the ASP.NET Core templates enable the Developer Exception Page in the development environment.

L'ambiente di sviluppo computer locale può essere impostato nel file Properties\launchSettings.json del progetto.The environment for local machine development can be set in the Properties\launchSettings.json file of the project. I valori di ambiente in launchSettings.json sostituiscono i valori impostati nell'ambiente di sistema.Environment values set in launchSettings.json override values set in the system environment.

Il codice JSON seguente visualizza tre profili di un file launchSettings.json:The following JSON shows three profiles from a launchSettings.json file:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:54339/",
      "sslPort": 0
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_My_Environment": "1",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_ENVIRONMENT": "Staging"
      }
    },
    "EnvironmentsSample": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging"
      },
      "applicationUrl": "http://localhost:54340/"
    },
    "Kestrel Staging": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_My_Environment": "1",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_ENVIRONMENT": "Staging"
      },
      "applicationUrl": "http://localhost:51997/"
    }
  }
}

Nota

La proprietà applicationUrl in launchSettings.json può specificare un elenco di URL di server.The applicationUrl property in launchSettings.json can specify a list of server URLs. Usare un punto e virgola tra gli URL dell'elenco:Use a semicolon between the URLs in the list:

"EnvironmentsSample": {
   "commandName": "Project",
   "launchBrowser": true,
   "applicationUrl": "https://localhost:5001;http://localhost:5000",
   "environmentVariables": {
     "ASPNETCORE_ENVIRONMENT": "Development"
   }
}

Quando l'app viene avviata con dotnet run viene usato il primo profilo con "commandName": "Project".When the app is launched with dotnet run, the first profile with "commandName": "Project" is used. Il valore di commandName specifica il server Web da avviare.The value of commandName specifies the web server to launch. commandName può avere uno dei valori seguenti:commandName can be any one of the following:

  • IISExpress
  • IIS
  • Project (che avvia Kestrel)Project (which launches Kestrel)

Quando un'app viene avviata con dotnet run:When an app is launched with dotnet run:

  • launchSettings.json, se disponibile, viene letto.launchSettings.json is read if available. Le impostazioni environmentVariables in launchSettings.json sostituiscono le variabili di ambiente.environmentVariables settings in launchSettings.json override environment variables.
  • Viene visualizzato l'ambiente host.The hosting environment is displayed.

L'output seguente visualizza un'app avviata con dotnet run:The following output shows an app started with dotnet run:

PS C:\Websites\EnvironmentsSample> dotnet run
Using launch settings from C:\Websites\EnvironmentsSample\Properties\launchSettings.json...
Hosting environment: Staging
Content root path: C:\Websites\EnvironmentsSample
Now listening on: http://localhost:54340
Application started. Press Ctrl+C to shut down.

La scheda Debug nelle proprietà di progetto di Visual Studio visualizza una GUI per la modifica del file launchSettings.json:The Visual Studio project properties Debug tab provides a GUI to edit the launchSettings.json file:

Proprietà progetto - Impostazione delle variabili di ambiente

È possibile che le modifiche apportate ai profili di progetto abbiano effetto solo dopo il riavvio del server Web.Changes made to project profiles may not take effect until the web server is restarted. Perché Kestrel rilevi le modifiche apportate al suo ambiente, deve essere riavviato.Kestrel must be restarted before it can detect changes made to its environment.

Avviso

Evitare di archiviare segreti in launchSettings.json.launchSettings.json shouldn't store secrets. Per l'archiviazione di segreti per lo sviluppo locale, usare lo strumento Secret Manager.The Secret Manager tool can be used to store secrets for local development.

Quando si usa Visual Studio Code, le variabili di ambiente possono essere impostate nel file .vscode/launch.json.When using Visual Studio Code, environment variables can be set in the .vscode/launch.json file. Nell'esempio seguente l'ambiente viene impostato su Development:The following example sets the environment to Development:

{
   "version": "0.2.0",
   "configurations": [
        {
            "name": ".NET Core Launch (web)",

            ... additional VS Code configuration settings ...

            "env": {
                "ASPNETCORE_ENVIRONMENT": "Development"
            }
        }
    ]
}

Un file .vscode/launch.json del progetto non viene letto quando si avvia l'app con dotnet run come accade per il file Properties/launchSettings.json.A .vscode/launch.json file in the project isn't read when starting the app with dotnet run in the same way as Properties/launchSettings.json. Quando si avvia un'app in un ambiente di sviluppo che non ha un file launchSettings.json, impostare una variabile di ambiente o un argomento della riga di comando sul comando dotnet run.When launching an app in development that doesn't have a launchSettings.json file, either set the environment with an environment variable or a command-line argument to the dotnet run command.

ProduzioneProduction

È necessario che l'ambiente di produzione sia configurato per ottimizzare la sicurezza, le prestazioni e l'affidabilità dell'app.The production environment should be configured to maximize security, performance, and app robustness. Alcune impostazioni comuni che differiscono dallo sviluppo includono:Some common settings that differ from development include:

  • Memorizzazione nella cache.Caching.
  • Risorse lato client in bundle, minimizzate e potenzialmente offerte da una rete CDN.Client-side resources are bundled, minified, and potentially served from a CDN.
  • Pagine di errore di diagnostica disabilitate.Diagnostic error pages disabled.
  • Pagine di errore descrittive abilitate.Friendly error pages enabled.
  • Registrazione e monitoraggio della produzione abilitati.Production logging and monitoring enabled. Ad esempio Application Insights.For example, Application Insights.

Impostare l'ambienteSet the environment

Spesso risulta utile impostare un ambiente specifico per i test.It's often useful to set a specific environment for testing. Se l'ambiente non viene impostato, il valore predefinito è Production, che disabilita la maggior parte delle funzionalità di debug.If the environment isn't set, it defaults to Production, which disables most debugging features. Il metodo per l'impostazione dell'ambiente dipende dal sistema operativo.The method for setting the environment depends on the operating system.

Servizio app di AzureAzure App Service

Per impostare l'ambiente in Servizio app di Azure, attenersi alla procedura seguente:To set the environment in Azure App Service, perform the following steps:

  1. Selezionare l'app dal pannello Servizi app.Select the app from the App Services blade.
  2. Nel gruppo IMPOSTAZIONI selezionare il pannello Impostazioni dell'applicazione.In the SETTINGS group, select the Application settings blade.
  3. Nell'area Impostazioni dell'applicazione selezionare Aggiungi nuova impostazione.In the Application settings area, select Add new setting.
  4. In Immettere un nome specificare ASPNETCORE_ENVIRONMENT.For Enter a name, provide ASPNETCORE_ENVIRONMENT. In Immettere un valore specificare l'ambiente (ad esempio, Staging).For Enter a value, provide the environment (for example, Staging).
  5. Selezionare la casella di controllo Impostazione slot per lasciare invariata l'impostazione dell'ambiente sullo slot corrente quando gli slot di distribuzione vengono scambiati.Select the Slot Setting check box if you wish the environment setting to remain with the current slot when deployment slots are swapped. Per altre informazioni, vedere Documentazione di Azure: Impostazioni incluse nello scambio.For more information, see Azure Documentation: Which settings are swapped?.
  6. Selezionare Salva nella parte superiore del pannello.Select Save at the top of the blade.

Servizio app di Azure riavvia automaticamente l'app quando un'impostazione dell'app (una variabile di ambiente) viene aggiunta, modificata o eliminata nel portale di Azure.Azure App Service automatically restarts the app after an app setting (environment variable) is added, changed, or deleted in the Azure portal.

WINDOWSWindows

Per impostare la variabile ASPNETCORE_ENVIRONMENT per la sessione corrente, se l'app viene avviata tramite dotnet run, vengono usati i comandi seguenti:To set the ASPNETCORE_ENVIRONMENT for the current session when the app is started using dotnet run, the following commands are used:

Prompt dei comandiCommand prompt

set ASPNETCORE_ENVIRONMENT=Development

PowerShellPowerShell

$Env:ASPNETCORE_ENVIRONMENT = "Development"

Questi comandi hanno effetto solo per la finestra corrente.These commands only take effect for the current window. Quando la finestra viene chiusa, l'impostazione ASPNETCORE_ENVIRONMENT viene ripristinata sull'impostazione predefinita o sul valore del computer.When the window is closed, the ASPNETCORE_ENVIRONMENT setting reverts to the default setting or machine value.

Per impostare il valore a livello globale in Windows, usare uno degli approcci seguenti:To set the value globally in Windows, use either of the following approaches:

  • Scegliere Pannello di controllo > Sistema > Impostazioni di sistema avanzate e aggiungere o modificare il valore ASPNETCORE_ENVIRONMENT:Open the Control Panel > System > Advanced system settings and add or edit the ASPNETCORE_ENVIRONMENT value:

    Proprietà di sistema avanzate

    Variabile di ambiente ASPNET Core

  • Aprire un prompt dei comandi di amministrazione e usare il comando setx o aprire un prompt dei comandi di PowerShell di amministrazione e usare [Environment]::SetEnvironmentVariable:Open an administrative command prompt and use the setx command or open an administrative PowerShell command prompt and use [Environment]::SetEnvironmentVariable:

    Prompt dei comandiCommand prompt

    setx ASPNETCORE_ENVIRONMENT Development /M
    

    L'opzione /M indica di impostare la variabile di ambiente a livello del sistema.The /M switch indicates to set the environment variable at the system level. Se non viene usata l'opzione /M, la variabile di ambiente viene impostata per l'account utente.If the /M switch isn't used, the environment variable is set for the user account.

    PowerShellPowerShell

    [Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Development", "Machine")
    

    Il valore dell'opzione Machine indica di impostare la variabile di ambiente a livello del sistema.The Machine option value indicates to set the environment variable at the system level. Se non viene usata l'opzione User, la variabile di ambiente viene impostata per l'account utente.If the option value is changed to User, the environment variable is set for the user account.

Quando la variabile di ambiente ASPNETCORE_ENVIRONMENT è impostata a livello globale, viene applicata per dotnet run in tutte le finestre di comando aperte dopo l'impostazione del valore.When the ASPNETCORE_ENVIRONMENT environment variable is set globally, it takes effect for dotnet run in any command window opened after the value is set.

web.configweb.config

Per impostare la variabile di ambiente ASPNETCORE_ENVIRONMENT con web.config, vedere la sezione Impostazione delle variabili di ambiente di Modulo ASP.NET Core.To set the ASPNETCORE_ENVIRONMENT environment variable with web.config, see the Setting environment variables section of Modulo ASP.NET Core.

File di progetto o profilo di pubblicazioneProject file or publish profile

Per le distribuzioni di Windows IIS: Includere la proprietà <EnvironmentName> nel profilo di pubblicazione (.pubxml) o nel file di progetto.For Windows IIS deployments: Include the <EnvironmentName> property in the publish profile (.pubxml) or project file. Questo approccio imposta l'ambiente in web.config quando viene pubblicato il progetto:This approach sets the environment in web.config when the project is published:

<PropertyGroup>
  <EnvironmentName>Development</EnvironmentName>
</PropertyGroup>

Pool di applicazioni IIS singoliPer IIS Application Pool

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 versioni successive), vedere la sezione AppCmd.exe dell'argomento Variabili di ambiente <environmentVariables>.To set the ASPNETCORE_ENVIRONMENT environment variable for an app running in an isolated Application Pool (supported on IIS 10.0 or later), see the AppCmd.exe command section of the Environment Variables <environmentVariables> topic. Quando la variabile di ambiente ASPNETCORE_ENVIRONMENT viene impostata per un pool di app, il suo valore esegue l'override di un'impostazione a livello di sistema.When the ASPNETCORE_ENVIRONMENT environment variable is set for an app pool, its value overrides a setting at the system level.

Importante

Durante l'hosting di un'app in IIS, quando si aggiunge o si modifica la variabile di ambiente ASPNETCORE_ENVIRONMENT, usare uno degli approcci seguenti per fare in modo che il nuovo valore venga selezionato dalle app:When hosting an app in IIS and adding or changing the ASPNETCORE_ENVIRONMENT environment variable, use any one of the following approaches to have the new value picked up by apps:

  • Eseguire net stop was /y seguito da net start w3svc da un prompt dei comandi.Execute net stop was /y followed by net start w3svc from a command prompt.
  • Riavviare il server.Restart the server.

macOSmacOS

L'impostazione dell'ambiente corrente per macOS può essere eseguita in linea durante l'esecuzione dell'app:Setting the current environment for macOS can be performed in-line when running the app:

ASPNETCORE_ENVIRONMENT=Development dotnet run

In alternativa, impostare l'ambiente tramite export prima di eseguire l'app:Alternatively, set the environment with export prior to running the app:

export ASPNETCORE_ENVIRONMENT=Development

Le variabili di ambiente a livello computer sono impostate nel file con estensione bashrc o bash_profile.Machine-level environment variables are set in the .bashrc or .bash_profile file. Modificare il file usando un qualsiasi editor di testo.Edit the file using any text editor. Aggiungere l'istruzione seguente:Add the following statement:

export ASPNETCORE_ENVIRONMENT=Development

LinuxLinux

Per le distribuzioni di Linux, usare il comando export al prompt dei comandi per le impostazioni delle variabili basate sulla sessione e il file bash_profile per le impostazioni di ambiente a livello di computer.For Linux distros, use the export command at a command prompt for session-based variable settings and bash_profile file for machine-level environment settings.

Configurazione per ambienteConfiguration by environment

Per caricare la configurazione dall'ambiente, sono consigliabili:To load configuration by environment, we recommend:

Classe Startup e metodi basati sull'ambienteEnvironment-based Startup class and methods

Convenzioni delle classi di avvioStartup class conventions

Quando viene avviata un'app ASP.NET Core, la classe Startup avvia l'app.When an ASP.NET Core app starts, the Startup class bootstraps the app. L'app può definire classi Startup separate per i diversi ambienti (ad esempio, StartupDevelopment) e la classe Startup appropriata viene selezionata durante il runtime.The app can define separate Startup classes for different environments (for example, StartupDevelopment), and the appropriate Startup class is selected at runtime. La classe il cui suffisso di nome corrisponde all'ambiente corrente ha la priorità.The class whose name suffix matches the current environment is prioritized. Se non viene trovata una classe Startup{EnvironmentName} corrispondente, viene usata la classe Startup.If a matching Startup{EnvironmentName} class isn't found, the Startup class is used.

Per implementare le classi Startup basate sull'ambiente, creare una classe Startup{EnvironmentName} per ogni ambiente in uso e una classe Startup di fallback:To implement environment-based Startup classes, create a Startup{EnvironmentName} class for each environment in use and a fallback Startup class:

// Startup class to use in the Development environment
public class StartupDevelopment
{
    public void ConfigureServices(IServiceCollection services)
    {
        ...
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        ...
    }
}

// Startup class to use in the Production environment
public class StartupProduction
{
    public void ConfigureServices(IServiceCollection services)
    {
        ...
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        ...
    }
}

// Fallback Startup class
// Selected if the environment doesn't match a Startup{EnvironmentName} class
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        ...
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        ...
    }
}

Usare l'overload UseStartup(IWebHostBuilder, String) che accetta un nome di assembly:Use the UseStartup(IWebHostBuilder, String) overload that accepts an assembly name:

public static void Main(string[] args)
{
    CreateWebHostBuilder(args).Build().Run();
}

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

    return WebHost.CreateDefaultBuilder(args)
        .UseStartup(assemblyName);
}

Convenzioni dei metodi di avvioStartup method conventions

Configure e ConfigureServices supportano versioni specifiche per l'ambiente con i formati Configure<EnvironmentName> e Configure<EnvironmentName>Services:Configure and ConfigureServices support environment-specific versions of the form Configure<EnvironmentName> and Configure<EnvironmentName>Services:

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        StartupConfigureServices(services);
    }

    public void ConfigureStagingServices(IServiceCollection services)
    {
        StartupConfigureServices(services);
    }

    private void StartupConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
    }

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

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

        app.UseStaticFiles();
        app.UseMvc();
    }

    public void ConfigureStaging(IApplicationBuilder app, IHostingEnvironment env)
    {
        if (!env.IsStaging())
        {
            throw new Exception("Not staging.");
        }

        app.UseExceptionHandler("/Error");
        app.UseStaticFiles();
        app.UseMvc();
    }
}

Risorse aggiuntiveAdditional resources