Einführung in ApplicationHost.config

von Tobin Titus

Einführung

ApplicationHost.config ist die Stammdatei des Konfigurationssystems, wenn Sie IIS 7 und höher verwenden. Sie enthält Definitionen aller Websites, Anwendungen, virtuellen Verzeichnisse und Anwendungspools sowie globale Standardwerte für die Webservereinstellungen (ähnlich wie machine.config und die Stammweb.config für .NET Framework-Einstellungen).

Es ist auch besonders wichtig, dass es sich um die einzige IIS-Konfigurationsdatei handelt, die beim Installieren des Webservers verfügbar ist (Benutzer können jedoch weiterhin Web.config-Dateien hinzufügen, wenn sie möchten). Sie enthält einen speziellen Abschnitt (als configSections bezeichnet) zum Registrieren aller IIS- und Windows-Aktivierungssystem (WAS)-Abschnitte (machine.config hat dasselbe Konzept für .NET Framework-Abschnitte). Es enthält Definitionen für das Sperren der meisten IIS-Abschnitte auf der globalen Ebene, sodass sie standardmäßig nicht durch Dateien auf niedrigerer Ebene „web.config“ in der Hierarchie außer Kraft gesetzt werden können.

Der Speicherort der Datei befindet sich derzeit im %windir%\system32\inetsrv\config-Verzeichnis. Dieses Dokument durchläuft alle Abschnitte, in der Reihenfolge, in der sie in der Datei angezeigt werden, und erläutert sie einzeln. Der komplexeste Abschnitt ist system.webServer, daher wird empfohlen, dass der Leser insbesondere die Beschreibung für diesen Abschnitt nicht überspringen sollte.

Beachten Sie Folgendes:

1. Dieses Dokument gibt den Inhalt jedes Konfigurationsabschnitts an, wie in applicationHost.config angezeigt. Im Design sind viele der Abschnitte leer oder nicht vollständig (nur einige ihrer Inhalte werden im XML-Code angezeigt). Die restlichen Werte werden aus den Schemastandardwerten entnommen. Dies geschieht, um zu viele Informationen und Unübersichtlichkeiten in der Datei zu vermeiden, und um sie vernünftig lesbar zu halten.

   • Vollständige Schemareferenz, einschließlich Standardwerte für alle Eigenschaften in jedem Abschnitt, deren gültigen Bereiche usw., finden Sie unter %windir%\system32\inetsrv\config\schema\IIS\_Schema.xml (für IIS-Einstellungen) oder ASPNET\_Schema.xml (für ASP.NET Einstellungen) oder FX_Schema.xml (für andere .NET Framework-Einstellungen).
   • Aus Gründen der Einfachheit sind Blöcke dieser Dateien in diesem Dokument in den entsprechenden Abschnitten enthalten, damit der Leser verstehen kann, welche Eigenschaften verfügbar sind, was die Standardwerte usw. für jeden Abschnitt sind. Weitere Informationen zum Lesen von Schemainformationen finden Sie weiter unten.

2. Nehmen Sie eine Sicherung der Datei vor, bevor Sie Änderungen daran vornehmen.

So lesen Sie das Konfigurationsschema

Wie oben erwähnt, enthält dieses Dokument Codeausschnitte von Schemainformationen für jeden Abschnitt, sodass der Leser ermitteln kann, welche Eigenschaften verfügbar sind und welche Standardwerte und gültige Bereiche vorhanden sind. Die Codeausschnitte werden direkt aus der Konfigurationsschemadatei für IIS-Einstellungen übernommen: %windir%\system32\inetsrv\config\schema\IIS\_Schema.xml. In diesem Abschnitt wird erläutert, wie Schemainformationen gelesen werden.

Das Schema für jeden Konfigurationsabschnitt wird in einem XML-Element definiert. Es gibt keine Schemadefinition für Abschnittsgruppen. Das folgende Format wird hier verwendet, um zu erläutern, wie das Schema gelesen wird:

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

<attribute-name> ist der Name des Konfigurationsattributes, wie in XML angezeigt. Jedes Attribut muss einen Namen haben.

<default-value> ist der standardmäßig verwendete Wert, wenn kein anderer Wert im XML-Code für das Attribut angegeben wird. Nicht alle Attribute weisen Standardwerte auf (z. B. Websitename). In diesem Fall lautet die Syntax "".

<metadata> enthält mehrere Elemente:

• Den Laufzeittyp des Attributs. Dies ist einer der folgenden: „bool“, „enum“, „flags“, „int“, „int64“, „String“, „timeSpan“. Jedes Attribut muss einen Typ aufweisen.
• „bool“ ist „true“ oder „false“.
• „Enumeration“ ist eine Reihe möglicher Werte, bei denen nur einer dieser Werte als das Attribut festgelegt werden kann. Jeder dieser Werte weist einen numerischen Wert und einen Anzeigenamen auf. Die Syntax verwendet das Zeichen "|" als Trennzeichen zwischen den Anzeigenamen: Wert1|Wert2|...|WertN.
• „Flags“ ähnelt „Enumeration“, mit der Ausnahme, dass Kombinationen von Werten zulässig sind. Daher sollten sich die numerischen Werte in Vielfachen von 2 befinden, sodass sie zusammen ausgelassen werden können, um Kombinationen zu bilden. Die Syntax ist identisch mit „Enumeration“: Wert1|Wert2|...|WertN.
• „int“ ist eine 32-Bit-Ganzzahl.
• „int64“ ist eine 64-Bit-Ganzzahl.
• „String“ ist eine Zeichenfolge.
• „timeSpan“ ist eine Darstellung einer Zeiteinheit, ähnlich dem TimeSpan-Typ mit verwaltetem Code. Sie kann als Zahl beibehalten werden (die Sekunden oder Minuten darstellt), oder als formatierte Zeichenfolge in Form von „[dd:]hh:mm:ss“. Das Element „[dd:]“ stellt eine optionale Anzahl von Tagen dar. Die anderen Elemente stellen die Anzahl der Stunden, Minuten und Sekunden dar. Das Attribut „timeSpanFormat“ gibt an, welches Format verwendet werden soll: Die Anzahl der Sekunden, die Anzahl der Minuten oder eine formatierte Zeichenfolge.
• Erforderliche Attribute sind als „Erforderlich“ gekennzeichnet. Dies bedeutet, dass ein Wert für sie im XML-Code festgelegt werden muss. Beispielsweise ist der Websitename ein erforderliches Attribut (jede Website muss einen Namen in IIS 7.0 und höher haben).

<description> ist eine kurze Beschreibung des Attributs.

Abschnittsschema

Das <sectionSchema>-XML-Element ist die Basiseinheit der Schemainformationen. Alle anderen Schemainformationen werden darin angegeben. Es hat ein Attribut direkt enthalten („Name“), und darin befindet sich dann der Rest des Schemas in Unterelementen:

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

Attributschema

Jedes Attribut wird in einem entsprechenden <attribute>-XML-Element im Schema definiert. Das <attribute>-Element kann sich direkt im <sectionSchema>-Element befinden (wenn sich das Attribut im Abschnittsbereich befindet) oder im Element (wenn sich das Attribut in einem Unterelement innerhalb des Abschnitts befindet) oder im <Auflistungselement> (wenn sich das Attribut in einer Auflistung innerhalb des Abschnitts befindet).

Ein Attributschema muss einen Namen und einen Laufzeittyp für das Attribut angeben. Es kann das Attribut als erforderlich markieren. Es kann das Attribut als eindeutigen Schlüssel (wenn innerhalb einer Sammlung) oder als Teil eines Sammlungsschlüssels (zusammen mit anderen Attributen) markieren. Es kann einen Standardwert für das Attribut angeben. Es kann das Attribut für die automatische Verschlüsselung auf dem Datenträger markieren. Es kann angegeben werden, ob das Wort „Infinite“ als Wert für das Attribut zulässig ist (nur für numerische Typen wie „int“ und „in64“ und für „timeSpan“). Es kann das Zeitbereichsformat (Sekunden, Minuten oder formatierte Zeichenfolge) für Zeitbereichsattribute angeben. Es kann Gültigkeitsprüfungsregeln für die Attribute angeben (siehe Abschnitt „Attributüberprüfung“ weiter unten in diesem Dokument).

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

Elementschema

Jedes Element wird in einem entsprechenden <element>-XML-Element im Schema definiert. Elemente können verschachtelt sein. Ein Element ist einfach ein Container für andere Attribute oder Unterelemente. Es muss über einen Namen verfügen und kann als Container mit Standardwerten für Sammlungselemente dienen (z. B. enthält „siteDefaults“ die Standardwerte für Websites in der <sites>-Auflistung).

Sammlungsschema

Jede Sammlung wird in einem entsprechenden <XML-Sammlungselement> im Schema definiert. Sammlungen enthalten mehrere Elemente, die einzeln hinzugefügt und entfernt werden können. In der Regel sind die Namen der Sammlungsdirektive „add“, „remove“ und „clear“, aber einige Sammlungen verwenden unterschiedliche Namen zur Übersichtlichkeit (z. B. verwendet die Sammlung „site“ anstelle von „add“).

Dazu werden Werte für addElement, removeElement und clearElement im Sammlungsschema angegeben. Wenn eine Sammlungsdirektive im Schema fehlt, wird sie von der Sammlung nicht unterstützt. Das Sammlungsschema kann den Namen eines Standardelements angeben, das als Container mit Standardwerten für Sammlungselemente verwendet wird (dies ergänzt isCollectionDefault im Elementschema).

Die Sammlung verwendet beispielsweise „siteDefaults“ als Standardelement. Die meisten Sammlungen hängen Elemente an, während sie Konfigurationsdateien im Namespace zusammenführen, aber einige können mergeAppend="false" im Schema angeben, um ein vordefiniertes Verhalten zu haben. Betrachten Sie beispielsweise zwei Konfigurationsebenen: applicationHost.config und web.config auf einer Website. In applicationHost.config:

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

In web.config:

<myCollection>

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

Wenn die Sammlung angefügt wird, lautet die zusammengeführte (effektive) Konfiguration auf Standortebene wie folgt:

<myCollection>

    <add value="1"/>

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

Wenn sie jedoch vorangestellt ist, lautet sie:

<myCollection>

    <add value="2"/>

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

Einige Sammlungen können doppelte Einträge zulassen, indem sie allowDuplicates="true" in ihrem Schema angeben. Dies geschieht hauptsächlich, um Legacysammlungen im .NET Framework (in machine.config) zu unterstützen.

Einige Sammlungen können zusätzliche Attribute zulassen, die über die im Schema angegebenen hinausgehen. Dazu geben Sie allowUnrecognizedAttributes="true" in ihrem Schema an. Es wird hauptsächlich getan, um anbieterbasierte Auflistungen im .NET Framework zu unterstützen.

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

Enumerationsschema

Jedes Attribut vom Typ „Enumeration“ muss seine Enumerationswerte in einem entsprechenden <Enumerations>-XML-Element im Schema definieren. Jeder Wert muss einen Anzeigenamen und einen numerischen Wert aufweisen.

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

Flags-Schema

Jedes Attribut vom Typ „Flags“ muss seine Flagwerte in einem entsprechenden XML-Element im Schema definieren. Jedes Kennzeichen muss einen Anzeigenamen und einen numerischen Wert aufweisen, der zusammen mit anderen Werten als Kombinationen verwendet werden kann. Daher sollte der Wert ein Vielfaches von 2 sein.

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

Attributüberprüfung

Die Attributüberprüfung erfolgt beim Analysieren des XML-Codes zum Abrufen eines Abschnitts aus der Datei und beim Aufrufen der Konfigurations-API zum Festlegen von Werten. Wenn die Überprüfung fehlschlägt, schlägt der gewünschte Vorgang fehl (Abrufen des Abschnitts oder Festlegen des ungültigen Werts).

Jedes Attribut kann einen Validator für seinen Wert zuordnen. Dazu geben Sie den entsprechenden Validatornamen im validationType und zusätzliche Parameter im validationParameter im Attributschema an.

Das System unterstützt diese Validatoren:

ApplicationPoolName-Validator

Dieser Validator schlägt bei diesen Zeichen fehl: |<>&"

validationType="applicationPoolName" validationParameter=""

IntegerRange-Validator

Dieser Validator schlägt fehl, wenn sich der Wert außerhalb des [innen]-Bereichs in ganzzahligen Zahlen befindet.

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

NonEmptyString-Validator

Dieser Validator schlägt fehl, wenn der Zeichenfolgenwert festgelegt ist.

validationType="nonEmptyString"
validationParameter=""

SiteName-Validator

Dieser Validator schlägt bei diesen Zeichen fehl: /.?

validationType="siteName"
validationParameter=""

TimeSpanRange-Validator

Dieser Validator schlägt fehl, wenn sich der Wert innerhalb von Sekunden außerhalb des Bereichs befindet.

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

TrimWhiteSpace-Validator

Dieser Validator schlägt fehl, wenn Leerzeichen am Anfang oder Ende des Werts festgelegt werden.

validationType="trimWhiteSpaceString"
validationParameter=""

XML-Header

Jede Konfigurationsdatei ist eine XML-Datei und kann optional die folgende Zeile als erste Zeile enthalten:

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

Darüber hinaus muss er seinen gesamten Inhalt in einem XML-<Konfigurationstag> enthalten:

<configuration>

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

</configuration>

ApplicationHost.config enthält die obigen Zeilen darin. Der Rest dieses Dokuments durchläuft die restlichen Abschnitte in der Datei.

<configSections>-Abschnitt

Dies ist der erste Abschnitt in der Datei. Er enthält eine Liste aller anderen Abschnitte in der Datei. Dies ist der Zeitpunkt der Registrierung für die Abschnitte (z. B. um die Registrierung eines Abschnitts aus dem System aufzuheben, entfernen Sie die Zeile aus diesem Abschnitt – sie müssen die Schemadatei nicht aus dem Verzeichnis „config\schema“ entfernen).

Beachten Sie, dass auch andere Konfigurationsdateien über einen Abschnitt verfügen, ganz oben in der Datei. Dies kann hilfreich sein, um Abschnitte auf niedrigeren Ebenen als der globalen Ebene zu registrieren. Diese Abschnitte werden nur für diesen Bereich des Namespaces registriert. Web.config-Dateien können nur Abschnitte zum System hinzufügen. Sie können Abschnitte, die in übergeordneten Ebenen registriert wurden, nicht neu definieren und keine Abschnitte entfernen (Registrierung aufheben).

Die Abschnitte sind nach ihrer Hierarchie nach Beinhalten von Abschnittsgruppen strukturiert. Jede Abschnittsregistrierung gibt den Abschnittsnamen an, den verwalteten Codetyp des Abschnittshandlers (dies hat keine Bedeutung in dieser Datei und wird nach Beta2 entfernt – es wird nur von System.Configuration verwendet, sodass er weiterhin in machine.config- und web.config-Dateien vorhanden ist), die allowDefinition-Ebene, wenn sich von der Standardeinstellung unterscheidet, und den overrideModeDefault (dieses Attribut wird verwendet, um die meisten IIS-Abschnitte in dieser Datei zu sperren).

Schema

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

Sperren

Die meisten IIS-Abschnitte sind standardmäßig mit overrideModeDefault="Deny" im Abschnitt gesperrt. Die empfohlene Methode zum Entsperren von Abschnitten ist die Verwendung von Tags wie folgt:

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

Das obige Speicherorttag entsperrt den Abschnitt nur für die Standardwebsite. Um sie für alle Websites zu entsperren, geben Sie dies in „applicationHost.config“ an:

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