Introducción a ApplicationHost.config

  • Artículo

por Tobin Titus

Introducción

ApplicationHost.config es el archivo raíz del sistema de configuración cuando se usa IIS 7 y versiones posteriores. Incluye definiciones de todos los sitios, aplicaciones, directorios virtuales y grupos de aplicaciones, así como valores predeterminados globales para la configuración de servidor web (similar a machine.config y web.config raíz para la configuración de .NET Framework).

También es especial en cuanto a que es el único archivo de configuración de IIS disponible cuando se instala el servidor web (sin embargo, los usuarios pueden agregar archivos web.config si quieren). Incluye una sección especial (llamada configSections) para registrar todas las secciones del Sistema de activación de Windows (WAS) e IIS (machine.config tiene el mismo concepto para las secciones de .NET Framework). Tiene definiciones para bloquear la mayoría de las secciones de IIS a nivel global de modo que, de forma predeterminada, no se pueden invalidar mediante archivos web.config de nivel inferior en la jerarquía.

La ubicación del archivo se encuentra actualmente en el directorio %windir%\system32\inetsrv\config. Este documento le guía por todas las secciones en el orden en que aparecen en el archivo y las explica una por una. La sección más compleja es system.webServer, por lo que se recomienda no dejar de leer la descripción de esa sección en particular.

Tenga en cuenta lo siguiente:

  1. Este documento especifica el contenido de cada sección de configuración, tal y como aparece en applicationHost.config. Por diseño, muchas de las secciones están vacías o no están completas (solo parte de su contenido aparece en el XML). El resto de los valores se toman de los valores predeterminados del esquema. Esto se hace para evitar que haya demasiada información y se colapse el archivo, así como para que sea razonablemente legible.

    • Para obtener una referencia completa del esquema, incluidos los valores predeterminados de todas las propiedades de cada sección, sus intervalos válidos, etc., consulte %windir%\system32\inetsrv\config\schema\IIS\_Schema.xml (para la configuración de IIS) o ASPNET\_Schema.xml (para la configuración de ASP.NET), o bien FX_Schema.xml (para otras configuraciones de .NET Framework).
    • Para mayor comodidad, se incluyen fragmentos de estos archivos en este documento en las secciones adecuadas para que el lector pueda comprender qué propiedades están disponibles y cuáles son los valores predeterminados, entre otras cosas, para cada sección. Consulte la nota adicional a continuación sobre cómo leer la información del esquema.

  2. Realice una copia de seguridad del archivo antes de realizar cambios en este.

Cómo leer el esquema de configuración

Como se ha indicado anteriormente, este documento contiene fragmentos de información del esquema para cada sección, por lo que el lector puede detectar qué propiedades están disponibles y cuáles son sus valores predeterminados y sus intervalos válidos. Estos fragmentos se toman directamente del archivo del esquema de configuración para la configuración de IIS: %windir%\system32\inetsrv\config\schema\IIS\_Schema.xml. En esta sección se explica cómo leer la información del esquema.

El esquema de cada sección de configuración se define en un elemento XML. No hay ninguna definición de esquema para los grupos de secciones. Aquí se utiliza el siguiente formato para explicar cómo leer el esquema:

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

<attribute-name> es el nombre del atributo de configuración, tal y como aparece en XML. Cada atributo debe tener un nombre.

<default-value> es el valor utilizado de forma predeterminada, si no se especifica ningún otro valor en el XML para el atributo. No todos los atributos tienen valores predeterminados (por ejemplo, nombre del sitio). En este caso, la sintaxis será "".

<metadata> contiene varios elementos:

  • Tipo de runtime del atributo. Es uno de los siguientes valores: "bool", "enum", "flags", "int", "int64", "String", "timeSpan". Cada atributo debe tener un tipo.
  • El tipo "bool" es "true" o "false".
  • El tipo "enum" es un conjunto de valores posibles, donde solo puede establecerse uno de ellos para el atributo. Cada valor de este tipo tiene un valor numérico y un nombre descriptivo. La sintaxis usa el carácter "|" como delimitador entre los nombres descriptivos: value1|value2|...|valueN.
  • El tipo "flags" es similar a "enum", salvo que se permiten combinaciones de valores. Por lo tanto, los valores numéricos deben aparecer en múltiplos de 2 y se les pueden aplicar operadores OR para formar combinaciones. La sintaxis es idéntica a la de "enum": value1|value2|...|valueN.
  • El tipo "int" es un entero de 32 bits.
  • El tipo "int64" es un entero de 64 bits.
  • El tipo "String" es una cadena de caracteres.
  • El tipo "timeSpan" es una representación de una unidad de tiempo, similar al tipo de código administrado TimeSpan. Se puede conservar como número (que representa segundos o minutos) o como cadena con formato "[dd:]hh:mm:ss". El elemento "[dd:]" representa un número opcional de días. El resto de elementos representan el número de horas, minutos y segundos, respectivamente. El atributo "timeSpanFormat" especifica qué formato se debe usar: número de segundos, número de minutos o una cadena con formato.
  • Los atributos obligatorios se marcan como "Required". Esto significa que debe establecerse un valor para ellos en el XML. Por ejemplo, el nombre del sitio es un atributo obligatorio (todos los sitios deben tener un nombre en IIS 7.0 y versiones posteriores).

<description> es una breve descripción del atributo.

Esquema de secciones

El elemento XML <sectionSchema> es la unidad base de información del esquema. Toda la información restante del esquema se especifica dentro de este. Tiene un atributo directo ("name") y el resto del esquema se incluye en subelementos dentro de este:

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

Esquema de atributos

Cada atributo se define en un elemento XML <attribute> correspondiente en el esquema. El elemento <attribute> puede estar directamente en el elemento <sectionSchema> (si el atributo está en el ámbito de sección) o en el elemento (si el atributo está en un subelemento dentro de la sección), o bien en el elemento <collection> (si el atributo está en una colección dentro de la sección).

Un esquema de atributo debe especificar un nombre y un tipo de runtime para el atributo. Puede marcar el atributo según sea necesario. Puede marcar el atributo como clave única (si está dentro de una colección) o como parte de una clave de colección (junto con otros atributos). Puede especificar un valor predeterminado para el atributo. Puede marcar el atributo para el cifrado automático en disco. Puede especificar si se permite la palabra "Infinite" como valor para el atributo (solo para tipos numéricos como int e in64, así como para timeSpan). Puede especificar el formato de intervalo de tiempo (segundos, minutos o cadena con formato) para los atributos timespan. Puede especificar reglas de validación para los atributos (consulte la sección Validación de atributos que aparece más adelante en este documento).

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

Esquema de elementos

Cada uno de los elementos se define en un elemento XML <element> correspondiente del esquema. Los elementos se pueden anidar. Un elemento es simplemente un contenedor de otros atributos o subelementos. Debe tener un nombre y puede servir como contenedor de valores predeterminados para los elementos de una colección (por ejemplo, siteDefaults contiene los valores predeterminados de los sitios de la colección <sites>).

Esquema de colecciones

Cada colección se define en un elemento XML <collection> correspondiente en el esquema. Las colecciones contienen varios elementos, que se pueden agregar y quitar de ellas de forma individual. Normalmente, los nombres de directiva de colección son "add", "remove" y "clear", pero algunas colecciones usan nombres distintos para mayor claridad (por ejemplo, la colección usa "site" en lugar de "add").

Para hacer esto, se especifican valores para addElement, removeElement y clearElement en el esquema de la colección. Si falta una directiva de colección en el esquema, la colección no lo admitirá. El esquema de colección puede especificar el nombre de un elemento predeterminado que se usará como contenedor de valores predeterminados para los elementos de la colección (esto complementa a isCollectionDefault en el esquema de elementos).

Por ejemplo, la colección usa siteDefaults como elemento predeterminado. La mayoría de las colecciones anexan elementos a medida que combinan archivos de configuración en el espacio de nombres, pero algunas pueden especificar mergeAppend="false" en el esquema para tener un comportamiento de anteposición. Por ejemplo, plantéese dos niveles de configuración: applicationHost.config y web.config en un sitio. En applicationHost.config:

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

En web.config:

<myCollection>

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

Si la colección anexa, la configuración combinada (efectiva) en el nivel de sitio será:

<myCollection>

    <add value="1"/>

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

Sin embargo, si antepone, será:

<myCollection>

    <add value="2"/>

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

Algunas colecciones pueden permitir entradas duplicadas; para ello, especifican allowDuplicates="true" en su esquema. Esto se hace principalmente para admitir colecciones heredadas en .NET Framework (en machine.config).

Algunas colecciones pueden permitir atributos adicionales, además de los especificados en el esquema. Para ello, se especifica allowUnrecognizedAttributes="true" en su esquema. Esto se hace principalmente para admitir colecciones basadas en proveedores en .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]
/>

Esquema de enumeraciones

Cada atributo de tipo "enum" debe definir sus valores de enumeración en un elemento XML <enum> correspondiente del esquema. Cada valor debe tener un nombre descriptivo y un valor numérico.

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

Esquema de marcas

Cada atributo de tipo "flags" debe definir sus valores de marca en un elemento XML correspondiente del esquema. Cada marca debe tener un nombre descriptivo y un valor numérico que pueden asociarse mediante operadores OR con otros valores para formar combinaciones; por lo tanto, el valor debe expresarse en múltiplos de 2.

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

Validación de atributos

La validación de atributos se realiza al analizar el XML para obtener una sección del archivo y al llamar a la API de configuración para establecer valores. Si se produce un error al validar, también se produce un error en la operación deseada (no se obtiene la sección o se establece un valor no válido).

Cada atributo puede asociar un validador para su valor. Para ello, especifique el nombre del validador adecuado en validationType y los parámetros adicionales en validationParameter en el esquema de atributos.

El sistema admite estos validadores:

Validador ApplicationPoolName

Este validador genera un error con estos caracteres: |<>&"

validationType="applicationPoolName" validationParameter=""

Validador IntegerRange

Este validador genera un error si el valor está fuera [dentro] del intervalo, en enteros.

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

Validador NonEmptyString

Este validador genera un error si el valor de la cadena está establecido.

validationType="nonEmptyString"
validationParameter=""

Validador SiteName

Este validador genera un error con estos caracteres: /.?

validationType="siteName"
validationParameter=""

Validador TimeSpanRange

Este validador genera un error si el valor está fuera [dentro] del intervalo, en segundos.

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

Validador TrimWhiteSpace

Este validador genera un error si hay espacio en blanco al principio o al final del valor.

validationType="trimWhiteSpaceString"
validationParameter=""

Encabezado XML

Cada archivo de configuración es un archivo XML y, opcionalmente, puede incluir la siguiente como primera línea:

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

Además, debe incluir todo su contenido entre etiquetas <configuration> de XML:

<configuration>

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

</configuration>

ApplicationHost.config incluye las líneas anteriores. El resto de este documento analiza las secciones restantes del archivo.

Sección <configSections>

Es la primera sección del archivo. Contiene una lista de todas las demás secciones del archivo. Es el punto de registro de las secciones (por ejemplo, para anular el registro de una sección del sistema, quite su línea de esta sección; no es necesario quitar su archivo de esquema del directorio config\schema).

Tenga en cuenta que también pueden tener una sección otros archivos de configuración, en la parte superior del archivo. Esto puede ser útil para registrar secciones en niveles inferiores al global. Estas secciones solo se registrarán para ese ámbito del espacio de nombres. Los archivos Web.config solo pueden agregar secciones al sistema; no pueden redefinir las secciones registradas en los niveles primarios ni quitar secciones (anularlas el registro).

Las secciones están estructuradas por su jerarquía de grupos de secciones contenedores. Cada registro de sección especifica el nombre de la sección; el tipo de código administrado del controlador de sección (esto no tiene ningún significado en este archivo y se quitará después de la versión beta2: solo lo usa System.Configuration, por lo que seguirá existiendo en los archivos machine.config y web.config); el nivel allowDefinition, si es distinto del valor predeterminado; y overrideModeDefault (este atributo se usa para bloquear la mayoría de las secciones de IIS de este archivo).

Nota:

La sección es la unidad básica de implementación, registro, bloqueo, búsqueda y contención de opciones de configuración. Cada sección pertenece a un grupo de secciones ("primario inmediato"). El grupo de secciones es un contenedor de secciones relacionadas lógicamente y se usa únicamente con fines de jerarquía estructurada. No se puede realizar ninguna operación en los grupos de secciones. Los grupos de secciones no pueden tener valores de configuración directamente (la configuración pertenece a las secciones). Los grupos de secciones pueden anidarse, pero una sola sección no puede.

Esquema

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

Bloqueo

La mayoría de las secciones de IIS están bloqueadas de forma predeterminada, con el uso de overrideModeDefault="Deny" en la sección. Para desbloquear las secciones se recomienda hacerlo mediante etiquetas, de la siguiente forma:

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

La etiqueta de ubicación anterior desbloquea la sección solo para el sitio web predeterminado. Para desbloquearla en todos los sitios, especifique lo siguiente en applicationHost.config:

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

Nota:

Tanto path="." como path="" tienen el mismo efecto. Hacen referencia al nivel actual de la jerarquía.