Compartilhar via

Solucionar problemas de aplicativos da API Web2 que funcionam no Visual Studio e falham em um servidor IIS de produção

  • Artigo

Este documento explica como solucionar problemas de aplicativos da API Web2 implantados em um servidor IIS de produção. Ele aborda erros comuns de HTTP 405 e 501.

Software usado neste tutorial

Os aplicativos de API Web normalmente usam vários verbos HTTP: GET, POST, PUT, DELETE e, às vezes, PATCH. Dito isto, os desenvolvedores podem encontrar situações em que esses verbos são implementados por outro módulo do IIS em seu servidor IIS de produção, o que leva a uma situação em que um controlador de API Web que funciona corretamente no Visual Studio ou em um servidor de desenvolvimento retornará um erro HTTP 405 quando ele for implantado em um servidor IIS de produção.

O que causa erros HTTP 405

A primeira etapa para aprender a solucionar problemas de erros HTTP 405 é entender o que realmente significa um erro HTTP 405. O principal documento de controle para HTTP é RFC 2616, que define o código http 405 status como Método Não Permitido e descreve ainda mais esse código status como uma situação em que "o método especificado no Request-Line não é permitido para o recurso identificado pelo Request-URI". Em outras palavras, o verbo HTTP não é permitido para a URL específica solicitada por um cliente HTTP.

Como uma breve revisão, aqui estão vários dos métodos HTTP mais usados, conforme definido em RFC 2616, RFC 4918 e RFC 5789:

Método HTTP Descrição
GET Esse método é usado para recuperar dados de um URI e, provavelmente, o método HTTP mais usado.
HEAD Esse método é muito parecido com o método GET, exceto que ele não recupera os dados do URI de solicitação – ele simplesmente recupera o status HTTP.
POST Esse método normalmente é usado para enviar novos dados para o URI; POST geralmente é usado para enviar dados de formulário.
PUT Esse método normalmente é usado para enviar dados brutos para o URI; PUT geralmente é usado para enviar dados JSON ou XML para aplicativos de API Web.
DELETE Esse método é usado para remover dados de um URI.
OPTIONS Esse método normalmente é usado para recuperar a lista de métodos HTTP com suporte para um URI.
COPIAR MOVIMENTAÇÃO Esses dois métodos são usados com WebDAV e sua finalidade é autoexplicativa.
MKCOL Esse método é usado com WebDAV e é usado para criar uma coleção (por exemplo, um diretório) no URI especificado.
PROPFIND PROPPATCH Esses dois métodos são usados com WebDAV e são usados para consultar ou definir propriedades para um URI.
LOCK UNLOCK Esses dois métodos são usados com WebDAV e são usados para bloquear/desbloquear o recurso identificado pelo URI de solicitação ao criar.
PATCH Esse método é usado para modificar um recurso HTTP existente.

Quando um desses métodos HTTP estiver configurado para uso no servidor, o servidor responderá com o status HTTP e outros dados apropriados para a solicitação. (Por exemplo, um método GET pode receber uma resposta HTTP 200 OK e um método PUT pode receber uma resposta HTTP 201 Created .)

Se o método HTTP não estiver configurado para uso no servidor, o servidor responderá com um erro HTTP 501 Não Implementado .

No entanto, quando um método HTTP estiver configurado para uso no servidor, mas ele tiver sido desabilitado para um determinado URI, o servidor responderá com um erro de Método HTTP 405 Não Permitido .

Exemplo de erro HTTP 405

O exemplo de solicitação e resposta HTTP a seguir ilustra uma situação em que um cliente HTTP está tentando colocar o valor em um aplicativo de API Web em um servidor Web e o servidor retorna um erro HTTP que afirma que o método PUT não é permitido:

Solicitação HTTP:

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

"Some Value"

Resposta HTTP:

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'."}

Neste exemplo, o cliente HTTP enviou uma solicitação JSON válida para a URL de um aplicativo de API Web em um servidor Web, mas o servidor retornou uma mensagem de erro HTTP 405 que indica que o método PUT não era permitido para a URL. Por outro lado, se o URI de solicitação não corresponder a uma rota para o aplicativo de API Web, o servidor retornará um erro HTTP 404 Não Encontrado .

Resolver erros HTTP 405

Há vários motivos pelos quais um verbo HTTP específico pode não ser permitido, mas há um cenário primário que é a principal causa desse erro no IIS: vários manipuladores são definidos para o mesmo verbo/método e um dos manipuladores está bloqueando o manipulador esperado de processar a solicitação. Por meio de explicação, o IIS processa manipuladores do primeiro ao último com base nas entradas do manipulador de pedidos nos arquivos applicationHost.config e web.config , em que a primeira combinação correspondente de caminho, verbo, recurso etc., será usada para lidar com a solicitação.

O exemplo a seguir é um trecho de um arquivo applicationHost.config para um servidor IIS que retornava um erro HTTP 405 ao usar o método PUT para enviar dados a um aplicativo de API Web. Neste trecho, vários manipuladores HTTP são definidos e cada manipulador tem um conjunto diferente de métodos HTTP para os quais ele está configurado – a última entrada na lista é o manipulador de conteúdo estático, que é o manipulador padrão usado após os outros manipuladores terem tido a chance de examinar a solicitação:

<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>

No exemplo anterior, o manipulador WebDAV e o Manipulador de URL sem extensão para ASP.NET (que é usado para API Web) são claramente definidos para listas separadas de métodos HTTP. Observe que o manipulador de DLL ISAPI está configurado para todos os métodos HTTP, embora essa configuração não necessariamente cause um erro. No entanto, configurações como essa precisam ser consideradas ao solucionar problemas de erros HTTP 405.

No exemplo anterior, o manipulador de DLL ISAPI não era o problema; na verdade, o problema não foi definido no arquivo applicationHost.config para o servidor IIS – o problema foi causado por uma entrada que foi feita no arquivo web.config quando o aplicativo de API Web foi criado no Visual Studio. O seguinte trecho do arquivo web.config do aplicativo mostra o local do problema:

<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>

Neste trecho, o Manipulador de URL sem extensão para ASP.NET é redefinido para incluir métodos HTTP adicionais que serão usados com o aplicativo de API Web. No entanto, como um conjunto semelhante de métodos HTTP é definido para o manipulador WebDAV, ocorre um conflito. Nesse caso específico, o manipulador WebDAV é definido e carregado pelo IIS, embora o WebDAV esteja desabilitado para o site que inclui o aplicativo de API Web. Durante o processamento de uma solicitação HTTP PUT, o IIS chama o módulo WebDAV, pois ele é definido para o verbo PUT. Quando o módulo WebDAV é chamado, ele verifica sua configuração e vê que ele está desabilitado, portanto, retornará um erro de Método HTTP 405 Não Permitido para qualquer solicitação semelhante a uma solicitação WebDAV. Para resolve esse problema, você deve remover o WebDAV da lista de módulos HTTP para o site em que seu aplicativo de API Web está definido. O exemplo a seguir mostra como isso pode ser:

<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>

Esse cenário geralmente é encontrado depois que um aplicativo é publicado de um ambiente de desenvolvimento para um ambiente de produção do IIS, e isso ocorre porque a lista de manipuladores/módulos é diferente entre seus ambientes de desenvolvimento e produção. Por exemplo, se você estiver usando o Visual Studio 2012 ou posterior para desenvolver um aplicativo de API Web, IIS Express será o servidor Web padrão para teste. Esse servidor Web de desenvolvimento é uma versão horizontal da funcionalidade completa do IIS que é fornecida em um produto de servidor e esse servidor Web de desenvolvimento contém algumas alterações que foram adicionadas para cenários de desenvolvimento. Por exemplo, o módulo WebDAV geralmente é instalado em um servidor Web de produção que está executando a versão completa do IIS, embora ele possa não estar em uso. A versão de desenvolvimento do IIS ,(IIS Express), instala o módulo WebDAV, mas as entradas do módulo WebDAV são intencionalmente comentadas, portanto, o módulo WebDAV nunca é carregado em IIS Express a menos que você altere especificamente suas configurações de IIS Express para adicionar a funcionalidade WebDAV à instalação do IIS Express. Como resultado, seu aplicativo Web pode funcionar corretamente em seu computador de desenvolvimento, mas você pode encontrar erros HTTP 405 ao publicar seu aplicativo de API Web no servidor Web do IIS de produção.

Erros HTTP 501

  • Indica que a funcionalidade específica não foi implementada no servidor.
  • Normalmente significa que não há nenhum manipulador definido nas configurações do IIS que corresponda à solicitação HTTP:
    • Provavelmente indica que algo não foi instalado corretamente no IIS ou
    • Algo modificou as configurações do IIS para que não haja manipuladores definidos que dão suporte ao método HTTP específico.

Para resolve esse problema, você precisaria reinstalar qualquer aplicativo que esteja tentando usar um método HTTP para o qual ele não tenha definições de módulo ou manipulador correspondentes.

Resumo

Erros HTTP 405 são causados quando um método HTTP não é permitido por um servidor Web para uma URL solicitada. Essa condição geralmente é vista quando um manipulador específico é definido para um verbo específico e esse manipulador está substituindo o manipulador que você espera processar a solicitação.