Používání více prostředí v ASP.NET Core

Autoři: Rick Anderson a Kirk Larkin

ASP.NET Core konfiguruje chování aplikace na základě prostředí runtime pomocí proměnné prostředí.

Prostředí

Pokud chcete určit prostředí runtime, ASP.NET Core čte z následujících proměnných prostředí:

1. DOTNET_ENVIRONMENT
2. ASPNETCORE_ENVIRONMENT při zavolání WebApplication.CreateBuilder metody. Výchozí ASP.NET šablony webové aplikace Core volají WebApplication.CreateBuilder. Hodnota DOTNET_ENVIRONMENT se přepíše ASPNETCORE_ENVIRONMENT při WebApplicationBuilder použití. U jiných hostitelů, například ConfigureWebHostDefaults a WebHost.CreateDefaultBuilder, ASPNETCORE_ENVIRONMENT má vyšší prioritu.

IHostEnvironment.EnvironmentName lze nastavit na libovolnou hodnotu, ale architektura poskytuje následující hodnoty:

• Development: Spouštěcí Nastavení.json soubor se nastaví ASPNETCORE_ENVIRONMENT na Development místní počítač.
• Staging
• Production: Výchozí hodnota, pokud DOTNET_ENVIRONMENT nebyla nastavena a ASPNETCORE_ENVIRONMENT nebyla nastavena.

Následující kód:

• Podobá se kódu vygenerovanému šablonami ASP.NET Core.
• Povolí stránku výjimky vývojáře, pokud ASPNETCORE_ENVIRONMENT je nastavena na Developmenthodnotu . To se provádí automaticky metodou WebApplication.CreateBuilder .
• Volání UseExceptionHandler , pokud hodnota je cokoli jiného ASPNETCORE_ENVIRONMENT než Development.
• IWebHostEnvironment Poskytuje instanci ve Environment vlastnosti 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();

Pomocný rutina značky prostředí používá hodnotu IHostEnvironment.EnvironmentName k zahrnutí nebo vyloučení značek v elementu:

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

Stránka O produktu z ukázkového kódu obsahuje předchozí kód a zobrazí hodnotu IWebHostEnvironment.EnvironmentName.

Ve Windows a macOS se proměnné prostředí a hodnoty nerozlišují malá a velká písmena. Proměnné a hodnoty prostředí Linuxu ve výchozím nastavení rozlišují malá a velká písmena.

Vytvoření prostředíSample

Vzorový kód použitý v tomto článku je založený na Razor projektu Pages s názvem EnvironmentSample.

Následující příkazy rozhraní příkazového řádku .NET vytvoří a spustí webovou aplikaci s názvem EnvironmentSample:

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

Když se aplikace spustí, zobrazí výstup podobný následujícímu:

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

Nastavení prostředí na příkazovém řádku

--environment K nastavení prostředí použijte příznak. Příklad:

dotnet run --environment Production

Předchozí příkaz nastaví prostředí a Production zobrazí výstup podobný následujícímu v příkazovém okně:

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

Vývoj a spuštění Nastavení.json

Vývojové prostředí může povolit funkce, které by neměly být zpřístupněny v produkčním prostředí. Například šablony projektu ASP.NET Core umožňují stránku výjimek pro vývojáře ve vývojovém prostředí. Kvůli nákladům na výkon dochází k ověřování rozsahu a ověřování závislostí pouze ve vývoji.

Prostředí pro vývoj místních počítačů lze nastavit v souboru Properties\launch Nastavení.json projektu. Hodnoty prostředí nastavené v launchSettings.json přepsání hodnoty nastavené v systémovém prostředí.

Soubor launchSettings.json:

• Používá se jenom na místním vývojovém počítači.
• Není nasazen.
• Obsahuje nastavení profilu.

Následující JSfunkce ON ukazuje launchSettings.json soubor webového projektu ASP.NET Core s názvem EnvironmentSample vytvořený pomocí sady Visual Studio nebo 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"
      }
    }
  }
}

Předchozí funkce JSON obsahuje dva profily:

• EnvironmentsSample: Název profilu je název projektu. Jako první uvedený profil se tento profil používá ve výchozím nastavení. Klíč "commandName" má hodnotu "Project", proto se Kestrel webový server spustí.

• IIS Express: Klíč "commandName" má hodnotu "IISExpress", proto IISExpress je webový server.

Spouštěcí profil můžete nastavit na projekt nebo jakýkoli jiný profil, který je launchSettings.jsonsoučástí . Například na následujícím obrázku vyberete název projektu, který spustí Kestrel webový server.

Hodnota commandName může zadat webový server, který se má spustit. commandName může být libovolná z následujících možností:

• IISExpress : Spustí službu IIS Express.
• IIS : Nebyl spuštěn žádný webový server. Očekává se, že služba IIS bude dostupná.
• Project : Starty Kestrel.

Karta Vlastnosti projektu sady Visual Studio 2022 Debug / General (Obecné ) poskytuje odkaz na uživatelské rozhraní pro otevření spouštěcích profilů ladění. Tento odkaz otevře dialogové okno Spustit profily , které umožňuje upravit nastavení proměnné prostředí v launchSettings.json souboru. Dialogové okno Spustit profily můžete otevřít také v nabídce Ladění výběrem <názvu> projektu Vlastnosti ladění. Změny provedené v profilech projektu se nemusí projevit, dokud se webový server nerestartuje. Kestrel je nutné restartovat, aby bylo možné detekovat změny provedené v jeho prostředí.

Následující launchSettings.json soubor obsahuje více profilů:

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

Profily je možné vybrat:

• V uživatelském rozhraní sady Visual Studio.

• Pomocí příkazu rozhraní příkazového dotnet run řádku s --launch-profile možností nastavenou na název profilu. Tento přístup podporuje Kestrel pouze profily.

  dotnet run --launch-profile "EnvironmentsSample"
  

Upozorňující

launchSettings.json by neměly ukládat tajné kódy. Nástroj Secret Manager lze použít k ukládání tajných kódů pro místní vývoj.

Při použití editoru .vscode/launch.json Visual Studio Code je možné v souboru nastavit proměnné prostředí. Následující příklad nastaví několik proměnných prostředí pro hodnoty konfigurace hostitele:

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

Tento .vscode/launch.json soubor používá pouze Visual Studio Code.

Výroba

Produkční prostředí by mělo být nakonfigurováno tak, aby maximalizovalo odolnost zabezpečení, výkonu a aplikací. Mezi běžná nastavení, která se liší od vývoje, patří:

• Ukládání do mezipaměti.
• Prostředky na straně klienta jsou seskupené, minifikované a potenciálně obsluhované z CDN.
• Diagnostické chybové stránky jsou zakázané.
• Byly povoleny popisné chybové stránky.
• Protokolování a monitorování v produkčním prostředí je povolené. Například pomocí Přehledy aplikace.

Nastavení prostředí nastavením proměnné prostředí

Často je užitečné nastavit konkrétní prostředí pro testování pomocí proměnné prostředí nebo nastavení platformy. Pokud prostředí není nastavené, nastaví se výchozí Productionhodnota , která zakáže většinu funkcí ladění. Metoda nastavení prostředí závisí na operačním systému.

Při vytváření hostitele určuje poslední nastavení prostředí přečtené aplikací prostředí. Prostředí aplikace se během běhu aplikace nedá změnit.

Na stránce O produktu z ukázkového kódu se zobrazí hodnota IWebHostEnvironment.EnvironmentName.

Azure App Service

Production je výchozí hodnota, pokud DOTNET_ENVIRONMENTASPNETCORE_ENVIRONMENT nebyla nastavena. Aplikace nasazené do Azure jsou Production ve výchozím nastavení.

Nastavení prostředí v aplikaci Aplikace Azure Service pomocí portálu:

1. Vyberte aplikaci ze stránky App Services .
2. Ve skupině Nastavení vyberte Konfigurace.
3. Na kartě Nastavení aplikace vyberte Nové nastavení aplikace.
4. V okně Pro přidání nebo úpravu nastavení aplikace zadejte ASPNETCORE_ENVIRONMENT název. Jako hodnotu zadejte prostředí (například Staging).
5. Pokud chcete, aby nastavení prostředí zůstalo s aktuálním slotem při prohození slotů nasazení, zaškrtněte políčko Nastavení slotu nasazení. Další informace najdete v tématu Nastavení přípravných prostředí ve službě Aplikace Azure v dokumentaci k Azure.
6. Kliknutím na tlačítko OK zavřete dialogové okno pro nastavení aplikace Přidat nebo upravit.
7. V horní části stránky Konfigurace vyberte Uložit.

Aplikace Azure Služba automaticky restartuje aplikaci po přidání, změně nebo odstranění aplikace na webu Azure Portal.

Windows – Nastavení proměnné prostředí pro proces

Hodnoty prostředí v launchSettings.json přepsání hodnot nastavené v systémovém prostředí.

Pokud chcete nastavit ASPNETCORE_ENVIRONMENT aktuální relaci při spuštění aplikace pomocí příkazu dotnet, použijte následující příkazy na příkazovém řádku nebo v PowerShellu:

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

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

Windows – Globální nastavení proměnné prostředí

Předchozí příkazy jsou nastavené ASPNETCORE_ENVIRONMENT pouze pro procesy spuštěné z příkazového okna.

Pokud chcete nastavit hodnotu globálně ve Windows, použijte některý z následujících přístupů:

• Otevřete nastavení systému Ovládací panely> System>Advanced a přidejte nebo upravte ASPNETCORE_ENVIRONMENT hodnotu:

  

  

• Otevřete příkazový řádek pro správu a použijte setx příkaz nebo otevřete příkazový řádek PowerShellu pro správu a použijte [Environment]::SetEnvironmentVariable:

  • setx ASPNETCORE_ENVIRONMENT Staging /M
    

    Přepínač /M nastaví proměnnou prostředí na úrovni systému. /M Pokud se přepínač nepoužívá, proměnná prostředí se nastaví pro uživatelský účet.

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

    Možnost Machine nastaví proměnnou prostředí na úrovni systému. Pokud se hodnota možnosti změní na User, proměnná prostředí se nastaví pro uživatelský účet.

ASPNETCORE_ENVIRONMENT Když je proměnná prostředí nastavená globálně, projeví dotnet run se v libovolném příkazovém okně otevřeném po nastavení hodnoty. Hodnoty prostředí v launchSettings.json přepsání hodnot nastavené v systémovém prostředí.

Windows – Použití web.config

Chcete-li nastavit proměnnou ASPNETCORE_ENVIRONMENT prostředí pomocí web.config, přečtěte si část Nastavení proměnných prostředí souboru web.config.

Windows – Nasazení služby IIS

<EnvironmentName> Zahrnout vlastnost do profilu publikování (.pubxml) nebo souboru projektu. Tento přístup nastaví prostředí v souboru web.config při publikování projektu:

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

Pokud chcete nastavit ASPNETCORE_ENVIRONMENT proměnnou prostředí pro aplikaci spuštěnou v izolovaném fondu aplikací (podporovaném ve službě IIS 10.0 nebo novějším), přečtěte si část AppCmd.exe příkazu environment Variables <environmentVariables>. ASPNETCORE_ENVIRONMENT Pokud je proměnná prostředí nastavená pro fond aplikací, její hodnota přepíše nastavení na úrovni systému.

Když hostuje aplikaci ve službě IIS a přidává nebo mění ASPNETCORE_ENVIRONMENT proměnnou prostředí, použijte jeden z následujících přístupů k tomu, aby aplikace získaly novou hodnotu:

• Spusťte net stop was /y následující net start w3svc příkaz z příkazového řádku.
• Restartujte server.

macOS

Nastavení aktuálního prostředí pro macOS se dá provést v řádku při spuštění aplikace:

ASPNETCORE_ENVIRONMENT=Staging dotnet run

Případně nastavte prostředí před export spuštěním aplikace:

export ASPNETCORE_ENVIRONMENT=Staging

Proměnné prostředí na úrovni počítače jsou nastavené v souboru .bashrc nebo .bash_profile . Upravte soubor pomocí libovolného textového editoru. Přidejte následující příkaz:

export ASPNETCORE_ENVIRONMENT=Staging

Linux

V případě linuxových distribucí použijte export příkaz na příkazovém řádku pro nastavení proměnných založených na relacích a soubor bash_profile pro nastavení prostředí na úrovni počítače.

Nastavení prostředí v kódu

Pokud chcete nastavit prostředí v kódu, použijte WebApplicationOptions.EnvironmentName při vytváření WebApplicationBuilder, jak je znázorněno v následujícím příkladu:

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

Konfigurace podle prostředí

Pokud chcete načíst konfiguraci podle prostředí, přečtěte si téma Konfigurace v ASP.NET Core.

Konfigurace služeb a middlewaru podle prostředí

V závislosti na aktuálním prostředí použijte WebApplicationBuilder.Environment nebo WebApplication.Environment podmíněně přidávat služby nebo middleware. Šablona projektu obsahuje příklad kódu, který přidává middleware pouze v případě, že aktuální prostředí není vývojové:

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

Zvýrazněný kód kontroluje aktuální prostředí při sestavování kanálu požadavku. Pokud chcete při konfiguraci služeb zkontrolovat aktuální prostředí, použijte builder.Environment místo app.Environment.

Další materiály

• Zobrazení nebo stažení ukázkového kódu (postup stažení)
• Spuštění aplikace v ASP.NET Core
• Konfigurace v ASP.NET Core
• Prostředí ASP.NET Core Blazor