Risolvere i problemi relativi alle app Web API2 che funzionano in Visual Studio e non riescono in un server IIS di produzione

  • Articolo

Questo documento illustra come risolvere i problemi relativi alle app API Web2 distribuite in un server IIS di produzione. Risolve gli errori HTTP 405 e 501 comuni.

Software usato in questa esercitazione

Le app per le API Web usano in genere diversi verbi HTTP: GET, POST, PUT, DELETE e talvolta PATCH. Detto questo, gli sviluppatori possono riscontrare situazioni in cui tali verbi vengono implementati da un altro modulo IIS nel server IIS di produzione, che comporta una situazione in cui un controller API Web che funziona correttamente in Visual Studio o in un server di sviluppo restituirà un errore HTTP 405 quando viene distribuito in un server IIS di produzione.

Che causa errori HTTP 405

Il primo passaggio per imparare a risolvere gli errori HTTP 405 consiste nel comprendere cosa significa effettivamente un errore HTTP 405. Il documento di governance primario per HTTP è RFC 2616, che definisce il codice di stato HTTP 405 come metodo non consentito e descrive ulteriormente questo codice di stato come situazione in cui "il metodo specificato nel Request-Line non è consentito per la risorsa identificata dall'URI richiesta". In altre parole, il verbo HTTP non è consentito per l'URL specifico richiesto da un client HTTP.

Come breve revisione, ecco alcuni dei metodi HTTP più usati come definito in RFC 2616, RFC 4918 e RFC 5789:

Metodo HTTP Descrizione
GET Questo metodo viene usato per recuperare i dati da un URI e probabilmente il metodo HTTP più usato.
HEAD Questo metodo è molto simile al metodo GET, ad eccezione del fatto che non recupera effettivamente i dati dall'URI della richiesta. Recupera semplicemente lo stato HTTP.
POST Questo metodo viene in genere usato per inviare nuovi dati all'URI; POST viene spesso usato per inviare i dati del modulo.
PUT Questo metodo viene in genere usato per inviare dati non elaborati all'URI; PUT viene spesso usato per inviare dati JSON o XML alle applicazioni API Web.
DELETE Questo metodo viene usato per rimuovere i dati da un URI.
OPTIONS Questo metodo viene in genere usato per recuperare l'elenco di metodi HTTP supportati per un URI.
COPIA SPOSTAMENTO Questi due metodi vengono usati con WebDAV e il loro scopo è auto-esplicativo.
MKCOL Questo metodo viene usato con WebDAV e viene usato per creare una raccolta (ad esempio una directory) all'URI specificato.
PROPFIND PROPPATCH Questi due metodi vengono usati con WebDAV e vengono usati per eseguire query o impostare proprietà per un URI.
BLOCCO SBLOCCA Questi due metodi vengono usati con WebDAV e vengono usati per bloccare/sbloccare la risorsa identificata dall'URI della richiesta durante la creazione.
PATCH Questo metodo viene usato per modificare una risorsa HTTP esistente.

Quando uno di questi metodi HTTP è configurato per l'uso nel server, il server risponderà con lo stato HTTP e altri dati appropriati per la richiesta. Ad esempio, un metodo GET potrebbe ricevere una risposta HTTP 200 OK e un metodo PUT potrebbe ricevere una risposta HTTP 201 Creata .

Se il metodo HTTP non è configurato per l'uso nel server, il server risponderà con un errore HTTP 501 Non implementato .

Tuttavia, quando un metodo HTTP è configurato per l'uso nel server, ma è stato disabilitato per un determinato URI, il server risponderà con un errore HTTP 405 Non consentito .

Esempio di errore HTTP 405

Nell'esempio seguente la richiesta HTTP e la risposta illustrano una situazione in cui un client HTTP sta tentando di inserire valore in un'app API Web in un server Web e il server restituisce un errore HTTP che indica che il metodo PUT non è consentito:

Richiesta HTTP:

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

"Some Value"

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

In questo esempio, il client HTTP ha inviato una richiesta JSON valida all'URL per un'applicazione API Web in un server Web, ma il server ha restituito un messaggio di errore HTTP 405 che indica che il metodo PUT non è stato consentito per l'URL. Al contrario, se l'URI della richiesta non corrisponde a una route per l'applicazione API Web, il server restituirà un errore HTTP 404 Not Found .

Risolvere gli errori HTTP 405

Esistono diversi motivi per cui un verbo HTTP specifico potrebbe non essere consentito, ma esiste uno scenario primario che rappresenta la causa principale di questo errore in IIS: più gestori sono definiti per lo stesso verbo/metodo e uno dei gestori blocca il gestore previsto dall'elaborazione della richiesta. In base alla spiegazione, IIS elabora i gestori dall'ultimo all'ultimo in base alle voci del gestore dell'ordine nei file applicationHost.config e web.config , in cui la prima combinazione corrispondente di percorso, verbo, risorsa e così via, verrà usata per gestire la richiesta.

L'esempio seguente è un estratto da un file diapplicationHost.config per un server IIS che restituisce un errore HTTP 405 quando si usa il metodo PUT per inviare dati a un'applicazione API Web. In questo estratto vengono definiti diversi gestori HTTP e ogni gestore ha un set diverso di metodi HTTP per i quali è configurata: l'ultima voce nell'elenco è il gestore contenuto statico, che è il gestore predefinito usato dopo che gli altri gestori hanno avuto la possibilità di esaminare la richiesta:

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

Nell'esempio precedente, il gestore WebDAV e il gestore URL meno estensione per ASP.NET (che viene usato per l'API Web) sono chiaramente definiti per elenchi separati di metodi HTTP. Si noti che il gestore DLL ISAPI è configurato per tutti i metodi HTTP, anche se questa configurazione non causerà necessariamente un errore. Tuttavia, le impostazioni di configurazione come questa devono essere considerate durante la risoluzione degli errori HTTP 405.

Nell'esempio precedente il gestore DLL ISAPI non è stato il problema; in effetti, il problema non è stato definito nel file applicationHost.configper il server IIS: il problema è stato causato da una voce eseguita nel file web.config quando l'applicazione API Web è stata creata in Visual Studio. L'estratto seguente del file diweb.config dell'applicazione mostra il percorso del 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>

In questo estratto, il gestore URL meno estensione per ASP.NET viene ridefinito per includere altri metodi HTTP che verranno usati con l'applicazione API Web. Tuttavia, poiché un set simile di metodi HTTP è definito per il gestore WebDAV, si verifica un conflitto. In questo caso specifico, il gestore WebDAV viene definito e caricato da IIS, anche se WebDAV è disabilitato per il sito Web che include l'applicazione API Web. Durante l'elaborazione di una richiesta HTTP PUT, IIS chiama il modulo WebDAV poiché è definito per il verbo PUT. Quando viene chiamato il modulo WebDAV, controlla la relativa configurazione e vede che è disabilitato, quindi restituirà un errore HTTP 405 Non consentito per qualsiasi richiesta simile a una richiesta WebDAV. Per risolvere questo problema, è necessario rimuovere WebDAV dall'elenco dei moduli HTTP per il sito Web in cui è definita l'applicazione API Web. Nell'esempio seguente viene illustrato l'aspetto simile al seguente:

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

Questo scenario viene spesso rilevato dopo la pubblicazione di un'applicazione da un ambiente di sviluppo a un ambiente di produzione IIS e si verifica perché l'elenco di gestori/moduli è diverso tra gli ambienti di sviluppo e di produzione. Ad esempio, se si usa Visual Studio 2012 o versione successiva per sviluppare un'applicazione API Web, IIS Express è il server Web predefinito per il test. Questo server Web di sviluppo è una versione ridotta della funzionalità IIS completa fornita in un prodotto server e questo server Web di sviluppo contiene alcune modifiche aggiunte per gli scenari di sviluppo. Ad esempio, il modulo WebDAV viene spesso installato in un server Web di produzione che esegue la versione completa di IIS, anche se potrebbe non essere in uso. La versione di sviluppo di IIS, (IIS Express), installa il modulo WebDAV, ma le voci per il modulo WebDAV vengono intenzionalmente commentate, quindi il modulo WebDAV non viene mai caricato in IIS Express a meno che non si modificano in modo specifico le impostazioni di configurazione IIS Express per aggiungere funzionalità WebDAV all'installazione di IIS Express. Di conseguenza, l'applicazione Web può funzionare correttamente nel computer di sviluppo, ma potrebbero verificarsi errori HTTP 405 quando si pubblica l'applicazione API Web nel server Web IIS di produzione.

Errori HTTP 501

  • Indica che la funzionalità specifica non è stata implementata nel server.
  • In genere, non esiste alcun gestore definito nelle impostazioni IIS che corrisponde alla richiesta HTTP:
    • Probabilmente indica che un elemento non è stato installato correttamente in IIS o
    • Le impostazioni IIS sono state modificate in modo che non siano presenti gestori definiti che supportano il metodo HTTP specifico.

Per risolvere il problema, è necessario reinstallare qualsiasi applicazione che tenta di usare un metodo HTTP per cui non ha definizioni di modulo o gestore corrispondenti.

Riepilogo

Gli errori HTTP 405 vengono causati quando un metodo HTTP non è consentito da un server Web per un URL richiesto. Questa condizione viene spesso vista quando un determinato gestore è stato definito per un verbo specifico e tale gestore esegue l'override del gestore che si prevede di elaborare la richiesta.