Usare più ambienti in ASP.NET Core

Articolo
11/06/2024

Nota

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

Avviso

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

Importante

Queste informazioni si riferiscono a un prodotto non definitive che può essere modificato in modo sostanziale prima che venga rilasciato commercialmente. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Per la versione corrente, vedere la versione .NET 8 di questo articolo.

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:

DOTNET_ENVIRONMENT
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 ASPNETCORE_ENVIRONMENT di DOTNET_ENVIRONMENT.

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

DOTNET_ENVIRONMENT
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.

Avvio di IIS Express nel menu

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.

Proprietà progetto - Impostazione delle variabili di 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:

Selezionare l'app nella pagina servizio app s.
Nel gruppo Impostazioni selezionare Variabili di ambiente.
Nella scheda Impostazioni app selezionare + Aggiungi.
Nella finestra Aggiungi/Modifica impostazione dell'applicazione specificare ASPNETCORE_ENVIRONMENT il nome. In Valore specificare l'ambiente , ad esempio Staging.
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.
Selezionare OK per chiudere la finestra di dialogo Aggiungi/Modifica impostazione applicazione.
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

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.

Ambienti

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

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

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:

Chiama UseDeveloperExceptionPage quando ASPNETCORE_ENVIRONMENT è impostato su Development.
Chiama UseExceptionHandler quando il valore di ASPNETCORE_ENVIRONMENT è impostato su Staging, Productiono Staging_2.
Inserisce IWebHostEnvironment in Startup.Configure. Questo approccio è utile quando l'app richiede solo la regolazione Startup.Configure per alcuni ambienti con differenze minime di codice per ogni ambiente.
È simile al codice generato dai modelli ASP.NET Core.

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

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

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

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

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

<environment include="Development">
    <div>The effective tag is: <environment include="Development"></div>
</environment>
<environment exclude="Development">
    <div>The effective tag is: <environment exclude="Development"></div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>
        The effective tag is:
        <environment include="Staging,Development,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 documento si basa su un Razor progetto Pages denominato EnvironmentsSample.

Il codice seguente crea ed esegue un'app Web denominata EnvironmentsSample:

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

Quando l'app viene eseguita, visualizza alcuni degli output seguenti:

Using launch settings from c:\tmp\EnvironmentsSample\Properties\launchSettings.json
info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
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:\tmp\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 ASP.NET Core abilitano la pagina delle eccezioni per gli sviluppatori nell'ambiente di sviluppo.

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:64645",
      "sslPort": 44366
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "EnvironmentsSample": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Il markup precedente contiene due profili:

IIS Express: profilo predefinito usato durante l'avvio dell'app da Visual Studio. 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. Nell'immagine seguente, ad esempio, selezionando il nome del progetto viene avviato il Kestrel server Web.
EnvironmentsSample: il nome del profilo è il nome del progetto. Questo profilo viene usato per impostazione predefinita quando si avvia l'app con dotnet run. La "commandName" chiave ha il valore "Project", pertanto, 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 delle proprietà del progetto di Visual Studio fornisce un'interfaccia utente grafica per modificare il 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.

Proprietà progetto - Impostazione delle variabili di ambiente

Il file seguente launchSettings.json contiene più profili:

{
  "iisSettings": {
    "windowsAuthentication": false, 
    "anonymousAuthentication": true, 
    "iisExpress": {
      "applicationUrl": "http://localhost:64645",
      "sslPort": 44366
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IISX-Production": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Production"
      }
    },
    "IISX-Staging": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
      }
    },
    "EnvironmentsSample": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "KestrelStaging": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging"
      }
    }
  }
}

È possibile selezionare i profili:

Dall'interfaccia utente di Visual Studio.
Usando il dotnet run comando in una shell dei comandi con l'opzione --launch-profile impostata sul nome del profilo. Questo approccio supporta Kestrel solo i profili.
```
dotnet run --launch-profile "SampleApp"
```

Avviso

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

{
    "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

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

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 Servizio app di Azure, attenersi alla procedura seguente:

Selezionare l'app dal pannello Servizi app.
Nel gruppo Impostazioni selezionare il pannello Configurazione.
Nella scheda Impostazioni applicazione selezionare Nuova impostazione applicazione.
Nella finestra Aggiungi/Modifica impostazione dell'applicazione specificare ASPNETCORE_ENVIRONMENT il nome. In Valore specificare l'ambiente , ad esempio Staging.
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.
Selezionare OK per chiudere la finestra Delle impostazioni dell'applicazione Aggiungi/Modifica.
Selezionare Salva nella parte superiore del pannello 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.

Finestre

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

Per impostare la variabile ASPNETCORE_ENVIRONMENT per la sessione corrente, se l'app viene avviata tramite dotnet run, vengono usati i comandi seguenti:

Prompt dei comandi

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

PowerShell

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

Il comando precedente imposta 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:

Prompt dei comandi
```
setx ASPNETCORE_ENVIRONMENT Staging /M
```
L'opzione /M indica di impostare la variabile di ambiente a livello del sistema. Se non viene usata l'opzione /M, la variabile di ambiente viene impostata per l'account utente.

PowerShell
```
[Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Staging", "Machine")
```
Il valore dell'opzione Machine indica di impostare la variabile di ambiente a livello del sistema. Se non viene usata l'opzione User, la variabile di ambiente viene impostata per l'account utente.

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.

File di progetto o profilo di pubblicazione

Per le distribuzioni di Windows IIS: includere la <EnvironmentName> proprietà nel profilo di pubblicazione (con estensione pubxml) o nel file di progetto. Questo approccio imposta l'ambiente in web.config quando viene pubblicato il progetto:

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

Pool di applicazioni IIS singoli

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>. 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.

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:

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 bash_profile file per le impostazioni dell'ambiente a livello di computer.

Impostare l'ambiente nel codice

Chiamare UseEnvironment quando si compila l'host. Vedere Host generico .NET in ASP.NET Core.

Configurazione per ambiente

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

Classe Startup e metodi basati sull'ambiente

Inserire IWebHostEnvironment nella classe Startup

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

Nell'esempio seguente :

L'ambiente viene mantenuto nel _env campo.
_env viene usato in ConfigureServices e Configure per applicare la configurazione di avvio in base all'ambiente dell'app.

public class Startup
{
    public Startup(IConfiguration configuration, IWebHostEnvironment env)
    {
        Configuration = configuration;
        _env = env;
    }

    public IConfiguration Configuration { get; }
    private readonly IWebHostEnvironment _env;

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            Console.WriteLine(_env.EnvironmentName);
        }
        else if (_env.IsStaging())
        {
            Console.WriteLine(_env.EnvironmentName);
        }
        else
        {
            Console.WriteLine("Not dev or staging");
        }

        services.AddRazorPages();
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

Convenzioni delle classi di avvio

Quando viene avviata un'app ASP.NET Core, la classe Startup avvia l'app. L'app può definire più Startup classi per ambienti diversi. La classe appropriata Startup è selezionata in fase di esecuzione. 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. Questo approccio è utile quando l'app richiede la configurazione dell'avvio per diversi ambienti con molte differenze di codice per ogni ambiente. Le app tipiche non necessitano di questo approccio.

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

public class StartupDevelopment
{
    public StartupDevelopment(IConfiguration configuration)
    {
        Configuration = configuration;
        Console.WriteLine(MethodBase.GetCurrentMethod().DeclaringType.Name);
    }

    public IConfiguration Configuration { get; }

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

    public void Configure(IApplicationBuilder app)
    {
        app.UseDeveloperExceptionPage();

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

public class StartupProduction
{
    public StartupProduction(IConfiguration configuration)
    {
        Configuration = configuration;
        Console.WriteLine(MethodBase.GetCurrentMethod().DeclaringType.Name);
    }

    public IConfiguration Configuration { get; }

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

    public void Configure(IApplicationBuilder app)
    {

        app.UseExceptionHandler("/Error");
        app.UseHsts();

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
        Console.WriteLine(MethodBase.GetCurrentMethod().DeclaringType.Name);
    }

    public IConfiguration Configuration { get; }

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

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

Usare l'overload UseStartup(IWebHostBuilder, String) che accetta un nome di assembly:

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

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

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

Convenzioni dei metodi di avvio

Configurare e configurareServices supportano versioni specifiche dell'ambiente del modulo Configure<EnvironmentName> e Configure<EnvironmentName>Services. Se non viene trovato un metodo o corrispondenteConfigure<EnvironmentName>Services, viene usato rispettivamente il ConfigureServices metodo o Configure .Configure<EnvironmentName> Questo approccio è utile quando l'app richiede la configurazione dell'avvio per diversi ambienti con molte differenze di codice per ambiente:

public class Startup
{
    private void StartupConfigureServices(IServiceCollection services)
    {
        services.AddRazorPages();
    }

    public void ConfigureDevelopmentServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void ConfigureStagingServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void ConfigureProductionServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void ConfigureServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        MyTrace.TraceMessage();

        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }

    public void ConfigureStaging(IApplicationBuilder app, IWebHostEnvironment env)
    {
        MyTrace.TraceMessage();

        app.UseExceptionHandler("/Error");
        app.UseHsts();

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

public static class MyTrace
{
    public static void TraceMessage([CallerMemberName] string memberName = "")
    {
        Console.WriteLine($"Method: {memberName}");
    }
}

Condividi tramite

Usare più ambienti in ASP.NET Core

Ambienti

Creare ambientiSample

Impostare l'ambiente nella riga di comando

Sviluppo e launchSettings.json

Produzione

Impostare l'ambiente impostando una variabile di ambiente

Servizio app di Azure

Windows - Impostare la variabile di ambiente per un processo

Windows - Impostare la variabile di ambiente a livello globale

Windows - Usare web.config

Windows - Distribuzioni IIS

macOS

Linux

Impostare l'ambiente nel codice

Configurazione per ambiente

Configurare servizi e middleware per ambiente

Risorse aggiuntive

Ambienti

Creare ambientiSample

Sviluppo e launchSettings.json

Produzione

Impostare l'ambiente

Servizio app di Azure

Finestre

macOS

Linux

Impostare l'ambiente nel codice

Configurazione per ambiente

Classe Startup e metodi basati sull'ambiente

Inserire IWebHostEnvironment nella classe Startup

Convenzioni delle classi di avvio

Convenzioni dei metodi di avvio

Risorse aggiuntive

Risorse aggiuntive