Présentation d’ApplicationHost.config

par Tobin Titus

Introduction

ApplicationHost.config est le fichier racine du système de configuration lorsque vous utilisez IIS 7 et des versions ultérieures. Il inclut des définitions de tous les sites, applications, répertoires virtuels et pools d’applications, ainsi que des valeurs par défaut globales pour les paramètres du serveur web (comme machine.config et web.config racine pour les paramètres .NET Framework).

Il est également spécial dans le fait qu’il s’agit du seul fichier de configuration IIS disponible lorsque le serveur web est installé (toutefois, les utilisateurs peuvent toujours ajouter des fichiers web.config s’ils le souhaitent). Il inclut une section spéciale (appelée configSections) pour inscrire toutes les sections IIS et système d’activation Windows (WAS) (machine.config a le même concept pour les sections .NET Framework). Elle a des définitions pour verrouiller la plupart des sections IIS au niveau global, afin qu’elles ne puissent pas être remplacées par des fichiers web.config de niveau inférieur dans la hiérarchie.

L’emplacement du fichier se trouve actuellement dans le répertoire %windir%\system32\inetsrv\config . Ce document décrit toutes les sections, dans l’ordre dans lequel ils apparaissent dans le fichier, et les explique un par un. La section la plus complexe est system.webServer. Il est donc recommandé au lecteur de ne pas lire la description de cette section en particulier.

Notez ce qui suit :

1. Ce document spécifie le contenu de chaque section de configuration, comme indiqué dans applicationHost.config. Par conception, la plupart des sections sont vides ou non terminées (seules certaines de leur contenu apparaissent dans le code XML). Les autres valeurs sont extraites des valeurs par défaut du schéma. Cela permet d’éviter trop d’informations et d’encombrement du fichier, et afin de le conserver raisonnablement lisible.

   • Pour obtenir une référence de schéma complète, y compris les valeurs par défaut pour toutes les propriétés de chaque section, leurs plages valides, etc., reportez-vous à %windir%\system32\inetsrv\config\schema\IIS\_Schema.xml (pour les paramètres IIS) ou ASPNET\_Schema.xml (pour les paramètres de ASP.NET) ou FX_Schema.xml (pour d’autres paramètres .NET Framework).
   • Pour des raisons pratiques, les blocs de ces fichiers sont inclus dans ce document dans les sections appropriées afin que le lecteur puisse comprendre quelles propriétés sont disponibles, quelles sont les valeurs par défaut, etc., pour chaque section. Consultez la note supplémentaire ci-dessous sur la lecture des informations de schéma.

2. Effectuez une sauvegarde du fichier avant d’y apporter des modifications.

Guide pratique pour lire le schéma de configuration

Comme indiqué ci-dessus, ce document contient des extraits d’informations de schéma pour chaque section, afin que le lecteur puisse découvrir les propriétés disponibles et les valeurs par défaut et les plages valides. Les extraits de code sont directement extraits du fichier de schéma de configuration pour les paramètres IIS : %windir%\system32\inetsrv\config\schema\IIS\_Schema.xml. Cette section explique comment lire les informations de schéma.

Le schéma de chaque section de configuration est défini dans un élément XML. Il n’existe aucune définition de schéma pour les groupes de sections. Le format suivant est utilisé ici pour expliquer comment lire le schéma :

<attribute-name>="<default-value>"  [<metadata>] [<description>]

<attribute-name> est le nom de l’attribut de configuration, comme indiqué dans XML. Chaque attribut doit avoir un nom.

<default-value> est la valeur utilisée par défaut, si aucune autre valeur n’est spécifiée dans le code XML de l’attribut. Tous les attributs ne possèdent pas de valeurs par défaut (par exemple, le nom du site). Dans ce cas, la syntaxe est « ».

<metadata> contient plusieurs éléments :

• Type d’exécution de l’attribut. Il s’agit de l’un des « bool », « enum », « flags », « int », « int64 », « String », « timeSpan ». Chaque attribut doit avoir un type.
• « bool » est « true » ou « false ».
• « enum » est un ensemble de valeurs possibles, où une seule d’entre elles peut être définie pour l’attribut. Chaque valeur de ce type a une valeur numérique et un nom convivial. La syntaxe utilise le caractère « | » comme délimiteur entre les noms conviviaux : value1|value2|...|valueN.
• Les « indicateurs » sont similaires à « enum », sauf que les combinaisons de valeurs sont autorisées. Par conséquent, les valeurs numériques doivent être en multiples de 2, afin qu’elles puissent être ORed ensemble pour former des combinaisons. La syntaxe est identique à « enum » : value1|value2|...|valueN.
• « int » est un entier 32 bits.
• « int64 » est un entier 64 bits.
• « String » est une chaîne de caractères.
• « timeSpan » est une représentation d’une unité de temps, similaire au type de code managé TimeSpan. Il peut être conservé sous la forme d’un nombre (représentant des secondes ou des minutes) ; ou sous forme de chaîne mise en forme sous la forme « [dd:]hh:mm:ss ». L’élément « [dd:] » représente un nombre facultatif de jours. Les autres éléments représentent respectivement des nombres d’heures, de minutes et de secondes. L’attribut « timeSpanFormat » spécifie le format à utiliser : nombre de secondes, nombre de minutes ou chaîne mise en forme.
• Les attributs obligatoires sont marqués « Obligatoire ». Cela signifie qu’une valeur doit être définie dans le code XML. Par exemple, le nom du site est un attribut obligatoire (chaque site doit avoir un nom dans IIS 7.0 et versions ultérieures).

<description> est une brève description de l’attribut.

Schéma de section

L’élément <XML sectionSchema> est l’unité de base des informations de schéma. Toutes les autres informations de schéma sont spécifiées dans celui-ci. Il a un attribut directement dans celui-ci (« name »), puis le reste du schéma se trouve dans des sous-éléments dans celui-ci :

<sectionSchema name=""  <!-- [String, Required] [XML full path of the section] --> >
    <!-- sub-elements here describing rest of schema; -->
    <!-- their description is right below in the doc. --> 
</sectionSchema>

Schéma d’attribut

Chaque attribut est défini dans un élément XML correspondant <attribute> dans le schéma. L’élément <attribute> peut se trouver directement dans l’élément <sectionSchema> (si l’attribut se trouve dans l’étendue de section) ou dans l’élément (si l’attribut se trouve dans un sous-élément dans la section) ; ou dans l’élément <de collection> (si l’attribut se trouve dans une collection dans la section).

Un schéma d’attribut doit spécifier un nom et un type d’exécution pour l’attribut. Il peut marquer l’attribut comme requis. Il peut marquer l’attribut comme clé unique (si elle se trouve à l’intérieur d’une collection) ou dans le cadre d’une clé de collection (avec d’autres attributs). Il peut spécifier une valeur par défaut pour l’attribut. Il peut marquer l’attribut pour le chiffrement automatique sur disque. Il peut spécifier si le mot « Infini » est autorisé comme valeur pour l’attribut (uniquement pour les types numériques tels que int et in64, et pour timeSpan). Il peut spécifier le format d’intervalle de temps (secondes, minutes ou chaîne mise en forme) pour les attributs d’intervalle de temps. Il peut spécifier des règles de validation pour les attributs (voir la section Validation des attributs ci-dessous dans ce document).

<attribute
    name=""  [String, Required] [XML name of the attribute]
    type=""  [bool|enum|flags|int|int64|string|timeSpan, Required][Runtime type]
    required="false"  [bool] [Indicates if must be set]
    isUniqueKey="false"    [bool] [Serves as the collection key]
    isCombinedKey="false"  [bool] [Part of a multi-attribute key]
    defaultValue=""  [String] [Default value or comma-delimited flags]
    encrypted="false"  [bool] [Indicates if value persisted encrypted]
    allowInfinite="false"  [bool] [Indicates if "Infinite" can be set]
    timeSpanFormat="string" [string|seconds|minutes] [hh:mm:ss or number]
    validationType=""       [See validation below]
    validationParameter=""  [See validation below]
/>

Schéma d'élément

Chaque élément est défini dans un élément XML <element> correspondant dans le schéma. Les éléments peuvent être imbriqués. Un élément est simplement un conteneur pour d’autres attributs ou sous-éléments. Il doit avoir un nom et peut servir de conteneur de valeurs par défaut pour les éléments de collection (par exemple, siteDefaults contient les valeurs par défaut pour les sites de la <sites> collection).

Schéma de collection

Chaque collection est définie dans un élément XML de collection< correspondant >dans le schéma. Les collections contiennent plusieurs éléments, qui peuvent être ajoutés et supprimés individuellement. En règle générale, les noms de directive de collection sont « add », « remove » et « clear », mais certaines collections utilisent des noms différents pour la clarté (par exemple, la collection utilise « site » au lieu de « add »).

Pour ce faire, spécifiez des valeurs pour addElement, removeElement et clearElement dans le schéma de collection. Si une directive de collection est manquante dans le schéma, la collection ne la prend pas en charge. Le schéma de collection peut spécifier le nom d’un élément par défaut qui sera utilisé comme conteneur de valeurs par défaut pour les éléments de collection (cela complète isCollectionDefault dans le schéma d’élément).

Par exemple, la collection utilise siteDefaults comme élément par défaut. La plupart des collections ajoutent des éléments au fur et à mesure qu’ils fusionnent les fichiers de configuration dans l’espace de noms, mais certains peuvent spécifier mergeAppend="false » dans le schéma pour avoir un comportement anticipé. Prenons par exemple deux niveaux de configuration : applicationHost.config et web.config dans un site. Dans applicationHost.config :

<myCollection>
    <add value="1"/> 
</myCollection>

Dans web.config :

<myCollection>

    <add value="2" />        
</myCollection>

Si la collection ajoute, sa configuration fusionnée (effective) au niveau du site sera :

<myCollection>

    <add value="1"/>

    <add value="2"/>    
</myCollection>

Toutefois, s’il précède, il sera :

<myCollection>

    <add value="2"/>

    <add value="1"/>    
</myCollection>

Certaines collections peuvent autoriser les entrées en double en spécifiant allowDuplicates="true » dans leur schéma. Cela est principalement fait pour prendre en charge les collections héritées dans le .NET Framework (dans machine.config).

Certaines collections peuvent autoriser des attributs supplémentaires, au-delà de ceux spécifiés dans le schéma. Pour ce faire, spécifiez allowUnrecognizedAttributes="true » dans leur schéma. Il est principalement fait pour prendre en charge les collections basées sur un fournisseur dans le .NET Framework.

<collection            
    addElement=""     [String] [Name of Add directive, if supported]
    removeElement=""  [String] [Name of Remove directive, if supported]
    clearElement=""   [String] [Name of Clear directive, if supported]
    defaultElement="" [applicationDefaults|applicationPoolDefaults|siteDefaults|virtualDirectoryDefaults] [See isCollectionDefault]
    mergeAppend="true"  [bool] [Indicates whether or not deepest set values are appended]  
    allowDuplicates="false"  [bool] [Indicates if multiple elements may have the same keys]
    allowUnrecognizedAttributes="false"  [bool] [Indicates if non-schema attributes ok]
/>

Schéma d’énumération

Chaque attribut de type « enum » doit définir ses valeurs d’énumération dans un élément XML d’énumération< correspondant >dans le schéma. Chaque valeur doit avoir un nom convivial et une valeur numérique.

<enum name=""  [String, Required] [Friendly name of the enum]
    value="" [int, Required] [Numeric value]
/>

Schéma des indicateurs

Chaque attribut de type « indicateurs » doit définir ses valeurs d’indicateur dans un élément XML correspondant dans le schéma. Chaque indicateur doit avoir un nom convivial et une valeur numérique qui peut être ORed avec d’autres valeurs pour former des combinaisons ; par conséquent, la valeur doit être en multiples de 2.

<flags            
    name=""  [String, Required] [Friendly name of the flag]
    value="" [int in power of 2, Required] [Numeric value]
/>

Validation d’attribut

La validation d’attribut est effectuée lors de l’analyse du code XML pour obtenir une section à partir du fichier et lors de l’appel de l’API de configuration pour définir des valeurs. En cas d’échec de la validation, l’opération souhaitée échoue (obtention de la section ou définition de la valeur non valide).

Chaque attribut peut associer un validateur pour sa valeur. Pour ce faire, spécifiez le nom de validateur approprié dans le validationType et des paramètres supplémentaires dans validationParameter dans le schéma d’attribut.

Le système prend en charge ces validateurs :

Validateur ApplicationPoolName

Ce validateur échoue sur ces caractères : |<>&"

validationType="applicationPoolName" validationParameter=""

Validateur IntegerRange

Ce validateur échoue si la valeur est en dehors de la plage [à l’intérieur], dans les entiers.

validationType="integerRange"
validationParameter="<minimum>,<maximum>[,exclude]"

Validateur NonEmptyString

Ce validateur échoue si la valeur de chaîne est définie.

validationType="nonEmptyString"
validationParameter=""

Validateur SiteName

Ce validateur échoue sur ces caractères : /.?

validationType="siteName"
validationParameter=""

Validateur TimeSpanRange

Ce validateur échoue si la valeur est en dehors de la plage [à l’intérieur], en secondes.

validationType="timeSpanRange"
validationParameter="<minimum>,<maximum>,<granularity>[,exclude]"

Validateur TrimWhiteSpace

Ce validateur échoue si l’espace blanc est défini au début ou à la fin de la valeur.

validationType="trimWhiteSpaceString"
validationParameter=""

En-tête XML

Chaque fichier de configuration est un fichier XML et peut éventuellement inclure la ligne suivante comme première ligne :

<?xml version="1.0" encoding="UTF-8" ?>

En outre, il doit inclure tout son contenu dans des balises de configuration< XML >:

<configuration>

   <!-- [All of the context goes here] -->

</configuration>

ApplicationHost.config inclut les lignes ci-dessus. Le reste de ce document décrit le reste des sections du fichier.

Section<configSections>

Il s’agit de la première section du fichier. Elle contient la liste de toutes les autres sections du fichier. Il s’agit du point d’inscription des sections (par exemple, pour annuler l’inscription d’une section du système, supprimer sa ligne de cette section. Il n’est pas nécessaire de supprimer son fichier de schéma du répertoire config\schema).

Notez que d’autres fichiers de configuration peuvent également avoir une section, en haut du fichier. Cela peut être utile pour inscrire des sections à des niveaux inférieurs au niveau global. Ces sections sont inscrites pour cette étendue de l’espace de noms uniquement. Les fichiers Web.config peuvent uniquement ajouter des sections au système ; ils ne peuvent pas redéfinir les sections inscrites dans les niveaux parents et ne peuvent pas supprimer (annuler l’inscription).

Les sections sont structurées par leur hiérarchie de groupes de sections. Chaque inscription de section spécifie le nom de la section ; le type de code managé du gestionnaire de sections (cela n’a aucune signification dans ce fichier et sera supprimé après la version beta2 : il est utilisé uniquement par System.Configuration, de sorte qu’il existe toujours dans les fichiers machine.config et web.config) ; le niveau allowDefinition, s’il diffère de la valeur par défaut ; et overrideModeDefault (cet attribut est utilisé pour verrouiller la plupart des sections IIS de ce fichier).

Remarque

La section est l’unité de base du déploiement, de l’inscription, du verrouillage, de la recherche et de l’isolement des paramètres de configuration. Chaque section appartient à un groupe de sections (« parent immédiat »). Le groupe de sections est un conteneur de sections liées logiquement et est utilisé uniquement à des fins de hiérarchie structurée. Aucune opération ne peut être effectuée sur les groupes de sections. Les groupes de sections ne peuvent pas avoir de paramètres de configuration directement (les paramètres appartiennent aux sections). Les groupes de sections peuvent être imbriqués ; la section ne peut pas.

schéma

<section
    name=""  [Required, Collection Key] [XML name of the section]
    allowDefinition="Everywhere" [MachineOnly|MachineToApplication|Everywhere] [Level where it can be set]
    overrideModeDefault="Allow"  [Allow|Deny] [Default delegation mode]
/>

Verrouillage

La plupart des sections IIS sont verrouillées par défaut, à l’aide de overrideModeDefault="Deny » dans la section. La méthode recommandée pour déverrouiller les sections consiste à utiliser des balises, comme suit :

<location path="Default Web Site" overrideMode="Allow" >
  <system.webServer>
    <asp/>
  </system.webServer>            
</location>

La balise d’emplacement ci-dessus déverrouille la section du site web par défaut uniquement. Pour le déverrouiller pour tous les sites, spécifiez-le dans applicationHost.config :

<location path="." overrideMode="Allow">
    <system.webServer>
         <asp/>
    </system.webServer>
</location>

Remarque

path= «.» et path= «» ont le même effet. Ils font référence au niveau actuel dans la hiérarchie.