běhová prostředí ASP.NET Core

ASP.NET Core konfiguruje chování aplikace na základě prostředí runtime, které obvykle odráží, kde je aplikace spuštěná.

Aplikace se obvykle spouštějí ve vývojovém prostředí během místního vývoje a testování na počítači vývojáře s jednou sadou nakonfigurovaných chování. Naproti tomu při nasazení na server s jinou sadou nakonfigurovaných chování běží v produkčním prostředí. Můžete použít libovolný počet dalších prostředí, jako je přípravné prostředí poskytované architekturou pro přípravu aplikace před živým nasazením nebo jinými prostředími, která vývojáři vytvářejí.

Tento článek popisuje prostředí runtime aplikací, použití prostředí k řízení chování aplikace a nastavení prostředí.

Pokyny Blazor k prostředím, která přidávají nebo nahrazují pokyny v tomto článku, najdete v tématu ASP.NET základních Blazor prostředích.

Environments

I když prostředí může být libovolná řetězcová hodnota, architektura poskytuje následující hodnoty prostředí:

• Development
• Staging
• Production

Produkční prostředí je nakonfigurované tak, aby maximalizovalo zabezpečení, výkon a spolehlivost aplikací. Mezi běžná nastavení a konfiguraci vývojáře, které se liší od vývojového prostředí, patří:

• Povolení ukládání do mezipaměti
• Sdružování a minimalizace prostředků na straně klienta spolu s možností poskytování z CDN.
• Zakázání diagnostických chybových stránek a povolení uživatelsky přívětivých chybových stránek.
• Povolení protokolování a monitorování v produkčním prostředí Protokolování je například povolené pro Azure Application Insights.

Poslední nastavení prostředí přečtené aplikací určuje prostředí aplikace. Prostředí aplikace se během běhu aplikace nedá změnit.

Logování

Výstup v příkazovém prostředí spuštěné aplikace při spuštění označuje prostředí aplikace. V následujícím příkladu je aplikace spuštěná v přípravném prostředí:

info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Staging

Proměnné prostředí, které určují prostředí runtime

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

• DOTNET_ENVIRONMENT
• ASPNETCORE_ENVIRONMENT

Při použití WebApplicationDOTNET_ENVIRONMENT má hodnota přednost před ASPNETCORE_ENVIRONMENT. Při použití WebHost má ASPNETCORE_ENVIRONMENT přednost.

DOTNET_ENVIRONMENT a ASPNETCORE_ENVIRONMENT nejsou nastaveny, je výchozím prostředím produkční prostředí.

V systémech Windows a macOS nerozlišuje názvy proměnných prostředí malá a velká písmena. Proměnné prostředí Linuxu rozlišují malá a velká písmena.

Řízení spouštění kódu 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.

Následující kód v souboru aplikace Program :

• Se používá WebApplication.Environment k rozlišení prostředí.
• Volá UseExceptionHandler, které přidává Middleware pro obsluhu výjimek do potrubí zpracování požadavku k obsluze výjimek.
• Volá UseHsts, které přidá HSTS Middleware pro použití hlavičky Strict-Transport-Security.

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

Předchozí příklad zkontroluje aktuální prostředí pro kanál zpracování požadavků. Pokud chcete při konfiguraci služeb zkontrolovat aktuální prostředí, použijte builder.Environment místo app.Environment.

V aplikaci IHostEnvironment poskytuje obecné informace o hostitelském prostředí aplikace a IHostEnvironment.EnvironmentName vlastnost označuje aktuální prostředí aplikace.

Ovládací prvek vykresleného obsahu

Vložte IHostEnvironment do součásti vykreslené Razor na serveru a pomocí rozšiřujících metod a EnvironmentName vlastností služby určete prostředí pro vykreslování obsahu:

@inject IHostEnvironment Env

@if (Env.IsDevelopment())
{
    <div>The environment is Development.</div>
}

@if (!Env.IsDevelopment())
{
    <div>The environment isn't Development.</div>
}

@if (Env.IsStaging() || Env.EnvironmentName == "Testing")
{
    <div>The environment is either Staging or Testing.</div>
}

Informace Blazor Web Appo prostředí, které vyžadují řízení vykreslování na straně klienta, najdete v tématu Prerender ASP.NET Core Razor components.

Nastavení prostředí v příkazovém prostředí při spuštění aplikace (dotnet run)

-e|--environment Pomocí možnosti nastavte prostředí:

dotnet run -e Staging

Nastavení prostředí pomocí souboru nastavení spuštění (launchSettings.json)

Prostředí pro místní vývoj lze nastavit v Properties\launchSettings.json souboru projektu. Hodnoty prostředí nastavené v launchSettings.json přepíší hodnoty nastavené systémovým prostředím.

Soubor launchSettings.json:

• Používá se jenom na místním vývojovém počítači.
• Při publikování aplikace není nasazena.
• Může obsahovat více profilů, z nichž každá konfiguruje jiné prostředí.

Následující příklad nastaví prostředí „Staging“ pro https spouštěcí profil pomocí proměnné prostředí ASPNETCORE_ENVIRONMENT.

"https": {
  "commandName": "Project",
  "dotnetRunMessages": true,
  "launchBrowser": true,
  "applicationUrl": "https://localhost:7205",
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "Staging"
  }
}

V sadě Visual Studio existují dva přístupy k nastavení prostředí prostřednictvím profilů spuštění:

• Po kliknutí pravým tlačítkem na projekt v Průzkumníku řešení stiskněte +Enter nebo vyberte Vlastnosti. Vyberte Ladit>Obecné, a poté vyberte odkaz Otevřít uživatelské rozhraní profilů spuštění ladění.

• Pokud je projekt vybraný v Průzkumníku řešení, v nabídce Ladění vyberte vlastnosti ladění {PROJECT NAME}, kde {PROJECT NAME} zástupný symbol je název projektu.

Předchozí přístupy otevřou dialogové okno Spustit profily , kde můžete upravit nastavení proměnné prostředí v launchSettings.json souboru. 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í.

Profily lze vybrat v uživatelském rozhraní sady Visual Studio vedle tlačítka Start (►).

Pokud řešení obsahuje více projektů, nastavte pouze prostředí pro spouštěný projekt.

Případně použijte příkaz dotnet run s volbou -lp|--launch-profile nastavenou na název profilu. Tento přístup podporuje pouze profily spuštění na Project základě příkazu.

dotnet run -lp "https"

Při použití Visual Studio Code v kombinaci se sadou C# Dev Kit pro Visual Studio Code (Začínáme s jazykem C# v editoru VS Code) jsou profily spuštění převzaty ze souboru aplikace launchSettings.json.

Pokud se Dev Kit C# nepoužívá, nastavte proměnnou prostředí ASPNETCORE_ENVIRONMENT v části .vscode/launch.json společně s dalšími proměnnými prostředí nastavenými v této části.

"env": {
    "ASPNETCORE_ENVIRONMENT": "Staging",
    ...
},

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

Nastavit prostředí pomocí 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 není prostředí nastaveno, výchozím prostředí je produkční prostředí, které vypne většinu funkcí ladění. Metoda nastavení prostředí závisí na operačním systému.

Azure App Service

Aplikace nasazené ve službě Azure App Service ve výchozím nastavení přijímají produkční prostředí.

Pokud chcete nastavit proměnnou ASPNETCORE_ENVIRONMENT prostředí, projděte si následující prostředky v dokumentaci k Azure:

• Konfigurace aplikace App Service
• Nastavení přípravných prostředí ve službě Azure App Service

Azure App Service automaticky restartuje aplikaci po přidání, změně nebo odstranění nastavení aplikace.

Nastavte proměnnou prostředí pro proces

Pokud chcete nastavit proměnnou ASPNETCORE_ENVIRONMENT prostředí pro aktuální relaci (příkazové prostředí) při spuštění aplikace pomocí dotnet run, použijte následující příkazy. Po nastavení proměnné prostředí se aplikace spustí bez spouštěcího profilu pomocí této --no-launch-profile možnosti.

1. V příkazovém prostředí nastavte proměnnou prostředí pomocí vhodného přístupu pro váš operační systém.

2. dotnet run Spusťte příkaz bez použití spouštěcího profilu:

   dotnet run --no-launch-profile
   

Při použití PowerShellu je možné předchozí kroky zkombinovat v následujících dvou příkazech. Následující příklad nastaví pracovní prostředí:

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

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

Pro nastavení proměnné prostředí ASPNETCORE_ENVIRONMENT použijte příslušné pokyny pro váš operační systém.

Když je proměnná prostředí nastavena globálně, projeví se pro příkaz ASPNETCORE_ENVIRONMENT v libovolném příkazovém prostředí, které se otevře až po nastavení této hodnoty. Hodnoty prostředí nastavené spouštěcími profily v launchSettings.json souboru přepíší hodnoty nastavené pro systémové prostředí.

Nastavení prostředí pro aplikace nasazené ve službě IIS

Pokud chcete nastavit proměnnou ASPNETCORE_ENVIRONMENT prostředí se web.config souborem, přečtěte si web.config soubor.

Chcete-li nastavit proměnnou prostředí při nasazení do služby IIS, zahrňte <EnvironmentName> vlastnost do profilu publikování (.pubxml) nebo souboru projektu. Následující příklad při publikování projektu nastaví prostředí web.config na přípravné prostředí:

<PropertyGroup>
  <EnvironmentName>Staging</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 téma Proměnné prostředí <proměnné prostředí>. ASPNETCORE_ENVIRONMENT Pokud je proměnná prostředí nastavená pro fond aplikací, její hodnota přepíše nastavení na úrovni systému.

Při hostování aplikace ve službě IIS a přidání nebo změně ASPNETCORE_ENVIRONMENT proměnné prostředí použijte jednu z následujících metod, aby se nová hodnota projevila ve běžících aplikacích:

• Spusťte net stop was /y, poté spusťte net start w3svc v příkazovém prostředí.
• Restartujte server.

Docker

Nastavte prostředí aplikace pomocí některého z přístupů v této části.

Použití souboru Dockerfile

Nastavte proměnnou ASPNETCORE_ENVIRONMENT prostředí v Dockerfile pomocí instrukce ENV:

ENV ASPNETCORE_ENVIRONMENT=Staging

Použití Docker Compose

U aplikací s více službami spravovaných pomocí Docker Compose definujte ASPNETCORE_ENVIRONMENT proměnné prostředí v souboru docker-compose.yml :

version: "3.9"
services:
  web:
    build: .
    ports:
      - "8000:5000"
    environment:
      - ASPNETCORE_ENVIRONMENT=Staging
      - API_KEY=...

Prostředí nastavené za běhu pomocí Docker Compose přepíše prostředí nastavené souborem Dockerfile.

Použijte příkaz docker run

Při spouštění Docker kontejneru docker run pomocí příkazu nastavte ASPNETCORE_ENVIRONMENT proměnnou prostředí pomocí -e|--env možnosti:

docker run -e ASPNETCORE_ENVIRONMENT=Staging aspnet_core_image

Prostředí nastavené za běhu s využitím docker run přepíše prostředí nastavené souborem Dockerfile.

Soubor prostředí Dockeru

Nastavte proměnnou ASPNETCORE_ENVIRONMENT prostředí pomocí souboru prostředí Dockeru (.env).

env_variables.env:

ASPNETCORE_ENVIRONMENT=Staging

Při spuštění --env-file načtěte soubor s docker run možností:

docker run --env-file ./env_variables.env aspnet_core_image

Prostředí nastavené za běhu s využitím docker run přepíše prostředí nastavené souborem Dockerfile.

Nastavení prostředí v spouštěcím kódu aplikace

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

Načtení konfigurace podle jednotlivých prostředí

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

Přístup k prostředí z Startup třídy

Startup Použití třídy (Startup.cs) s metodami Configure a ConfigureServices bylo vyžadováno před vydáním .NET 6 a zůstává podporováno.

Vložte IWebHostEnvironment do konstruktoru Startup pro řízení provádění kódu. Tento přístup je užitečný, když aplikace vyžaduje konfiguraci spouštěcího kódu jenom pro několik prostředí s minimálními rozdíly v kódu na prostředí.

V následujícím příkladu se prostředí uchovává v _env poli a řídí spouštění kódu na základě prostředí aplikace:

public class Startup
{
    private readonly IWebHostEnvironment _env;

    public Startup(IWebHostEnvironment env)
    {
        _env = env;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            ...
        }
        else if (_env.IsStaging())
        {
            ...
        }
        else
        {
            ...
        }
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            ...
        }
        else
        {
            ...
        }

        ...
    }
}

Třída specifická pro Startup prostředí

Aplikace může definovat více Startup tříd pro různá prostředí s konvencí pojmenování třídy Startup{EnvironmentName}, kde {ENVIRONMENT NAME} zástupný symbol je název prostředí.

Třída, jejíž přípona názvu odpovídá aktuálnímu prostředí, má prioritu. Startup{EnvironmentName} Pokud se odpovídající třída nenajde, použije se Startup třída.

Pokud chcete implementovat třídy založené na Startup prostředí, vytvořte libovolný počet Startup{EnvironmentName} tříd a náhradní Startup třídu:

public class StartupDevelopment
{
    ...
}

public class StartupProduction
{
    ...
}

public class Startup
{
    ...
}

Kde je vytvořen tvůrce hostitele, zavolejte HostingAbstractionsWebHostBuilderExtensions.UseStartup, který přijímá název sestavení pro načtení správné Startup třídy.

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

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

Metody třídy Startup specifické pro prostředí

Metody Configure a ConfigureServices podporují verze formuláře specifické pro prostředí Configure{ENVIRONMENT NAME} a Configure{ENVIRONMENT NAME}Services, kde zástupný symbol {ENVIRONMENT NAME} je název prostředí. Pokud se nenajde odpovídající název prostředí pro pojmenované metody, použije se metoda ConfigureServices nebo Configure.

public void ConfigureDevelopmentServices(IServiceCollection services)
{
    ...
}

public void ConfigureStagingServices(IServiceCollection services)
{
    ...
}

public void ConfigureProductionServices(IServiceCollection services)
{
    ...
}

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

Dodatečné zdroje

• 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