Общие сведения о ApplicationHost.config

Tobin Titus

Введение

ApplicationHost.config является корневым файлом системы конфигурации при использовании IIS 7 и более поздних версий. Он включает определения всех сайтов, приложений, виртуальных каталогов и пулов приложений, а также глобальные значения по умолчанию для параметров веб-сервера (аналогичные machine.config и корневым web.config для параметров .NET Framework).

Кроме того, это единственный файл конфигурации IIS, доступный при установке веб-сервера (однако пользователи по-прежнему могут добавлять web.config файлы, если они хотят). Он содержит специальный раздел (называемый configSections) для регистрации всех разделов IIS и системы активации Windows (WAS) (machine.config имеет ту же концепцию для разделов .NET Framework). Он содержит определения для блокировки большинства разделов IIS на глобальном уровне, поэтому по умолчанию они не могут быть переопределены файлами web.config нижнего уровня в иерархии.

Расположение файла в настоящее время находится в каталоге %windir%\system32\inetsrv\config . В этом документе рассматриваются все разделы, в том порядке, в который они отображаются в файле, и объясняют их по одному. Самый сложный раздел — system.webServer, поэтому рекомендуется не пропускать чтение описания этого раздела в частности.

Обратите внимание на следующее:

1. Этот документ указывает содержимое каждого раздела конфигурации, как показано в applicationHost.config. По дизайну многие разделы пустые или не завершены (только некоторые из их содержимого отображаются в XML). Остальные значения взяты из значений по умолчанию схемы. Это делается, чтобы избежать слишком большого объема информации и загромождения файла, а также для обеспечения достаточной удобочитаемой информации.

   • Полный справочник по схеме, включая значения по умолчанию для всех свойств в каждом разделе, их допустимые диапазоны и т. д.; см. %windir%\system32\inetsrv\config\schema\IIS\_Schema.xml (для параметров IIS), ASPNET\_Schema.xml (для параметров ASP.NET) или FX_Schema.xml (для других параметров .NET Framework).
   • Для удобства блоки этих файлов включены в этот документ в соответствующие разделы, чтобы читатель смог понять, какие свойства доступны, какие значения по умолчанию имеются и т. д. для каждого раздела. Дополнительные сведения о том, как считывать сведения о схеме, см. ниже.

2. Создайте резервную копию файла перед внесением изменений в него.

Чтение схемы конфигурации

Как отмечалось выше, в этом документе содержатся фрагменты сведений о схеме для каждого раздела, поэтому читатель может обнаружить доступные свойства и значения по умолчанию и допустимые диапазоны. Фрагменты кода принимаются непосредственно из файла схемы конфигурации для параметров IIS: %windir%\system32\inetsrv\config\schema\IIS\_Schema.xml В этом разделе объясняется, как считывать сведения о схеме.

Схема для каждого раздела конфигурации определяется в XML-элементе. Определение схемы для групп разделов отсутствует. Следующий формат используется здесь, чтобы объяснить, как считывать схему:

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

<attribute-name> — это имя атрибута конфигурации, как показано в XML. У каждого атрибута должно быть имя.

<default-value> — это значение, используемое по умолчанию, если в XML-файле для атрибута не указано другое значение. Не все атрибуты имеют значения по умолчанию (например, имя сайта). В этом случае синтаксис будет иметь значение "".

<metadata> содержит несколько элементов:

• Тип среды выполнения атрибута. Это один из типов: "bool", "enum", "flags", "int", "int64", "String", "timeSpan". Каждый атрибут должен иметь тип.
• "bool" имеет значение "true" или "false".
• Перечисление — это набор возможных значений, где для атрибута можно задать только один из них. Каждое такое значение имеет числовое значение и понятное имя. Синтаксис использует символ "|" в качестве разделителя между понятными именами: value1|value2|...|valueN.
• Флаги аналогичны перечислениям, но допускают сочетания значений. Поэтому числовые значения должны быть кратными 2, чтобы их можно было сложить для формирования сочетаний. Синтаксис идентичен перечислению: value1|value2|...|valueN.
• Int — 32-разрядное целое число.
• Int64 — 64-разрядное целое число.
• String — это символьная строка.
• "TimeSpan" — это представление единицы времени, аналогичной типу TimeSpan в управляемом коде. Его можно сохранить как число (представляющее секунды или минуты); или как форматированная строка в виде "[dd:]hh:mm:ss". Элемент "[dd:]" представляет необязательное количество дней. Другие элементы представляют количество часов, минут и секунд соответственно. Атрибут timeSpanFormat указывает, какой формат следует использовать: количество секунд, количество минут или отформатированная строка.
• Обязательные атрибуты помечены как "Обязательный". Это означает, что значение для них должно быть задано в ФОРМАТЕ XML. Например, имя сайта является обязательным атрибутом (каждый сайт должен иметь имя в IIS 7.0 и выше).

<description> — краткое описание атрибута.

Схема раздела

Xml-элемент <sectionSchema> — это базовая единица сведений о схеме. Все остальные сведения о схеме указываются внутри него. Он имеет один атрибут непосредственно в нем ("имя"), а остальная часть схемы находится в вложенных элементах внутри нее:

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

Схема атрибутов

Каждый атрибут определяется в соответствующем <attribute> XML-элементе схемы. Элемент <attribute> может находиться непосредственно в элементе <sectionSchema> (если атрибут находится в области раздела); или в элементе <(если атрибут находится в подэлементе в разделе); или в элементе <коллекции> (если атрибут находится в коллекции в разделе).

Схема атрибута должна указывать имя и тип среды выполнения для атрибута. Он может пометить атрибут как обязательный. Он может пометить атрибут как уникальный ключ (если внутри коллекции) или как часть ключа коллекции (вместе с другими атрибутами). Он может указать значение по умолчанию для атрибута. Он может пометить атрибут для автоматического шифрования на диске. Он может указать, разрешено ли слово "Infinite" в качестве значения атрибута (только для числовых типов, таких как int и in64, и timeSpan). Он может указать формат интервала времени (секунды, минуты или форматированные строки) для атрибутов интервала времени. Он может указывать правила проверки атрибутов (см. раздел проверки атрибутов ниже в этом документе).

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

Схема элементов

Каждый элемент определяется в соответствующем <element> XML-элементе схемы. Элементы могут быть вложены. Элемент — это просто контейнер для других атрибутов или вложенных элементов. Он должен иметь имя, и он может служить контейнером значений по умолчанию для элементов коллекции (например, siteDefaults содержит значения по умолчанию для сайтов в <sites> коллекции).

Схема коллекции

Каждая коллекция определяется в соответствующем <XML-элементе коллекции> в схеме. Коллекции содержат несколько элементов, которые можно добавить и удалить из них по отдельности. Как правило, имена директив коллекции : add, remove и clear, но некоторые коллекции используют разные имена для ясности (например, коллекция использует "сайт" вместо "добавить").

Это делается путем указания значений для addElement, removeElement и clearElement в схеме коллекции. Если директива коллекции отсутствует в схеме, коллекция не будет поддерживать ее. Схема коллекции может указать имя элемента по умолчанию, который будет использоваться в качестве контейнера значений по умолчанию для элементов коллекции (это дополняет isCollectionDefault в схеме элемента).

Например, коллекция использует siteDefaults в качестве элемента по умолчанию. Большинство коллекций добавляет элементы по нисходящей иерархии пространства имен при объединении файлов конфигурации, но некоторые из них могут указывать mergeAppend="false" в схеме, чтобы иметь поведение добавления в начало. Например, рассмотрим два уровня конфигурации: applicationHost.config и web.config на сайте. В applicationHost.config:

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

В web.config:

<myCollection>

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

Если коллекция добавляется, ее объединенная (эффективная) конфигурация на уровне сайта будет:

<myCollection>

    <add value="1"/>

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

Тем не менее, если он предустановлен, он будет следующим:

<myCollection>

    <add value="2"/>

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

Некоторые коллекции могут разрешать повторяющиеся записи, указав allowDuplicates="true" в схеме. В основном это делается для поддержки устаревших коллекций в платформе .NET (в machine.config).

Некоторые коллекции могут разрешать в них дополнительные атрибуты, кроме указанных в схеме. Это делается путем указания allowUnrecognizedAttributes="true" в схеме. Это в основном делается для поддержки коллекций, поддерживающих поставщиков, в платформе .NET.

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

Схема перечисления

Каждый атрибут типа "enum" должен определять его значения в соответствующем <элементе enum> XML в схеме. Каждое значение должно иметь понятное имя и числовое значение.

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

Схема флагов

Каждый атрибут типа "flags" должен определять значения флагов в соответствующем XML-элементе в схеме. Каждый флаг должен иметь понятное имя и числовое значение, которое может быть объединено по операциям ИЛИ с другими значениями для формирования сочетаний; следовательно, значение должно быть кратно 2.

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

Проверка атрибутов

Проверка атрибутов выполняется при анализе XML для получения раздела из файла и при вызове API конфигурации для задания значений. Если проверка завершается ошибкой, это приводит к сбою требуемой операции (либо получение раздела, либо установка недопустимого значения).

Каждый атрибут может ассоциировать один валидатор со своим значением. Это делается путем указания соответствующего имени валидатора в параметре validationType и дополнительных параметров в параметре validationParameter в схеме атрибутов.

Система поддерживает следующие проверяющие элементы:

Валидатор ApplicationPoolName

Этот валидатор выдает ошибку на следующих символах: |<>&"

validationType="applicationPoolName" validationParameter=""

Проверяющий элемент IntegerRange

Этот валидатор не проходит проверку, если значение находится вне [внутри] заданного диапазона в целых числах.

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

Валидатор NonEmptyString

Этот валидатор дает сбой, если задано строковое значение.

validationType="nonEmptyString"
validationParameter=""

Валидатор SiteName

Этот валидатор выдаёт ошибку при наличии следующих символов: /.?

validationType="siteName"
validationParameter=""

Валидатор TimeSpanRange

Этот валидатор завершает работу с ошибкой, если значение вне [внутри] диапазона, заданного в секундах.

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

Валидатор TrimWhiteSpace

Этот валидатор срабатывает с ошибкой, если пробел задан в начале или конце значения.

validationType="trimWhiteSpaceString"
validationParameter=""

Заголовок XML

Каждый файл конфигурации является XML-файлом и может включать следующую строку в качестве первой строки:

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

Кроме того, он должен включать все содержимое внутри тегов <конфигурации> XML.

<configuration>

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

</configuration>

ApplicationHost.config включает в себя указанные выше строки. Остальная часть этого документа описывает остальные разделы в файле.

<configSections> Раздел

Это самый первый раздел в файле. Он содержит список всех остальных разделов в файле. Это точка регистрации разделов (например, отмена регистрации раздела из системы, удаление строки из этого раздела — не требуется удалять файл схемы из каталога конфигурации\схемы).

Обратите внимание, что другие файлы конфигурации также могут содержать раздел в верхней части файла. Это может быть полезно для регистрации разделов на уровнях ниже глобального уровня. Эти разделы будут зарегистрированы только для этой области пространства имен. Web.config файлы могут добавлять только разделы в систему; они не могут переопределить разделы, зарегистрированные на родительских уровнях, и они не могут удалять (отмена регистрации) разделов.

Разделы структурированы по их иерархии, содержащей группы разделов. Каждая регистрация раздела указывает имя раздела; тип управляемого кода обработчика разделов (это не имеет значения в этом файле и будет удалено после бета-версии 2 — оно используется только System.Configuration, поэтому оно по-прежнему существует в machine.config и web.config файлах); уровень allowDefinition, если отличается от значения по умолчанию; и переопределениеModeDefault (этот атрибут используется для блокировки большинства разделов IIS в этом файле).

Схема

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

Блокировка

Большинство разделов IIS заблокированы по умолчанию, используя overrideModeDefault="Deny" в разделе. Рекомендуемый способ разблокировки разделов — использовать теги следующим образом:

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

Приведенный выше тег расположения разблокирует раздел только для веб-сайта по умолчанию. Чтобы разблокировать его для всех сайтов, укажите его в applicationHost.config:

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