ASP.NET Core 런타임 환경

ASP.NET Core는 일반적으로 앱이 실행되는 위치를 반영하는 런타임 환경을 기반으로 앱 동작을 구성합니다.

앱은 일반적으로 하나의 구성된 동작 집합을 사용하여 개발자 컴퓨터에서 로컬 개발 및 테스트 중에 개발 환경에서 실행됩니다. 반면, 구성된 동작 집합이 다른 서버에 배포될 때 프로덕션 환경에서 실행됩니다. 라이브 배포 전에 앱을 스테이징하기 위해 프레임워크에서 제공하는 스테이징 환경 또는 개발자가 만드는 다른 환경과 같은 다양한 추가 환경을 사용할 수 있습니다.

이 문서에서는 앱 런타임 환경, 환경을 사용하여 앱 동작을 제어하는 방법 및 환경을 설정하는 방법을 설명합니다.

Blazor 이 문서의 지침을 추가하거나 대체하는 환경 지침은 ASP.NET Core Blazor 환경을 참조하세요.

Environments

환경은 문자열 값일 수 있지만 프레임워크에서 제공하는 환경 값은 다음과 같습니다.

• Development
• Staging
• Production

프로덕션 환경은 보안, 성능 및 앱 안정성을 최대화하도록 구성됩니다. 개발 환경과 다른 일반적인 개발자 설정 및 구성은 다음과 같습니다.

• 캐싱을 사용하도록 설정합니다.
• 클라이언트 쪽 리소스를 번들화 및 축소하고 CDN에서 서비스를 제공합니다.
• 진단 오류 페이지를 사용하지 않도록 설정하고 친숙한 오류 페이지를 사용하도록 설정합니다.
• 프로덕션 로깅 및 모니터링을 사용하도록 설정합니다. 예를 들어 Azure Application Insights에 대해 로깅을 사용하도록 설정됩니다.

앱에서 읽은 마지막 환경 설정은 앱의 환경을 결정합니다. 앱을 실행하는 동안에는 앱 환경을 변경할 수 없습니다.

로깅 (로그 기록)

시작 시 실행 중인 앱의 명령 셸 출력은 앱의 환경을 나타냅니다. 다음 예제에서 앱은 스테이징 환경에서 실행됩니다.

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

런타임 환경을 결정하는 환경 변수

런타임 환경을 확인하려면 다음 환경 변수에서 ASP.NET Core를 읽습니다.

DOTNET_ENVIRONMENT 환경 변수 및 ASPNETCORE_ENVIRONMENT 환경 변수가 설정되지 않은 경우 프로덕션 환경이 기본 환경입니다.

Windows 및 macOS에서 환경 변수 이름은 대/소문자를 구분하지 않습니다. Linux 환경 변수는 대/소문자를 구분합니다.

환경별 코드 실행 제어

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

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

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

    ...
}

앱 내에서 앱 IHostEnvironment 의 호스팅 환경에 대한 일반 정보를 제공하고 속성은 IHostEnvironment.EnvironmentName 앱의 현재 환경을 나타냅니다.

렌더링된 콘텐츠 제어

서버 렌더링 IHostEnvironment 컴포넌트에 Razor을 삽입하고 서비스의 확장 메서드 및 EnvironmentName 속성을 사용하여 콘텐츠를 렌더링할 환경을 결정합니다.

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

클라이언트 쪽 렌더링을 제어하는 환경이 필요한 경우 Blazor Web AppPrerender ASP.NET Core Razor 구성 요소를 참조하세요.

앱이 실행되면 명령 셸에서 환경 설정(dotnet run)

이-e|--environment 옵션을 사용하여 환경을 설정합니다.

dotnet run -e Staging

시작 설정 파일을 사용하여 환경 설정(launchSettings.json)

로컬 개발 환경은 프로젝트 파일에서 Properties\launchSettings.json 설정할 수 있습니다. launchSettings.json에서 설정된 환경 값이 시스템 환경에서 설정된 값을 재정의합니다.

파일:launchSettings.json

• 로컬 개발 머신에서만 사용됩니다.
• 앱이 게시될 때 배포되지 않습니다.
• 각각 다른 환경을 구성하는 여러 프로필을 포함할 수 있습니다.

다음 예제에서는 https 시작 프로필을 위해 환경 변수 ASPNETCORE_ENVIRONMENT를 사용하여 스테이징 환경을 설정합니다.

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

Visual Studio에서는 시작 프로필을 통해 환경을 설정하는 두 가지 방법이 있습니다.

• 솔루션 탐색기에서 프로젝트를 마우스 오른쪽 단추로 클릭한 후 +Enter 키를 누르거나 속성을 선택합니다. 디버그>일반을 선택한 다음, 디버그 시작 프로필 열기 UI 링크를 선택합니다.

• 솔루션 탐색기에서 프로젝트를 선택한 상태에서 디버그 메뉴에서 {PROJECT NAME} 디버그 속성을 선택합니다. 여기서 {PROJECT NAME} 자리 표시자는 프로젝트 이름입니다.

위의 방법은 파일에서 환경 변수 설정을 편집할 수 있는 launchSettings.json 대화 상자를 엽니다. 웹 서버가 다시 시작되기 전에는 프로젝트 프로필의 변경 내용이 적용되지 않을 수 있습니다. 해당 환경에 대한 변경 내용을 감지하려면 Kestrel을 다시 시작해야 합니다.

시작 단추(**) 옆에 있는 Visual Studio UI에서 프로필을 선택할 수 있습니다.

솔루션에 여러 프로젝트가 포함된 경우 시작 프로젝트에 대한 환경만 설정합니다.

또는 프로필의 이름으로 설정된 옵션과 함께 명령을 사용합니다. 이 방법은 명령에 따라 Project 시작 프로필만 지원합니다.

dotnet run -lp "https"

Visual Studio Code용 C# 개발 키트(VS Code에서 C# 시작)와 함께 Visual Studio Code를 사용하는 경우 앱 파일 launchSettings.json 에서 시작 프로필이 선택됩니다.

C# Dev Kit를 사용하지 않는 경우, 섹션 ASPNETCORE_ENVIRONMENT에서 환경 변수 .vscode/launch.json를 설정하고, 그 외 다른 환경 변수들은 env 섹션에서 설정합니다.

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

이 .vscode/launch.json 파일은 Visual Studio Code에서만 사용됩니다.

환경 변수를 사용하여 환경 설정

환경 변수 또는 플랫폼 설정을 사용하여 테스트하기 위해 특정 환경을 설정하면 유용한 경우가 많습니다. 환경이 설정되지 않은 경우 대부분의 디버깅 기능을 사용하지 않도록 설정하는 프로덕션 환경으로 기본 설정됩니다. 환경 설정에 대한 메서드는 운영 체제에 따라 다릅니다.

Azure App Service

Azure App Service에 배포된 앱은 기본적으로 프로덕션 환경을 채택합니다.

환경 변수를 ASPNETCORE_ENVIRONMENT 설정하려면 Azure 설명서에서 다음 리소스를 참조하세요.

• App Service 앱 구성
• Azure App Service에서 스테이징 환경 설정

앱 설정이 추가, 변경 또는 삭제된 후 Azure App Service가 자동으로 앱을 다시 시작합니다.

프로세스에 대한 환경 변수 설정

현재 세션(명령 셸)에서 ASPNETCORE_ENVIRONMENT을(를) 사용하여 앱을 시작할 때 환경 변수를 설정하려면 다음 명령을 사용합니다. 환경 변수가 설정된 후, --no-launch-profile 옵션을 사용하여 시작 프로필 없이 앱이 시작됩니다.

1. 명령 셸에서 운영 체제에 적절한 접근 방식을 사용하여 환경 변수를 설정합니다.

2. dotnet run 시작 프로필을 사용하지 않고 명령을 실행합니다.

   dotnet run --no-launch-profile
   

PowerShell을 사용하는 경우 다음 두 명령에서 이전 단계를 결합할 수 있습니다. 다음 예제에서는 스테이징 환경을 설정합니다.

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

환경 변수를 전역적으로 설정

운영 체제에 대한 적절한 지침을 사용하여 환경 변수를 ASPNETCORE_ENVIRONMENT 설정합니다.

환경 변수가 ASPNETCORE_ENVIRONMENT 전역적으로 설정되면, 그 값이 설정된 후에 열리는 명령 셸의 dotnet run 명령에 적용됩니다. 파일에서 시작 프로필에 의해 설정된 환경 값은 launchSettings.json 시스템 환경에 대해 설정된 값을 재정의합니다.

IIS에 배포된 앱에 대한 환경 설정

파일을 사용하여 환경 변수를 ASPNETCORE_ENVIRONMENTweb.config 설정하려면 web.config 파일을 참조하세요.

배포 시 환경 변수를 IIS로 설정하려면 <EnvironmentName> 또는 프로젝트 파일에 속성을 포함합니다. 다음 예제에서는 프로젝트가 게시될 때 환경을 web.config 스테이징 환경으로 설정합니다.

<PropertyGroup>
  <EnvironmentName>Staging</EnvironmentName>
</PropertyGroup>

격리된 애플리케이션 풀에서 실행되는 앱의 환경 변수를 설정 ASPNETCORE_ENVIRONMENT 하려면(IIS 10.0 이상에서 지원됨) 환경 변수 environmentVariables <를 참조하세요>. 애플리케이션 풀에 ASPNETCORE_ENVIRONMENT 대해 환경 변수가 설정되면 해당 값이 시스템 수준에서 설정을 재정의합니다.

IIS에서 앱을 호스팅하고 환경 변수를 ASPNETCORE_ENVIRONMENT 추가하거나 변경하는 경우 다음 방법 중 하나를 사용하여 앱 실행에 새 값을 적용합니다.

• 명령 셸에서 net stop was /y을(를) 먼저 실행한 후 net start w3svc을(를) 실행합니다.
• 서버를 다시 시작합니다.

도커

이 섹션의 접근 방식을 사용하여 앱의 환경을 설정합니다.

Dockerfile 사용

다음 ASPNETCORE_ENVIRONMENT 명령을 사용하여 Dockerfile 내에서 환경 변수를 설정합니다.ENV

ENV ASPNETCORE_ENVIRONMENT=Staging

Docker Compose 사용

Docker Compose로 관리되는 다중 서비스 앱의 경우, ASPNETCORE_ENVIRONMENT 파일 내에서 환경 변수를 정의합니다.

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

Docker Compose를 사용하여 런타임에 설정된 환경은 Dockerfile에서 설정한 환경을 재정의합니다.

docker run 명령 사용

명령을 사용하여 Docker 컨테이너를 docker run실행할 때 다음 옵션을 사용하여 ASPNETCORE_ENVIRONMENT 환경 변수를 -e|--env 설정합니다.

docker run -e ASPNETCORE_ENVIRONMENT=Staging aspnet_core_image

런타임에 설정된 환경은 docker run Dockerfile에서 설정한 환경을 재정의합니다.

Docker 환경 파일

ASPNETCORE_ENVIRONMENT Docker 환경 파일(.env)을 사용하여 환경 변수를 설정합니다.

env_variables.env:

ASPNETCORE_ENVIRONMENT=Staging

--env-file을 실행할 때 docker run 옵션을 사용하여 파일을 로드합니다.

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

런타임에 설정된 환경은 docker run Dockerfile에서 설정한 환경을 재정의합니다.

앱의 시작 코드에서 환경 설정

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    EnvironmentName = Environments.Staging
}); 

환경별 구성 로드

환경별로 구성을 로드하려면 ASP.NET Core의 구성을 참조하세요.

클래스에서 Startup 환경에 액세스

.NET 6이 출시되기 전에는 Startup 클래스(Startup.cs)의 Configure와 ConfigureServices 메서드를 사용해야 했으며, 이는 계속 지원됩니다.

IWebHostEnvironment을 Startup 생성자에 삽입하여 코드 실행을 제어합니다. 이 방법은 앱이 환경당 코드 차이를 최소화하면서 몇 가지 환경에 대해서만 시작 코드를 구성해야 하는 경우에 유용합니다.

다음 예제에서는 환경이 필드에 저장 _env 되고 앱의 환경에 따라 코드 실행을 제어합니다.

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

        ...
    }
}

환경별 Startup 클래스

앱은 명명 규칙 Startup 클래스를 사용하여 여러 환경에 대해 여러 Startup{EnvironmentName} 클래스를 정의할 수 있습니다. 여기서 {ENVIRONMENT NAME} 자리 표시자는 환경 이름입니다.

이름 접미사가 현재 환경과 일치하는 클래스에 우선 순위가 부여됩니다. 일치하는 Startup{EnvironmentName} 클래스를 찾을 수 없으면 Startup 클래스가 사용됩니다.

환경 기반 Startup 클래스를 구현하려면 필요한 만큼 Startup{EnvironmentName} 의 클래스와 대체 Startup 클래스를 만듭니다.

public class StartupDevelopment
{
    ...
}

public class StartupProduction
{
    ...
}

public class Startup
{
    ...
}

호스트 빌더가 생성되는 위치에서, 어셈블리 이름을 수락하여 정확한 HostingAbstractionsWebHostBuilderExtensions.UseStartup 클래스를 로드할 수 있도록 Startup을 호출하십시오.

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

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

환경별 Startup 클래스 메서드

Configure 및 ConfigureServices 메서드는 Configure{ENVIRONMENT NAME} 및 Configure{ENVIRONMENT NAME}Services와 같은 환경에 따른 버전의 폼을 지원하며, 여기서 {ENVIRONMENT NAME} 자리 표시자는 환경 이름입니다. 명명된 메서드 ConfigureServices 에 대해 일치하는 환경 이름을 찾을 수 없는 경우 각각 또는 Configure 메서드가 사용됩니다.

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

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

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

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

추가 리소스

• 샘플 코드 보기 및 다운로드(다운로드 방법)
• ASP.NET Core의 앱 시작
• ASP.NET Core의 구성
• ASP.NET Core Blazor 환경