Share via

Введение в ApplicationHost.config

  • Статья

По Тобин Титус

Введение

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".
  • "enum" — это набор возможных значений, где для атрибута можно задать только одно из них. Каждое такое значение имеет числовое значение и понятное имя. Синтаксис использует символ "|" в качестве разделителя между понятными именами: value1|value2|...|valueN.
  • "flags" похож на "enum", за исключением того, что разрешены сочетания значений. Поэтому числовые значения должны быть кратными 2, чтобы они могли быть ORed вместе для формирования комбинаций. Синтаксис идентичен "enum": value1|value2|...|valueN.
  • "int" — это 32-разрядное целое число.
  • int64 — это 64-разрядное целое число.
  • "String" — это символьная строка.
  • TimeSpan — это представление единицы времени, аналогичное управляемому коду TimeSpan. Его можно сохранить в виде числа (представляющего секунды или минуты); или в виде строки в формате "[дд:]чч:мм:сс". Элемент "[dd:]" представляет необязательное количество дней. Другие элементы представляют количество часов, минут и секунд соответственно. Атрибут timeSpanFormat указывает, какой формат следует использовать: количество секунд, количество минут или форматированная строка.
  • Обязательные атрибуты помечены как обязательные. Это означает, что значение для них должно быть задано в XML. Например, имя сайта является обязательным атрибутом (каждый сайт должен иметь имя в IIS 7.0 и более поздних версиях).

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

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

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

<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", но в некоторых коллекциях для ясности используются разные имена (например, коллекция использует "site" вместо "add").

Это делается путем указания значений для 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 Framework (в machine.config).

Некоторые коллекции могут разрешать в них дополнительные атрибуты, помимо указанных в схеме. Для этого в схеме укажите allowUnrecognizedAttributes="true". В основном это делается для поддержки коллекций на основе поставщиков в .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]
/>

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

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

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

Схема флагов

Каждый атрибут типа flags должен определять свои значения флагов в соответствующем XML-элементе в схеме. Каждый флаг должен иметь понятное имя и числовое значение, которое может быть ORed вместе с другими значениями для формирования комбинаций; поэтому значение должно быть кратно 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> Разделе

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

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

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

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

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

Примечание

path="." и path="" имеют одинаковый эффект. Они ссылаются на текущий уровень в иерархии.