ApplicationHost.config 简介

项目
03/12/2024

介绍

使用 IIS 7 及更高版本时，ApplicationHost.config 是配置系统的根文件。其中包括所有站点、应用程序、虚拟目录和应用程序池的定义，以及 Web 服务器设置的全局默认值（类似于 machine.config 和 .NET Framework 设置的根 web.config）。

它的特殊之处还在于，它是安装 Web 服务器时唯一可用的 IIS 配置文件（但是，如果用户愿意，用户仍然可以添加 web.config 文件）。它包括一个特殊部分（称为 configSections），用于注册所有 IIS 和 Windows 激活系统 (WAS) 部分（对于 .NET Framework 部分，machine.config 具有相同的概念）。它具有将大多数 IIS 部分锁定到全局级别的定义，因此默认情况下不能被层次结构中较低级别的 web.config 文件覆盖。

文件目前位于 %windir%\system32\inetsrv\config 目录中。本文档按照各部分在文件中的出现顺序对其进行介绍，并逐一解释。最复杂的部分是 system.webServer，因此建议读者不要跳过读取该部分的说明。

请注意以下事项：

本文档指定每个配置节的内容，如 applicationHost.config 中所示。根据设计，许多部分为空或不完整（只有部分内容出现在 XML 中）。其余值取自架构默认值。这样做是为了避免信息过多和文件混乱，并使其保持合理性与可读性。
- 有关完整架构参考，包括每个节中所有属性的默认值、其有效范围等，请参阅 %windir%\system32\inetsrv\config\schema\IIS\_Schema.xml（面向 IIS 设置）或 ASPNET\_Schema.xml（面向 ASP.NET 设置），或 FX_Schema.xml（面向其他 .NET Framework 设置）。
- 为了方便起见，这些文件的片段位于本文档的对应部分中，以便读者可以了解每个部分中的可用属性以及默认值等内容。请参阅下面的其他说明，了解如何读取架构信息。
在对文件进行任何更改之前备份文件。

如何读取配置架构

如上所述，对于各个部分，本文档包含对应的架构信息代码片段，以便读者可以发现可用属性及其默认值和有效范围。这些片段直接取自 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 的倍数，这样就可以通过“OR”运算形成组合。语法与“enum”相同：value1|value2|...|valueN。
“int”是一个 32 位整数。
“int64”是一个 64 位整数。
“String”是一个字符串。
“timeSpan”是时间单位的表示形式，类似于托管代码类型 TimeSpan。可以保留为数字（表示秒或分钟）：或采用“[dd:]hh:mm:ss”格式的格式化字符串。 “[dd:]”元素表示可选天数。其他元素分别表示小时数、分钟数和秒数。 “timeSpanFormat”属性指定应使用哪种格式：秒数、分钟数或格式化字符串。
必要属性会带有“必要”标签。这意味着必须在 XML 中设置它们的值。例如，站点名称是必要属性（每个站点都必须在 IIS 7.0 及更高版本中具有名称）。

<description> 是属性的简短说明。

节架构

<sectionSchema> XML 元素是架构信息的基础单位。需在其中指定所有其他架构信息。其中直接包含一个属性（“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> 元素中（如果该属性位于节范围内）；或在元素中（如果属性位于该节内的子元素中）；或在 <collection> 元素中（如果该属性位于该节内的集合中）。

属性架构必须指定属性的名称和运行时类型。它可以将属性标记为必要项。它可以将属性标记为唯一键（如果位于集合内），或作为集合键的一部分（与其他属性一起）。它可以指定属性的默认值。它可以在磁盘上标记自动加密的属性。它可以指定是否允许将“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> 集合中站点的默认值）。

集合架构

每个集合在架构中的对应 <collection> 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”类型的每个属性都必须在架构中相应的 <enum> XML 元素中定义其枚举值。每个值都必须具有易记名称和数值。

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

标志架构

“flags”类型的每个属性都必须在架构中相应的 XML 元素中定义其标志值。每个标志必须具有易记名称和可以与其他值进行“OR”运算以形成组合的数值；因此，该值应为 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> 标记中：

<configuration>

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

</configuration>

ApplicationHost.config 包含其中上述行。本文档的其余部分将介绍文件中其余部分。

`<configSections>` 节

这是文件中出现的第一节。它包含文件中所有其他节的列表。这是节的注册点（例如，要从系统中取消注册节，请从此节中删除对应行 - 无需从 config\schema 目录中删除其模式文件）。

请注意，其他配置文件也可能有一个节，位于文件顶部。这对于注册低于全局级别的节可能很有用。系统将仅在命名空间的该范围内注册这些节。 Web.config 文件只能向系统添加节；这些文件无法重新定义在父级中注册的节，也无法删除（取消注册）对应节。

系统会按包含节组的层次结构对这些节进行结构化。每个节注册指定节名称；节处理程序的托管代码类型（这在此文件中没有任何意义，并且在 beta2 之后将被删除 - 它仅由 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]
/>

锁定

默认情况下，已在节中使用 overrideModeDefault="Deny"锁定大多数 IIS 节。如要解锁节，建议方法是使用标记，如下所示：

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

注意

path="." 和 path="" 效果相同。其均指代层次结构中的当前级别。

通过

ApplicationHost.config 简介

介绍

如何读取配置架构

节架构

属性架构

元素架构

集合架构

枚举架构

标志架构

属性验证

ApplicationPoolName 验证程序

IntegerRange 验证程序

NonEmptyString 验证程序

SiteName 验证程序

TimeSpanRange 验证程序

TrimWhiteSpace 验证程序

XML 标头

`<configSections>` 节

架构

锁定

反馈

其他资源

通过

ApplicationHost.config 简介

介绍

如何读取配置架构

节架构

属性架构

元素架构

集合架构

枚举架构

标志架构

属性验证

ApplicationPoolName 验证程序

IntegerRange 验证程序

NonEmptyString 验证程序

SiteName 验证程序

TimeSpanRange 验证程序

TrimWhiteSpace 验证程序

XML 标头

<configSections> 节

架构

锁定

反馈

其他资源

`<configSections>` 节