Share via

Introduzione alle ApplicationHost.config

  • Articolo

di Tobin Titus

Introduzione

ApplicationHost.config è il file radice del sistema di configurazione quando si usa IIS 7 e versioni successive. Include le definizioni di tutti i siti, le applicazioni, le directory virtuali e i pool di applicazioni, nonché le impostazioni predefinite globali per le impostazioni del server Web (analogamente a machine.config e ai web.config radice per le impostazioni di .NET Framework).

È anche speciale in quanto è l'unico file di configurazione IIS disponibile quando il server Web è installato (tuttavia, gli utenti possono comunque aggiungere web.config file se lo desiderano). Include una sezione speciale (denominata configSections) per la registrazione di tutte le sezioni IIS e Windows Activation System (WAS) (machine.config ha lo stesso concetto per le sezioni di .NET Framework). Include definizioni per bloccare la maggior parte delle sezioni IIS al livello globale, in modo che per impostazione predefinita non possano essere sottoposte a override da file di livello inferiore web.config nella gerarchia.

Il percorso del file si trova attualmente nella %windir%\system32\inetsrv\config directory . Questo documento illustra tutte le sezioni, nell'ordine in cui vengono visualizzate nel file e le spiega una alla sola. La sezione più complessa è system.webServer, pertanto è consigliabile che il lettore non ignori la lettura della descrizione per tale sezione in particolare.

Tenere presente quanto segue:

  1. Questo documento specifica il contenuto di ogni sezione di configurazione, come visualizzato in applicationHost.config. Per impostazione predefinita, molte delle sezioni sono vuote o non complete (solo alcuni dei relativi contenuti vengono visualizzati nel codice XML). Il resto dei valori viene ricavato dalle impostazioni predefinite dello schema. Questa operazione viene eseguita per evitare troppe informazioni e confusione del file e per mantenerle ragionevolmente leggibili.

    • Per informazioni di riferimento sullo schema completo, inclusi i valori predefiniti per tutte le proprietà in ogni sezione, i relativi intervalli validi e così via, fare riferimento a %windir%\system32\inetsrv\config\schema\IIS\_Schema.xml (per le impostazioni iis) o ASPNET\_Schema.xml (per le impostazioni di ASP.NET) o FX_Schema.xml (per altre impostazioni di .NET Framework).
    • Per praticità, i blocchi di questi file sono inclusi in questo documento nelle sezioni appropriate, in modo che il lettore possa comprendere quali proprietà sono disponibili, quali sono i valori predefiniti e così via, per ogni sezione. Vedere la nota aggiuntiva seguente su come leggere le informazioni sullo schema.

  2. Eseguire un backup del file prima di apportare modifiche.

Come leggere lo schema di configurazione

Come indicato in precedenza, questo documento contiene frammenti di informazioni sullo schema per ogni sezione, in modo che il lettore possa individuare quali proprietà sono disponibili e quali sono i valori predefiniti e gli intervalli validi. I frammenti di codice vengono ricavati direttamente dal file dello schema di configurazione per le impostazioni di IIS: %windir%\system32\inetsrv\config\schema\IIS\_Schema.xml. Questa sezione illustra come leggere le informazioni sullo schema.

Lo schema per ogni sezione di configurazione viene definito in un elemento XML. Non esiste alcuna definizione di schema per i gruppi di sezioni. Il formato seguente viene usato qui per spiegare come leggere lo schema:

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

<attribute-name> è il nome dell'attributo di configurazione, come viene visualizzato in XML. Ogni attributo deve avere un nome.

<default-value> è il valore utilizzato per impostazione predefinita, se non viene specificato alcun altro valore nel codice XML per l'attributo . Non tutti gli attributi hanno valori predefiniti, ad esempio il nome del sito. In questo caso, la sintassi sarà "".

<metadata> contiene diversi elementi:

  • Tipo di runtime dell'attributo. Questo è uno di "bool", "enum", "flags", "int", "int64", "String", "timeSpan". Ogni attributo deve avere un tipo.
  • "bool" è "true" o "false".
  • "enum" è un set di valori possibili, in cui solo uno di essi può essere impostato per l'attributo. Ogni valore di questo tipo ha un valore numerico e un nome descrittivo. La sintassi usa il carattere "|" come delimitatore tra i nomi descrittivi: value1|value2|...|valueN.
  • "flags" è simile a "enum", ad eccezione del fatto che sono consentite combinazioni di valori. Pertanto, i valori numerici devono essere in multipli di 2, in modo che possano essere ORed insieme per formare combinazioni. La sintassi è identica a "enum": value1|value2|...|valueN.
  • "int" è un intero a 32 bit.
  • "int64" è un intero a 64 bit.
  • "String" è una stringa di caratteri.
  • "timeSpan" è una rappresentazione di un'unità temporale, simile al tipo di codice gestito TimeSpan. Può essere persistente come numero (che rappresenta secondi o minuti); o come stringa formattata sotto forma di "[dd:]hh:mm:ss". L'elemento "[dd:]" rappresenta un numero facoltativo di giorni. Gli altri elementi rappresentano rispettivamente il numero di ore, minuti e secondi. L'attributo "timeSpanFormat" specifica il formato da usare: numero di secondi, numero di minuti o stringa formattata.
  • Gli attributi obbligatori sono contrassegnati come "Obbligatorio". Significa che un valore per tali valori deve essere impostato nel codice XML. Ad esempio, il nome del sito è un attributo obbligatorio (ogni sito deve avere un nome in IIS 7.0 e versioni successive).

<description> è una breve descrizione dell'attributo.

Schema sezione

L'elemento <XML sectionSchema> è l'unità di base delle informazioni sullo schema. Tutte le altre informazioni sullo schema vengono specificate al suo interno. Ha un attributo direttamente in esso ("name") e quindi il resto dello schema è in sottoelementi all'interno di esso:

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

Schema degli attributi

Ogni attributo viene definito in un elemento XML corrispondente <attribute> nello schema. L'elemento <attribute> può trovarsi direttamente nell'elemento <sectionSchema> (se l'attributo si trova nell'ambito della sezione) o nell'elemento (se l'attributo si trova in un sottoelemento all'interno della sezione) o nell'elemento <collection> (se l'attributo si trova in una raccolta all'interno della sezione).

Uno schema di attributo deve specificare un nome e un tipo di runtime per l'attributo. Può contrassegnare l'attributo come richiesto. Può contrassegnare l'attributo come chiave univoca (se all'interno di una raccolta) o come parte di una chiave di raccolta (insieme ad altri attributi). Può specificare un valore predefinito per l'attributo . Può contrassegnare l'attributo per la crittografia automatica su disco. Può specificare se la parola "Infinite" è consentita come valore per l'attributo (solo per i tipi numerici come int e in64 e per timeSpan). Può specificare il formato di intervallo di tempo (secondi, minuti o stringa formattata) per gli attributi di intervallo di tempo. Può specificare regole di convalida per gli attributi . Vedere la sezione Convalida degli attributi riportata di seguito in questo documento.

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

Schema degli elementi

Ogni elemento viene definito in un elemento XML corrispondente <element> nello schema. Gli elementi possono essere annidati. Un elemento è semplicemente un contenitore per altri attributi o sottoelementi. Deve avere un nome e può fungere da contenitore di valori predefiniti per gli elementi della raccolta, ad esempio siteDefaults contiene i valori predefiniti per i siti nella <sites> raccolta.

Schema raccolta

Ogni raccolta viene definita in un elemento XML della raccolta> corrispondente <nello schema. Le raccolte contengono più elementi, che possono essere aggiunti e rimossi singolarmente. In genere i nomi delle direttive di raccolta sono "add", "remove" e "clear", ma alcune raccolte usano nomi diversi per maggiore chiarezza (ad esempio, la raccolta usa "site" anziché "add").

Questa operazione viene eseguita specificando i valori per addElement, removeElement e clearElement nello schema della raccolta. Se una direttiva di raccolta non è presente nello schema, la raccolta non la supporterà. Lo schema della raccolta può specificare il nome di un elemento predefinito che verrà usato come contenitore di valori predefiniti per gli elementi della raccolta (questo complemento è isCollectionDefault nello schema dell'elemento).

Ad esempio, la raccolta usa siteDefaults come elemento predefinito. La maggior parte delle raccolte aggiunge elementi mentre uniscono i file di configurazione verso il basso nello spazio dei nomi, ma alcuni possono specificare mergeAppend="false" nello schema per avere un comportamento prepend. Si considerino ad esempio due livelli di configurazione: applicationHost.config e web.config in un sito. In applicationHost.config:

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

In web.config:

<myCollection>

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

Se la raccolta viene aggiunta, la configurazione unita (effettiva) a livello di sito sarà:

<myCollection>

    <add value="1"/>

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

Tuttavia, se antepone, sarà:

<myCollection>

    <add value="2"/>

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

Alcune raccolte possono consentire voci duplicate specificando allowDuplicates="true" nel relativo schema. Questa operazione viene eseguita principalmente per supportare le raccolte legacy in .NET Framework (in machine.config).

Alcune raccolte possono consentire attributi aggiuntivi, oltre a quelli specificati nello schema. Questa operazione viene eseguita specificando allowUnrecognizedAttributes="true" nel relativo schema. Viene eseguita principalmente per supportare le raccolte basate su provider in .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]
/>

Schema enumerazione

Ogni attributo di tipo "enum" deve definire i valori di enumerazione in un elemento XML enumerazione> corrispondente <nello schema. Ogni valore deve avere un nome descrittivo e un valore numerico.

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

Flags Schema

Ogni attributo di tipo "flags" deve definire i valori del flag in un elemento XML corrispondente nello schema. Ogni flag deve avere un nome descrittivo e un valore numerico che può essere ORed insieme ad altri valori per formare combinazioni; pertanto, il valore deve essere in multipli di 2.

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

Convalida degli attributi

La convalida degli attributi viene eseguita durante l'analisi del codice XML per ottenere una sezione dal file e quando si chiama l'API di configurazione per impostare i valori. Se la convalida ha esito negativo, l'operazione desiderata non riesce (ottenendo la sezione o impostando il valore non valido).

Ogni attributo può associare un validator per il relativo valore. A tale scopo, specificare il nome del validator appropriato in validationType e parametri aggiuntivi nello schema dell'attributo validationParameter.

Il sistema supporta questi validator:

Validator ApplicationPoolName

Questo validator ha esito negativo nei caratteri seguenti: |<>&"

validationType="applicationPoolName" validationParameter=""

Validator IntegerRange

Questo validator ha esito negativo se il valore non è compreso nell'intervallo [interno], in numeri interi.

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

Validator NonEmptyString

Questo validator ha esito negativo se il valore stringa è impostato.

validationType="nonEmptyString"
validationParameter=""

Validator SiteName

Questo validator ha esito negativo in questi caratteri: /.?

validationType="siteName"
validationParameter=""

Validator TimeSpanRange

Questo validator ha esito negativo se il valore non è compreso nell'intervallo [interno], in secondi.

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

Validator TrimWhiteSpace

Questo validator ha esito negativo se lo spazio vuoto viene impostato all'inizio o alla fine del valore.

validationType="trimWhiteSpaceString"
validationParameter=""

Intestazione XML

Ogni file di configurazione è un file XML e può facoltativamente includere la riga seguente come prima riga:

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

Inoltre, deve includere tutto il contenuto all'interno di un tag di configurazione> XML<:

<configuration>

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

</configuration>

ApplicationHost.config include le righe sopra riportate. Il resto di questo documento illustra il resto delle sezioni del file.

<configSections> Sezione

Questa è la prima sezione del file. Contiene un elenco di tutte le altre sezioni del file. Questo è il punto di registrazione per le sezioni, ad esempio per annullare la registrazione di una sezione dal sistema, rimuovere la riga da questa sezione, senza dover rimuovere il relativo file di schema dalla directory config\schema.

Si noti che anche altri file di configurazione possono avere una sezione, all'inizio del file. Ciò può essere utile per registrare sezioni a livelli inferiori al livello globale. Queste sezioni verranno registrate solo per l'ambito dello spazio dei nomi. Web.config file possono aggiungere solo sezioni al sistema; non possono ridefinire le sezioni registrate nei livelli padre e non possono rimuovere (annullare la registrazione).

Le sezioni sono strutturate in base alla gerarchia dei gruppi di sezioni contenenti. Ogni registrazione di sezione specifica il nome della sezione; il tipo di codice gestito del gestore della sezione (questo non ha alcun significato in questo file e verrà rimosso dopo beta2, viene usato solo da System.Configuration, quindi sarà ancora presente in machine.config e web.config file); il livello allowDefinition, se è diverso dal valore predefinito; e overrideModeDefault (questo attributo viene usato per bloccare la maggior parte delle sezioni IIS in questo file).

Nota

La sezione è l'unità di base di distribuzione, registrazione, blocco, ricerca e contenimento delle impostazioni di configurazione. Ogni sezione appartiene a un gruppo di sezioni ("padre immediato"). Il gruppo di sezioni è un contenitore di sezioni correlate logicamente e viene usato esclusivamente ai fini della gerarchia strutturata. Nessuna operazione può essere eseguita nei gruppi di sezioni. I gruppi di sezioni non possono avere impostazioni di configurazione direttamente (le impostazioni appartengono alle sezioni). I gruppi di sezioni possono essere annidati; la sezione non può.

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

Blocco

La maggior parte delle sezioni iis è bloccata per impostazione predefinita, usando overrideModeDefault="Deny" nella sezione . Il modo consigliato per sbloccare le sezioni consiste nell'usare i tag, come indicato di seguito:

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

Il tag di posizione precedente sblocca la sezione solo per il sito Web predefinito. Per sbloccarlo per tutti i siti, specificarlo in applicationHost.config:

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

Nota

path="." e path="" hanno lo stesso effetto. Fanno riferimento al livello corrente nella gerarchia.