Condividi tramite


Errori <HTTP httpErrors>

Panoramica

L'elemento <httpErrors> consente di configurare messaggi di errore personalizzati per il sito Web o l'applicazione. I messaggi di errore personalizzati consentono di fornire una risposta descrittiva o più informativa inviando un file, restituendo un'altra risorsa o reindirizzando l'utente a un URL quando i visitatori del sito non riescono ad accedere al contenuto richiesto. È possibile ad esempio personalizzare le pagine dei messaggi di errore del sito Web in modo da avere lo stesso aspetto del resto del sito.

L'elemento <httpErrors> contiene una raccolta di <error> elementi, ognuno dei quali definisce un messaggio di errore usato da IIS per rispondere a errori HTTP specifici. È possibile aggiungere messaggi di errore personalizzati a IIS aggiungendo un <error> elemento all'elemento nel file di Web.config per il sito, l'applicazione o l'URL <httpErrors> . Ogni <error> elemento usa l'attributo responseMode per specificare se IIS gestisce contenuto statico, contenuto dinamico o reindirizza a un URL separato in risposta a un errore.

È possibile utilizzare l'elemento <remove> per rimuovere un messaggio di errore specifico dalla raccolta di messaggi di errore ereditati dal sito o dall'applicazione da un livello superiore nella gerarchia di configurazione iis. È anche possibile usare l'elemento <clear> per rimuovere tutti i messaggi di errore HTTP dalla raccolta di messaggi di errore HTTP ereditati dal sito o dall'applicazione.

L'elemento <httpErrors> contiene anche attributi che configurano IIS 7 per elaborare le richieste che causano errori. L'attributo existingResponse definisce le operazioni che IIS 7 esegue a una risposta esistente quando il server restituisce un codice di stato di errore HTTP. L'attributo defaultPath definisce il percorso di una pagina di errore del cliente se si sceglie File per l'attributo responseMode in un <error> elemento.

L'attributo detailedMoreInformationLink specifica un collegamento a ulteriori informazioni su un errore specifico.

L'elemento <httpErrors> può anche contenere un attributo errorMode che è possibile usare per controllare il livello di dettaglio restituito da IIS a un browser quando si verifica un errore HTTP. È possibile impostare l'attributo errorMode su DetailedLocalOnly, ovvero l'impostazione predefinita oppure impostarlo su Personalizzato o Dettagliato. Se si specifica DetailedLocalOnly o se non si specifica un valore errorMode, IIS restituisce informazioni dettagliate sull'errore solo al browser nel server locale e un messaggio di errore personalizzato a un browser in un computer esterno. Se si imposta il valore errorMode su Personalizzato, IIS restituisce solo messaggi di errore personalizzati a tutti i browser che richiedono. Se si imposta il valore errorMode su Detailed, IIS restituisce informazioni dettagliate sull'errore a tutti i browser che richiedono. Il valore predefinito DetailedLocalOnly consente di risolvere gli errori HTTP nel server locale senza esporre informazioni riservate a browser esterni.

Per impostazione predefinita, IIS gestisce i messaggi di errore definiti nei file archiviati nella cartella %SystemRoot%\Help\IisHelp\Common. È possibile creare un messaggio di errore personalizzato per gli utenti e configurare IIS per restituire questa pagina ogni volta che si verifica un errore HTTP specifico nel sito.

Compatibilità

Versione Note
IIS 10.0 L'elemento <httpErrors> non è stato modificato in IIS 10.0.
IIS 8,5 L'elemento <httpErrors> non è stato modificato in IIS 8.5.
IIS 8,0 L'elemento <httpErrors> non è stato modificato in IIS 8.0.
IIS 7,5 L'attributo allowAbsolutePathsWhenDelegated è stato aggiunto all'elemento <httpErrors> in IIS 7.5
IIS 7.0 L'elemento <httpErrors> è stato introdotto in IIS 7.0.
IIS 6.0 L'elemento <httpErrors> sostituisce la proprietà HttpErrors di IIS 6.0 dell'oggetto metabase IIsWebService .

Installazione

L'elemento <httpErrors> è incluso nell'installazione predefinita di IIS 7.

Procedure

Come aggiungere una pagina di errore personalizzata

  1. Aprire Gestione Internet Information Services (IIS):

    • Se si usa Windows Server 2012 o Windows Server 2012 R2:

      • Sulla barra delle applicazioni fare clic su Server Manager, scegliere Strumenti, quindi fare clic su Gestione Internet Information Services (IIS).
    • Se si usa Windows 8 o Windows 8.1:

      • Tenere premuto il tasto Windows, premere la lettera X e quindi fare clic su Pannello di controllo.
      • Fare clic su Strumenti di amministrazione, quindi fare doppio clic su Gestione Internet Information Services (IIS).
    • Se si usa Windows Server 2008 o Windows Server 2008 R2:

      • Sulla barra delle applicazioni fare clic su Start, scegliere Strumenti di amministrazione, quindi fare clic su Gestione Internet Information Services (IIS).
    • Se si usa Windows Vista o Windows 7:

      • Sulla barra delle applicazioni fare clic su Start e quindi su Pannello di controllo.
      • Fare doppio clic su Strumenti di amministrazione, quindi fare doppio clic su Gestione Internet Information Services (IIS).
  2. Nel riquadro Connessioni espandere il nome del server, espandere Siti e quindi passare al sito Web o all'applicazione per cui si desidera configurare pagine di errore personalizzate.

  3. Nel riquadro Home fare doppio clic su Pagine di errore.
    Screenshot che mostra il doppio clic su Pagine di errore.

  4. Nel riquadro Azioni fare clic su Aggiungi...

  5. Nella finestra di dialogo Aggiungi pagina errore personalizzata digitare il numero del codice di stato HTTP per il quale si desidera creare un messaggio di errore personalizzato.
    Screenshot che mostra la pagina Aggiungi errore personalizzato.

  6. Nella sezione Azione di risposta eseguire una delle operazioni seguenti:

    • Selezionare Inserisci contenuto dal file statico nella risposta di errore per gestire il contenuto statico, ad esempio un file di .html, per l'errore personalizzato.
    • Selezionare Execute a URL on this site (Esegui un URL in questo sito ) per gestire il contenuto dinamico, ad esempio un file asp per l'errore personalizzato.
    • Selezionare Rispondi con un reindirizzamento 302 per reindirizzare i browser client a un URL diverso che contiene il file di errore personalizzato.
  7. Nella casella di testo Percorso file digitare il percorso della pagina di errore personalizzata se si sceglie Inserisci contenuto da un file statico nella risposta di errore o nell'URL della pagina di errore personalizzata se si utilizza l'opzione Esegui un URL in questo sito o Rispondi con un reindirizzamento 302 e quindi fare clic su OK.

    Nota

    Se si seleziona Esegui un URL in questo sito, il percorso deve essere un percorso relativo. Se si seleziona Rispondi con un reindirizzamento 302, l'URL deve essere un URL assoluto.

Configurazione

È possibile configurare l'elemento <httpErrors> a livello di server nel file ApplicationHost.config e a livello di sito e applicazione nel file di Web.config appropriato.

Attributi

Attributo Descrizione
allowAbsolutePathsWhenDelegated Attributo booleano facoltativo.

Se impostato su true, i percorsi assoluti sono consentiti per le pagine di errore personalizzate quando la <httpErrors> sezione viene delegata. Se impostato su false, sono consentiti solo i percorsi relativi alla radice del sito.

Il valore predefinito è false.
defaultPath Attributo stringa facoltativo.

Specifica il percorso predefinito della pagina di errore personalizzata. Il tipo di percorso è determinato dall'attributo defaultResponseMode . Se si sceglie File, viene restituito il percorso del file. Se si sceglie il tipo di percorso ExecuteURL o Reindirizzamento , viene restituito l'URL della pagina di errore personalizzata.
defaultResponseMode Attributo di enumerazione facoltativo.

Specifica la modalità di restituzione del contenuto dell'errore personalizzato.

L'attributo defaultResponseMode può essere uno dei valori possibili seguenti; il valore predefinito è File.
Valore Descrizione
File Serve contenuto statico, ad esempio un file di .html per l'errore personalizzato. Se responseMode è impostato su File, il valore del percorso deve essere un percorso di file.

Il valore numerico è 0.
ExecuteURL Gestisce il contenuto dinamico, ad esempio un file asp per l'errore personalizzato. Se responseMode è impostato su ExecuteURL, il valore del percorso deve essere un URL relativo al server.

Il valore numerico è 1.
Redirect Reindirizza i browser client a un URL diverso che contiene il file di errore personalizzato. Se responseMode è impostato su Reindirizzamento, il valore del percorso deve essere un URL assoluto.

Il valore numerico è 2.
detailedMoreInformationLink Attributo stringa facoltativo.

Specifica un collegamento, visualizzato nella parte inferiore della pagina, in una pagina con informazioni più dettagliate su un errore specifico. È possibile utilizzare questa proprietà per indirizzare gli utenti finali a un percorso personalizzato per informazioni sugli errori. Lo stato, lo stato secondario, HRESULT e l'ID del messaggio vengono inviati come parte della stringa di query.

Il valore predefinito è https://go.microsoft.com/fwlink/?LinkID=62293.
errorMode Attributo di enumerazione facoltativo.

Specifica se gli errori HTTP sono abilitati.

L'attributo errorMode può essere uno dei valori seguenti; il valore predefinito è DetailedLocalOnly.
Valore Descrizione
DetailedLocalOnly Restituisce informazioni dettagliate sull'errore se la richiesta proviene dal computer locale e restituisce un messaggio di errore personalizzato se la richiesta proviene da un computer esterno.

Il valore numerico è 0.
Custom Sostituisce l'errore generato dal modulo o dal server con una pagina personalizzata specificata. Questa modalità è utile per fornire messaggi di errore più descrittivi agli utenti finali.

Nota: questa impostazione disattiva gli errori dettagliati, anche per le richieste locali.

Il valore numerico è 1.
Detailed Invia informazioni dettagliate sull'errore al client. Questa modalità è utile per il test e il debug di siti Web e applicazioni.

Il valore numerico è 2.
existingResponse Attributo di enumerazione facoltativo.

Specifica cosa accade a una risposta esistente quando il codice di stato HTTP è un errore, ad esempio i codici >di risposta = 400.

L'attributo existingResponse può essere uno dei valori seguenti; il valore predefinito è Auto.
Valore Descrizione
Auto Lascia invariata la risposta solo se è impostato il flag SetStatus .

Il valore numerico è 0.
Replace Sostituisce la risposta esistente anche se è impostato il flag SetStatus .

Il valore numerico è 1.
PassThrough Lascia invariata la risposta se esiste una risposta esistente.

Il valore numerico è 2.

Elementi figlio

Elemento Descrizione
error Elemento facoltativo.

Aggiunge un errore HTTP alla raccolta di errori HTTP.
remove Elemento facoltativo.

Rimuove un riferimento a un errore HTTP dalla raccolta di errori HTTP.
clear Elemento facoltativo.

Rimuove tutti i riferimenti agli errori HTTP dalla raccolta di errori HTTP.

Esempio di configurazione

Nell'esempio di configurazione seguente, se incluso nel file di Web.config per un sito Web o un'applicazione, viene utilizzato l'attributo errorMode per consentire solo la visualizzazione di messaggi di errore dettagliati nel computer locale. Usa anche l'attributo defaultResponseMode per impostare la modalità di risposta per il sito o l'applicazione. L'esempio rimuove quindi il messaggio di errore ereditato per il codice di stato 500. Imposta quindi l'attributo prefixLanguageFilePath sulla directory in cui IIS deve cercare una nuova pagina di errore personalizzata e imposta l'attributo path su 500.htm, il file che contiene il messaggio di errore personalizzato.

<configuration>
   <system.webServer>
      <httpErrors errorMode="DetailedLocalOnly" defaultResponseMode="File" >
         <remove statusCode="500" />
         <error statusCode="500"
            prefixLanguageFilePath="C:\Contoso\Content\errors"
            path="500.htm" />
       </httpErrors>
   </system.webServer>
</configuration>

Codice di esempio

Gli esempi seguenti aggiungono un nuovo file per tutti gli errori di codice di stato 404 con uno stato secondario pari a 5, che IIS restituisce per gli errori "URL Sequence Denied". In questi esempi il percorso del prefisso è impostato su "%SystemDrive%\inetpub\custerr" e il nome del file viene specificato come "404.5.htm".

AppCmd.exe

appcmd.exe set config -section:system.webServer/httpErrors /+"[statusCode='404',subStatusCode='5',prefixLanguageFilePath='%SystemDrive%\inetpub\custerr',path='404.5.htm']" /commit:apphost

Nota

È necessario assicurarsi di impostare il parametro commit su apphost quando si usa AppCmd.exe per configurare queste impostazioni. In questo modo le impostazioni di configurazione vengono confermate nella sezione relativa al percorso appropriato nel file ApplicationHost.config.

C#

using System;
using System.Text;
using Microsoft.Web.Administration;

internal static class Sample
{
   private static void Main()
   {
      using (ServerManager serverManager = new ServerManager())
      {
         Configuration config = serverManager.GetApplicationHostConfiguration();
         ConfigurationSection httpErrorsSection = config.GetSection("system.webServer/httpErrors");
         ConfigurationElementCollection httpErrorsCollection = httpErrorsSection.GetCollection();

         ConfigurationElement errorElement = httpErrorsCollection.CreateElement("error");
         errorElement["statusCode"] = 404;
         errorElement["subStatusCode"] = 5;
         errorElement["prefixLanguageFilePath"] = @"%SystemDrive%\inetpub\custerr";
         errorElement["path"] = @"404.5.htm";
         httpErrorsCollection.Add(errorElement);

         serverManager.CommitChanges();
      }
   }
}

VB.NET

Imports System
Imports System.Text
Imports Microsoft.Web.Administration

Module Sample
   Sub Main()
      Dim serverManager As ServerManager = New ServerManager
      Dim config As Configuration = serverManager.GetApplicationHostConfiguration
      Dim httpErrorsSection As ConfigurationSection = config.GetSection("system.webServer/httpErrors")
      Dim httpErrorsCollection As ConfigurationElementCollection = httpErrorsSection.GetCollection

      Dim errorElement As ConfigurationElement = httpErrorsCollection.CreateElement("error")
      errorElement("statusCode") = 404
      errorElement("subStatusCode") = 5
      errorElement("prefixLanguageFilePath") = "%SystemDrive%\inetpub\custerr"
      errorElement("path") = "404.5.htm"
      httpErrorsCollection.Add(errorElement)

      serverManager.CommitChanges()
   End Sub
End Module

JavaScript

var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST";
var httpErrorsSection = adminManager.GetAdminSection("system.webServer/httpErrors", "MACHINE/WEBROOT/APPHOST");
var httpErrorsCollection = httpErrorsSection.Collection;

var errorElement = httpErrorsCollection.CreateNewElement("error");
errorElement.Properties.Item("statusCode").Value = 404;
errorElement.Properties.Item("subStatusCode").Value = 5;
errorElement.Properties.Item("prefixLanguageFilePath").Value = "%SystemDrive%\\inetpub\\custerr";
errorElement.Properties.Item("path").Value = "404.5.htm";
httpErrorsCollection.AddElement(errorElement);

adminManager.CommitChanges();

VBScript

Set adminManager = createObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST"
Set httpErrorsSection = adminManager.GetAdminSection("system.webServer/httpErrors", "MACHINE/WEBROOT/APPHOST")
Set httpErrorsCollection = httpErrorsSection.Collection

Set errorElement = httpErrorsCollection.CreateNewElement("error")
errorElement.Properties.Item("statusCode").Value = 404
errorElement.Properties.Item("subStatusCode").Value = 5
errorElement.Properties.Item("prefixLanguageFilePath").Value = "%SystemDrive%\inetpub\custerr"
errorElement.Properties.Item("path").Value = "404.5.htm"
httpErrorsCollection.AddElement errorElement

adminManager.CommitChanges()