HTTP 오류 <httpErrors>

아티클
07/19/2023

개요

<httpErrors> 요소를 사용하면 웹 사이트 또는 애플리케이션에 대한 사용자 지정 오류 메시지를 구성할 수 있습니다. 사용자 지정 오류 메시지를 사용하면 사이트 방문자는 자신이 요청한 콘텐츠에 액세스할 수 없을 때 파일 제공, 다른 리소스 반환, URL 리디렉션 등의 방법을 통해 친숙하거나 자세한 응답을 제공받을 수 있습니다. 예를 들어 나머지 사이트와 동일한 모양 및 느낌을 갖도록 해당 웹 사이트의 각 오류 메시지 페이지를 사용자 지정할 수 있습니다.

<httpErrors> 요소는 요소의 <error> 컬렉션을 포함하며, 각 요소는 IIS가 특정 HTTP 오류에 응답하는 데 사용하는 오류 메시지를 정의합니다. 사이트, 애플리케이션 또는 URL에 대한 Web.config 파일의 <httpErrors> 요소에 요소를 추가하여 <error> IIS에 사용자 지정 오류 메시지를 추가할 수 있습니다. 각 <error> 요소는 responseMode 특성을 사용하여 IIS가 정적 콘텐츠, 동적 콘텐츠를 제공하는지 또는 오류에 대한 응답으로 별도의 URL로 리디렉션되는지 여부를 지정합니다.

요소를 사용하여 <remove> 사이트 또는 애플리케이션이 IIS 구성 계층 구조의 상위 수준에서 상속하는 오류 메시지 컬렉션에서 특정 오류 메시지를 제거할 수 있습니다. 또한 요소를 사용하여 <clear> 사이트 또는 애플리케이션이 상속하는 HTTP 오류 메시지 컬렉션에서 모든 HTTP 오류 메시지를 제거할 수 있습니다.

<httpErrors> 요소에는 오류를 발생시키는 요청을 처리하도록 IIS 7을 구성하는 특성도 포함되어 있습니다. existingResponse 특성은 서버가 HTTP 오류 상태 코드를 반환할 때 IIS 7이 기존 응답에 수행하는 작업을 정의합니다. defaultPath 특성은 요소에서 responseMode 특성 <error> 에 대해 파일 지정을 선택하는 경우 고객 오류 페이지의 경로를 정의합니다.

detailedMoreInformationLink 특성은 특정 오류에 대한 자세한 정보에 대한 링크를 지정합니다.

또한 요소에는 <httpErrors> HTTP 오류가 발생할 때 IIS가 브라우저로 반환하는 세부 정보 수준을 제어하는 데 사용할 수 있는 errorMode 특성이 포함될 수 있습니다. errorMode 특성을 기본 설정인 DetailedLocalOnly로 설정하거나 사용자 지정 또는 세부 정보로 설정할 수 있습니다. DetailedLocalOnly를 지정하거나 errorMode 값을 지정하지 않으면 IIS는 로컬 서버의 브라우저에만 자세한 오류 정보를 반환하고 외부 컴퓨터의 브라우저에 사용자 지정 오류 메시지를 반환합니다. errorMode 값을 Custom으로 설정하면 IIS는 요청하는 모든 브라우저에 사용자 지정 오류 메시지만 반환합니다. errorMode 값을 Detailed로 설정하면 IIS는 모든 요청 브라우저에 자세한 오류 정보를 반환합니다. 기본 DetailedLocalOnly 값을 사용하면 외부 브라우저에 중요한 정보를 노출하지 않으면서 로컬 서버에서 HTTP 오류를 해결할 수 있습니다.

기본적으로 IIS는 %SystemRoot%\Help\IisHelp\Common 폴더에 저장된 파일에 정의된 오류 메시지를 제공합니다. 사용자에 대한 사용자 지정 오류 메시지를 만들고 사이트에서 특정 HTTP 오류가 발생할 때마다 이 페이지를 반환하도록 IIS를 구성할 수 있습니다.

호환성

버전	참고
IIS 10.0	`<httpErrors>` 요소가 IIS 10.0에서 수정되지 않았습니다.
IIS 8.5	`<httpErrors>` 요소가 IIS 8.5에서 수정되지 않았습니다.
IIS 8.0	`<httpErrors>` 요소가 IIS 8.0에서 수정되지 않았습니다.
IIS 7.5	특성이 `allowAbsolutePathsWhenDelegated` IIS 7.5의 `<httpErrors>` 요소에 추가되었습니다.
IIS 7.0	요소는 `<httpErrors>` IIS 7.0에서 도입되었습니다.
IIS 6.0	요소는 `<httpErrors>`IIsWebService 메타베이스 개체의 IIS 6.0 HttpErrors 속성을 대체합니다.

설치 프로그램

요소는 <httpErrors> IIS 7의 기본 설치에 포함됩니다.

방법

사용자 지정 오류 페이지를 추가하는 방법

IIS(인터넷 정보 서비스) 관리자를 엽니다.
- Windows Server 2012 또는 Windows Server 2012 R2를 사용하는 경우:
  - 작업 표시줄에서 서버 관리자 클릭하고 도구를 클릭한 다음 IIS(인터넷 정보 서비스) 관리자를 클릭합니다.
- Windows 8 또는 Windows 8.1 사용하는 경우:
  - Windows 키를 누른 채로 문자 X를 누른 다음 제어판 클릭합니다.
  - 관리 도구를 클릭한 다음 IIS(인터넷 정보 서비스) 관리자를 두 번 클릭합니다.
- Windows Server 2008 또는 Windows Server 2008 R2를 사용하는 경우:
  - 작업 표시줄에서 시작을 클릭하고 관리 도구를 가리킨 다음 IIS(인터넷 정보 서비스) 관리자를 클릭합니다.
- Windows Vista 또는 Windows 7을 사용하는 경우:
  - 작업 표시줄에서 시작을 클릭한 다음 제어판 클릭합니다.
  - 관리 도구를 두 번 클릭한 다음 IIS(인터넷 정보 서비스) 관리자를 두 번 클릭합니다.
연결 창에서 서버 이름을 확장하고 사이트를 확장한 다음 사용자 지정 오류 페이지를 구성할 웹 사이트 또는 애플리케이션으로 이동합니다.
홈 창에서 오류 페이지를 두 번 클릭합니다.
작업 창에서 추가...를 클릭합니다.
사용자 지정 오류 페이지 추가 대화 상자의 상태 코드에서 사용자 지정 오류 메시지를 만들 HTTP 상태 코드의 번호를 입력합니다.
응답 작업 섹션에서 다음 중 하나를 수행합니다.
- 정적 파일의 콘텐츠 삽입을 오류 응답에 선택하여 사용자 지정 오류에 대해 정적 콘텐츠(예: .html 파일)를 제공합니다.
- 이 사이트에서 URL 실행을 선택하여 동적 콘텐츠(예: 사용자 지정 오류에 대한 .asp 파일)를 제공합니다.
- 302 리디렉션으로 응답을 선택하여 클라이언트 브라우저를 사용자 지정 오류 파일이 포함된 다른 URL로 리디렉션합니다.
이 사이트에서 URL 실행 또는 302 리디렉션으로 응답 중 하나를 사용하는 경우 정적 파일의 콘텐츠 삽입 또는 사용자 지정 오류 페이지의 URL을 선택한 경우 파일 경로 텍스트 상자에 사용자 지정 오류 페이지의 경로를 입력한 다음 확인을 클릭합니다.

참고

이 사이트에서 URL 실행을 선택하는 경우 경로는 상대 경로여야 합니다. 302 리디렉션으로 응답을 선택하는 경우 URL은 절대 URL이어야 합니다.

구성

ApplicationHost.config 파일의 서버 수준과 적절한 Web.config 파일의 사이트 및 애플리케이션 수준에서 요소를 구성할 <httpErrors> 수 있습니다.

특성

attribute Description

allowAbsolutePathsWhenDelegated 선택적 부울 특성입니다.

true로 설정하면 섹션이 위임될 때 사용자 지정 오류 페이지에 절대 경로가 <httpErrors> 허용됩니다. false로 설정하면 사이트 루트를 기준으로 하는 경로만 허용됩니다.

기본값은 false입니다.

defaultPath 선택적 문자열 특성입니다.

사용자 지정 오류 페이지의 기본 경로를 지정합니다. 경로의 형식은 defaultResponseMode 특성에 의해 결정됩니다. 파일을 선택하면 파일 경로가 반환됩니다. ExecuteURL 또는 리디렉션 경로 유형을 선택하면 사용자 지정 오류 페이지의 URL이 반환됩니다.

defaultResponseMode

선택적 열거형 특성입니다.

사용자 지정 오류 콘텐츠가 반환되는 방법을 지정합니다.

defaultResponseMode 특성은 다음과 같은 가능한 값 중 하나일 수 있습니다. 기본값은 입니다File.

값	Description
`File`	정적 콘텐츠(예: 사용자 지정 오류에 대한 .html 파일)를 제공합니다. responseMode가 File로 설정된 경우 경로 값은 파일 경로여야 합니다. 숫자 값은 입니다 `0`.
`ExecuteURL`	동적 콘텐츠(예: 사용자 지정 오류에 대한 .asp 파일)를 제공합니다. responseMode가 ExecuteURL로 설정된 경우 경로 값은 서버 상대 URL이어야 합니다. 숫자 값은 입니다 `1`.
`Redirect`	클라이언트 브라우저를 사용자 지정 오류 파일이 포함된 다른 URL로 리디렉션합니다. responseMode가 리디렉션으로 설정된 경우 경로 값은 절대 URL이어야 합니다. 숫자 값은 입니다 `2`.

detailedMoreInformationLink 선택적 문자열 특성입니다.

페이지 아래쪽에 표시된 특정 오류에 대한 자세한 정보가 포함된 페이지에 대한 링크를 지정합니다. 이 속성을 사용 하 여 오류 정보에 대 한 사용자 지정 위치를 최종 사용자를 가리킬 수 있습니다. 상태, 하위 상태, HRESULT 및 메시지 ID는 쿼리 문자열의 일부로 전송됩니다.

기본값은 https://go.microsoft.com/fwlink/?LinkID=62293입니다.

errorMode

선택적 열거형 특성입니다.

HTTP 오류를 사용할 수 있는지 여부를 지정합니다.

errorMode 특성은 다음 값 중 하나일 수 있습니다. 기본값은 입니다DetailedLocalOnly.

값	Description
`DetailedLocalOnly`	요청이 로컬 컴퓨터에서 온 경우 자세한 오류 정보를 반환하고 요청이 외부 컴퓨터에서 온 경우 사용자 지정 오류 메시지를 반환합니다. 숫자 값은 입니다 `0`.
`Custom`	모듈 또는 서버에서 생성하는 오류를 지정한 사용자 지정 페이지로 바꿉니다. 이 모드는 최종 사용자에게 친숙한 오류 메시지를 제공하는 데 유용합니다. 참고: 이 설정은 로컬 요청에 대해서도 자세한 오류를 해제합니다. 숫자 값은 입니다 `1`.
`Detailed`	자세한 오류 정보를 클라이언트로 다시 보냅니다. 이 모드는 웹 사이트 및 애플리케이션을 테스트하고 디버깅하는 데 유용합니다. 숫자 값은 입니다 `2`.

existingResponse

선택적 열거형 특성입니다.

HTTP 상태 코드가 오류인 경우(예: 응답 코드 = 400) 기존 응답에 발생하는 작업을 지정합니다>.

existingResponse 특성은 다음 값 중 하나일 수 있습니다. 기본값은 입니다Auto.

값	Description
`Auto`	SetStatus 플래그가 설정된 경우에만 응답을 그대로 둡니다. 숫자 값은 입니다 `0`.
`Replace`	SetStatus 플래그가 설정된 경우에도 기존 응답을 바꿉니다. 숫자 값은 입니다 `1`.
`PassThrough`	기존 응답이 있는 경우 응답을 그대로 둡니다. 숫자 값은 입니다 `2`.

자식 요소

요소	Description
`error`	선택적 요소입니다. HTTP 오류 컬렉션에 HTTP 오류를 추가합니다.
`remove`	선택적 요소입니다. HTTP 오류 컬렉션에서 HTTP 오류에 대한 참조를 제거합니다.
`clear`	선택적 요소입니다. HTTP 오류 컬렉션에서 HTTP 오류에 대한 모든 참조를 제거합니다.

구성 샘플

웹 사이트 또는 애플리케이션에 대한 Web.config 파일에 포함된 다음 구성 예제에서는 errorMode 특성을 사용하여 자세한 오류 메시지만 로컬 컴퓨터에 표시할 수 있도록 합니다. 또한 defaultResponseMode 특성을 사용하여 사이트 또는 애플리케이션에 대한 응답 모드를 설정합니다. 그런 다음 샘플은 500 상태 코드에 대한 상속된 오류 메시지를 제거합니다. 다음으로 prefixLanguageFilePath 특성을 IIS가 새 사용자 지정 오류 페이지를 검색해야 하는 디렉터리로 설정하고 경로 특성을 사용자 지정 오류 메시지가 포함된 파일인 500.htm 설정합니다.

<configuration>
   <system.webServer>
      <httpErrors errorMode="DetailedLocalOnly" defaultResponseMode="File" >
         <remove statusCode="500" />
         <error statusCode="500"
            prefixLanguageFilePath="C:\Contoso\Content\errors"
            path="500.htm" />
       </httpErrors>
   </system.webServer>
</configuration>

샘플 코드

다음 예제에서는 하위 통계가 5인 모든 상태 코드 404 오류에 대한 새 파일을 추가합니다. IIS는 "URL 시퀀스 거부" 오류에 대해 를 반환합니다. 이러한 예제에서 접두사 경로는 "%SystemDrive%\inetpub\custerr"로 설정되고 파일 이름은 "404.5.htm"로 지정됩니다.

AppCmd.exe

appcmd.exe set config -section:system.webServer/httpErrors /+"[statusCode='404',subStatusCode='5',prefixLanguageFilePath='%SystemDrive%\inetpub\custerr',path='404.5.htm']" /commit:apphost

참고

AppCmd.exe 사용하여 이러한 설정을 구성할 때 commit 매개 변수 apphost 를 로 설정해야 합니다. 그러면 구성 설정이 ApplicationHost.config 파일의 적절한 위치 섹션에 커밋됩니다.

C#

using System;
using System.Text;
using Microsoft.Web.Administration;

internal static class Sample
{
   private static void Main()
   {
      using (ServerManager serverManager = new ServerManager())
      {
         Configuration config = serverManager.GetApplicationHostConfiguration();
         ConfigurationSection httpErrorsSection = config.GetSection("system.webServer/httpErrors");
         ConfigurationElementCollection httpErrorsCollection = httpErrorsSection.GetCollection();

         ConfigurationElement errorElement = httpErrorsCollection.CreateElement("error");
         errorElement["statusCode"] = 404;
         errorElement["subStatusCode"] = 5;
         errorElement["prefixLanguageFilePath"] = @"%SystemDrive%\inetpub\custerr";
         errorElement["path"] = @"404.5.htm";
         httpErrorsCollection.Add(errorElement);

         serverManager.CommitChanges();
      }
   }
}

VB.NET

Imports System
Imports System.Text
Imports Microsoft.Web.Administration

Module Sample
   Sub Main()
      Dim serverManager As ServerManager = New ServerManager
      Dim config As Configuration = serverManager.GetApplicationHostConfiguration
      Dim httpErrorsSection As ConfigurationSection = config.GetSection("system.webServer/httpErrors")
      Dim httpErrorsCollection As ConfigurationElementCollection = httpErrorsSection.GetCollection

      Dim errorElement As ConfigurationElement = httpErrorsCollection.CreateElement("error")
      errorElement("statusCode") = 404
      errorElement("subStatusCode") = 5
      errorElement("prefixLanguageFilePath") = "%SystemDrive%\inetpub\custerr"
      errorElement("path") = "404.5.htm"
      httpErrorsCollection.Add(errorElement)

      serverManager.CommitChanges()
   End Sub
End Module

JavaScript

var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST";
var httpErrorsSection = adminManager.GetAdminSection("system.webServer/httpErrors", "MACHINE/WEBROOT/APPHOST");
var httpErrorsCollection = httpErrorsSection.Collection;

var errorElement = httpErrorsCollection.CreateNewElement("error");
errorElement.Properties.Item("statusCode").Value = 404;
errorElement.Properties.Item("subStatusCode").Value = 5;
errorElement.Properties.Item("prefixLanguageFilePath").Value = "%SystemDrive%\\inetpub\\custerr";
errorElement.Properties.Item("path").Value = "404.5.htm";
httpErrorsCollection.AddElement(errorElement);

adminManager.CommitChanges();

VBScript

Set adminManager = createObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST"
Set httpErrorsSection = adminManager.GetAdminSection("system.webServer/httpErrors", "MACHINE/WEBROOT/APPHOST")
Set httpErrorsCollection = httpErrorsSection.Collection

Set errorElement = httpErrorsCollection.CreateNewElement("error")
errorElement.Properties.Item("statusCode").Value = 404
errorElement.Properties.Item("subStatusCode").Value = 5
errorElement.Properties.Item("prefixLanguageFilePath").Value = "%SystemDrive%\inetpub\custerr"
errorElement.Properties.Item("path").Value = "404.5.htm"
httpErrorsCollection.AddElement errorElement

adminManager.CommitChanges()

다음을 통해 공유