Usare più ambienti in ASP.NET Core

Di Rick Anderson e Kirk Larkin

ASP.NET Core configura il comportamento dell'app in base all'ambiente di runtime e tramite una variabile di ambiente.

Per Blazor indicazioni per gli ambienti, che aggiunge o sostituisce le linee guida in questo articolo, vedere ASP.NET Ambienti principaliBlazor.

Ambienti

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

1. DOTNET_ENVIRONMENT
2. ASPNETCORE_ENVIRONMENT quando viene chiamato il WebApplication.CreateBuilder metodo . I modelli predefiniti di app Web core ASP.NET chiamano WebApplication.CreateBuilder. Il valore esegue l'override DOTNET_ENVIRONMENT ASPNETCORE_ENVIRONMENT quando WebApplicationBuilder viene utilizzato. Per altri host, ad esempio ConfigureWebHostDefaults e WebHost.CreateDefaultBuilder, ASPNETCORE_ENVIRONMENT ha una precedenza maggiore.

IHostEnvironment.EnvironmentName può essere impostato su qualsiasi valore, ma i valori seguenti vengono forniti dal framework:

• Development: il file launchSettings.json imposta su ASPNETCORE_ENVIRONMENT Development nel computer locale.
• Staging
• Production: valore predefinito se DOTNET_ENVIRONMENT e ASPNETCORE_ENVIRONMENT non sono stati impostati.

Il codice seguente:

• È simile al codice generato dai modelli ASP.NET Core.
• Abilita la pagina delle eccezioni per gli sviluppatori quando ASPNETCORE_ENVIRONMENT è impostata Developmentsu . Questa operazione viene eseguita automaticamente dal WebApplication.CreateBuilder metodo .
• Chiama UseExceptionHandler quando il valore di ASPNETCORE_ENVIRONMENT è diverso da Development.
• Fornisce un'istanza IWebHostEnvironment nella Environment proprietà di WebApplication.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

L'helper tag di ambiente usa il valore di IHostEnvironment.EnvironmentName per includere o escludere markup nell'elemento :

<environment include="Development">
    <div>Environment is Development</div>
</environment>
<environment exclude="Development">
    <div>Environment is NOT Development</div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>Environment is: Staging, Development or Staging_2</div>
</environment>

La pagina Informazioni dal codice di esempio include il markup precedente e visualizza il valore di IWebHostEnvironment.EnvironmentName .

In Windows e macOS le variabili di ambiente e i valori non fanno distinzione tra maiuscole e minuscole. Per impostazione predefinita, le variabili e i valori di ambiente Linux fanno distinzione tra maiuscole e minuscole.

Creare ambientiSample

Il codice di esempio usato in questo articolo si basa su un Razor progetto Pages denominato EnvironmentsSample.

I comandi dell'interfaccia della riga di comando .NET seguenti creano ed eseguono un'app Web denominata EnvironmentsSample:

dotnet new webapp -o EnvironmentsSample
cd EnvironmentsSample
dotnet run --verbosity normal

Quando l'app viene eseguita, viene visualizzato un output simile al seguente:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7152
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5105
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\Path\To\EnvironmentsSample

Impostare l'ambiente nella riga di comando

Usare il --environment flag per impostare l'ambiente. Ad esempio:

dotnet run --environment Production

Il comando precedente imposta l'ambiente su Production e visualizza un output simile al seguente nella finestra di comando:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7262
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5005
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Production
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\Path\To\EnvironmentsSample

Sviluppo e launchSettings.json

L'ambiente di sviluppo può abilitare funzionalità che non devono essere esposte nell'ambiente di produzione. Ad esempio, i modelli di progetto ASP.NET Core abilitano la pagina Eccezioni sviluppatore nell'ambiente di sviluppo. A causa del costo delle prestazioni, la convalida dell'ambito e la convalida delle dipendenze si verificano solo nello sviluppo.

L'ambiente di sviluppo computer locale può essere impostato nel file Properties\launchSettings.json del progetto. I valori di ambiente impostati nei launchSettings.json valori di override impostati nell'ambiente di sistema.

Ecco il file launchSettings.json:

• Viene usato solo nel computer di sviluppo locale.
• Non viene distribuito.
• Contiene le impostazioni del profilo.

Il codice JSON seguente mostra il launchSettings.json file per un progetto Web ASP.NET Core denominato EnvironmentsSample creato con Visual Studio o dotnet new:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:59481",
      "sslPort": 44308
    }
  },
  "profiles": {
    "EnvironmentsSample": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Il codice JSON precedente contiene due profili:

• EnvironmentsSample: il nome del profilo è il nome del progetto. Come primo profilo elencato, questo profilo viene usato per impostazione predefinita. La "commandName" chiave ha il valore "Project", pertanto, viene avviato il Kestrel server Web.

• IIS Express: la "commandName" chiave ha il valore "IISExpress", pertanto IISExpress è il server Web.

È possibile impostare il profilo di avvio sul progetto o su qualsiasi altro profilo incluso in launchSettings.json. Nell'immagine seguente, ad esempio, selezionando il nome del progetto viene avviato il Kestrel server Web.

Il valore di commandName può specificare il server Web da avviare. commandName può avere uno dei valori seguenti:

• IISExpress : avvia IIS Express.
• IIS : nessun server Web avviato. È previsto che IIS sia disponibile.
• Project : avvia Kestrel.

La scheda Debug/Generale delle proprietà del progetto di Visual Studio 2022 fornisce un collegamento Apri interfaccia utente profili di avvio debug. Questo collegamento apre una finestra di dialogo Launch Profiles (Profili di avvio) che consente di modificare le impostazioni delle variabili di ambiente nel launchSettings.json file. È anche possibile aprire la finestra di dialogo Avvia profili dal menu Debug selezionando <nome> progetto Proprietà debug. È 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.

Il file seguente launchSettings.json contiene più profili:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:59481",
      "sslPort": 44308
    }
  },
  "profiles": {
    "EnvironmentsSample": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "EnvironmentsSample-Staging": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
      }
    },
    "EnvironmentsSample-Production": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Production"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

È possibile selezionare i profili:

• Dall'interfaccia utente di Visual Studio.

• Usando il comando dell'interfaccia della dotnet run riga di comando con l'opzione --launch-profile impostata sul nome del profilo. Questo approccio supporta Kestrel solo i profili.

  dotnet run --launch-profile "EnvironmentsSample"
  

Avviso

launchSettings.json non deve archiviare segreti. Per l'archiviazione di segreti per lo sviluppo locale, usare lo strumento Secret Manager.

Quando si usa Visual Studio Code, le variabili di ambiente possono essere impostate nel .vscode/launch.json file. L'esempio seguente imposta diverse variabili di ambiente per i valori di configurazione host:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": ".NET Core Launch (web)",
            "type": "coreclr",
            // Configuration ommitted for brevity.
            "env": {
                "ASPNETCORE_ENVIRONMENT": "Development",
                "ASPNETCORE_URLS": "https://localhost:5001",
                "ASPNETCORE_DETAILEDERRORS": "1",
                "ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
            },
            // Configuration ommitted for brevity.

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

Produzione

L'ambiente di produzione deve essere configurato per ottimizzare la sicurezza, le prestazioni e l'affidabilità delle applicazioni. Alcune impostazioni comuni che differiscono dallo sviluppo includono:

• Memorizzazione nella cache.
• Risorse lato client in bundle, minimizzate e potenzialmente offerte da una rete CDN.
• Pagine di errore di diagnostica disabilitate.
• Pagine di errore descrittive abilitate.
• Registrazione e monitoraggio di produzione abilitati. Ad esempio, usando Application Insights.

Impostare l'ambiente impostando 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 viene impostato, il valore predefinito è Production, che disabilita la maggior parte delle funzionalità di debug. Il metodo per l'impostazione dell'ambiente dipende dal sistema operativo.

Quando l'host viene compilato, 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.

Nella pagina Informazioni del codice di esempio viene visualizzato il valore IWebHostEnvironment.EnvironmentName di .

Servizio app di Azure

Production è il valore predefinito se DOTNET_ENVIRONMENT e ASPNETCORE_ENVIRONMENT non sono stati impostati. Le app distribuite in Azure sono Production per impostazione predefinita.

Per impostare l'ambiente in un'app del servizio app Azure tramite il portale:

1. Selezionare l'app nella pagina servizio app s.
2. Nel gruppo Impostazioni selezionare Variabili di ambiente.
3. Nella scheda Impostazioni app selezionare + Aggiungi.
4. Nella finestra Aggiungi/Modifica impostazione dell'applicazione specificare ASPNETCORE_ENVIRONMENT il nome. In Valore specificare l'ambiente , ad esempio Staging.
5. Selezionare la casella di controllo Impostazione slot di distribuzione se si desidera che l'impostazione dell'ambiente rimanga nello slot corrente quando gli slot di distribuzione vengono scambiati. Per altre informazioni, vedere Configurare gli ambienti di gestione temporanea in app Azure Servizio nella documentazione di Azure.
6. Selezionare OK per chiudere la finestra di dialogo Aggiungi/Modifica impostazione applicazione.
7. Selezionare Salva nella parte superiore della pagina Configurazione .

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

Windows - Impostare la variabile di ambiente per un processo

Valori di ambiente nei launchSettings.json valori di override impostati nell'ambiente di sistema.

Per impostare per ASPNETCORE_ENVIRONMENT la sessione corrente quando l'app viene avviata usando dotnet run, usare i comandi seguenti al prompt dei comandi o in PowerShell:

set ASPNETCORE_ENVIRONMENT=Staging
dotnet run --no-launch-profile

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

Windows - Impostare la variabile di ambiente a livello globale

I comandi precedenti impostati ASPNETCORE_ENVIRONMENT solo per i processi avviati da tale finestra di comando.

Per impostare il valore a livello globale in Windows, usare uno degli approcci seguenti:

• Scegliere Pannello di controllo>Sistema>Impostazioni di sistema avanzate e aggiungere o modificare il valore ASPNETCORE_ENVIRONMENT:

  

  

• 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:

  • setx ASPNETCORE_ENVIRONMENT Staging /M
    

    L'opzione /M imposta la variabile di ambiente a livello di sistema. Se non viene usata l'opzione /M, la variabile di ambiente viene impostata per l'account utente.

  • [Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Staging", "Machine")
    

    L'opzione Machine imposta la variabile di ambiente a livello di sistema. Se non viene usata l'opzione User, la variabile di ambiente viene impostata per l'account utente.

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. Valori di ambiente nei launchSettings.json valori di override impostati nell'ambiente di sistema.

Windows - Usare web.config

Per impostare la ASPNETCORE_ENVIRONMENT variabile di ambiente con web.config, vedere la sezione Impostare le variabili di ambiente del file web.config.

Windows - Distribuzioni IIS

Includere la proprietà <EnvironmentName> nel profilo di pubblicazione (.pubxml) o nel file di progetto. Questo approccio imposta l'ambiente in web.config quando viene pubblicato il progetto:

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

Per impostare la ASPNETCORE_ENVIRONMENT variabile di ambiente per un'app in esecuzione in un pool di applicazioni isolato (supportato in IIS 10.0 o versione successiva), vedere la sezione del comando AppCmd.exe dell'ambiente Variabili <di ambienteVariables>. 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.

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 fare in modo che il nuovo valore venga selezionato dalle app:

• Eseguire net stop was /y seguito da net start w3svc da un prompt dei comandi.
• Riavviare il server.

macOS

L'impostazione dell'ambiente corrente per macOS può essere eseguita in linea durante l'esecuzione dell'app:

ASPNETCORE_ENVIRONMENT=Staging dotnet run

In alternativa, impostare l'ambiente tramite export prima di eseguire l'app:

export ASPNETCORE_ENVIRONMENT=Staging

Le variabili di ambiente a livello computer sono impostate nel file con estensione bashrc o bash_profile. Modificare il file usando un qualsiasi editor di testo. Aggiungere l'istruzione seguente:

export ASPNETCORE_ENVIRONMENT=Staging

Linux

Per le distribuzioni Linux, usare il export comando al prompt dei comandi per le impostazioni delle variabili basate su sessione e il file bash_profile per le impostazioni dell'ambiente a livello di computer.

Impostare l'ambiente nel codice

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
}); 

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Configurazione per ambiente

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

Configurare servizi e middleware per ambiente

Usare WebApplicationBuilder.Environment o WebApplication.Environment per aggiungere servizi o middleware in modo condizionale a seconda dell'ambiente corrente. Il modello di progetto include un esempio di codice che aggiunge middleware solo quando l'ambiente corrente non è Sviluppo:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Il codice evidenziato controlla l'ambiente corrente durante la compilazione della pipeline di richiesta. Per controllare l'ambiente corrente durante la configurazione dei servizi, usare builder.Environment anziché app.Environment.

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