web.config 파일

참고 항목

이 문서의 최신 버전은 아닙니다. 현재 릴리스는 이 문서의 .NET 9 버전을 참조 하세요.

Warning

이 버전의 ASP.NET Core는 더 이상 지원되지 않습니다. 자세한 내용은 .NET 및 .NET Core 지원 정책을 참조 하세요. 현재 릴리스는 이 문서의 .NET 8 버전을 참조 하세요.

Important

이 정보는 상업적으로 출시되기 전에 실질적으로 수정될 수 있는 시험판 제품과 관련이 있습니다. Microsoft는 여기에 제공된 정보에 대해 어떠한 명시적, 또는 묵시적인 보증을 하지 않습니다.

현재 릴리스는 이 문서의 .NET 9 버전을 참조 하세요.

web.config는 IIS에서 호스트되는 앱을 구성하기 위해 IIS 및 ASP.NET Core 모듈이 읽는 파일입니다.

web.config 파일 위치

ASP.NET Core 모듈을 올바르게 설정하려면 배포된 앱의 콘텐츠 루트 경로(일반적으로 앱 기본 경로)에 web.config 파일이 있어야 합니다. IIS에 제공되는 웹 사이트 실제 경로와 동일한 위치입니다. web.config 웹 배포를 사용하여 여러 앱을 게시할 수 있도록 하려면 앱의 루트에 파일이 필요합니다.

중요한 파일은 {ASSEMBLY}.runtimeconfig.json, {ASSEMBLY}.xml(XML 문서 주석) 및 {ASSEMBLY}.deps.json과 같은 앱의 실제 경로에 있습니다. 여기서 자리 표시자 {ASSEMBLY}는 어셈플리 이름입니다. web.config 파일이 있고 사이트가 정상적으로 시작되면 IIS는 요청된 경우 이러한 중요한 파일을 제공하지 않습니다. web.config 파일이 없거나, 이름이 잘못 지정되었거나, 정상적인 시작을 위해 사이트를 구성할 수 없는 경우 IIS는 중요한 파일을 공개적으로 제공할 수 있습니다.

web.config 파일이 항상 배포에 있고, 올바르게 이름이 지정되고, 정상적으로 시작되도록 사이트를 구성할 수 있어야 합니다. 프로덕션 배포에서 web.config 파일을 제거하지 마세요.

프로젝트에 web.config 파일이 없는 경우, ASP.NET Core 모듈을 구성하기 위해 올바른 processPath 및 arguments로 파일이 생성되어 게시된 출력으로 이동됩니다.

web.config 프로젝트에 파일이 있는 경우 파일이 올바른 processPath 상태로 변환되고 arguments ASP.NET Core 모듈을 구성하고 게시된 출력으로 이동합니다. 변환은 이 파일의 IIS 구성 설정을 수정하지 않습니다.

이 파일은 web.config 활성 IIS 모듈을 제어하는 추가 IIS 구성 설정을 제공할 수 있습니다. ASP.NET Core 앱을 사용하여 요청을 처리할 수 있는 IIS 모듈에 대한 자세한 내용은 IIS 모듈 항목을 참조하세요.

파일 만들기, 변환 및 게시 web.config 는 프로젝트가 게시될 때 MSBuild 대상(_TransformWebConfig)에 의해 처리됩니다. 이 대상은 웹 SDK 대상(Microsoft.NET.Sdk.Web)에 나타납니다. SDK는 프로젝트 파일을 기반으로 해서 설정됩니다.

<Project Sdk="Microsoft.NET.Sdk.Web">

웹 SDK가 web.config 파일을 변환하지 못하도록 하려면 프로젝트 파일의 <IsTransformWebConfigDisabled> 속성을 사용합니다.

<PropertyGroup>
  <IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled>
</PropertyGroup>

웹 SDK가 파일을 변환하지 않도록 설정하는 경우 개발자가 processPath arguments 수동으로 설정해야 합니다. 자세한 내용은 IIS용 ANCM(ASP.NET Core 모듈)을 참조하세요.

web.config를 사용하여 ASP.NET Core 모듈 구성

ASP.NET Core 모듈은 사이트 web.config 파일의 system.webServer 노드 섹션으로 aspNetCore 구성됩니다.

다음 web.config 파일은 프레임워크 종속 배포를 위해 게시되고 사이트 요청을 처리하도록 ASP.NET Core 모듈을 구성합니다.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath="dotnet"
                  arguments=".\MyApp.dll"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

다음 web.config는 자체 포함 배포를 위해 게시됩니다.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath=".\MyApp.exe"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

InheritInChildApplications 속성이 false로 설정되어 <location> 요소 내에서 지정된 설정이 하위 디렉터리에 있는 앱에 상속되지 않음을 나타냅니다.

앱이 Azure App Service에 배포되면 stdoutLogFile 경로가 \\?\%home%\LogFiles\stdout로 설정됩니다. 경로는 서비스에서 자동으로 만든 위치인 폴더에 LogFiles stdout 로그를 저장합니다.

IIS 하위 애플리케이션 구성에 대한 자세한 내용은 고급 구성을 참조하세요.

aspNetCore 요소의 특성

attribute	설명	기본값
arguments	선택적 문자열 특성입니다. 에 지정된 실행 파일에 대한 인수입니다 processPath.
disableStartUpErrorPage	선택적 부울 특성입니다. true인 경우 502.5 - 프로세스 실패 페이지가 표시되지 않고 web.config에 구성된 502 상태 코드 페이지가 우선 적용됩니다.	false
forwardWindowsAuthToken	선택적 부울 특성입니다. true인 경우 토큰은 %ASPNETCORE_PORT%에서 수신 대기하는 자식 프로세스에 요청별 헤더 ‘MS-ASPNETCORE-WINAUTHTOKEN’으로 전달됩니다. 이 프로세스는 요청별로 이 토큰에서 CloseHandle을 호출합니다.	true
hostingModel	선택적 문자열 특성입니다. 호스팅 모델을 In-Process(InProcess/inprocess) 또는 Out-of-Process(OutOfProcess/outofprocess)로 지정합니다.	OutOfProcess/outofprocess 없는 경우
processesPerApplication	선택적 정수 특성입니다. 앱별로 회전할 수 있는 설정에 processPath 지정된 프로세스의 인스턴스 수를 지정합니다. †In Process 호스팅의 경우 이 값은 1로 제한됩니다. 설정 processesPerApplication은 권장되지 않습니다. 이 특성은 이후 릴리스에서 제거됩니다.	기본값: 1 최소: 1 최대: 100†
processPath	필수 문자열 특성입니다. HTTP 요청을 수신 대기하는 프로세스를 시작하는 실행 파일의 경로입니다. 상대 경로가 지원됩니다. 경로가 .로 시작되면 경로는 사이트 루트의 상대 경로로 간주됩니다.
rapidFailsPerMinute	선택적 정수 특성입니다. 지정한 프로세스가 분당 크래시할 수 있는 processPath 횟수를 지정합니다. 이 제한을 초과하면 모듈은 남은 시간 동안 프로세스 시작을 중지합니다. In-Process 호스팅에서는 지원되지 않습니다.	기본값: 10 최소: 0 최대: 100
requestTimeout	선택적 시간 간격 특성입니다. ASP.NET Core 모듈이 %ASPNETCORE_PORT%에서 수신 대기하는 프로세스의 응답을 기다리는 기간을 지정합니다. ASP.NET Core 2.1 이상 릴리스와 함께 제공되는 ASP.NET Core 모듈 버전에서는 requestTimeout이 전체 시간, 분, 초로 지정됩니다. In-Process 호스팅에는 적용되지 않습니다. In-Process 호스팅의 경우 모듈은 앱이 요청을 처리할 때까지 기다립니다. 문자열의 분 및 초 세그먼트에 유효한 값은 0-59 범위입니다. 분 또는 초의 값에 60을 사용하면 500 - 내부 서버 오류가 발생됩니다.	기본값: 00:02:00 최소: 00:00:00 최대: 360:00:00
shutdownTimeLimit	선택적 정수 특성입니다. 파일이 검색될 때 app_offline.htm 모듈이 실행 파일이 정상적으로 종료될 때까지 기다리는 기간(초)입니다.	기본값: 10 최소: 0 최대: 600
startupTimeLimit	선택적 정수 특성입니다. 실행 파일이 포트에서 수신 대기하는 프로세스를 시작할 때까지 모듈이 기다리는 기간(초)입니다. 이 시간 제한을 초과하면 모듈이 프로세스를 종료합니다. In Process를 호스트하는 경우: 프로세스가 다시 시작되지 않고 rapidFailsPerMinute 설정을 사용하지 않습니다. Out of Process를 호스트하는 경우: 모듈은 새 요청을 수신할 때 프로세스를 다시 시작하려고 하고, 마지막 롤링 기간(분)에 앱이 rapidFailsPerMinute번 시작에 실패한 경우가 아니면 이후 요청이 들어올 때 프로세스를 계속 다시 시작하려고 합니다. 값 0은 무한 시간 제한으로 간주되지 않습니다.	기본값: 120 최소: 0 최대: 3600
stdoutLogEnabled	선택적 부울 특성입니다. true이 stdout stderr 면 지정된 프로세스에 대해 .에 processPath stdoutLogFile지정된 파일로 리디렉션됩니다.	false
stdoutLogFile	선택적 문자열 특성입니다. 지정 processPath 한 프로세스에서 로그되는 stdout stderr 상대 또는 절대 파일 경로를 지정합니다. 상대 경로는 사이트 루트에 상대적인 경로입니다. .로 시작하는 모든 경로는 사이트 루트에 상대적인 경로이고 다른 모든 경로는 절대 경로로 처리됩니다. 경로에 제공된 모든 폴더는 로그 파일을 만들 때 모듈에 의해 생성됩니다. 밑줄 구분 기호를 사용하면 타임스탬프, 프로세스 ID 및 파일 확장명(.log)이 경로의 stdoutLogFile 마지막 세그먼트에 추가됩니다. .\logs\stdout이 값으로 제공되는 경우 예제 stdout 로그는 2018년 2월 5일 19시 41분 32초에 프로세스 ID 1934를 사용하여 저장될 때 stdout_20180205194132_1934.log로 logs 폴더에 저장됩니다.	aspnetcore-stdout

환경 변수 설정

processPath 특성에서 프로세스에 대한 환경 변수를 지정할 수 있습니다. <environmentVariables> 컬렉션 요소의 <environmentVariable> 자식 요소를 사용하여 환경 변수를 지정합니다. 이 섹션에 설정된 환경 변수가 시스템 환경 변수보다 우선 적용됩니다.

다음 예제에서는 web.config에서 두 개의 환경 변수를 설정합니다. ASPNETCORE_ENVIRONMENT는 앱의 환경을 Development로 구성합니다. 앱 예외를 디버그할 때 개발자 예외 페이지를 강제로 로드하기 위해 개발자가 web.config 파일에서 이 값을 일시적으로 설정할 수 있습니다. CONFIG_DIR은 개발자가 앱 구성 파일을 로드할 경로를 생성하기 위해 시작 시 값을 읽는 코드를 작성한 사용자 정의 환경 변수의 예입니다.

<aspNetCore processPath="dotnet"
      arguments=".\MyApp.dll"
      stdoutLogEnabled="false"
      stdoutLogFile=".\logs\stdout"
      hostingModel="inprocess">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
    <environmentVariable name="CONFIG_DIR" value="f:\application_config" />
  </environmentVariables>
</aspNetCore>

참고 항목

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

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

Warning

인터넷과 같은 신뢰할 수 없는 네트워크에 액세스할 수 없는 스테이징 및 테스트 서버에서는 ASPNETCORE_ENVIRONMENT 환경 변수를 Development로 설정하면 됩니다.

web.config를 사용하여 IIS 구성

IIS 구성은 ASP.NET Core 모듈을 사용하는 ASP.NET Core 앱에 대해 작동하는 IIS 시나리오의 섹션 web.config 에 의해 <system.webServer> 영향을 받습니다. 예를 들어, IIS 구성은 동적 압축에 대해 작동합니다. IIS가 동적 압축 <urlCompression> 을 사용하도록 서버 수준에서 구성된 경우 앱 파일의 web.config 요소가 ASP.NET Core 앱에 대해 사용하지 않도록 설정할 수 있습니다.

자세한 내용은 아래 항목을 참조하세요.

• <system.webServer>의 구성 참조
• IIS용 ANCM(ASP.NET Core 모듈)
• ASP.NET Core를 사용하는 IIS 모듈

격리된 앱 풀에서 실행되는 개별 앱에 대해 환경 변수를 설정하려면(IIS 10.0 이상에서 지원됨), IIS 참조 문서에서 환경 변수 <environmentVariables> 항목의 ‘AppCmd.exe 명령’ 섹션을 참조하세요.

web.config의 구성 섹션

ASP.NET 4.x 앱의 구성 섹션은 ASP.NET Core 앱에서 web.config 구성에 사용되지 않습니다.

• <system.web>
• <appSettings>
• <connectionStrings>
• <location>

ASP.NET Core 앱은 다른 구성 공급자를 사용하여 구성됩니다. 자세한 내용은 구성을 참고하시기 바랍니다.

web.config 변환

게시할 때 web.config를 변환해야 하는 경우 web.config 변환을 참조하세요. 구성, 프로필 또는 환경을 기반으로 하는 환경 변수를 설정하려면 게시할 때 web.config를 변환해야 할 수도 있습니다.

추가 리소스

• IIS <system.webServer>
• ASP.NET Core를 사용하는 IIS 모듈
• web.config 변환