Structure du fichier de configuration ASP.NET (sections et gestionnaires de sections)

Article
10/22/2014

Mise à jour : novembre 2007

Toutes les informations de configuration ASP.NET résident à l'intérieur de l'élément configuration dans les fichiers Web.config. Les informations de configuration figurant dans cet élément sont regroupées dans deux zones principales : la zone des déclarations de gestionnaires de sections de configuration et la zone des paramètres des sections de configuration.

Déclarations des gestionnaires de sections de configuration

La zone des déclarations de gestionnaires de sections de configuration figure dans l'élément configSections des fichiers Web.config. Elle contient les éléments section de configuration ASP.NET dans lesquels les gestionnaires de section sont déclarés. Ces déclarations de gestionnaires de sections de configuration peuvent être imbriquées dans des éléments sectionGroup pour mieux organiser les informations de configuration. En général, les éléments sectionGroup représentent l'espace de noms auquel les paramètres de configuration s'appliquent. Par exemple, tous les gestionnaires de section de configuration ASP.NET sont groupés dans le groupe de sections system.web, comme l'illustre l'exemple de code suivant.

    <sectionGroup name="system.web"
      type="System.Web.Configuration.SystemWebSectionGroup, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a">
      <!-- <section /> elements. -->
    </sectionGroup>

Il existe une déclaration de gestionnaire de section pour chaque section de configuration dans la zone des paramètres des sections de configuration. Un gestionnaire de section est une classe .NET Framework qui implémente l'interface ConfigurationSection. Les déclarations de gestionnaires de section contiennent le nom d'une section de paramètres de configuration, par exemple pages, et le nom de la classe de gestionnaire de section qui traite les données de configuration de cette section, par exemple System.Web.Configuration.PagesSection. L'exemple de code suivant l'illustre.

      <section name="pages"
        type="System.Web.Configuration.PagesSection, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a">
      </section>

Vous ne devez déclarer un gestionnaire de section de configuration qu'une seule fois. Les gestionnaires des sections de configuration ASP.NET par défaut sont déjà déclarés dans le fichier Machine.config par défaut. Le fichier Web.config racine et d'autres fichiers de configuration des applications ASP.NET héritent automatiquement des gestionnaires de configuration déclarés dans le fichier Machine.config. Vous devez uniquement déclarer un nouveau gestionnaire de section si vous créez une classe de gestionnaire de section personnalisée qui gère une section de paramètres personnalisée.

Les sections de configuration ASP.NET prédéfinies sont répertoriées dans Paramètres de configuration ASP.NET. Pour plus d'informations sur la définition de vos propres sections de paramètres personnalisées et le développement de vos propres gestionnaires de section de configuration pour les gérer, consultez Classes utilisées pour créer les gestionnaires de sections personnalisés et Comment : créer des sections de configuration personnalisées à l'aide de ConfigurationSection.

Paramètres des sections de configuration

La zone des paramètres des sections de configuration suit la zone des déclarations de gestionnaires de section de configuration et contient les paramètres de configuration à proprement parler.

Par défaut, il existe, en interne ou dans l'un des fichiers de configuration racine, un élément de section de configuration spécifié pour chaque élément section et sectionGroup dans la zone configSections. Vous pouvez consulter ces valeurs par défaut dans le fichier systemroot\Microsoft.NET\Framework\Numéroversion\CONFIG\Machine.config.comments.

Un élément de section de configuration peut également contenir des éléments enfants qui sont gérés par le même gestionnaire de section que le parent. Par exemple, l'élément pages suivant contient un élément namespaces qui ne possède aucun gestionnaire de section correspondant puisqu'il est géré par le gestionnaire de la section pages.

  <pages
    buffer="true"
    enableSessionState="true"
    asyncTimeout="45"
  <!-- Other attributes. -->
  >
    <namespaces>
      <add namespace="System" />
      <add namespace="System.Collections" />
    </namespaces>
  </pages>

Exemple d'un fichier Web.config

L'exemple de code suivant montre où sont placés les exemples de code précédents dans un fichier Web.config. Notez que l'élément namespaces de l'élément pages ne possède pas de déclaration de gestionnaire de section de configuration. En effet, le gestionnaire de la section System.Web.Configuration.PagesSection gère tous les éléments enfants de la section des paramètres pages.

<?xml version="1.0" encoding="us-ascii"?>
<configuration>

<!-- Configuration section-handler declaration area. -->
  <configSections>
    <sectionGroup name="system.web"
      type="System.Web.Configuration.SystemWebSectionGroup, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a">
      <section
        name="pages" 
        type="System.Web.Configuration.PagesSection, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"
      />
      <!-- Other <section /> elements. -->
    </sectionGroup>
    <!-- Other <sectionGroup /> and <section /> elements. -->
  </configSections>

<!-- Configuration section settings area. -->
  <pages
    buffer="true"
    enableSessionState="true"
    asyncTimeout="45"
  <!-- Other attributes. -->
  >
    <namespaces>
      <add namespace="System" />
      <add namespace="System.Collections" />
    </namespaces>
  </pages>
  <!-- Other section settings elements. -->

</configuration>

Problèmes d'édition

Dans la mesure où les éléments des sections de configuration doivent être en langage XML correct, les éléments et les attributs respectent la casse. Il existe de nombreuses façons de modifier des paramètres de configuration. Pour plus d'informations, consultez Modification des fichiers de configuration ASP.NET.

Les gestionnaires des sections de configuration personnalisés doivent être créés par programme avant de pouvoir utiliser des éléments de section personnalisés dans vos fichiers de configuration ASP.NET. Pour plus d'informations, consultez Comment : créer des sections de configuration personnalisées à l'aide de ConfigurationSection.

Attributs Path dans les fichiers de configuration

Lorsqu'ils font référence à un chemin d'accès d'une application Web, les attributs path dans les fichiers Web.config peuvent commencer par le raccourci " ~/ ", lequel indique la racine de l'application. Pour plus d'informations, consultez Chemins d'accès aux sites Web ASP.NET.