Устранение неполадок в приложениях веб-API2, работающих в Visual Studio, и ошибках на рабочем сервере IISTroubleshoot Web API2 apps that work in Visual Studio and fail on a production IIS server

В этом документе объясняется, как устранять неполадки в приложениях веб-API2, развернутых на рабочем сервере IIS.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 обычно используется несколько глаголов HTTP: GET, POST, размещение, удаление и иногда исправление.Web API apps typically use several HTTP verbs: GET, POST, PUT, DELETE, and sometimes PATCH. С другой стороны, разработчики могут столкнуться с ситуациями, когда эти глаголы реализуются другим модулем IIS на рабочем сервере IIS, что приводит к ситуации, когда контроллер веб-API, который правильно работает в Visual Studio или на сервере разработки, будет Возвращает ошибку HTTP 405 при развертывании на рабочем сервере IIS.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 405What 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 не разрешена для конкретного URL-адреса, запрошенного клиентом HTTP.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.

В качестве краткого анализа ниже приведены некоторые из наиболее используемых методов HTTP, как определено в RFC 2616, RFC 4918 и RFC 5789.As a brief review, here are several of the most-used HTTP methods as defined in RFC 2616, RFC 4918, and RFC 5789:

Метод HTTPHTTP Method DescriptionDescription
GETGET Этот метод используется для получения данных из универсального кода ресурса (URI), который, вероятно, является наиболее используемым методом HTTP.This method is used to retrieve data from a URI, and it probably the most-used HTTP method.
HEADHEAD Этот метод во многом аналогичен методу GET, за исключением того, что он фактически не извлекает данные из URI запроса. он просто извлекает состояние HTTP.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). РАЗМЕЩЕНИЕ часто используется для отправки данных JSON или XML в приложения веб-API.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 Этот метод обычно используется для получения списка методов HTTP, которые поддерживаются для URI.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.
PROPPATCH PROPFINDPROPFIND 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 ОК , а метод размещения может получить ответ, созданный 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 405Example HTTP 405 error

Следующий пример HTTP-запроса и ответа иллюстрирует ситуацию, когда клиент HTTP пытается разместить значение в веб-API на веб-сервере, а сервер возвращает ошибку 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-клиент отправил допустимый запрос JSON к URL-адресу для приложения Web API на сервере, но сервер вернул сообщение об ошибке HTTP 405, которое указывает на то, что метод размещения не разрешен для 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 405Resolve 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. config и Web. 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.

Следующий пример является выдержкой из файла ApplicationHost. config для сервера IIS, который ВОЗВРАЩАЛ ошибку HTTP 405 при использовании метода размещения для отправки данных в приложение веб-API.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, для которых он настроен — последняя запись в списке является статическим обработчиком содержимого, который является обработчиком по умолчанию, который используется после того, как другие обработчики имели Чанк д для проверки запроса: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 и обработчик URL-адресов без расширений для ASP.NET (который используется для веб-API) четко определены для отдельных списков методов 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. Обратите внимание, что обработчик DLL ISAPI настроен для всех методов 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.

В предыдущем примере обработчик DLL ISAPI не является проблемой. на самом деле, проблема не была определена в файле ApplicationHost. config для сервера IIS — проблема была вызвана записью, которая была создана в файле Web. config при создании приложения веб-API в Visual Studio.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>

В этом отрывке обработчик URL-адресов без расширений для ASP.NET переопределен для включения дополнительных методов HTTP, которые будут использоваться с приложением веб-API.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. В этом конкретном случае обработчик WebDAV определяется и загружается службами IIS, даже если для веб-сайта, включающего приложение веб-API, отключен протокол WebDAV.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-размещения IIS вызывает модуль WebDAV, так как он определен для команды размещения.During the processing of an HTTP PUT request, IIS calls the WebDAV module since it is defined for the PUT verb. При вызове модуля WebDAV проверяет его конфигурацию и видит, что он отключен, поэтому он возвращает ошибку "метод HTTP 405 не разрешен " для любого запроса, напоминающего запрос WebDAV.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. Чтобы устранить эту проблему, следует удалить WebDAV из списка модулей HTTP для веб-сайта, на котором определено приложение веб-API.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 или более поздней версии для разработки приложения веб-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 намеренно заносятся в комментарий, поэтому модуль WebDAV никогда не загружается на IIS Express, если только вы специально не измените конфигурацию IIS Express параметры для добавления функции WebDAV к установке IIS Express.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 501HTTP 501 errors

  • Указывает, что на сервере не реализована конкретная функциональность.Indicates the specific functionality has not been implemented on the server.
  • Обычно это означает, что в параметрах IIS не определен обработчик, который соответствует HTTP-запросу: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
    • Что-то изменило параметры IIS, так что не определены обработчики, поддерживающие конкретный метод HTTP.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.