Visual Studio에서 작동 하 고 프로덕션 IIS 서버에서 실패 하는 웹 API2 앱 문제 해결Troubleshoot Web API2 apps that work in Visual Studio and fail on a production IIS server

이 문서에서는 프로덕션 IIS 서버에 배포 된 웹 API2 앱의 문제를 해결 하는 방법을 설명 합니다.This doc explains how to troubleshoot Web API2 apps that are deployed to a production IIS server. 일반적인 HTTP 405 및 501 오류를 해결 합니다.It addresses common HTTP 405 and 501 errors.

이 자습서에서 사용 되는 소프트웨어Software used in this tutorial

웹 API 앱은 일반적으로 GET, POST, PUT, DELETE, 간혹 PATCH 등의 몇 가지 HTTP 동사를 사용 합니다.Web API apps typically use several HTTP verbs: GET, POST, PUT, DELETE, and sometimes PATCH. 즉, 개발자는 해당 동사가 프로덕션 IIS 서버의 다른 IIS 모듈에 의해 구현 되는 상황이 발생할 수 있으며,이로 인해 Visual Studio 또는 개발 서버에서 올바르게 작동 하는 Web API 컨트롤러가 있는 상황이 발생할 수 있습니다. 프로덕션 IIS 서버에 배포 되는 경우 HTTP 405 오류를 반환 합니다.That being said, developers may run into situations where those verbs are implemented by another IIS module on their production IIS server, which leads to a situation where a Web API controller that works correctly in Visual Studio or on a development server will return an HTTP 405 error when it is deployed to a production IIS server.

HTTP 405 오류를 발생 시키는 원인What causes HTTP 405 errors

HTTP 405 오류 문제를 해결 하는 방법에 대 한 첫 번째 단계는 HTTP 405 오류가 실제로 무엇을 의미 하는지 이해 하는 것입니다.The first step toward learning how to troubleshoot HTTP 405 errors is to understand what an HTTP 405 error actually means. HTTP에 대 한 기본 관리 문서는 RFC 2616로, http 405 상태 코드를 허용 되지 않는 메서드로정의 하 고, 요청 줄에 지정 된 메서드가 요청 URI로 식별 되는 리소스에 허용 되지 않는 "상황으로이 상태 코드를 추가로 설명 합니다. 즉, http 동사는 HTTP 클라이언트가 요청한 특정 URL에 대해 허용 되지 않습니다."The primary governing document for HTTP is RFC 2616, which defines the HTTP 405 status code as Method Not Allowed, and further describes this status code as a situation where "the method specified in the Request-Line is not allowed for the resource identified by the Request-URI." In other words, the HTTP verb is not allowed for the specific URL that an HTTP client has requested.

간단한 검토로, RFC 2616, RFC 4918 및 RFC 5789에 정의 된 가장 많이 사용 되는 HTTP 메서드는 다음과 같습니다.As a brief review, here are several of the most-used HTTP methods as defined in RFC 2616, RFC 4918, and RFC 5789:

HTTP 메서드HTTP Method DescriptionDescription
GETGET 이 메서드는 URI에서 데이터를 검색 하는 데 사용 되며, 가장 많이 사용 되는 HTTP 메서드입니다.This method is used to retrieve data from a URI, and it probably the most-used HTTP method.
HEADHEAD 이 메서드는 단순히 HTTP 상태를 검색 하는 요청 URI에서 데이터를 검색 하지 않는다는 점을 제외 하 고 GET 메서드와 매우 유사 합니다.This method is much like the GET method, except that it doesn't actually retrieve the data from the request URI - it simply retrieves the HTTP status.
POSTPOST 이 메서드는 일반적으로 새 데이터를 URI로 보내는 데 사용 됩니다. POST는 종종 양식 데이터를 전송 하는 데 사용 됩니다.This method is typically used to send new data to the URI; POST is often used to submit form data.
PUTPUT 이 메서드는 일반적으로 원시 데이터를 URI로 보내는 데 사용 됩니다. PUT은 Web API 응용 프로그램에 JSON 또는 XML 데이터를 전송 하는 데 종종 사용 됩니다.This method is typically used to send raw data to the URI; PUT is often used to submit JSON or XML data to Web API applications.
DELETEDELETE 이 메서드는 URI에서 데이터를 제거 하는 데 사용 됩니다.This method is used to remove data from a URI.
OPTIONSOPTIONS 이 메서드는 일반적으로 URI에 대해 지원 되는 HTTP 메서드 목록을 검색 하는 데 사용 됩니다.This method is typically used to retrieve the list of HTTP methods that are supported for a URI.
이동 복사COPY MOVE 이러한 두 가지 메서드는 WebDAV와 함께 사용 되며 자체의 용도에 대 한 설명이 필요 합니다.These two methods are used with WebDAV, and their purpose is self-explanatory.
MKCOLMKCOL 이 메서드는 WebDAV와 함께 사용 되며 지정 된 URI에 컬렉션 (예: 디렉터리)을 만드는 데 사용 됩니다.This method is used with WebDAV, and it is used to create a collection (e.g. a directory) at the specified URI.
PROPFIND PROPPATCHPROPFIND PROPPATCH 이러한 두 메서드는 WebDAV에서 사용 되며, URI에 대 한 속성을 쿼리하거나 설정 하는 데 사용 됩니다.These two methods are used with WebDAV, and they are used to query or set properties for a URI.
잠금 잠금 해제LOCK UNLOCK 이러한 두 메서드는 WebDAV에서 사용 되며, 작성할 때 요청 URI에 의해 식별 되는 리소스를 잠그거나 잠금 해제 하는 데 사용 됩니다.These two methods are used with WebDAV, and they are used to lock/unlock the resource identified by the request URI when authoring.
PATCHPATCH 이 메서드는 기존 HTTP 리소스를 수정 하는 데 사용 됩니다.This method is used to modify an existing HTTP resource.

이러한 HTTP 메서드 중 하나가 서버에서 사용 하도록 구성 된 경우 서버는 HTTP 상태 및 요청에 적절 한 기타 데이터를 사용 하 여 응답 합니다.When one of these HTTP methods is configured for use on the server, the server will respond with the HTTP status and other data that is appropriate for the request. 예를 들어 GET 메서드는 HTTP 200 OK 응답을 받을 수 있으며 PUT 메서드는 Http 201 생성 응답을 받을 수 있습니다.(For example, a GET method might receive an HTTP 200 OK response, and a PUT method might receive an HTTP 201 Created response.)

서버에서 사용할 수 있도록 HTTP 메서드가 구성 되지 않은 경우 서버는 HTTP 501 구현 되지 않음 오류와 함께 응답 합니다.If the HTTP method is not configured for use on the server, the server will respond with an HTTP 501 Not Implemented error.

그러나 HTTP 메서드가 서버에서 사용 하도록 구성 되었지만 지정 된 URI에 대해 사용 하지 않도록 설정 된 경우 서버는 HTTP 405 메서드를 사용할 수 없음 오류를 사용 하 여 응답 합니다.However, when an HTTP method is configured for use on the server, but it has been disabled for a given URI, the server will respond with an HTTP 405 Method Not Allowed error.

예제 HTTP 405 오류Example HTTP 405 error

다음 예제 HTTP 요청 및 응답은 HTTP 클라이언트가 웹 서버에서 Web API 앱에 값을 삽입 하려고 시도 하는 상황을 보여 줍니다. 서버는 PUT 메서드가 허용 되지 않는다는 내용의 HTTP 오류를 반환 합니다.The following example HTTP request and response illustrate a situation where an HTTP client is attempting to PUT value to a Web API app on a web server, and the server returns an HTTP error which states that the PUT method is not allowed:

HTTP 요청:HTTP Request:

PUT /api/values/1 HTTP/1.1
Content-type: application/json
Host: localhost
Accept: */*
Content-Length: 12

"Some Value"

HTTP 응답:HTTP Response:

HTTP/1.1 405 Method Not Allowed
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Server: Microsoft-IIS/8.0
X-Powered-By: ASP.NET
Date: Wed, 15 May 2013 02:38:57 GMT
Content-Length: 72

{"Message":"The requested resource does not support http method 'PUT'."}

이 예제에서 HTTP 클라이언트는 웹 서버에서 Web API 응용 프로그램에 대 한 URL에 유효한 JSON 요청을 보냈지만 서버에서 HTTP 405 오류 메시지를 반환 했습니다 .이 메시지는 PUT 메서드가 URL에 허용 되지 않았음을 나타냅니다.In this example, the HTTP client sent a valid JSON request to the URL for a Web API application on a web server, but the server returned an HTTP 405 error message which indicates that the PUT method was not allowed for the URL. 반대로 요청 URI가 웹 API 응용 프로그램에 대 한 경로와 일치 하지 않는 경우 서버는 HTTP 404 찾을 수 없음 오류를 반환 합니다.In contrast, if the request URI did not match a route for the Web API application, the server would return an HTTP 404 Not Found error.

HTTP 405 오류 해결Resolve HTTP 405 errors

특정 HTTP 동사가 허용 되지 않는 이유는 여러 가지가 있지만 IIS에서이 오류가 발생 하는 가장 큰 원인은 다음과 같습니다. 동일한 동사/메서드에 대해 여러 처리기가 정의 되 고 처리기 중 하나가 요청 처리에서 예상한 처리기를 차단 하 고 있습니다.There are several reasons why a specific HTTP verb may not be allowed, but there is one primary scenario that is the leading cause of this error in IIS: multiple handlers are defined for the same verb/method, and one of the handlers is blocking the expected handler from processing the request. 설명 방식으로 IIS는 applicationhost.configweb.config 파일의 주문 처리기 항목을 기반으로 처음부터 마지막으로 처리기를 처리 합니다. 여기서 경로, 동사, 리소스 등의 첫 번째 일치 하는 조합이 요청을 처리 하는 데 사용 됩니다.By way of explanation, IIS processes handlers from first to last based on the order handler entries in the applicationHost.config and web.config files, where the first matching combination of path, verb, resource, etc., will be used to handle the request.

다음 예제는 PUT 메서드를 사용 하 여 Web API 응용 프로그램에 데이터를 전송할 때 HTTP 405 오류를 반환 하는 IIS 서버의 applicationhost.config 파일에서 발췌 한 것입니다.The following example is an excerpt from an applicationHost.config file for an IIS server that was returning an HTTP 405 error when using the PUT method to submit data to a Web API application. 이 발췌문에서는 몇 가지 HTTP 처리기가 정의 되 고 각 처리기는 구성 된 다른 HTTP 메서드 집합을 가집니다. 목록의 마지막 항목은 다른 처리기에 chanc 된 후 사용 되는 기본 처리기 인 정적 콘텐츠 처리기입니다. e: 요청을 검토 합니다.In this excerpt, several HTTP handlers are defined, and each handler has a different set of HTTP methods for which it is configured - the last entry in the list is the static content handler, which is the default handler that is used after the other handlers have had a chance to examine the request:

<handlers accessPolicy="Read, Script">
   <add name="WebDAV"
      path="*"
      verb="PROPFIND,PROPPATCH,MKCOL,PUT,COPY,DELETE,MOVE,LOCK,UNLOCK"
      modules="WebDAVModule"
      resourceType="Unspecified"
      requireAccess="None" />
   <add name="ISAPI-dll"
      path="*.dll"
      verb="*"
      modules="IsapiModule"
      resourceType="File"
      requireAccess="Execute"
      allowPathInfo="true" />
   <add name="ExtensionlessUrlHandler-ISAPI-4.0_64bit"
      path="*."
      verb="GET,HEAD,POST,DEBUG"
      modules="IsapiModule"
      scriptProcessor="%windir%\Microsoft.NET\Framework64\v4.0.30319\aspnet_isapi.dll"
      preCondition="classicMode,runtimeVersionv4.0,bitness64"
      responseBufferLimit="0" />

   <!-- Additional handlers will be defined here. -->

   <add name="StaticFile"
      path="*"
      verb="*"
      modules="StaticFileModule,DefaultDocumentModule,DirectoryListingModule"
      resourceType="Either"
      requireAccess="Read" />
</handlers>

앞의 예제에서 WebDAV 처리기와 ASP.NET (Web API에 사용 됨)에 대 한 확장 URL 처리기는 별도의 HTTP 메서드 목록에 대해 명확 하 게 정의 됩니다.In the preceding example, the WebDAV handler and the Extension-less URL Handler for ASP.NET (which is used for Web API) are clearly defined for separate lists of HTTP methods. 이 구성으로 인해 오류가 발생 하지는 않지만 ISAPI DLL 처리기가 모든 HTTP 메서드에 대해 구성 되어 있습니다.Note that the ISAPI DLL handler is configured for all HTTP methods, although this configuration will not necessarily cause an error. 그러나 HTTP 405 오류 문제를 해결할 때 이와 같은 구성 설정을 고려해 야 합니다.However, configuration settings like this need to be considered when troubleshooting HTTP 405 errors.

위의 예제에서 ISAPI DLL 처리기는 문제가 되지 않았습니다. 실제로 IIS 서버의 applicationhost.config 파일에 문제가 정의 되지 않았습니다. Visual Studio에서 web API 응용 프로그램을 만들 때 web.config 파일에서 발생 한 항목으로 인해 문제가 발생 했습니다.In the preceding example, the ISAPI DLL handler was not the problem; in fact, the problem was not defined in the applicationHost.config file for the IIS server - the problem was caused by an entry that was made in the web.config file when the Web API application was created in Visual Studio. 응용 프로그램의 web.config 파일에서 발췌 한 다음은 문제의 위치를 보여 줍니다.The following excerpt from the application's web.config file shows the location of the problem:

<handlers accessPolicy="Read, Script">
   <remove name="ExtensionlessUrlHandler-ISAPI-4.0_64bit" />
   <add name="ExtensionlessUrlHandler-ISAPI-4.0_64bit"
      path="*."
      verb="GET,HEAD,POST,DEBUG,PUT,DELETE,PATCH,OPTIONS"
      modules="IsapiModule"
      scriptProcessor="%windir%\Microsoft.NET\Framework64\v4.0.30319\aspnet_isapi.dll"
      preCondition="classicMode,runtimeVersionv4.0,bitness64"
      responseBufferLimit="0" />
</handlers>

이 발췌문에서는 ASP.NET에 대 한 확장 URL 처리기가 웹 API 응용 프로그램과 함께 사용 될 추가 HTTP 메서드를 포함 하도록 다시 정의 됩니다.In this excerpt, the Extension-less URL Handler for ASP.NET is redefined to include additional HTTP methods that will be used with the Web API application. 그러나 WebDAV 처리기에 대해 유사한 HTTP 메서드 집합이 정의 되어 있기 때문에 충돌이 발생 합니다.However, since a similar set of HTTP methods is defined for the WebDAV handler, a conflict occurs. 웹 API 응용 프로그램을 포함 하는 웹 사이트에서 WebDAV를 사용 하지 않도록 설정한 경우에도이 특정 경우에 WebDAV 처리기는 IIS에서 정의 되 고 로드 됩니다.In this specific case, the WebDAV handler is defined and loaded by IIS, even though WebDAV is disabled for the website that includes the Web API application. HTTP PUT 요청을 처리 하는 동안 IIS는 PUT 동사에 대해 정의 되어 있으므로 WebDAV 모듈을 호출 합니다.During the processing of an HTTP PUT request, IIS calls the WebDAV module since it is defined for the PUT verb. WebDAV 모듈이 호출 되 면 해당 구성을 확인 하 고 사용 하지 않도록 설정 된 것을 확인 하 여 WebDAV 요청과 유사한 모든 요청에 대해 HTTP 405 메서드를 사용할 수 없음 오류가 반환 됩니다.When the WebDAV module is called, it checks its configuration and sees that it is disabled, so it will return an HTTP 405 Method Not Allowed error for any request that resembles a WebDAV request. 이 문제를 해결 하려면 웹 API 응용 프로그램이 정의 된 웹 사이트에 대 한 HTTP 모듈 목록에서 WebDAV를 제거 해야 합니다.To resolve this issue, you should remove WebDAV from the list of HTTP modules for the website where your Web API application is defined. 다음 예제에서는 다음과 같은 결과를 보여 줍니다.The following example shows what that might look like:

<handlers accessPolicy="Read, Script">
   <remove name="WebDAV" />
   <remove name="ExtensionlessUrlHandler-ISAPI-4.0_64bit" />
   <add name="ExtensionlessUrlHandler-ISAPI-4.0_64bit"
      path="*."
      verb="GET,HEAD,POST,DEBUG,PUT,DELETE,PATCH,OPTIONS"
      modules="IsapiModule"
      scriptProcessor="%windir%\Microsoft.NET\Framework64\v4.0.30319\aspnet_isapi.dll"
      preCondition="classicMode,runtimeVersionv4.0,bitness64"
      responseBufferLimit="0" />
</handlers>

이 시나리오는 응용 프로그램이 개발 환경에서 IIS 프로덕션 환경으로 게시 된 후에 발생 하며,이는 처리기/모듈의 목록이 개발 환경과 프로덕션 환경 간에 다르기 때문에 발생 합니다.This scenario is often encountered after an application is published from a development environment to an IIS production environment, and this occurs because the list of handlers/modules is different between your development and production environments. 예를 들어 Visual Studio 2012 이상 버전을 사용 하 여 Web API 응용 프로그램을 개발 하는 경우 IIS Express는 테스트를 위한 기본 웹 서버입니다.For example, if you are using Visual Studio 2012 or later to develop a Web API application, IIS Express is the default web server for testing. 이 개발 웹 서버는 서버 제품에서 제공 되는 전체 IIS 기능을 축소 한 버전으로,이 개발 웹 서버에는 개발 시나리오에 추가 된 몇 가지 변경 내용이 포함 되어 있습니다.This development web server is a scaled-down version of the full IIS functionality that ships in a server product, and this development web server contains a few changes that were added for development scenarios. 예를 들어 WebDAV 모듈은 사용 되지 않을 수도 있지만 전체 버전의 IIS를 실행 하는 프로덕션 웹 서버에 설치 되는 경우가 많습니다.For example, the WebDAV module is often installed on a production web server that is running the full version of IIS, although it may not be in use. IIS의 개발 버전 (IIS Express)은 WebDAV 모듈을 설치 하지만 WebDAV 모듈의 항목은 의도적으로 주석 처리 되어 있으므로 IIS Express 구성을 특별히 변경 하지 않는 한 WebDAV 모듈이 IIS Express에 로드 되지 않습니다. IIS Express 설치에 WebDAV 기능을 추가 하는 설정입니다.The development version of IIS, (IIS Express), installs the WebDAV module, but the entries for the WebDAV module are intentionally commented out, so the WebDAV module is never loaded on IIS Express unless you specifically alter your IIS Express configuration settings to add WebDAV functionality to your IIS Express installation. 따라서 웹 응용 프로그램은 개발 컴퓨터에서 제대로 작동할 수 있지만 웹 API 응용 프로그램을 프로덕션 IIS 웹 서버에 게시할 때 HTTP 405 오류가 발생할 수 있습니다.As a result, your web application may work correctly on your development computer, but you may encounter HTTP 405 errors when you publish your Web API application to your production IIS web server.

HTTP 501 오류HTTP 501 errors

  • 서버에서 특정 기능을 구현 하지 않았음을 나타냅니다.Indicates the specific functionality has not been implemented on the server.
  • 일반적으로 HTTP 요청과 일치 하는 IIS 설정에 정의 된 처리기가 없음을 의미 합니다.Typically means that there is no handler defined in your IIS settings which matches the HTTP request:
    • 는 IIS에 항목이 제대로 설치 되지 않았음을 나타낼 수 있습니다.Probably indicates that something was not installed correctly on IIS or
    • 특정 HTTP 메서드를 지 원하는 처리기가 정의 되지 않도록 IIS 설정을 수정 했습니다.Something has modified your IIS settings so that there are no handlers defined that support the specific HTTP method.

이 문제를 해결 하려면 해당 모듈 또는 처리기 정의가 없는 HTTP 메서드를 사용 하려는 모든 응용 프로그램을 다시 설치 해야 합니다.To resolve that issue, you would need to reinstall any application that is attempting to use an HTTP method for which it has no corresponding module or handler definitions.

요약Summary

Http 405 오류는 HTTP 메서드가 요청 된 URL에 대해 웹 서버에서 허용 되지 않는 경우에 발생 합니다.HTTP 405 errors are caused when an HTTP method is not allowed by a web server for a requested URL. 이 조건은 특정 동사에 대해 특정 처리기가 정의 되 고 해당 처리기가 요청을 처리할 것으로 간주 되는 처리기를 재정의 하는 경우에 주로 표시 됩니다.This condition is often seen when a particular handler has been defined for a specific verb, and that handler is overriding the handler that you expect to process the request.