IIS용 ANCM(ASP.NET Core 모듈)
ANCM(ASP.NET Core 모듈)은 IIS 파이프라인에 연결되어 ASP.NET Core 애플리케이션이 IIS에서 작동할 수 있도록 하는 네이티브 IIS 모듈입니다. 다음 중 하나를 사용하여 IIS에서 ASP.NET Core 앱을 실행합니다.
- IIS 작업자 프로세스(
w3wp.exe) 내부에 ASP.NET Core 앱을 호스트하며 In Process 호스팅 모델이라고 합니다. - Kestrel 서버를 실행하는 백 엔드 ASP.NET Core 앱으로 웹 요청을 전달하며 Out of Process 호스팅 모델이라고 합니다.
각 호스팅 모델에는 장단점이 있습니다. 기본적으로 더 나은 성능 및 진단 기능으로 인해 In Process 호스팅 모델이 사용됩니다.
자세한 내용 및 구성 지침은 다음 항목을 참조하세요.
ANCM(ASP.NET Core 모듈) 설치
ANCM(ASP.NET Core 모듈)은 .NET Core 호스팅 번들의 .NET Core 런타임과 함께 설치됩니다. ASP.NET Core 모듈은 .NET의 지원 내 릴리스와 앞으로 및 이전 버전과 호환됩니다.
주요 변경 내용 및 보안 권고는 공지 리포지토리에 보고됩니다. 레이블 필터를 선택하여 공지를 특정 버전으로 제한할 수 있습니다.
다음 링크를 사용하여 설치 관리자를 다운로드합니다.
현재 .NET Core 호스팅 번들 설치 관리자(직접 다운로드)
이전 버전의 모듈 설치를 포함한 자세한 내용은 호스팅 번들을 참조하세요.
IIS 서버에 ASP.NET Core 앱을 게시하는 방법에 대한 자습서 환경은 IIS에 ASP.NET Core 앱 게시를 참조하세요.
ANCM(ASP.NET Core 모듈)은 다음을 위해 IIS 파이프라인에 연결되는 네이티브 IIS 모듈입니다.
- IIS 작업자 프로세스(
w3wp.exe) 내부에 ASP.NET Core 앱을 호스트하며 In-Process 호스팅 모델이라고 합니다. - Out of Process 호스팅 모델이라고 하는 Kestrel 서버를 실행하는 백 엔드 ASP.NET Core 앱으로 웹 요청을 전달합니다.
지원되는 Windows 버전:
- Windows 7 이상
- Windows Server 2012 R2 이상
In Process를 호스트하는 경우 모듈에서는 IIS HTTP Server(IISHttpServer)라는 IIS용 In Process 서버 구현을 사용합니다.
Out-of-Process로 호스팅하는 경우 모듈은 Kestrel에서만 작동합니다. 이 모듈은 HTTP.sys와 작동하지 않습니다.
호스팅 모델
In-process 호스팅 모델
ASP.NET Core 앱의 기본값은 In-process 호스팅 모델입니다.
다음 특성은 In-Process로 호스팅할 때 적용됩니다.
Kestrel 서버 대신 IIS HTTP 서버(
IISHttpServer)가 사용됩니다. In Process의 경우 CreateDefaultBuilder는 UseIIS를 호출하여 다음을 수행합니다.IISHttpServer를 등록합니다.- ASP.NET Core 모듈 뒤에서 실행될 때 서버가 수신 대기해야 하는 포트 및 기본 경로를 구성합니다.
- 시작 오류를 캡처하도록 호스트를 구성합니다.
requestTimeout 특성이 In-Process 호스팅에 적용되지 않습니다.
앱 간의 앱 풀 공유는 지원되지 않습니다. 앱당 하나의 앱 풀을 사용합니다.
웹 배포를 사용하거나
app_offline.htm파일을 배포에 수동으로 배치할 경우 열린 연결이 있으면 앱이 즉시 종료되지 않을 수 있습니다. 예를 들어 WebSocket 연결은 앱 종료를 지연시킬 수 있습니다.앱 및 설치된 런타임(x64 또는 x86)의 아키텍처(비트)는 앱 풀의 아키텍처와 일치해야 합니다.
클라이언트의 연결 끊김이 검색되었습니다. 클라이언트의 연결이 끊어지면
HttpContext.RequestAborted취소 토큰이 취소됩니다.ASP.NET Core 2.2.1 이전 GetCurrentDirectory 버전에서는 앱의 디렉터리(예
C:\Windows\System32\inetsrvw3wp.exe: )가 아닌 IIS에서 시작한 프로세스의 작업자 디렉터리를 반환합니다.앱의 현재 디렉터리를 설정하는 샘플 코드는
CurrentDirectoryHelpers클래스를 참조하세요.SetCurrentDirectory메서드를 호출합니다. GetCurrentDirectory에 대한 후속 호출은 앱의 디렉터리를 제공합니다.In-process로 호스팅하는 경우 사용자를 초기화하기 위해 AuthenticateAsync를 내부적으로 호출하지 않습니다. 따라서 모든 인증 후에 클레임을 변환하는 데 사용되는 IClaimsTransformation 구현은 기본적으로 활성화되지 않습니다. IClaimsTransformation 구현으로 클레임을 변환할 때 AddAuthentication을 호출하여 인증 서비스를 추가합니다.
public void ConfigureServices(IServiceCollection services) { services.AddTransient<IClaimsTransformation, ClaimsTransformer>(); services.AddAuthentication(IISServerDefaults.AuthenticationScheme); } public void Configure(IApplicationBuilder app) { app.UseAuthentication(); }- 웹 패키지(단일 파일) 배포는 지원되지 않습니다.
Out-of-process 호스팅 모델
Out-of-process 호스팅에 대한 앱을 구성하려면 속성 OutOfProcess 값을 <AspNetCoreHostingModel> 프로젝트 파일(.csproj)로 설정합니다.
<PropertyGroup>
<AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
</PropertyGroup>
In-Process 호스팅은 기본값 InProcess로 설정됩니다.
<AspNetCoreHostingModel>의 값은 대/소문자를 구분하지 않으므로 inprocess와 outofprocess는 유효한 값입니다.
IIS HTTP 서버(IISHttpServer) 대신 Kestrel 서버가 사용됩니다.
Out of Process의 경우 CreateDefaultBuilder는 UseIISIntegration을 호출합니다.
- ASP.NET Core 모듈 뒤에서 실행될 때 서버가 수신 대기해야 하는 포트 및 기본 경로를 구성합니다.
- 시작 오류를 캡처하도록 호스트를 구성합니다.
호스팅 모델 변경
hostingModel 설정이 web.config 파일에서 변경되면(web.config로 구성 섹션에 설명되어 있음) 모듈은 IIS에 대한 작업자 프로세스를 재순환합니다.
IIS Express의 경우 모듈은 작업자 프로세스를 재순환하지 않고, 대신 현재 IIS Express 프로세스의 정상 종료를 트리거합니다. 앱에 대한 다음 요청은 새 IIS Express 프로세스를 생성합니다.
프로세스 이름
Process.GetCurrentProcess().ProcessName은 w3wp/iisexpress(In-Process) 또는 dotnet(Out-of-Process)을 보고합니다.
Windows 인증 등의 많은 네이티브 모듈이 활성 상태로 유지됩니다. ASP.NET Core 모듈과 함께 활성화된 IIS 모듈에 대한 자세한 내용은 IIS 모듈 및 ASP.NET Core를 참조하세요.
ASP.NET Core 모듈은 다음 작업을 수행할 수도 있습니다.
- 작업자 프로세스의 환경 변수를 설정합니다.
- 시작 문제를 해결하기 위해 stdout 출력을 파일 스토리지에 기록합니다.
- Windows 인증 토큰을 전달합니다.
ANCM(ASP.NET Core 모듈)을 설치하고 사용하는 방법
ASP.NET Core 모듈을 설치하는 방법에 대한 지침은 .NET Core 호스팅 번들 설치를 참조하세요. ASP.NET Core 모듈은 .NET의 지원 내 릴리스와 앞으로 및 이전 버전과 호환됩니다.
주요 변경 내용 및 보안 권고는 공지 리포지토리에 보고됩니다. 레이블 필터를 선택하여 공지를 특정 버전으로 제한할 수 있습니다.
web.config를 사용한 구성
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 하위 애플리케이션 구성에 대한 자세한 내용은 IIS가 있는 Windows에서 ASP.NET Core 호스팅을 참조하세요.
aspNetCore 요소의 특성
| attribute | 설명 | 기본값 |
|---|---|---|
arguments |
선택적 문자열 특성입니다. processPath에 지정된 실행 파일에 대한 인수입니다. |
|
disableStartUpErrorPage |
선택적 부울 특성입니다. true인 경우 502.5 - 프로세스 실패 페이지가 표시되지 않고 web.config에 구성된 502 상태 코드 페이지가 우선 적용됩니다. |
false |
forwardWindowsAuthToken |
선택적 부울 특성입니다. true인 경우 토큰은 |
true |
hostingModel |
선택적 문자열 특성입니다. 호스팅 모델을 In-Process( |
InProcessinprocess |
processesPerApplication |
선택적 정수 특성입니다. 앱별로 스핀 업할 수 있는 processPath 설정에 지정된 프로세스의 인스턴스 수를 지정합니다. †In Process 호스팅의 경우 이 값은 설정 |
기본값: 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 모듈 버전에서는 In-Process 호스팅에는 적용되지 않습니다. In-Process 호스팅의 경우 모듈은 앱이 요청을 처리할 때까지 기다립니다. 문자열의 분 및 초 세그먼트에 유효한 값은 0-59 범위입니다. 분 또는 초의 값에 60을 사용하면 500 - 내부 서버 오류가 발생됩니다. |
기본값: 00:02:00최소: 00:00:00최대: 360:00:00 |
shutdownTimeLimit |
선택적 정수 특성입니다. 파일이 검색될 때 |
기본값: 10최소: 0최대: 600 |
startupTimeLimit |
선택적 정수 특성입니다. 실행 파일이 포트에서 수신 대기하는 프로세스를 시작할 때까지 모듈이 기다리는 기간(초)입니다. 이 시간 제한을 초과하면 모듈이 프로세스를 종료합니다. In-Process를 호스팅하는 경우: 프로세스가 다시 시작되지 않고 rapidFailsPerMinute 설정을 사용하지 않습니다. Out-of-process를 호스팅하는 경우: 모듈은 새 요청을 수신할 때 프로세스를 다시 시작하려고 시도하고 앱이 마지막 롤링 분에 rapidFailsPerMinute 횟수를 시작하지 못하는 한 후속 들어오는 요청에서 프로세스를 계속 다시 시작하려고 시도합니다. 값 0은 무한 시간 제한으로 간주되지 않습니다. |
기본값: 120최소: 0최대: 3600 |
stdoutLogEnabled |
선택적 부울 특성입니다. true인 경우 processPath에 지정된 프로세스에 대한 stdout 및 stderr이 stdoutLogFile에 지정된 파일로 리디렉션됩니다. |
false |
stdoutLogFile |
선택적 문자열 특성입니다. processPath에 지정된 프로세스에서 stdout 및 stderr이 기록되는 상대 또는 절대 파일 경로를 지정합니다. 상대 경로는 사이트 루트에 상대적인 경로입니다. |
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로 설정하면 됩니다.
app_offline.htm
이름의 app_offline.htm 파일이 앱의 루트 디렉터리에서 검색되면 ASP.NET Core 모듈은 정상적으로 앱을 종료하고 들어오는 요청 처리를 중지하려고 시도합니다. shutdownTimeLimit에 정의된 시간(초) 후에도 앱이 계속 실행되면 ASP.NET Core 모듈은 실행 중인 프로세스를 종료합니다.
app_offline.htm 파일이 있는 동안 ASP.NET Core 모듈은 파일의 app_offline.htm 내용을 다시 전송하여 요청에 응답합니다. app_offline.htm 파일이 제거되면 다음 요청이 앱을 시작합니다.
Out-of-Process 호스팅 모델을 사용할 때 열린 연결이 있으면 앱이 즉시 종료되지 않을 수 있습니다. 예를 들어 WebSocket 연결은 앱 종료를 지연시킬 수 있습니다.
시작 오류 페이지
In process 및 out of process 호스팅은 모두 앱을 시작하지 못할 때 사용자 지정 오류 페이지를 생성합니다.
ASP.NET Core 모듈이 in-process 또는 out-of-process 요청 처리기를 찾지 못하면 500.0 - In-Process/Out-of-process 처리기 로드 실패 상태 코드 페이지가 나타납니다.
in-process 호스팅의 경우 ASP.NET Core 모듈이 앱을 시작하지 못하면 500.30 - 시작 실패 상태 코드 페이지가 나타납니다.
out-of-process 호스팅의 경우 ASP.NET Core 모듈이 백 엔드 프로세스를 시작하지 못하거나 백 엔드 프로세스가 시작되지만 구성된 포트에서 수신 대기하지 못하면 502.5 - 프로세스 실패 상태 코드 페이지가 나타납니다.
이 페이지를 표시하지 않고 기본 IIS 5xx 상태 코드 페이지로 되돌리려면 disableStartUpErrorPage 특성을 사용합니다. 사용자 지정 오류 메시지 구성에 대한 자세한 내용은 HTTP 오류<httpErrors>를 참조하세요.
로그 만들기 및 리디렉션
ASP.NET Core 모듈은 aspNetCore 요소의 stdoutLogEnabled 및 stdoutLogFile 특성이 설정된 경우 stdout 및 stderr 콘솔 출력을 디스크로 리디렉션합니다. stdoutLogFile 경로의 모든 폴더는 로그 파일을 만들 때 모듈에 의해 생성됩니다. 앱 풀에는 로그가 기록될 위치에 쓰기 권한이 있어야 합니다(IIS AppPool\<app_pool_name>을 사용하여 쓰기 권한 제공).
프로세스 재생/다시 시작이 발생하지 않는 한 로그는 회전되지 않습니다. 로그에서 사용하는 디스크 공간을 제한하는 것은 호스터의 책임입니다.
stdout 로그는 IIS에서 호스팅할 때 또는 Visual Studio에서 IIS를 위한 개발 시간 지원을 사용할 때 앱 시작 문제를 해결하기 위해서만 사용하는 것이 좋으며, 로컬에서 디버깅하면서 IIS Express를 사용하여 앱을 실행할 때는 권장되지 않습니다.
일반 앱 로깅을 위해 stdout 로그를 사용하지 마세요. ASP.NET Core 앱의 루틴 로깅에는 로그 파일 크기를 제한하고 로그를 회전하는 로깅 라이브러리를 사용합니다. 자세한 내용은 타사 로깅 공급자를 참조하세요.
로그 파일이 만들어질 때 타임스탬프 및 파일 확장명이 자동으로 추가됩니다. 로그 파일 이름은 밑줄로 구분된 경로의 stdoutLogFile 마지막 세그먼트(.log일반적으로stdout)에 타임스탬프, 프로세스 ID 및 파일 확장명()을 추가하여 구성됩니다. 경로가 stdoutLogFilestdout끝나는 경우 2018년 2월 5일 19:42:32에 만들어진 PID가 1934인 앱의 로그에는 파일 이름이 stdout_20180205194132_1934.log있습니다.
stdoutLogEnabled가 false이면 앱 시작 시 발생하는 오류가 캡처되어 최대 30KB의 이벤트 로그로 내보냅니다. 시작 후에는 모든 추가 로그가 삭제됩니다.
다음 샘플 aspNetCore 요소는 상대 경로 .\log\에서 stdout 로깅을 구성합니다. AppPool 사용자 ID에 제공된 경로에 쓸 수 있는 권한이 있는지 확인합니다.
<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="true"
stdoutLogFile=".\logs\stdout"
hostingModel="inprocess">
</aspNetCore>
Azure App Service 배포를 위해 앱을 게시할 때는 웹 SDK가 stdoutLogFile 값을 \\?\%home%\LogFiles\stdout으로 설정합니다. %home 환경 변수는 Azure App Service에 의해 호스팅되는 앱에 대해 미리 정의됩니다.
로깅 필터 규칙을 만들려면 ASP.NET Core 로깅 설명서의 코드에서 로그 필터 적용 섹션을 참조하세요.
경로 형식에 대한 자세한 내용은 Windows 시스템의 파일 경로 형식을 참조하세요.
개선된 진단 로그
ASP.NET Core 모듈은 개선된 진단 로그를 제공하도록 구성할 수 있습니다. web.config에서 <handlerSettings> 요소를 <aspNetCore> 요소에 추가합니다. debugLevel을 TRACE으로 설정하면 진단 정보의 충실도가 높아집니다.
<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile="\\?\%home%\LogFiles\stdout"
hostingModel="inprocess">
<handlerSettings>
<handlerSetting name="debugFile" value=".\logs\aspnetcore-debug.log" />
<handlerSetting name="debugLevel" value="FILE,TRACE" />
</handlerSettings>
</aspNetCore>
경로의 모든 폴더(logs 앞의 예제)는 로그 파일을 만들 때 모듈에 의해 만들어집니다. 앱 풀에는 로그가 기록될 위치에 쓰기 권한이 있어야 합니다(IIS AppPool\{APP POOL NAME}를 사용하여 쓰기 권한 제공, 여기서 자리 표시자 {APP POOL NAME}는 앱 풀 이름임).
디버그 수준 (debugLevel) 값은 수준과 위치를 모두 포함할 수 있습니다.
수준(최소한에서 가장 자세한 정보까지 순서대로 ):
- 오류
- WARNING
- INFO
- TRACE
위치(여러 위치가 허용됨):
- CONSOLE
- EVENTLOG
- FILE
처리기 설정은 환경 변수를 통해서도 제공할 수 있습니다.
ASPNETCORE_MODULE_DEBUG_FILE: 디버그 로그 파일의 경로입니다. (기본값:aspnetcore-debug.log)ASPNETCORE_MODULE_DEBUG: 디버그 수준 설정입니다.
Warning
배포에서 문제를 해결하는 데 필요한 시간보다 오래 디버그 로깅을 사용하도록 설정하지 마세요. 로그의 크기는 제한되지 않습니다. 디버그 로그를 사용하도록 설정한 대로 두면 사용 가능한 디스크 공간이 소진되어 서버 또는 앱 서비스가 크래시될 수 있습니다.
web.config 파일에 있는 aspNetCore 요소의 예제에 대해서는 web.config를 사용한 구성을 참조하세요.
스택 크기 수정
In-process 호스팅 모델을 사용하는 경우에만 적용됩니다.
web.config에서 stackSize 설정을 사용하여 관리형 스택 크기(바이트)를 구성합니다. 기본 크기는 1,048,576 bytes(1MB)입니다.
<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile="\\?\%home%\LogFiles\stdout"
hostingModel="inprocess">
<handlerSettings>
<handlerSetting name="stackSize" value="2097152" />
</handlerSettings>
</aspNetCore>
프록시 구성은 HTTP 프로토콜 및 페어링 토큰을 사용합니다.
호스팅에만 적용됩니다.
ASP.NET Core 모듈과 Kestrel 간에 만들어진 프록시는 HTTP 프로토콜을 사용합니다. 서버에서 분리된 위치에서 모듈과 Kestrel 간의 트래픽 도청의 위험은 없습니다.
페어링 토큰은 Kestrel에서 받은 요청이 IIS에서 프록시되었으며 다른 원본에서 오지 않았다는 것을 보장하는 데 사용됩니다. 페어링 토큰은 모듈에 의해 생성되며 환경 변수(ASPNETCORE_TOKEN)로 설정됩니다. 페어링 토큰은 프록시된 모든 요청에서 헤더(MS-ASPNETCORE-TOKEN)로도 설정됩니다. IIS 미들웨어는 수신하는 각 요청을 검사하여 페어링 토큰 헤더 값이 환경 변수 값과 일치하는지 확인합니다. 토큰 값이 일치하지 않는 경우 요청이 기록되고 거부됩니다. 페어링 토큰 환경 변수와 모듈과 Kestrel 간의 트래픽은 서버에서 분리된 위치에서 액세스할 수 없습니다. 페어링 토큰 값을 알지 못하면 공격자는 IIS 미들웨어에서 검사를 무시하는 요청을 전송할 수 없습니다.
IIS 공유 구성이 포함된 ASP.NET Core 모듈
ASP.NET Core 모듈 설치 관리자는 TrustedInstaller 계정의 권한으로 실행됩니다. 로컬 시스템 계정에는 IIS 공유 구성에서 사용하는 공유 경로에 대한 수정 권한이 없으므로 설치 관리자는 공유의 파일에서 applicationHost.config 모듈 설정을 구성하려고 할 때 액세스 거부 오류를 throw합니다.
IIS 설치와 동일한 머신에서 IIS 공유 구성을 사용하는 경우 OPT_NO_SHARED_CONFIG_CHECK 매개 변수를 1로 설정한 상태에서 ASP.NET Core Hosting Bundle 설치 관리자를 실행합니다
dotnet-hosting-{VERSION}.exe OPT_NO_SHARED_CONFIG_CHECK=1
공유 구성에 대한 경로가 IIS 설치와 동일한 머신에 있지 않으면 다음 단계를 수행합니다.
- IIS 공유 구성을 사용하지 않도록 설정합니다.
- 설치 관리자를 실행합니다.
- 업데이트
applicationHost.config된 파일을 공유로 내보냅니다. - IIS 공유 구성을 다시 사용하도록 설정합니다.
모듈 버전 및 호스팅 번들 설치 관리자 로그
설치된 ASP.NET Core 모듈의 버전을 확인하려면:
- 호스팅 시스템에서
%windir%\System32\inetsrv. aspnetcore.dll파일을 찾습니다.- 파일을 마우스 오른쪽 단추로 클릭하고 상황에 맞는 메뉴에서 속성을 선택합니다.
- 세부 정보 탭을 선택합니다. 파일 버전 및 제품 버전은 설치된 모듈 버전을 나타냅니다.
모듈의 호스팅 번들 설치 관리자 로그는 C:\Users\%UserName%\AppData\Local\Temp에 있습니다. 파일 이름은 dd_DotNetCoreWinSvrHosting__{TIMESTAMP}_000_AspNetCoreModule_x64.log로 지정됩니다.
모듈, 스키마 및 구성 파일 위치
모듈
IIS(x86/amd64):
%windir%\System32\inetsrv\aspnetcore.dll%windir%\SysWOW64\inetsrv\aspnetcore.dll%ProgramFiles%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll%ProgramFiles(x86)%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll
IIS Express(x86/amd64):
%ProgramFiles%\IIS Express\aspnetcore.dll%ProgramFiles(x86)%\IIS Express\aspnetcore.dll%ProgramFiles%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll%ProgramFiles(x86)%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll
스키마
IIS
%windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml%windir%\System32\inetsrv\config\schema\aspnetcore_schema_v2.xml
IIS Express
%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema_v2.xml
구성
IIS
%windir%\System32\inetsrv\config\applicationHost.config
IIS Express
Visual Studio:
{APPLICATION ROOT}\.vs\config\applicationHost.configiisexpress.exe CLI:
%USERPROFILE%\Documents\IISExpress\config\applicationhost.config
파일에서 applicationHost.config 검색 aspnetcore 하여 파일을 찾을 수 있습니다.
ANCM(ASP.NET Core 모듈)은 다음을 위해 IIS 파이프라인에 연결되는 네이티브 IIS 모듈입니다.
- IIS 작업자 프로세스(
w3wp.exe) 내부에 ASP.NET Core 앱을 호스트하며 In-Process 호스팅 모델이라고 합니다. - Out of Process 호스팅 모델이라고 하는 Kestrel 서버를 실행하는 백 엔드 ASP.NET Core 앱으로 웹 요청을 전달합니다.
지원되는 Windows 버전:
- Windows 7 이상
- Windows Server 2008 R2 이상
In Process를 호스트하는 경우 모듈에서는 IIS HTTP Server(IISHttpServer)라는 IIS용 In Process 서버 구현을 사용합니다.
Out-of-Process로 호스팅하는 경우 모듈은 Kestrel에서만 작동합니다. 이 모듈은 HTTP.sys와 작동하지 않습니다.
호스팅 모델
In-process 호스팅 모델
In-Process 호스팅용 앱을 구성하려면 <AspNetCoreHostingModel> 속성을 InProcess 값의 앱 프로젝트 파일에 추가합니다(Out-of-Process 호스팅은 OutOfProcess로 설정됨).
<PropertyGroup>
<AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
</PropertyGroup>
In-process 호스팅 모델은 .NET Framework를 대상으로 하는 ASP.NET Core 앱을 지원하지 않습니다.
<AspNetCoreHostingModel>의 값은 대/소문자를 구분하지 않으므로 inprocess와 outofprocess는 유효한 값입니다.
파일에 <AspNetCoreHostingModel> 속성이 없으면 기본값은 OutOfProcess입니다.
다음 특성은 In-Process로 호스팅할 때 적용됩니다.
Kestrel 서버 대신 IIS HTTP 서버(
IISHttpServer)가 사용됩니다. In Process의 경우 CreateDefaultBuilder는 UseIIS를 호출하여 다음을 수행합니다.IISHttpServer를 등록합니다.- ASP.NET Core 모듈 뒤에서 실행될 때 서버가 수신 대기해야 하는 포트 및 기본 경로를 구성합니다.
- 시작 오류를 캡처하도록 호스트를 구성합니다.
requestTimeout 특성이 In-Process 호스팅에 적용되지 않습니다.
앱 간의 앱 풀 공유는 지원되지 않습니다. 앱당 하나의 앱 풀을 사용합니다.
웹 배포를 사용하거나 app_offline.htm 파일을 배포에 수동으로 배치할 경우 열린 연결이 있으면 앱이 즉시 종료되지 않을 수 있습니다. 예를 들어, WebSocket 연결은 앱 종료를 지연시킬 수 있습니다.
앱 및 설치된 런타임(x64 또는 x86)의 아키텍처(비트)는 앱 풀의 아키텍처와 일치해야 합니다.
클라이언트의 연결 끊김이 검색되었습니다. 클라이언트의 연결이 끊어지면 HttpContext.RequestAborted 취소 토큰이 취소됩니다.
ASP.NET Core 2.2.1 이하에서 GetCurrentDirectory는 앱 디렉터리가 아닌 IIS에 의해 시작된 프로세스의 작업자 디렉터리를 반환합니다(예: w3wp.exe에 대한 C:\Windows\System32\inetsrv).
앱의 현재 디렉터리를 설정하는 샘플 코드는 CurrentDirectoryHelpers 클래스를 참조하세요.
SetCurrentDirectory메서드를 호출합니다. GetCurrentDirectory에 대한 후속 호출은 앱의 디렉터리를 제공합니다.In-process로 호스팅하는 경우 사용자를 초기화하기 위해 AuthenticateAsync를 내부적으로 호출하지 않습니다. 따라서 모든 인증 후에 클레임을 변환하는 데 사용되는 IClaimsTransformation 구현은 기본적으로 활성화되지 않습니다. IClaimsTransformation 구현으로 클레임을 변환할 때 AddAuthentication을 호출하여 인증 서비스를 추가합니다.
public void ConfigureServices(IServiceCollection services) { services.AddTransient<IClaimsTransformation, ClaimsTransformer>(); services.AddAuthentication(IISServerDefaults.AuthenticationScheme); } public void Configure(IApplicationBuilder app) { app.UseAuthentication(); }
Out-of-process 호스팅 모델
Out of Process 호스팅을 위한 앱을 구성하려면 프로젝트 파일에서 다음 방법 중 하나를 사용합니다.
<AspNetCoreHostingModel>속성을 지정하지 마세요. 파일에<AspNetCoreHostingModel>속성이 없으면 기본값은OutOfProcess입니다.<AspNetCoreHostingModel>속성 값을OutOfProcess로 설정합니다(In Process 호스트팅은InProcess로 설정됨).
<PropertyGroup>
<AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
</PropertyGroup>
이 값은 대/소문자를 구분하지 않으므로 inprocess와 outofprocess는 유효한 값입니다.
IIS HTTP 서버(IISHttpServer) 대신 Kestrel 서버가 사용됩니다.
Out of Process의 경우 CreateDefaultBuilder는 UseIISIntegration를 호출하여 다음을 수행합니다.
- ASP.NET Core 모듈 뒤에서 실행될 때 서버가 수신 대기해야 하는 포트 및 기본 경로를 구성합니다.
- 시작 오류를 캡처하도록 호스트를 구성합니다.
호스팅 모델 변경
hostingModel 설정이 web.config 파일에서 변경되면(web.config로 구성 섹션에 설명되어 있음) 모듈은 IIS에 대한 작업자 프로세스를 재순환합니다.
IIS Express의 경우 모듈은 작업자 프로세스를 재순환하지 않고, 대신 현재 IIS Express 프로세스의 정상 종료를 트리거합니다. 앱에 대한 다음 요청은 새 IIS Express 프로세스를 생성합니다.
프로세스 이름
Process.GetCurrentProcess().ProcessName은 w3wp/iisexpress(In-Process) 또는 dotnet(Out-of-Process)을 보고합니다.
Windows 인증 등의 많은 네이티브 모듈이 활성 상태로 유지됩니다. ASP.NET Core 모듈과 함께 활성화된 IIS 모듈에 대한 자세한 내용은 IIS 모듈 및 ASP.NET Core를 참조하세요.
ASP.NET Core 모듈은 다음 작업을 수행할 수도 있습니다.
- 작업자 프로세스의 환경 변수를 설정합니다.
- 시작 문제를 해결하기 위해 stdout 출력을 파일 스토리지에 기록합니다.
- Windows 인증 토큰을 전달합니다.
ANCM(ASP.NET Core 모듈)을 설치하고 사용하는 방법
ASP.NET Core 모듈을 설치하는 방법에 대한 지침은 .NET Core 호스팅 번들 설치를 참조하세요. ASP.NET Core 모듈은 .NET의 지원 내 릴리스와 앞으로 및 이전 버전과 호환됩니다.
주요 변경 내용 및 보안 권고는 공지 리포지토리에 보고됩니다. 레이블 필터를 선택하여 공지를 특정 버전으로 제한할 수 있습니다.
web.config를 사용한 구성
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 하위 애플리케이션 구성에 대한 자세한 내용은 IIS가 있는 Windows에서 ASP.NET Core 호스팅을 참조하세요.
aspNetCore 요소의 특성
| attribute | 설명 | 기본값 |
|---|---|---|
arguments |
선택적 문자열 특성입니다. 에 지정된 실행 파일에 대한 인수입니다 |
|
disableStartUpErrorPage |
선택적 부울 특성입니다. true인 경우 502.5 - 프로세스 실패 페이지가 표시되지 않고 web.config에 구성된 502 상태 코드 페이지가 우선 적용됩니다. |
false |
forwardWindowsAuthToken |
선택적 부울 특성입니다. true인 경우 토큰은 %ASPNETCORE_PORT%에서 수신 대기하는 자식 프로세스에 요청별 헤더 'MS-ASPNETCORE-WINAUTHTOKEN'으로 전달됩니다. 이 프로세스는 요청별로 이 토큰에서 CloseHandle을 호출합니다. |
true |
hostingModel |
선택적 문자열 특성입니다. 호스팅 모델을 In-Process( |
OutOfProcessoutofprocess |
processesPerApplication |
선택적 정수 특성입니다. 앱별로 회전할 수 있는 설정에 †In Process 호스팅의 경우 이 값은 설정 |
기본값: 1최소: 1최대: 100† |
processPath |
필수 문자열 특성입니다. HTTP 요청을 수신 대기하는 프로세스를 시작하는 실행 파일의 경로입니다. 상대 경로가 지원됩니다. 경로가 |
|
rapidFailsPerMinute |
선택적 정수 특성입니다. 지정한 프로세스가 분당 크래시할 수 있는 In-Process 호스팅에서는 지원되지 않습니다. |
기본값: 10최소: 0최대: 100 |
requestTimeout |
선택적 시간 간격 특성입니다. ASP.NET Core 모듈이 %ASPNETCORE_PORT%에서 수신 대기하는 프로세스의 응답을 기다리는 기간을 지정합니다. ASP.NET Core 2.1 이상 릴리스와 함께 제공되는 ASP.NET Core 모듈 버전에서는 In-Process 호스팅에는 적용되지 않습니다. In-Process 호스팅의 경우 모듈은 앱이 요청을 처리할 때까지 기다립니다. 문자열의 분 및 초 세그먼트에 유효한 값은 0-59 범위입니다. 분 또는 초의 값에 60을 사용하면 500 - 내부 서버 오류가 발생됩니다. |
기본값: 00:02:00최소: 00:00:00최대: 360:00:00 |
shutdownTimeLimit |
선택적 정수 특성입니다. 파일이 검색될 때 |
기본값: 10최소: 0최대: 600 |
startupTimeLimit |
선택적 정수 특성입니다. 실행 파일이 포트에서 수신 대기하는 프로세스를 시작할 때까지 모듈이 기다리는 기간(초)입니다. 이 시간 제한을 초과하면 모듈이 프로세스를 종료합니다. In Process를 호스트하는 경우: 프로세스가 다시 시작되지 않고 Out of Process를 호스트하는 경우: 모듈은 새 요청을 수신할 때 프로세스를 다시 시작하려고 하고, 마지막 롤링 기간(분)에 앱이 값 0은 무한 시간 제한으로 간주되지 않습니다. |
기본값: 120최소: 0최대: 3600 |
stdoutLogEnabled |
선택적 부울 특성입니다. true인 경우 |
false |
stdoutLogFile |
선택적 문자열 특성입니다. 지정 |
aspnetcore-stdout |
환경 변수 설정
processPath 특성에서 프로세스에 대한 환경 변수를 지정할 수 있습니다. <environmentVariables> 컬렉션 요소의 <environmentVariable> 자식 요소를 사용하여 환경 변수를 지정합니다. 이 섹션에 설정된 환경 변수가 시스템 환경 변수보다 우선 적용됩니다.
다음 예제에서는 두 개의 환경 변수를 설정합니다. 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로 설정하면 됩니다.
app_offline.htm
이름의 app_offline.htm 파일이 앱의 루트 디렉터리에서 검색되면 ASP.NET Core 모듈은 정상적으로 앱을 종료하고 들어오는 요청 처리를 중지하려고 시도합니다. shutdownTimeLimit에 정의된 시간(초) 후에도 앱이 계속 실행되면 ASP.NET Core 모듈은 실행 중인 프로세스를 종료합니다.
app_offline.htm 파일이 있는 동안 ASP.NET Core 모듈은 파일의 app_offline.htm 내용을 다시 전송하여 요청에 응답합니다. app_offline.htm 파일이 제거되면 다음 요청이 앱을 시작합니다.
Out-of-Process 호스팅 모델을 사용할 때 열린 연결이 있으면 앱이 즉시 종료되지 않을 수 있습니다. 예를 들어, WebSocket 연결은 앱 종료를 지연시킬 수 있습니다.
시작 오류 페이지
In process 및 out of process 호스팅은 모두 앱을 시작하지 못할 때 사용자 지정 오류 페이지를 생성합니다.
ASP.NET Core 모듈이 in-process 또는 out-of-process 요청 처리기를 찾지 못하면 500.0 - In-Process/Out-of-process 처리기 로드 실패 상태 코드 페이지가 나타납니다.
in-process 호스팅의 경우 ASP.NET Core 모듈이 앱을 시작하지 못하면 500.30 - 시작 실패 상태 코드 페이지가 나타납니다.
out-of-process 호스팅의 경우 ASP.NET Core 모듈이 백 엔드 프로세스를 시작하지 못하거나 백 엔드 프로세스가 시작되지만 구성된 포트에서 수신 대기하지 못하면 502.5 - 프로세스 실패 상태 코드 페이지가 나타납니다.
이 페이지를 표시하지 않고 기본 IIS 5xx 상태 코드 페이지로 되돌리려면 disableStartUpErrorPage 특성을 사용합니다. 사용자 지정 오류 메시지 구성에 대한 자세한 내용은 HTTP 오류 <httpErrors>를 참조하세요.
로그 만들기 및 리디렉션
ASP.NET Core 모듈은 aspNetCore 요소의 stdoutLogEnabled 및 stdoutLogFile 특성이 설정된 경우 stdout 및 stderr 콘솔 출력을 디스크로 리디렉션합니다. stdoutLogFile 경로의 모든 폴더는 로그 파일을 만들 때 모듈에 의해 생성됩니다. 앱 풀에는 로그가 기록될 위치에 쓰기 권한이 있어야 합니다(IIS AppPool\{APP POOL NAME}를 사용하여 쓰기 권한 제공, 여기서 자리 표시자 {APP POOL NAME}는 앱 풀 이름임).
프로세스 재생/다시 시작이 발생하지 않는 한 로그는 회전되지 않습니다. 로그에서 사용하는 디스크 공간을 제한하는 것은 호스터의 책임입니다.
stdout 로그는 IIS에서 호스팅할 때 또는 Visual Studio에서 IIS를 위한 개발 시간 지원을 사용할 때 앱 시작 문제를 해결하기 위해서만 사용하는 것이 좋으며, 로컬에서 디버깅하면서 IIS Express를 사용하여 앱을 실행할 때는 권장되지 않습니다.
일반 앱 로깅을 위해 stdout 로그를 사용하지 마세요. ASP.NET Core 앱의 루틴 로깅에는 로그 파일 크기를 제한하고 로그를 회전하는 로깅 라이브러리를 사용합니다. 자세한 내용은 타사 로깅 공급자를 참조하세요.
로그 파일이 만들어질 때 타임스탬프 및 파일 확장명이 자동으로 추가됩니다. 로그 파일 이름은 밑줄로 구분된 경로의 stdoutLogFile 마지막 세그먼트(.log일반적으로stdout)에 타임스탬프, 프로세스 ID 및 파일 확장명()을 추가하여 구성됩니다. 경로가 stdoutLogFilestdout끝나는 경우 2018년 2월 5일 19:42:32에 만들어진 PID가 1934인 앱의 로그에는 파일 이름이 stdout_20180205194132_1934.log있습니다.
stdoutLogEnabled가 false이면 앱 시작 시 발생하는 오류가 캡처되어 최대 30KB의 이벤트 로그로 내보냅니다. 시작 후에는 모든 추가 로그가 삭제됩니다.
다음 샘플 aspNetCore 요소는 상대 경로 .\log\에서 stdout 로깅을 구성합니다. 앱 풀 사용자 ID에 제공된 경로에 쓸 수 있는 권한이 있는지 확인합니다.
<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="true"
stdoutLogFile=".\logs\stdout"
hostingModel="inprocess">
</aspNetCore>
Azure App Service 배포를 위해 앱을 게시할 때는 웹 SDK가 stdoutLogFile 값을 \\?\%home%\LogFiles\stdout으로 설정합니다. %home 환경 변수는 Azure App Service에 의해 호스팅되는 앱에 대해 미리 정의됩니다.
경로 형식에 대한 자세한 내용은 Windows 시스템의 파일 경로 형식을 참조하세요.
개선된 진단 로그
ASP.NET Core 모듈은 개선된 진단 로그를 제공하도록 구성할 수 있습니다. web.config에서 <handlerSettings> 요소를 <aspNetCore> 요소에 추가합니다. debugLevel을 TRACE으로 설정하면 진단 정보의 충실도가 높아집니다.
<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile="\\?\%home%\LogFiles\stdout"
hostingModel="inprocess">
<handlerSettings>
<handlerSetting name="debugFile" value=".\logs\aspnetcore-debug.log" />
<handlerSetting name="debugLevel" value="FILE,TRACE" />
</handlerSettings>
</aspNetCore>
이전 예제에서 값logs에 <handlerSetting> 제공된 경로의 폴더는 모듈에서 자동으로 생성되지 않으며 배포에 미리 존재해야 합니다. 앱 풀에는 로그가 기록될 위치에 쓰기 권한이 있어야 합니다(IIS AppPool\{APP POOL NAME}를 사용하여 쓰기 권한 제공, 여기서 자리 표시자 {APP POOL NAME}는 앱 풀 이름임).
디버그 수준 (debugLevel) 값은 수준과 위치를 모두 포함할 수 있습니다.
수준(최소한에서 가장 자세한 정보까지 순서대로 ):
- 오류
- WARNING
- INFO
- TRACE
위치(여러 위치가 허용됨):
- CONSOLE
- EVENTLOG
- FILE
처리기 설정은 환경 변수를 통해서도 제공할 수 있습니다.
ASPNETCORE_MODULE_DEBUG_FILE: 디버그 로그 파일의 경로입니다. (기본값:aspnetcore-debug.log)ASPNETCORE_MODULE_DEBUG: 디버그 수준 설정입니다.
Warning
배포에서 문제를 해결하는 데 필요한 시간보다 오래 디버그 로깅을 사용하도록 설정하지 마세요. 로그의 크기는 제한되지 않습니다. 디버그 로그를 사용하도록 설정한 대로 두면 사용 가능한 디스크 공간이 소진되어 서버 또는 앱 서비스가 크래시될 수 있습니다.
web.config 파일에 있는 aspNetCore 요소의 예제에 대해서는 web.config를 사용한 구성을 참조하세요.
프록시 구성은 HTTP 프로토콜 및 페어링 토큰을 사용합니다.
호스팅에만 적용됩니다.
ASP.NET Core 모듈과 Kestrel 간에 만들어진 프록시는 HTTP 프로토콜을 사용합니다. 서버에서 분리된 위치에서 모듈과 Kestrel 간의 트래픽 도청의 위험은 없습니다.
페어링 토큰은 Kestrel에서 받은 요청이 IIS에서 프록시되었으며 다른 원본에서 오지 않았다는 것을 보장하는 데 사용됩니다. 페어링 토큰은 모듈에 의해 생성되며 환경 변수(ASPNETCORE_TOKEN)로 설정됩니다. 페어링 토큰은 프록시된 모든 요청에서 헤더(MS-ASPNETCORE-TOKEN)로도 설정됩니다. IIS 미들웨어는 수신하는 각 요청을 검사하여 페어링 토큰 헤더 값이 환경 변수 값과 일치하는지 확인합니다. 토큰 값이 일치하지 않는 경우 요청이 기록되고 거부됩니다. 페어링 토큰 환경 변수와 모듈과 Kestrel 간의 트래픽은 서버에서 분리된 위치에서 액세스할 수 없습니다. 페어링 토큰 값을 알지 못하면 공격자는 IIS 미들웨어에서 검사를 무시하는 요청을 전송할 수 없습니다.
IIS 공유 구성이 포함된 ASP.NET Core 모듈
ASP.NET Core 모듈 설치 관리자는 계정의 TrustedInstaller 권한으로 실행됩니다. 로컬 시스템 계정에는 IIS 공유 구성에서 사용하는 공유 경로에 대한 수정 권한이 없으므로 설치 관리자는 공유의 파일에서 applicationHost.config 모듈 설정을 구성하려고 할 때 액세스 거부 오류를 throw합니다.
IIS 설치와 동일한 머신에서 IIS 공유 구성을 사용하는 경우 OPT_NO_SHARED_CONFIG_CHECK 매개 변수를 1로 설정한 상태에서 ASP.NET Core Hosting Bundle 설치 관리자를 실행합니다
dotnet-hosting-{VERSION}.exe OPT_NO_SHARED_CONFIG_CHECK=1
공유 구성에 대한 경로가 IIS 설치와 동일한 머신에 있지 않으면 다음 단계를 수행합니다.
- IIS 공유 구성을 사용하지 않도록 설정합니다.
- 설치 관리자를 실행합니다.
- 업데이트
applicationHost.config된 파일을 공유로 내보냅니다. - IIS 공유 구성을 다시 사용하도록 설정합니다.
모듈 버전 및 호스팅 번들 설치 관리자 로그
설치된 ASP.NET Core 모듈의 버전을 확인하려면:
- 호스팅 시스템에서
%windir%\System32\inetsrv. aspnetcore.dll파일을 찾습니다.- 파일을 마우스 오른쪽 단추로 클릭하고 상황에 맞는 메뉴에서 속성을 선택합니다.
- 세부 정보 탭을 선택합니다. 파일 버전 및 제품 버전은 설치된 모듈 버전을 나타냅니다.
모듈의 호스팅 번들 설치 관리자 로그는 C:\\Users\\%UserName%\\AppData\\Local\\Temp에 있습니다. 파일 이름은 dd_DotNetCoreWinSvrHosting__\{TIMESTAMP}_000_AspNetCoreModule_x64.log입니다. 여기서 자리 표시자 {TIMESTAMP}는 타임스탬프입니다.
모듈, 스키마 및 구성 파일 위치
모듈
IIS(x86/amd64):
%windir%\System32\inetsrv\aspnetcore.dll%windir%\SysWOW64\inetsrv\aspnetcore.dll%ProgramFiles%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll%ProgramFiles(x86)%\IIS\Asp.Net Core Module\V2\aspnetcorev2.dll
IIS Express(x86/amd64):
%ProgramFiles%\IIS Express\aspnetcore.dll%ProgramFiles(x86)%\IIS Express\aspnetcore.dll%ProgramFiles%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll%ProgramFiles(x86)%\IIS Express\Asp.Net Core Module\V2\aspnetcorev2.dll
스키마
IIS
%windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml%windir%\System32\inetsrv\config\schema\aspnetcore_schema_v2.xml
IIS Express
%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema_v2.xml
구성
IIS
%windir%\System32\inetsrv\config\applicationHost.config
IIS Express
Visual Studio:
{APPLICATION ROOT}\.vs\config\applicationHost.configiisexpress.exe CLI:
%USERPROFILE%\Documents\IISExpress\config\applicationhost.config
파일에서 applicationHost.config 검색 aspnetcore 하여 파일을 찾을 수 있습니다.
ANCM(ASP.NET Core 모듈)은 백 엔드 ASP.NET Core 앱으로 웹 요청을 전달하는 IIS 파이프라인에 연결되는 네이티브 IIS 모듈입니다.
지원되는 Windows 버전:
- Windows 7 이상
- Windows Server 2008 R2 이상
모듈은 Kestrel에서만 작동합니다. 모듈이 HTTP.sys와 호환되지 않습니다.
ASP.NET Core 앱은 IIS 작업자 프로세스와 별도의 프로세스에서 실행되므로 이 모듈은 프로세스 관리도 수행합니다. 이 모듈은 첫 번째 요청이 들어올 때 ASP.NET Core 앱용 프로세스를 시작하고 충돌이 발생하면 앱을 다시 시작합니다. 이는 Windows Process Activation Service(WAS)로 관리되는 IIS에서 In Process로 실행되는 ASP.NET 4.x 앱에서 볼 수 있는 동작과 기본적으로 동일합니다.
다음 다이어그램은 IIS, ASP.NET Core 모듈 및 앱 간의 관계를 보여 줍니다.
요청은 웹에서 커널 모드 HTTP.sys 드라이버로 도착합니다. 드라이버는 웹 사이트의 구성된 포트(일반적으로 80(HTTP) 또는 443(HTTPS))에서 IIS로 요청을 라우팅합니다. 모듈은 포트 80 또는 443이 아닌 앱의 임의의 포트에서 Kestrel으로 요청을 전달합니다.
모듈은 시작 시 환경 변수를 통해 포트를 지정하고 IIS 통합 미들웨어는 http://localhost:{port}에서 수신 대기하도록 서버를 구성합니다. 추가 검사가 수행되고 모듈에서 시작되지 않은 요청은 거부됩니다. 모듈은 HTTPS 전달을 지원하지 않으므로 HTTPS를 통해 IIS에서 수신된 경우에도 HTTP를 통해 요청이 전달됩니다.
Kestrel이 모듈에서 요청을 선택한 후 요청은 ASP.NET Core 미들웨어 파이프라인으로 푸시됩니다. 미들웨어 파이프라인은 요청을 처리하고 앱의 논리에 HttpContext 인스턴스로 전달합니다. IIS 통합에 의해 추가된 미들웨어는 체계, 원격 IP 및 PathBase를 Kestrel에 요청을 전달하기 위한 계정으로 업데이트합니다. 앱의 응답은 IIS로 다시 전달되고, 요청을 시작한 HTTP 클라이언트에 다시 푸시됩니다.
Windows 인증 등의 많은 네이티브 모듈이 활성 상태로 유지됩니다. ASP.NET Core 모듈과 함께 활성화된 IIS 모듈에 대한 자세한 내용은 IIS 모듈 및 ASP.NET Core를 참조하세요.
ASP.NET Core 모듈은 다음 작업을 수행할 수도 있습니다.
- 작업자 프로세스의 환경 변수를 설정합니다.
- 시작 문제를 해결하기 위해 stdout 출력을 파일 스토리지에 기록합니다.
- Windows 인증 토큰을 전달합니다.
ANCM(ASP.NET Core 모듈)을 설치하고 사용하는 방법
ASP.NET Core 모듈을 설치하는 방법에 대한 지침은 .NET Core 호스팅 번들 설치를 참조하세요.
web.config를 사용한 구성
ASP.NET Core 모듈은 사이트의 web.config 파일에 있는 system.webServer 노드의 aspNetCore 섹션으로 구성됩니다.
다음 web.config 파일은 프레임워크 종속 배포를 위해 게시되고 사이트 요청을 처리하도록 ASP.NET Core 모듈을 구성합니다.
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<system.webServer>
<handlers>
<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />
</handlers>
<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile=".\logs\stdout" />
</system.webServer>
</configuration>
다음 web.config는 자체 포함 배포를 위해 게시됩니다.
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<system.webServer>
<handlers>
<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />
</handlers>
<aspNetCore processPath=".\MyApp.exe"
stdoutLogEnabled="false"
stdoutLogFile=".\logs\stdout" />
</system.webServer>
</configuration>
앱이 Azure App Service에 배포되면 stdoutLogFile 경로가 \\?\%home%\LogFiles\stdout로 설정됩니다. 이 경로는 서비스에서 자동으로 만들어진 위치인 LogFiles 폴더에 stdout 로그를 저장합니다.
IIS 하위 애플리케이션 구성에 대한 자세한 내용은 IIS가 있는 Windows에서 ASP.NET Core 호스팅을 참조하세요.
aspNetCore 요소의 특성
| attribute | 설명 | 기본값 |
|---|---|---|
arguments |
선택적 문자열 특성입니다. processPath에 지정된 실행 파일에 대한 인수입니다. |
|
disableStartUpErrorPage |
선택적 부울 특성입니다. true인 경우 502.5 - 프로세스 실패 페이지가 표시되지 않고 web.config에 구성된 502 상태 코드 페이지가 우선 적용됩니다. |
false |
forwardWindowsAuthToken |
선택적 부울 특성입니다. true인 경우 토큰은 %ASPNETCORE_PORT%에서 수신 대기하는 자식 프로세스에 요청별 헤더 'MS-ASPNETCORE-WINAUTHTOKEN'으로 전달됩니다. 이 프로세스는 요청별로 이 토큰에서 CloseHandle을 호출합니다. |
true |
processesPerApplication |
선택적 정수 특성입니다. 앱별로 스핀 업할 수 있는 processPath 설정에 지정된 프로세스의 인스턴스 수를 지정합니다. 설정 |
기본값: 1최소: 1최대: 100 |
processPath |
필수 문자열 특성입니다. HTTP 요청을 수신 대기하는 프로세스를 시작하는 실행 파일의 경로입니다. 상대 경로가 지원됩니다. 경로가 |
|
rapidFailsPerMinute |
선택적 정수 특성입니다. processPath에 지정된 프로세스의 분당 크래시 허용 횟수를 지정합니다. 이 제한을 초과하면 모듈은 남은 시간 동안 프로세스 시작을 중지합니다. |
기본값: 10최소: 0최대: 100 |
requestTimeout |
선택적 시간 간격 특성입니다. ASP.NET Core 모듈이 %ASPNETCORE_PORT%에서 수신 대기하는 프로세스의 응답을 기다리는 기간을 지정합니다. ASP.NET Core 2.1 이상 릴리스와 함께 제공되는 ASP.NET Core 모듈 버전에서는 |
기본값: 00:02:00최소: 00:00:00최대: 360:00:00 |
shutdownTimeLimit |
선택적 정수 특성입니다. 파일이 검색될 때 |
기본값: 10최소: 0최대: 600 |
startupTimeLimit |
선택적 정수 특성입니다. 실행 파일이 포트에서 수신 대기하는 프로세스를 시작할 때까지 모듈이 기다리는 기간(초)입니다. 이 시간 제한을 초과하면 모듈이 프로세스를 종료합니다. 모듈은 새 요청을 수신할 때 프로세스를 다시 시작하려고 하고, 마지막 롤링 기간(분)에 앱이 rapidFailsPerMinute번 시작에 실패한 경우가 아니면 이후 요청이 들어올 때 프로세스를 계속 다시 시작하려고 합니다. 값 0은 무한 시간 제한으로 간주되지 않습니다. |
기본값: 120최소: 0최대: 3600 |
stdoutLogEnabled |
선택적 부울 특성입니다. true인 경우 processPath에 지정된 프로세스에 대한 stdout 및 stderr이 stdoutLogFile에 지정된 파일로 리디렉션됩니다. |
false |
stdoutLogFile |
선택적 문자열 특성입니다. processPath에 지정된 프로세스에서 stdout 및 stderr이 기록되는 상대 또는 절대 파일 경로를 지정합니다. 상대 경로는 사이트 루트에 상대적인 경로입니다. |
aspnetcore-stdout |
환경 변수 설정
processPath 특성에서 프로세스에 대한 환경 변수를 지정할 수 있습니다. <environmentVariables> 컬렉션 요소의 <environmentVariable> 자식 요소를 사용하여 환경 변수를 지정합니다.
Warning
이 섹션에 설정된 환경 변수가 동일한 이름으로 설정된 시스템 환경 변수와 충돌합니다. 환경 변수가 web.config 파일과 Windows의 시스템 수준에 모두 설정된 경우 web.config 파일의 값은 시스템 환경 변수 값(예: ASPNETCORE_ENVIRONMENT: Development;Development)에 추가되어 앱이 시작되지 않습니다.
다음 예제에서는 두 개의 환경 변수를 설정합니다. ASPNETCORE_ENVIRONMENT는 앱의 환경을 Development로 구성합니다. 앱 예외를 디버그할 때 개발자 예외 페이지를 강제로 로드하기 위해 개발자가 web.config 파일에서 이 값을 일시적으로 설정할 수 있습니다. CONFIG_DIR은 개발자가 앱 구성 파일을 로드할 경로를 생성하기 위해 시작 시 값을 읽는 코드를 작성한 사용자 정의 환경 변수의 예입니다.
<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile="\\?\%home%\LogFiles\stdout">
<environmentVariables>
<environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
<environmentVariable name="CONFIG_DIR" value="f:\application_config" />
</environmentVariables>
</aspNetCore>
Warning
인터넷과 같은 신뢰할 수 없는 네트워크에 액세스할 수 없는 스테이징 및 테스트 서버에서는 ASPNETCORE_ENVIRONMENT 환경 변수를 Development로 설정하면 됩니다.
app_offline.htm
이름의 app_offline.htm 파일이 앱의 루트 디렉터리에서 검색되면 ASP.NET Core 모듈은 정상적으로 앱을 종료하고 들어오는 요청 처리를 중지하려고 시도합니다. shutdownTimeLimit에 정의된 시간(초) 후에도 앱이 계속 실행되면 ASP.NET Core 모듈은 실행 중인 프로세스를 종료합니다.
app_offline.htm 파일이 있는 동안 ASP.NET Core 모듈은 파일의 app_offline.htm 내용을 다시 전송하여 요청에 응답합니다. app_offline.htm 파일이 제거되면 다음 요청이 앱을 시작합니다.
시작 오류 페이지
ASP.NET Core 모듈이 백 엔드 프로세스를 시작하지 못하거나 백 엔드 프로세스가 시작되지만 구성된 포트에서 수신 대기하지 못하면 502.5 - 프로세스 실패 상태 코드 페이지가 나타납니다. 이 페이지를 표시하지 않고 기본 IIS 502 상태 코드 페이지로 되돌리려면 disableStartUpErrorPage 특성을 사용합니다. 사용자 지정 오류 메시지 구성에 대한 자세한 내용은 HTTP 오류 <httpErrors>를 참조하세요.
로그 만들기 및 리디렉션
ASP.NET Core 모듈은 aspNetCore 요소의 stdoutLogEnabled 및 stdoutLogFile 특성이 설정된 경우 stdout 및 stderr 콘솔 출력을 디스크로 리디렉션합니다. stdoutLogFile 경로의 모든 폴더는 로그 파일을 만들 때 모듈에 의해 생성됩니다. 앱 풀에는 로그가 기록될 위치에 쓰기 권한이 있어야 합니다(IIS AppPool\<app_pool_name>을 사용하여 쓰기 권한 제공).
프로세스 재생/다시 시작이 발생하지 않는 한 로그는 회전되지 않습니다. 로그에서 사용하는 디스크 공간을 제한하는 것은 호스터의 책임입니다.
stdout 로그는 IIS에서 호스팅할 때 또는 Visual Studio에서 IIS를 위한 개발 시간 지원을 사용할 때 앱 시작 문제를 해결하기 위해서만 사용하는 것이 좋으며, 로컬에서 디버깅하면서 IIS Express를 사용하여 앱을 실행할 때는 권장되지 않습니다.
일반 앱 로깅을 위해 stdout 로그를 사용하지 마세요. ASP.NET Core 앱의 루틴 로깅에는 로그 파일 크기를 제한하고 로그를 회전하는 로깅 라이브러리를 사용합니다. 자세한 내용은 타사 로깅 공급자를 참조하세요.
로그 파일이 만들어질 때 타임스탬프 및 파일 확장명이 자동으로 추가됩니다. 로그 파일 이름은 타임스탬프, 프로세스 ID 및 파일 확장명(.log)을 밑줄로 구분된 stdoutLogFile 경로의 마지막 세그먼트(일반적으로 stdout)에 추가하여 작성됩니다. stdoutLogFile 경로가 stdout으로 끝나는 경우 2018년 2월 5일 19시 42분 32초에 만들어진 PID 1934를 사용하는 앱에 대한 로그의 파일 이름은 stdout_20180205194132_1934.log입니다.
다음 샘플 aspNetCore 요소는 상대 경로 .\log\에서 stdout 로깅을 구성합니다. AppPool 사용자 ID에 제공된 경로에 쓸 수 있는 권한이 있는지 확인합니다.
<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="true"
stdoutLogFile=".\logs\stdout">
</aspNetCore>
Azure App Service 배포를 위해 앱을 게시할 때는 웹 SDK가 stdoutLogFile 값을 \\?\%home%\LogFiles\stdout으로 설정합니다. %home 환경 변수는 Azure App Service에 의해 호스팅되는 앱에 대해 미리 정의됩니다.
로깅 필터 규칙을 만들려면 ASP.NET Core 로깅 설명서의 코드에서 로그 필터 적용 섹션을 참조하세요.
경로 형식에 대한 자세한 내용은 Windows 시스템의 파일 경로 형식을 참조하세요.
프록시 구성은 HTTP 프로토콜 및 페어링 토큰을 사용합니다.
ASP.NET Core 모듈과 Kestrel 간에 만들어진 프록시는 HTTP 프로토콜을 사용합니다. 서버에서 분리된 위치에서 모듈과 Kestrel 간의 트래픽 도청의 위험은 없습니다.
페어링 토큰은 Kestrel에서 받은 요청이 IIS에서 프록시되었으며 다른 원본에서 오지 않았다는 것을 보장하는 데 사용됩니다. 페어링 토큰은 모듈에 의해 생성되며 환경 변수(ASPNETCORE_TOKEN)로 설정됩니다. 페어링 토큰은 프록시된 모든 요청에서 헤더(MS-ASPNETCORE-TOKEN)로도 설정됩니다. IIS 미들웨어는 수신하는 각 요청을 검사하여 페어링 토큰 헤더 값이 환경 변수 값과 일치하는지 확인합니다. 토큰 값이 일치하지 않는 경우 요청이 기록되고 거부됩니다. 페어링 토큰 환경 변수와 모듈과 Kestrel 간의 트래픽은 서버에서 분리된 위치에서 액세스할 수 없습니다. 페어링 토큰 값을 알지 못하면 공격자는 IIS 미들웨어에서 검사를 무시하는 요청을 전송할 수 없습니다.
IIS 공유 구성이 포함된 ASP.NET Core 모듈
ASP.NET Core 모듈 설치 관리자는 TrustedInstaller 계정의 권한으로 실행됩니다. 로컬 시스템 계정에는 IIS 공유 구성에서 사용하는 공유 경로에 대한 수정 권한이 없으므로 공유의 applicationHost.config에서 모듈 설정을 구성하려고 하면 설치 관리자에서 액세스 거부 오류가 throw됩니다.
IIS 공유 구성을 사용할 경우 다음 단계를 수행합니다.
- IIS 공유 구성을 사용하지 않도록 설정합니다.
- 설치 관리자를 실행합니다.
- 업데이트된 applicationHost.config 파일을 공유로 내보냅니다.
- IIS 공유 구성을 다시 사용하도록 설정합니다.
모듈 버전 및 호스팅 번들 설치 관리자 로그
설치된 ASP.NET Core 모듈의 버전을 확인하려면:
- 호스팅 시스템에서 %windir%\System32\inetsrv로 이동합니다.
- aspnetcore.dll 파일을 찾습니다.
- 파일을 마우스 오른쪽 단추로 클릭하고 상황에 맞는 메뉴에서 속성을 선택합니다.
- 세부 정보 탭을 선택합니다. 파일 버전 및 제품 버전은 설치된 모듈 버전을 나타냅니다.
모듈에 대한 호스팅 번들 설치 관리자 로그는 C:\Users\%UserName%\AppData\Local\Temp에 있습니다. 파일 이름은 dd_DotNetCoreWinSvrHosting__<timestamp>_000_AspNetCoreModule_x64.log입니다.
모듈, 스키마 및 구성 파일 위치
모듈
IIS(x86/amd64):
%windir%\System32\inetsrv\aspnetcore.dll
%windir%\SysWOW64\inetsrv\aspnetcore.dll
IIS Express(x86/amd64):
%ProgramFiles%\IIS Express\aspnetcore.dll
%ProgramFiles(x86)%\IIS Express\aspnetcore.dll
스키마
IIS
- %windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml
IIS Express
- %ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml
구성
IIS
- %windir%\System32\inetsrv\config\applicationHost.config
IIS Express
Visual Studio: {APPLICATION ROOT}\.vs\config\applicationHost.config
iisexpress.exe CLI: %USERPROFILE%\Documents\IISExpress\config\applicationhost.config
applicationHost.config 파일에서 aspnetcore를 검색하여 파일을 찾을 수 있습니다.
추가 리소스
- IIS가 있는 Windows에서 ASP.NET Core 호스팅
- Azure App Service에 ASP.NET Core 앱 배포
- ASP.NET Core 모듈 참조 원본[기본 분기(main)]: 분기 드롭다운 목록을 사용하여 특정 릴리스를 선택할 수 있습니다(예:
release/3.1). - ASP.NET Core를 사용하는 IIS 모듈
ASP.NET Core
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기