ApplicationHost.config の概要

[アーティクル]
03/11/2024

はじめに

IIS 7 以降を使用する場合は、ApplicationHost.config が構成システムのルートファイルとなります。これには、すべてのサイト、アプリケーション、仮想ディレクトリ、アプリケーションプールに関する定義に加え、Web サーバー設定のグローバルな既定値が含まれます (machine.config や .NET Framework 設定のルート web.config と同様)。

また、Web サーバーのインストール時に使用できる唯一の IIS 構成ファイルであるという点でも特別です (ただし、ユーザーは必要に応じて、引き続き web.config ファイルを追加できます)。 IIS および Windows ライセンス認証システム (WAS) のすべてのセクションを登録するための特殊なセクション (configSections と呼ばれます) が含まれています (machine.config には .NET Framework のセクションと同じ概念が使用されています)。ほとんどの IIS セクションをグローバルレベルにロックダウンするための定義が含まれているので、既定では、それらを階層内の下位レベルの web.config ファイルでオーバーライドすることはできません。

このファイルは現在、%windir%\system32\inetsrv\config ディレクトリに置かれています。このドキュメントではすべてのセクションをファイル内に表示される順序で取り上げ、1 つずつ説明します。最も複雑なセクションは 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" は使用可能な値のセットです。ただし、属性に設定できるのはそのうちの 1 つだけです。このような値すべてに、数値とフレンドリ名が含まれます。構文では、フレンドリ名の間の区切り記号として文字 "|" を使用します: value1|value2|…|valueN。
"flags" は、値の組み合わせが許可される点を除けば、"enum" によく似ています。したがって、数値は 2 の倍数単位で指定する必要があります。それにより、それらの論理和を取って組み合わせを形成できます。構文は "enum" と同じです: value1|value2|…|valueN。
"int" は 32 ビット整数です。
"int64" は 64 ビット整数です。
"String" は文字列です。
"timeSpan" は時間単位を表し、マネージドコード型の TimeSpan に似ています。これは数値 (秒または分を表す) として保持することも、"書式設定された文字列として [dd:]hh:mm:ss" の形式で保持することもできます。 "[dd:]" 要素は日数を表し省略可能です。その他の要素は、それぞれ時間、分、秒の数を表します。 "timeSpanFormat" 属性では、使用する形式を指定します: 秒数、分数、または書式設定された文字列。
必須の属性は "Required" とマークされます。これは、値を XML で設定する必要があることを意味します。たとえば、サイト名は必須の属性です (IIS 7.0 以降では、すべてのサイトに名前が必要です)。

<description> は属性の簡単な説明です。

セクションスキーマ

<sectionSchema> XML 要素は、スキーマ情報の基本単位です。その他のスキーマ情報はすべて、この中で指定されます。 1 つの属性 ("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" ですが、一部のコレクションでは、わかりやすくするために異なる名前を使用する場合があります (たとえば、コレクションで、"add" ではなく "site" を使用します)。

これを行うには、コレクションスキーマ内で addElement、removeElement、clearElement の値を指定します。これは、コレクションディレクティブがスキーマにない場合、コレクションではサポートされません。コレクションスキーマでは、コレクション要素の既定値のコンテナーとして使用される既定の要素の名前を指定できます (これにより、要素スキーマ内の isCollectionDefault が補完されます)。

たとえば、コレクションで siteDefaults を既定の要素として使用します。ほとんどのコレクションでは、構成ファイルを名前空間の下にマージするのと同様に要素を追加しますが、一部のコレクションでは、スキーマ内で mergeAppend="false" を指定して先頭への追加動作を行う場合があります。たとえば、次の 2 つのレベルの構成について考えてみましょう: サイト内の 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 要素にそれぞれのフラグ値を定義する必要があります。すべてのフラグには、フレンドリ名と、他の値との論理和を取って組み合わせを形成するための数値とを含める必要があります。したがって、値は 2 の倍数単位とする必要があります。

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

属性の検証

属性の検証が行われるのは、XML を解析してファイルからセクションを取得するとき、および構成 API を呼び出して値を設定するときです。検証が失敗した場合、目的の操作 (セクションの取得または無効な値の設定) は行われません。

各属性では、その値に対して 1 つの検証コントロールを関連付けることがあります。これを行うには、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 セクションは、この属性を使用してロックダウンします)。

Note

セクションは、構成設定の展開、登録、ロック、検索、および包含の基本単位です。すべてのセクションはそれぞれ、1 つのセクショングループ ("直接の親") に属しています。セクショングループは、論理的に関連するセクションのコンテナーであり、構造化された階層の目的でのみ使用されます。セクショングループに対して操作を行うことはできません。セクショングループに構成設定を直接含めることはできません (設定はセクションに属します)。セクショングループは入れ子にすることができます。セクションは、できません。

[スキーマ]

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

上記の場所タグを使用すると、既定の Web サイトのセクションのみがロック解除されます。そのロックをすべてのサイトで解除するには、applicationHost.config 内で次のように指定します。

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

Note

path="." および path="" の結果は同じになります。これらは階層内の現在のレベルを参照します。

ApplicationHost.config の概要

はじめに

構成スキーマの読み方

セクションスキーマ

属性スキーマ

要素スキーマ

コレクションスキーマ

列挙型スキーマ

フラグスキーマ

属性の検証

ApplicationPoolName 検証コントロール

IntegerRange 検証コントロール

NonEmptyString 検証コントロール

SiteName 検証コントロール

TimeSpanRange 検証コントロール

TrimWhiteSpace 検証コントロール

XML ヘッダー

`<configSections>` セクション

[スキーマ]

ロック

フィードバック

フィードバック

その他のリソース

ApplicationHost.config の概要

はじめに

構成スキーマの読み方

セクション スキーマ

属性スキーマ

要素スキーマ

コレクション スキーマ

列挙型スキーマ

フラグ スキーマ

属性の検証

ApplicationPoolName 検証コントロール

IntegerRange 検証コントロール

NonEmptyString 検証コントロール

SiteName 検証コントロール

TimeSpanRange 検証コントロール

TrimWhiteSpace 検証コントロール

XML ヘッダー

<configSections> セクション

[スキーマ]

ロック

フィードバック

フィードバック

その他のリソース

セクションスキーマ

コレクションスキーマ

フラグスキーマ

`<configSections>` セクション