Solucionar problemas de aplicativos Web API2 que funcionam no Visual Studio e falham em um servidor IIS de produção

Este documento explica como solucionar problemas de aplicativos Web API2 que são 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 isso, os desenvolvedores podem se deparar com 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 da Web que funciona corretamente no Visual Studio ou em um servidor de desenvolvimento irá 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 erros de HTTP 405 é entender o que um erro HTTP 405 realmente significa. O documento principal de controle para HTTP é RFC 2616, que define o código de status http 405 como método não permitidoe descreve ainda mais esse código de status como uma situação em que "o método especificado na linha de solicitação não é permitido para o recurso identificado pelo URI da solicitação." em outras palavras, o verbo HTTP não é permitido para a URL específica que um cliente HTTP solicitou.

Como uma breve revisão, aqui estão vários dos métodos de 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 realmente os dados do URI de solicitação – ele simplesmente recupera o status HTTP.
POST Normalmente, esse método é usado para enviar novos dados para o URI; A POSTAgem é frequentemente usada 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 o WebDAV e sua finalidade é auto-explicativa.
MKCOL Esse método é usado com o WebDAV e é usado para criar uma coleção (por exemplo, um diretório) no URI especificado.
PROPPATCH PROPFIND Esses dois métodos são usados com o WebDAV e são usados para consultar ou definir propriedades para um URI.
DESBLOQUEAR BLOQUEIO Esses dois métodos são usados com o WebDAV e são usados para bloquear/desbloquear o recurso identificado pelo URI de solicitação durante a criação.
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 que são 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 criada .)

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 é configurado para uso no servidor, mas ele foi desabilitado para um determinado URI, o servidor responderá com um erro de método HTTP 405 não permitido .

Erro HTTP 405 de exemplo

O exemplo de solicitação e resposta HTTP a seguir ilustram uma situação em que um cliente HTTP está tentando colocar o valor em um aplicativo de API da Web em um servidor Web, e o servidor retorna um erro HTTP que declara 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 foi permitido para a URL. Por outro lado, se o URI de solicitação não coincidir com uma rota para o aplicativo de API Web, o servidor retornará um erro HTTP 404 não encontrado .

Resolver erros HTTP 405

Há várias razões pelas quais um verbo HTTP específico pode não ser permitido, mas há um cenário primário que é a causa principal desse erro no IIS: vários manipuladores são definidos para o mesmo verbo/método, e um dos manipuladores está impedindo o manipulador esperado do processamento da solicitação. Por meio de explicação, o IIS processa os manipuladores da primeira para a última 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 estava retornando um erro http 405 ao usar o método Put para enviar dados a um aplicativo de API da Web. Neste trecho, vários manipuladores HTTP são definidos, e cada manipulador tem um conjunto diferente de métodos HTTP para o qual está configurado-a última entrada na lista é o manipulador de conteúdo estático, que é o manipulador padrão que é usado depois que os outros manipuladores tinham um chanc e para 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 cause, necessariamente, um erro. No entanto, as definições de configuração como essa precisam ser consideradas ao solucionar erros de 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 da API Web foi criado no Visual Studio. O trecho a seguir 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 da 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 da Web. Durante o processamento de uma solicitação HTTP PUT, o IIS chama o módulo WebDAV, já que ele é definido para o verbo PUT. Quando o módulo WebDAV é chamado, ele verifica sua configuração e vê que está desabilitado, portanto, retornará um erro HTTP 405 sem permissão para qualquer solicitação que se assemelha a uma solicitação WebDAV. Para resolver esse problema, você deve remover o WebDAV da lista de módulos HTTP para o site em que seu aplicativo de API Web é 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 reduzida 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 talvez não esteja 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 no IIS Express, a menos que você altere especificamente sua configuração de IIS Express configurações para adicionar a funcionalidade WebDAV à sua instalação do IIS Express. Como resultado, seu aplicativo Web pode funcionar corretamente no 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 ofereçam suporte ao método HTTP específico.

Para resolver esse problema, você precisará reinstalar qualquer aplicativo que esteja tentando usar um método HTTP para o qual não tenha nenhuma definição de módulo ou manipulador correspondente.

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 foi definido para um verbo específico e esse manipulador está substituindo o manipulador que você espera processar a solicitação.