Erreurs HTTP <httpErrors>

Article
03/25/2024

Vue d’ensemble

L’élément <httpErrors> vous permet de configurer des messages d’erreur personnalisés pour votre site web ou votre application. Grâce aux messages d’erreur personnalisés, vous pouvez fournir une réponse conviviale ou plus informative en proposant un fichier, en retournant une autre ressource ou en effectuant une redirection vers une autre URL lorsque les visiteurs de votre site n’ont pas accès au contenu demandé. Par exemple, vous pouvez personnaliser chacune des pages de messages d’erreur de votre site Web de sorte qu’elles présentent une apparence similaire au reste de votre site.

L’élément <httpErrors> contient une collection d’éléments <error>, chacun définissant un message d’erreur que IIS utilise pour répondre à des erreurs HTTP spécifiques. Vous pouvez ajouter des messages d’erreur personnalisés à IIS en ajoutant un élément <error> à l’élément <httpErrors> dans le fichier Web.config de votre site, application ou URL. Chaque élément <error> utilise l’attribut responseMode pour spécifier si IIS sert du contenu statique, du contenu dynamique ou redirige vers une URL distincte en réponse à une erreur.

Vous pouvez utiliser l’élément <remove> pour supprimer un message d’erreur spécifique de la collection de messages d’erreur que votre site ou votre application hérite d’un niveau supérieur dans la hiérarchie de configuration IIS. En outre, vous pouvez utiliser l’élément <clear> pour supprimer tous les messages d’erreur HTTP de la collection de messages d’erreur HTTP que votre site ou votre application hérite.

L’élément <httpErrors> contient également des attributs qui configurent IIS 7 pour traiter les requêtes qui provoquent des erreurs. L’attribut existingResponse définit ce que fait IIS 7 à une réponse existante lorsque le serveur retourne un code d’état d’erreur HTTP. L’attribut defaultPath définit le chemin d’accès à une page d’erreur client si vous choisissez de spécifier File pour l’attribut responseMode dans un élément <error>.

L’attribut detailedMoreInformationLink spécifie un lien vers plus d’informations sur une erreur particulière.

L’élément <httpErrors> peut également contenir un attribut errorMode que vous pouvez utiliser pour contrôler le niveau de détail que IIS retourne à un navigateur lorsqu’une erreur HTTP se produit. Vous pouvez définir l’attribut errorMode sur DetailedLocalOnly, qui est le paramètre par défaut, ou vous pouvez le définir sur Personnalisé ou Détaillé. Si vous spécifiez DetailedLocalOnlyou si vous ne spécifiez pas de valeur errorMode, IIS retourne des informations d’erreur détaillées uniquement sur le navigateur sur le serveur local et un message d’erreur personnalisé sur un navigateur sur un ordinateur externe. Si vous définissez la valeur errorMode sur Personnalisé, IIS retourne uniquement les messages d’erreur personnalisés à tous les navigateurs demandeurs. Si vous définissez la valeur errorMode sur Détaillé, IIS retourne des informations d’erreur détaillées à tous les navigateurs demandeurs. La valeur DetailedLocalOnly par défaut vous permet de résoudre les erreurs HTTP sur le serveur local tout en n’exposant pas d’informations sensibles aux navigateurs externes.

Par défaut, IIS traite les messages d’erreur définis dans les fichiers stockés dans le dossier %SystemRoot%\Help\IisHelp\Common. Vous pouvez créer un message d’erreur personnalisé pour les utilisateurs et configurer IIS pour qu’il retourne cette page chaque fois qu’il rencontre une erreur HTTP spécifique sur votre site.

Compatibilité

Version	Notes
IIS 10.0	L’élément `<httpErrors>` n’a pas été modifié dans IIS 10.0.
IIS 8.5	L’élément `<httpErrors>` n’a pas été modifié dans IIS 8.5.
IIS 8.0	L’élément `<httpErrors>` n’a pas été modifié dans IIS 8.0.
IIS 7.5	L’attribut `allowAbsolutePathsWhenDelegated` a été ajouté à l’élément `<httpErrors>` dans IIS 7.5.
IIS 7.0	L’élément `<httpErrors>` a été introduit dans IIS 7.0.
IIS 6.0	L’élément `<httpErrors>` remplace la propriétéHttpErrors IIS 6.0 de l’objet de métabase IIsWebService.

Programme d’installation

L’élément <httpErrors> est inclus dans l’installation par défaut d’IIS 7.

Procédure

Comment ajouter une page d’erreur personnalisée

Ouvrez le Gestionnaire des services Internet (IIS) :
- Si vous utilisez Windows Server 2012 ou Windows Server 2012 R2 :
  - Dans la barre des tâches, cliquez sur Gestionnaire de serveur, cliquez sur Outils, puis sur Gestionnaire Internet Information Services (IIS).
- Si vous utilisez Windows 8 ou Windows 8.1 :
  - Maintenez la touche Windows enfoncée, appuyez sur la lettre X, puis cliquez sur Panneau de configuration.
  - Cliquez sur Outils d’administration, puis double-cliquez sur Gestionnaire Internet Information Services (IIS).
- Si vous utilisez Windows Server 2008 ou Windows Server 2008 R2 :
  - Cliquez sur Démarrer, placez le curseur sur Outils d’administration, puis cliquez sur Gestionnaire Internet Information Services (IIS).
- Si vous utilisez Windows Vista ou Windows 7 :
  - Dans la barre des tâches, cliquez sur Démarrer, puis sur Panneau de configuration.
  - Double-cliquez sur Outils d’administration, puis double-cliquez sur Gestionnaire Internet Information Services (IIS).
Dans le volet Connexions, développez le nom du serveur, développez Sites, puis accédez au site Web ou à l’application pour lesquels vous souhaitez configurer des pages d’erreur customisées.
Dans la page Accueil, double-cliquez sur Pages d’erreur.
Dans le volet Actions, cliquer sur Ajouter….
Dans la boîte de dialogue Ajouter une page d’erreur personnalisée, sous Code d’état, tapez le numéro du code d’état HTTP pour lequel vous souhaitez créer un message d’erreur personnalisé.
Dans la section Action de réponse, effectuez l’une des opérations suivantes :
- Sélectionnez Insérer du contenu à partir d’un fichier statique dans la réponse d’erreur pour servir du contenu statique, par exemple, un fichier .html, pour l’erreur personnalisée.
- Sélectionnez Exécuter une URL sur ce site pour servir du contenu dynamique, par exemple, un fichier .asp pour l’erreur personnalisée.
- Sélectionnez Répondre avec une redirection 302 pour rediriger les navigateurs clients vers une autre URL qui contient le fichier d’erreur personnalisé.
Dans la zone de texte Chemin d’accès au fichier, tapez le chemin d’accès de la page d’erreur personnalisée si vous avez choisi Insérer du contenu à partir d’un fichier statique dans la réponse d’erreur ou l’URL de la page d’erreur personnalisée si vous utilisez Exécuter une URL sur ce site ou Répondre avec une redirection 302, puis cliquez sur OK.

Remarque

Si vous sélectionnez Exécuter une URL sur ce site, le chemin d’accès doit être un chemin d’accès relatif. Si vous sélectionnez Répondre avec une redirection 302, l’URL doit être une URL absolue.

Configuration

Vous pouvez configurer l’élément <httpErrors> au niveau du serveur dans le fichier ApplicationHost.config et au niveau du site et de l’application dans le fichier Web.config approprié.

Attributs

Attribut Description

allowAbsolutePathsWhenDelegated Attribut booléen facultatif.

Lorsque la valeur est true, les chemins d’accès absolus sont autorisés pour les pages d’erreur personnalisées lorsque la section <httpErrors> est déléguée. Lorsque la valeur est false, seuls les chemins d’accès relatifs à la racine du site sont autorisés.

La valeur par défaut est false.

defaultPath Attribut de chaîne facultatif.

Spécifie le chemin d’accès par défaut de la page d’erreur personnalisée. Le type de chemin d’accès est déterminé par l’attribut defaultResponseMode. Si vous choisissez Fichier, le chemin d’accès au fichier est retourné. Si vous choisissez le type de chemin d’accès ExecuteURL ou Redirect, l’URL de la page d’erreur personnalisée est retournée.

defaultResponseMode

Attribut enum facultatif.

Spécifie la façon dont le contenu d’erreur personnalisé est retourné.

L’attribut defaultResponseMode peut être l’une des valeurs possibles suivantes. La valeur par défaut est File.

Valeur	Description
`File`	Sert du contenu statique, par exemple, un fichier .html pour l’erreur personnalisée. Si responseMode est défini sur File, la valeur du chemin d’accès doit être un chemin d’accès de fichier. La valeur numérique est `0`.
`ExecuteURL`	Sert du contenu dynamique, par exemple, un fichier .asp pour l’erreur personnalisée. Si responseMode est défini sur ExecuteURL, la valeur du chemin d’accès doit être une URL relative de serveur. La valeur numérique est `1`.
`Redirect`	Redirige les navigateurs clients vers une autre URL qui contient le fichier d’erreur personnalisé. Si responseMode est défini sur Redirect, la valeur du chemin d’accès doit être une URL absolue. La valeur numérique est `2`.

detailedMoreInformationLink Attribut de chaîne facultatif.

Spécifie un lien, affiché en bas de la page, vers une page contenant des informations plus détaillées sur une erreur particulière. Vous pouvez utiliser cette propriété pour pointer les utilisateurs finaux vers un emplacement personnalisé pour les informations d’erreur. L’état, le sous-état, HRESULT et l’ID de message sont envoyés dans le cadre de la chaîne de requête.

La valeur par défaut est https://go.microsoft.com/fwlink/?LinkID=62293.

errorMode

Attribut enum facultatif.

Spécifie si les erreurs HTTP sont activées.

L’attribut errorMode peut être l’une des valeurs suivantes. La valeur par défaut est DetailedLocalOnly.

Valeur	Description
`DetailedLocalOnly`	Retourne des informations d’erreur détaillées si la requête provient de l’ordinateur local et retourne un message d’erreur personnalisé si la requête provient d’un ordinateur externe. La valeur numérique est `0`.
`Custom`	Remplace l’erreur générée par le module ou le serveur par une page personnalisée que vous spécifiez. Ce mode est utile pour fournir des messages d’erreur plus conviviaux aux utilisateurs finaux. Remarque : ce paramètre désactive les erreurs détaillées, même pour les demandes locales. La valeur numérique est `1`.
`Detailed`	Renvoie des informations d’erreur détaillées au client. Ce mode est utile pour tester et déboguer des sites web et des applications. La valeur numérique est `2`.

existingResponse

Attribut enum facultatif.

Spécifie ce qu’il advient d’une réponse existante lorsque le code d’état HTTP est une erreur, c’est-à-dire des codes de réponse > = 400.

L’attribut existingResponse peut être l’une des valeurs suivantes. La valeur par défaut est Auto.

Valeur	Description
`Auto`	Laisse la réponse intacte uniquement si l’indicateur SetStatus est défini. La valeur numérique est `0`.
`Replace`	Remplace la réponse existante même si l’indicateur SetStatus est défini. La valeur numérique est `1`.
`PassThrough`	Laisse la réponse intacte s’il existe déjà une réponse. La valeur numérique est `2`.

Éléments enfants

Élément	Description
`error`	Élément facultatif. Ajoute une erreur HTTP à la collection d’erreurs HTTP.
`remove`	Élément facultatif. Supprime une référence à une erreur HTTP de la collection d’erreurs HTTP.
`clear`	Élément facultatif. Supprime toutes les références aux erreurs HTTP de la collection d’erreurs HTTP.

Exemple Configuration

L’exemple de configuration suivant, lorsqu’il est inclus dans le fichier Web.config pour un site web ou une application, utilise l’attribut errorMode pour n’autoriser l’affichage de messages d’erreur détaillés que sur l’ordinateur local. Il utilise également l’attribut defaultResponseMode pour définir le mode de réponse pour le site ou l’application. L’exemple supprime ensuite le message d’erreur hérité pour le code d’état 500. Ensuite, il définit l’attribut prefixLanguageFilePath dans le répertoire où IIS doit rechercher une nouvelle page d’erreur personnalisée et définit l’attribut chemin d’accès sur 500.htm, le fichier qui contient le message d’erreur personnalisé.

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

Exemple de code

Les exemples suivants ajoutent un nouveau fichier pour toutes les erreurs de code d’état 404 avec un sous-état de 5, que IIS retourne pour les erreurs « Séquence d’URL refusée ». Dans ces exemples, le chemin du préfixe est défini sur « %SystemDrive%\inetpub\custerr », et le nom de fichier est « 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

Remarque

Vous devez veiller à définir le paramètre commit sur apphost quand vous utilisez AppCmd.exe pour configurer ces paramètres. Cela valide les paramètres de configuration dans la section d’emplacement appropriée dans le fichier 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()