Résoudre les problèmes d’applications WEB API2 qui fonctionnent dans Visual Studio et échouent sur un serveur IIS de production
Ce document explique comment résoudre les problèmes liés aux applications WEB API2 déployées sur un serveur IIS de production. Il résout les erreurs HTTP 405 et 501 courantes.
Logiciel utilisé dans ce tutoriel
- Internet Information Services (IIS) (version 7 ou ultérieure)
- API Web
Les applications d’API web utilisent généralement plusieurs verbes HTTP : GET, POST, PUT, DELETE et parfois PATCH. Cela étant dit, les développeurs peuvent se trouver dans des situations où ces verbes sont implémentés par un autre module IIS sur leur serveur IIS de production, ce qui conduit à une situation où un contrôleur d’API web qui fonctionne correctement dans Visual Studio ou sur un serveur de développement retourne une erreur HTTP 405 lorsqu’il est déployé sur un serveur IIS de production.
Causes des erreurs HTTP 405
La première étape pour apprendre à résoudre les erreurs HTTP 405 consiste à comprendre ce que signifie réellement une erreur HTTP 405. Le principal document régissant HTTP est RFC 2616, qui définit le code http 405 status comme méthode non autorisée, et décrit plus en détail cette status code comme une situation où « la méthode spécifiée dans le Request-Line n’est pas autorisée pour la ressource identifiée par l’URI de requête ». En d’autres termes, le verbe HTTP n’est pas autorisé pour l’URL spécifique demandée par un client HTTP.
Voici quelques-unes des méthodes HTTP les plus utilisées telles que définies dans RFC 2616, RFC 4918 et RFC 5789 :
| Méthode HTTP | Description |
|---|---|
| GET | Cette méthode est utilisée pour récupérer des données à partir d’un URI, et probablement la méthode HTTP la plus utilisée. |
| HEAD | Cette méthode ressemble beaucoup à la méthode GET, sauf qu’elle ne récupère pas réellement les données à partir de l’URI de requête , elle récupère simplement le status HTTP. |
| POST | Cette méthode est généralement utilisée pour envoyer de nouvelles données à l’URI ; POST est souvent utilisé pour envoyer des données de formulaire. |
| PUT | Cette méthode est généralement utilisée pour envoyer des données brutes à l’URI ; PUT est souvent utilisé pour envoyer des données JSON ou XML aux applications d’API web. |
| DELETE | Cette méthode est utilisée pour supprimer des données d’un URI. |
| OPTIONS | Cette méthode est généralement utilisée pour récupérer la liste des méthodes HTTP prises en charge pour un URI. |
| COPIER LE DÉPLACEMENT | Ces deux méthodes sont utilisées avec WebDAV et leur objectif est explicite. |
| MKCOL | Cette méthode est utilisée avec WebDAV et elle est utilisée pour créer une collection (par exemple, un répertoire) à l’URI spécifié. |
| PROPFIND PROPPATCH | Ces deux méthodes sont utilisées avec WebDAV et sont utilisées pour interroger ou définir des propriétés pour un URI. |
| VERROUILLER LE DÉVERROUILLAGE | Ces deux méthodes sont utilisées avec WebDAV et sont utilisées pour verrouiller/déverrouiller la ressource identifiée par l’URI de requête lors de la création. |
| PATCH | Cette méthode est utilisée pour modifier une ressource HTTP existante. |
Quand l’une de ces méthodes HTTP est configurée pour être utilisée sur le serveur, le serveur répond avec le status HTTP et d’autres données appropriées pour la demande. (Par exemple, une méthode GET peut recevoir une réponse HTTP 200 OK , et une méthode PUT peut recevoir une réponse HTTP 201 Created .)
Si la méthode HTTP n’est pas configurée pour une utilisation sur le serveur, le serveur répond avec une erreur HTTP 501 Non implémentée .
Toutefois, lorsqu’une méthode HTTP est configurée pour une utilisation sur le serveur, mais qu’elle a été désactivée pour un URI donné, le serveur répond avec une erreur HTTP 405 Méthode non autorisée .
Exemple d’erreur HTTP 405
L’exemple de requête et de réponse HTTP suivant illustre une situation où un client HTTP tente d’obtenir une valeur PUT dans une application d’API web sur un serveur web et où le serveur retourne une erreur HTTP qui indique que la méthode PUT n’est pas autorisée :
Requête HTTP :
PUT /api/values/1 HTTP/1.1
Content-type: application/json
Host: localhost
Accept: */*
Content-Length: 12
"Some Value"
Réponse 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'."}
Dans cet exemple, le client HTTP a envoyé une requête JSON valide à l’URL d’une application d’API web sur un serveur web, mais le serveur a renvoyé un message d’erreur HTTP 405 qui indique que la méthode PUT n’était pas autorisée pour l’URL. En revanche, si l’URI de requête ne correspondait pas à un itinéraire pour l’application API web, le serveur retournerait une erreur HTTP 404 introuvable .
Résoudre les erreurs HTTP 405
Il existe plusieurs raisons pour lesquelles un verbe HTTP spécifique peut ne pas être autorisé, mais il existe un scénario principal qui est la cause principale de cette erreur dans IIS : plusieurs gestionnaires sont définis pour le même verbe/méthode, et l’un des gestionnaires empêche le gestionnaire attendu de traiter la requête. À titre d’explication, IIS traite les gestionnaires du premier au dernier en fonction des entrées du gestionnaire de commandes dans les fichiers applicationHost.config et web.config , où la première combinaison correspondante de chemin, de verbe, de ressource, etc., sera utilisée pour gérer la demande.
L’exemple suivant est un extrait d’un fichier applicationHost.config pour un serveur IIS qui renvoyait une erreur HTTP 405 lors de l’utilisation de la méthode PUT pour envoyer des données à une application d’API web. Dans cet extrait, plusieurs gestionnaires HTTP sont définis, et chaque gestionnaire a un ensemble différent de méthodes HTTP pour lesquelles il est configuré . La dernière entrée de la liste est le gestionnaire de contenu statique, qui est le gestionnaire par défaut qui est utilisé après que les autres gestionnaires ont eu la possibilité d’examiner la demande :
<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>
Dans l’exemple précédent, le gestionnaire WebDAV et le gestionnaire d’URL sans extension pour ASP.NET (utilisé pour l’API web) sont clairement définis pour des listes distinctes de méthodes HTTP. Notez que le gestionnaire DE DLL ISAPI est configuré pour toutes les méthodes HTTP, bien que cette configuration ne provoque pas nécessairement une erreur. Toutefois, des paramètres de configuration tels que celui-ci doivent être pris en compte lors de la résolution des erreurs HTTP 405.
Dans l’exemple précédent, le gestionnaire de DLL ISAPI n’était pas le problème ; en fait, le problème n’a pas été défini dans le fichier applicationHost.config pour le serveur IIS . Le problème a été provoqué par une entrée effectuée dans le fichierweb.configlors de la création de l’application API web dans Visual Studio. L’extrait suivant du fichier web.config de l’application montre l’emplacement du problème :
<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>
Dans cet extrait, le gestionnaire d’URL sans extension pour ASP.NET est redéfini pour inclure des méthodes HTTP supplémentaires qui seront utilisées avec l’application API web. Toutefois, étant donné qu’un ensemble similaire de méthodes HTTP est défini pour le gestionnaire WebDAV, un conflit se produit. Dans ce cas spécifique, le gestionnaire WebDAV est défini et chargé par IIS, même si WebDAV est désactivé pour le site web qui inclut l’application API web. Pendant le traitement d’une requête HTTP PUT, IIS appelle le module WebDAV, car il est défini pour le verbe PUT. Lorsque le module WebDAV est appelé, il vérifie sa configuration et voit qu’il est désactivé. Il retourne donc une erreur HTTP 405 Method Not Allowed pour toute requête qui ressemble à une requête WebDAV. Pour résoudre ce problème, vous devez supprimer WebDAV de la liste des modules HTTP pour le site web sur lequel votre application API web est définie. L’exemple suivant montre à quoi cela peut ressembler :
<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>
Ce scénario est souvent rencontré après la publication d’une application à partir d’un environnement de développement vers un environnement de production IIS, et cela se produit parce que la liste des gestionnaires/modules est différente entre vos environnements de développement et de production. Par exemple, si vous utilisez Visual Studio 2012 ou version ultérieure pour développer une application API web, IIS Express est le serveur web par défaut pour les tests. Ce serveur web de développement est une version scale-down de la fonctionnalité IIS complète fournie dans un produit serveur, et ce serveur web de développement contient quelques modifications qui ont été ajoutées pour les scénarios de développement. Par exemple, le module WebDAV est souvent installé sur un serveur web de production qui exécute la version complète d’IIS, même s’il n’est peut-être pas utilisé. La version de développement d’IIS (IIS Express), installe le module WebDAV, mais les entrées du module WebDAV sont intentionnellement commentées. Le module WebDAV n’est donc jamais chargé sur IIS Express, sauf si vous modifiez spécifiquement vos paramètres de configuration IIS Express pour ajouter des fonctionnalités WebDAV à votre installation IIS Express. Par conséquent, votre application web peut fonctionner correctement sur votre ordinateur de développement, mais vous pouvez rencontrer des erreurs HTTP 405 lorsque vous publiez votre application d’API web sur votre serveur web IIS de production.
Erreurs HTTP 501
- Indique que la fonctionnalité spécifique n’a pas été implémentée sur le serveur.
- En règle générale, aucun gestionnaire n’est défini dans vos paramètres IIS qui correspond à la requête HTTP :
- Indique probablement qu’un élément n’a pas été installé correctement sur IIS ou
- Quelque chose a modifié vos paramètres IIS afin qu’aucun gestionnaire ne soit défini qui prend en charge la méthode HTTP spécifique.
Pour résoudre ce problème, vous devez réinstaller toute application qui tente d’utiliser une méthode HTTP pour laquelle elle n’a aucune définition de module ou de gestionnaire correspondante.
Résumé
Les erreurs HTTP 405 sont provoquées lorsqu’une méthode HTTP n’est pas autorisée par un serveur web pour une URL demandée. Cette condition est souvent observée lorsqu’un gestionnaire particulier a été défini pour un verbe spécifique et que ce gestionnaire substitue le gestionnaire que vous prévoyez de traiter la demande.