Document par défaut <defaultDocument>

Article
03/24/2024

Vue d’ensemble

L’élément <defaultDocument> vous permet d’activer ou de désactiver le comportement de document par défaut pour votre site web ou votre application. Cet élément contient un élément enfant <files>, qui contient une collection d’éléments <add>. Chaque élément <add> définit les documents par défaut retournés par le site ou l’application à un navigateur client lorsque le site reçoit une demande au répertoire racine.

L’élément <defaultDocument> peut également contenir un ou plusieurs éléments <remove>. Chaque élément <remove> supprime un fichier de document par défaut spécifique hérité d’un fichier de configuration de niveau supérieur sur le serveur Internet Information Services (IIS) 7. Vous pouvez également utiliser l’élément <clear> pour supprimer tous les paramètres de document par défaut définis plus haut dans la hiérarchie de configuration.

Les documents par défaut sont activés par défaut et IIS 7 définit les fichiers de documents par défaut suivants dans le fichier ApplicationHost.config comme valeurs par défaut à l’échelle du serveur :

Default.htm
Default.asp
Index.htm
Index.html
Iisstart.htm

(Si vous installez ASP.NET sur votre serveur web, le processus d’installation ajoute le fichier Default.aspx à cette liste.)

Par défaut, lorsqu’une demande arrive pour le répertoire racine de votre site ou de votre application, IIS 7 envoie une réponse au navigateur en fonction des noms de fichiers que vous avez définis dans l’élément <defaultDocument>. IIS tente de retourner les fichiers corrects dans l’ordre dans lequel ils apparaissent dans l’élément <defaultDocument>. Si le fichier Default.htm existe, IIS l’envoie au navigateur client. Si le fichier Default.htm n’existe pas, IIS tente d’envoyer le fichier Default.asp au navigateur et, si le fichier Default.asp n’existe pas, IIS tente d’envoyer le fichier Index.htm au navigateur. IIS continue ainsi jusqu’à ce qu’il tente d’envoyer chaque fichier de document par défaut au navigateur client.

Remarque

Si vous ordonnez correctement cette liste de documents par défaut, vous pouvez améliorer les performances d’IIS. Par exemple, si vous avez l’intention d’utiliser Index.php pour la page d’accueil dans tous les dossiers de votre site Web et que vous ajoutez Index.php au bas de la liste des documents par défaut, IIS devra vérifier chacun des documents par défaut dans la liste avant de tenter de retourner Index.php au navigateur client. Selon le nombre de dossiers de votre site web et le nombre de demandes de navigateur client, cela peut avoir un impact sur vos performances.

Si vous désactivez les documents par défaut mais que vous avez activé l’exploration des répertoires, IIS retourne une liste de répertoires lorsqu’une demande pour le répertoire racine arrive à partir d’un navigateur. Si vous désactivez à la fois les documents par défaut et l’exploration des répertoires, IIS envoie une erreur « HTTP 404 Le fichier n’existe pas » au navigateur.

Compatibilité

Version	Notes
IIS 10.0	L’élément `<defaultDocument>` n’a pas été modifié dans IIS 10.0.
IIS 8.5	L’élément `<defaultDocument>` n’a pas été modifié dans IIS 8.5.
IIS 8.0	L’élément `<defaultDocument>` n’a pas été modifié dans IIS 8.0.
IIS 7.5	L’élément `<defaultDocument>` n’a pas été modifié dans IIS 7.5.
IIS 7.0	L’élément `<defaultDocument>` a été introduit dans IIS 7.0.
IIS 6.0	L’élément `<defaultDocument>` remplace la propriété DefaultDoc de IIS 6.0 et la valeur EnableDefaultDoc de la propriété DirBrowseFlags sur l’objet de métabase IIsWebService.

Programme d’installation

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

Procédure

Comment ajouter un document par défaut pour une application ou un site

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 des services Internet (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 des services Internet (IIS).
Dans le volet Connexions, développez le nom du serveur, développez Sites, puis accédez au site Web ou à l’application web où vous souhaitez configurer les documents par défaut.
Dans le volet Accueil, double-cliquez sur Document par défaut.
Dans le volet Actions, cliquez sur Ajouter….
Dans la boîte de dialogue Ajouter un document par défaut, tapez le nom du document par défaut que vous souhaitez ajouter dans la zone Nom, puis cliquez sur OK.
Si nécessaire, dans le volet Actions, sélectionnez un document par défaut dans la liste, puis cliquez sur Déplacer vers le haut ou Déplacer vers le bas pour définir l’ordre dans lequel IIS doit effectuer une recherche dans la liste de documents par défaut.
Dans le message d’alerte Document par défaut, cliquez sur Oui pour refuser l’héritage de configuration à partir d’un niveau de configuration parent, ou cliquez sur Non ou Annuler pour annuler la modification dans l’ordre de document par défaut.
Si nécessaire, cliquez sur Supprimer dans le volet Actions pour supprimer les noms de fichiers que vous ne souhaitez pas utiliser comme documents par défaut.

Configuration

Vous pouvez modifier l’ordre dans lequel IIS traite les documents par défaut en modifiant l’ordre des éléments <add> dans l’élément <defaultDocument>.

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

Attributs

Attribut	Description
`enabled`	Attribut booléen facultatif. Spécifie que les documents par défaut sont activés. La valeur par défaut est `true`.

Éléments enfants

Élément	Description
`files`	Élément facultatif. Spécifie une liste de noms de fichiers qui peuvent être retournés en tant que documents par défaut.

Exemple Configuration

L’exemple de configuration suivant, lorsqu’il est inclus dans un fichier Web.config pour un site ou une application, active les documents par défaut pour le site ou l’application. Il ajoute ensuite le nom de fichier « Home.html » à la liste des documents par défaut du site ou de l’application.

<configuration>
   <system.webServer>
      <defaultDocument enabled="true">
         <files>
            <add value="home.html" />
         </files>
      </defaultDocument>
   </system.webServer>
</configuration>

Exemple de code

Les exemples suivants activent les documents par défaut sur un site web nommé Contoso, puis ajoutent un fichier nommé Home.html à la liste des documents par défaut pour le site.

AppCmd.exe

appcmd.exe set config "Contoso" /section:defaultDocument /enabled:true /+files.[value='home.html']

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.GetWebConfiguration("Contoso");
            
            ConfigurationSection defaultDocumentSection = config.GetSection("system.webServer/defaultDocument");
            
            defaultDocumentSection["enabled"] = true;
            
            ConfigurationElementCollection filesCollection = defaultDocumentSection.GetCollection("files");
            ConfigurationElement addElement = filesCollection.CreateElement("add");
            addElement["value"] = @"home.html";
            filesCollection.AddAt(0, addElement);
            
            serverManager.CommitChanges();
        }
    }
}

VB.NET

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

Class Sample
   Shared Sub Main()
      Dim serverManager As ServerManager = New ServerManager
      Dim config As Configuration = serverManager.GetWebConfiguration("Contoso")
      Dim defaultDocumentSection As ConfigurationSection = config.GetSection("system.webServer/defaultDocument")

      defaultDocumentSection("enabled") = True

      Dim filesCollection As ConfigurationElementCollection = defaultDocumentSection.GetCollection("files")
      Dim addElement As ConfigurationElement = filesCollection.CreateElement("add")
      addElement("value") = "home.html"
      filesCollection.AddAt(0, addElement)

      serverManager.CommitChanges()
   End Sub
End Class

JavaScript

var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/Contoso";

var defaultDocumentSection = adminManager.GetAdminSection("system.webServer/defaultDocument",
   "MACHINE/WEBROOT/APPHOST/Contoso");

defaultDocumentSection.Properties.Item("enabled").Value = true;

var filesCollection = defaultDocumentSection.ChildElements.Item("files").Collection;

var addElement = filesCollection.CreateNewElement("add");
addElement.Properties.Item("value").Value = "home.html";
filesCollection.AddElement(addElement, 0);

adminManager.CommitChanges();

VBScript

Set adminManager = WScript.CreateObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST/Contoso"

Set defaultDocumentSection = adminManager.GetAdminSection("system.webServer/defaultDocument", _
   "MACHINE/WEBROOT/APPHOST/Contoso")

defaultDocumentSection.Properties.Item("enabled").Value = True  

Set filesCollection = defaultDocumentSection.ChildElements.Item("files").Collection

Set addElement = filesCollection.CreateNewElement("add")
addElement.Properties.Item("value").Value = "home.html"
filesCollection.AddElement addElement, 0

adminManager.CommitChanges

Partager via