ASP.NET Core에서 여러 환경 사용

작성자: Rick Anderson 및 Kirk Larkin

ASP.NET Core는 환경 변수를 사용하여 런타임 환경에 따라 앱 동작을 구성합니다.

환경

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

1. DOTNET_ENVIRONMENT
2. WebApplication.CreateBuilder 메서드가 호출된 경우 ASPNETCORE_ENVIRONMENT. 기본 ASP.NET Core 웹앱 템플릿은 WebApplication.CreateBuilder를 호출합니다. DOTNET_ENVIRONMENT 사용되는 경우 값이 재정의 ASPNETCORE_ENVIRONMENTWebApplicationBuilder 됩니다. 다른 호스트(예: ConfigureWebHostDefaults 및 WebHost.CreateDefaultBuilder) ASPNETCORE_ENVIRONMENT 의 경우 우선 순위가 더 높습니다.

IHostEnvironment.EnvironmentName을 임의의 값으로 설정할 수 있지만 다음 값은 프레임워크에서 제공됩니다.

• Development: launchSettings.json 파일은 로컬 컴퓨터에서 ASPNETCORE_ENVIRONMENT를 Development로 설정합니다.
• Staging
• Production: DOTNET_ENVIRONMENT 및 ASPNETCORE_ENVIRONMENT가 설정되지 않은 경우 기본값입니다.

코드는 다음과 같습니다.

• ASP.NET Core 템플릿에서 생성된 코드와 유사합니다.
• ASPNETCORE_ENVIRONMENT가 Development로 설정된 경우 개발자 예외 페이지를 사용하도록 설정합니다. 이 작업은 WebApplication.CreateBuilder 메서드에 의해 자동으로 수행됩니다.
• ASPNETCORE_ENVIRONMENT의 값이 Development 이외의 값이면 UseExceptionHandler를 호출합니다.
• WebApplication의 Environment 속성에 IWebHostEnvironment 인스턴스를 제공합니다.

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

Environment 태그 도우미는 IHostEnvironment.EnvironmentName의 값을 사용하여 요소에 태그를 포함하거나 제외합니다.

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

샘플 코드의 정보 페이지에는 이전 태그가 포함되며 IWebHostEnvironment.EnvironmentName의 값이 표시됩니다.

Windows 및 macOS에서 환경 변수 및 값은 대/소문자를 구분하지 않습니다. Linux 환경 변수 및 값은 기본적으로 대/소문자를 구분합니다.

EnvironmentsSample 만들기

이 문서에서 사용되는 샘플 코드는 EnvironmentsSample이라는 Razor Pages 프로젝트를 기반으로 합니다.

다음 .NET CLI 명령은 EnvironmentsSample이라는 웹앱을 만들고 실행합니다.

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

이 앱은 다음과 같은 출력을 표시합니다.

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

명령줄에서 환경 설정

--environment 플래그를 사용하여 환경을 설정합니다. 예시:

dotnet run --environment Production

위의 명령은 환경을 Production으로 설정하며 명령 창에서 다음과 유사한 출력을 표시합니다.

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

개발 및 launchSettings.json

개발 환경은 프로덕션에서 노출해서는 안 되는 기능을 활성화할 수 있습니다. 예를 들어 ASP.NET Core 프로젝트 템플릿은 개발 환경에서 개발자 예외 페이지를 활성화합니다. 성능 비용 때문에 범위 유효성 검사 및 종속성 유효성 검사는 개발에서만 발생합니다.

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

파일:launchSettings.json

• 로컬 개발 머신에서만 사용됩니다.
• 배포되지 않습니다.
• 프로필 설정을 포함합니다.

다음 JSON은 Visual Studio 또는 dotnet new를 사용하여 만든 EnvironmentsSample이라는 ASP.NET Core 웹 프로젝트에 대한 launchSettings.json 파일을 보여 줍니다.

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

위의 JSON에는 다음과 같은 두 프로필이 포함되어 있습니다.

• EnvironmentsSample: 프로필 이름은 프로젝트 이름입니다. 첫 번째로 나열된 이 프로필은 기본적으로 사용됩니다. "commandName" 키에 값 "Project"가 있으므로 Kestrel 웹 서버가 시작됩니다.

• IIS Express: "commandName" 키에 "IISExpress" 값이 있으므로 IISExpress는 웹 서버입니다.

시작 프로필을 프로젝트 또는 에 포함된 다른 프로필로 설정할 수 있습니다 launchSettings.json. 예를 들어 아래 이미지에서 프로젝트 이름을 선택하면 Kestrel 웹 서버가 시작됩니다.

commandName의 값은 시작할 웹 서버를 지정할 수 있습니다. commandName은 다음 중 하나일 수 있습니다.

• IISExpress : IIS Express를 시작합니다.
• IIS : 웹 서버가 시작되지 않았습니다. IIS를 사용할 수 있어야 합니다.
• Project: Kestrel을 시작합니다.

Visual Studio 2022 프로젝트 속성 디버그/일반 탭은 디버그 시작 프로필 UI 열기 링크를 제공합니다. 이 링크는 파일의 환경 변수 설정을 launchSettings.json 편집할 수 있는 프로필 시작 대화 상자를 엽니다. 디버그 메뉴에서 <프로젝트 이름> 디버그 속성을 선택하여 시작 프로필 대화 상자를 열 수도 있습니다. 웹 서버가 다시 시작되기 전에는 프로젝트 프로필의 변경 내용이 적용되지 않을 수 있습니다. 해당 환경에 대한 변경 내용을 감지하려면 Kestrel을 다시 시작해야 합니다.

다음 launchSettings.json 파일에는 여러 프로필이 포함되어 있습니다.

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

프로필은 다음과 같이 선택할 수 있습니다.

• Visual Studio UI에서 선택

• --launch-profile 옵션이 프로필 이름으로 설정된 dotnet run CLI 명령을 사용. 이 방법은 Kestrel 프로필만 지원합니다.

  dotnet run --launch-profile "EnvironmentsSample"
  

Warning

launchSettings.json 비밀을 저장하면 안 됩니다. 암호 관리자 도구를 사용하여 로컬 개발에 사용되는 암호를 저장할 수 있습니다.

Visual Studio Code를 사용하는 경우 파일에서 환경 변수를 .vscode/launch.json 설정할 수 있습니다. 다음 예제에서는 다음과 같이 여러 호스트 구성 값 환경 변수를 설정합니다.

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

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

생산

프로덕션 환경은 보안, 성능 및 애플리케이션 견고성을 최대화하도록 구성되어야 합니다. 개발과 다른 몇 가지 일반적인 설정은 다음과 같습니다.

• 캐싱.
• 클라이언트 쪽 리소스가 번들로 제공되고, 축소되며, 잠재적으로 CDN에서 처리됩니다.
• 진단 오류 페이지를 사용하지 않습니다.
• 친숙한 오류 페이지를 사용하도록 설정합니다.
• 프로덕션 로깅 및 모니터링을 사용합니다. 예를 들어 Application Insights를 사용합니다.

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

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

호스트를 빌드할 때 앱에서 읽은 마지막 환경 설정에 따라 앱의 환경이 결정됩니다. 앱을 실행하는 동안에는 앱 환경을 변경할 수 없습니다.

샘플 코드의 정보 페이지에는 IWebHostEnvironment.EnvironmentName의 값이 표시됩니다.

Azure App Service

DOTNET_ENVIRONMENT 및 ASPNETCORE_ENVIRONMENT가 설정되지 않으면 Production이 기본값입니다. Azure에 배포된 앱은 기본적으로 Production입니다.

포털을 사용하여 Azure App Service 앱에서 환경을 설정하려면

1. App Services 페이지에서 앱을 선택합니다.
2. 설정 그룹에서 구성을 선택합니다.
3. 애플리케이션 설정 탭에서 새 애플리케이션 설정를 선택합니다.
4. 애플리케이션 설정 추가/편집 창에서 이름에 대한 ASPNETCORE_ENVIRONMENT를 제공합니다. 값에는 환경을 입력합니다(예: Staging).
5. 배포 슬롯을 교환할 때 환경 설정을 현재 슬롯으로 유지하려면 배포 슬롯 설정 확인란을 선택합니다. 자세한 내용은 Azure 설명서의 Azure App Service에서 스테이징 환경 설정을 참조하세요.
6. 확인을 선택하여 애플리케이션 설정 추가/편집 대화 상자를 닫습니다.
7. 구성 페이지의 맨 위에 있는 저장을 선택합니다.

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

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

시스템 환경에서 설정된 재정의 값의 환경 값 launchSettings.json 입니다.

앱이 dotnet run을 사용하여 시작할 때 현재 세션에 ASPNETCORE_ENVIRONMENT를 설정하려면 명령 프롬프트 또는 PowerShell에서 다음 명령을 사용합니다.

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

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

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

위의 명령은 해당 명령 창에서 시작된 프로세스에 대해서만 ASPNETCORE_ENVIRONMENT를 설정합니다.

Windows에서 전역적으로 값을 설정하려면 다음 방법 중 하나를 사용합니다.

• 제어판>시스템>고급 시스템 설정을 열고 ASPNETCORE_ENVIRONMENT 값을 추가하거나 편집합니다.

  

  

• 관리 명령 프롬프트를 열고 setx 명령을 사용하거나 관리 PowerShell 명령 프롬프트를 열고 [Environment]::SetEnvironmentVariable을 사용합니다.

  • setx ASPNETCORE_ENVIRONMENT Staging /M
    

    /M 스위치는 시스템 수준에서 환경 변수를 설정합니다. /M 스위치를 사용하지 않으면 환경 변수가 사용자 계정으로 설정됩니다.

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

    Machine 옵션은 시스템 수준에서 환경 변수를 설정합니다. 옵션 값이 User로 변경되면 환경 변수가 사용자 계정에 대해 설정됩니다.

ASPNETCORE_ENVIRONMENT 환경 변수를 전역적으로 설정하면 값이 설정된 후 열리는 모든 명령 창에서 dotnet run에 대해 적용됩니다. 시스템 환경에서 설정된 재정의 값의 환경 값 launchSettings.json 입니다.

Windows - web.config 사용

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

Windows - IIS 배포

<EnvironmentName> 속성을 게시 프로필(.pubxml) 또는 프로젝트 파일에 포함합니다. 이 방법은 프로젝트가 게시될 때 web.config에 환경을 설정합니다.

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

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

IIS에서 앱을 호스트하고 ASPNETCORE_ENVIRONMENT 환경 변수를 추가 또는 변경하는 경우 다음 방법 중 하나를 사용하여 앱에서 새 값을 가져옵니다.

• 명령 프롬프트에서 net stop was /y 다음에 net start w3svc를 실행합니다.
• 서버를 다시 시작합니다.

macOS

macOS에 대한 현재 환경 설정은 앱을 실행할 때 인라인으로 수행할 수 있습니다.

ASPNETCORE_ENVIRONMENT=Staging dotnet run

또는 앱을 실행하기 전에 export를 사용하여 환경을 설정합니다.

export ASPNETCORE_ENVIRONMENT=Staging

컴퓨터 수준 환경 변수는 .bashrc 또는 .bash_profile 파일에서 설정됩니다. 임의의 텍스트 편집기를 사용하여 파일을 편집합니다. 다음 문을 추가합니다.

export ASPNETCORE_ENVIRONMENT=Staging

Linux

Linux 배포의 경우 세션 기반 변수 설정을 위해 명령 프롬프트에서 export 명령을 사용하거나 컴퓨터 수준 환경 설정을 위해 bash_profile 파일을 사용합니다.

코드에서 환경 설정

코드에서 환경을 설정하려면 다음 예제와 같이 WebApplicationBuilder를 만들 때 WebApplicationOptions.EnvironmentName을 사용합니다.

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

환경별 구성

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

환경별로 서비스 및 미들웨어 구성

WebApplicationBuilder.Environment 또는 WebApplication.Environment를 사용하여 현재 환경에 따라 조건부로 서비스 또는 미들웨어를 추가합니다. 프로젝트 템플릿에는 현재 환경이 개발이 아닌 경우에만 미들웨어를 추가하는 코드 예제가 포함되어 있습니다.

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

강조 표시된 코드는 요청 파이프라인을 빌드하는 동안 현재 환경을 확인합니다. 서비스를 구성하는 동안 현재 환경을 확인하려면 app.Environment 대신 builder.Environment를 사용합니다.

추가 리소스

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