14.3 Die Konfigurationskaskade mit machine.config und web.config 

ASP.NET bietet ein hierarchisches Konfigurationsschema. Die erste Konfigurationsdatei, die ASP.NET stets auswertet, heißt machine.config. Sie liegt im Verzeichnis C:\WINNT\Microsoft.NET\Framework\v1.0.3705\CONFIG, wobei die Laufwerksbezeichnung und der Pfadanteil, der die Version enthält, gegebenenfalls angepasst werden müssen.

Ihre eigene Anwendung können Sie mit Hilfe der Datei web.config steuern, die genauso aufgebaut ist wie die zentrale Datei machine.config. Wenn Sie eine Datei web.config im Stammverzeichnis Ihrer Anwendung erstellt haben, gelten diese Angaben für die gesamte Anwendung einschließlich aller Unterverzeichnisse. Sie können in Unterverzeichnissen Ihrer Anwendung außerdem weitere web.config-Dateien anlegen, die dann nur für dieses Unterverzeichnis und alle darunter liegenden Verzeichnisse gelten. Jedes Verzeichnis kann maximal eine web.config enthalten.

Diese Kaskade, die bei machine.config beginnt und sich mehrstufig über mehrere Ebenen von web.config-Dateien erstrecken kann, funktioniert nach dem Prinzip der Vererbung. Wenn eine web.config bestimmte Angaben nicht enthält, gelten die Angaben der nächsthöheren Konfigurationsdatei. Wenn ein Entwickler eine eigene web.config erstellt, wird er in dieser Datei in der Regel nur wenige Angaben machen, nämlich nur die, bei denen er von den Standardvorgaben der machine.config abweicht. Den ganzen Rest muss er nicht noch einmal in die web.config schreiben. Die übrigen Konfigurationseinstellungen erbt die Anwendung von machine.config.

machine.config und web.config sind reine XML-Dateien. machine.config und web.config sind außerdem identisch aufgebaut. machine.config ist sozusagen nur eine web.config-Datei mit dem besonderen Namen machine.config und ihrem besonderen Ort, an dem sie gespeichert ist. Im Folgenden ist deswegen nur noch von der Datei web.config die Rede. Alle Aussagen gelten aber genauso für die machine.config.

14.3.1 Konfiguration von virtuellen und von physikalischen Verzeichnissen 

Ihr Anwendungsstammverzeichnis heißt myApp. Im Verzeichnis myApp legen Sie eine web.config an. Wenn Sie http://localhost/myApp aufrufen, gelten die Konfigurationsangaben dieser lokalen web.config.

myApp enthält ein Verzeichnis myDir. Wenn Sie im Browser Daten aus http://localhost/myApp/myDir aufrufen, gelten die Angaben der web.config, die im Verzeichnis myApp liegt, auch für das Verzeichnis myDir. Das ist das Prinzip der Vererbung, das bei web.config gilt.

Tückisch wird es dann, wenn Sie auf die Idee kommen sollten, das Verzeichnis myDir über das virtuelle Verzeichnis myVirtual zugänglich zu machen. Wenn Sie dann im Browser http://localhost/myVirtual aufrufen, dann gelten die Angaben aus der web.config im Verzeichnis myApp nicht. Da der virtuelle Pfad in diesem Fall erst im physikalischen Verzeichnis myDir beginnt, wertet ASP.NET web.config-Dateien erst ab dem Verzeichnis myDir aus.

14.3.2 Das Format von web.config 

web.config ist eine reine XML-Datei. Abgesehen von der XML-Direktive in der ersten Zeile und den eingefügten Kommentaren besteht web.config also ausschließlich aus Elementen und deren Attributen.

Beim Umgang mit der Datei web.config spricht man für die leichtere Orientierung nicht von Elementen, sondern von Abschnitten und Abschnittsgruppen. Eine Abschnittsgruppe ist ein XML-Element, das die einzelnen Abschnitte in Form eigener XML-Elemente enthält. Abschnitt ist die Übersetzung der englischen section und Abschnittsgruppe ist äquivalent zur sectionGroup.

Kamelnotation

Achten Sie beim Erstellen einer web.config-Datei darauf, dass Groß- und Kleinschreibung signifikant sind. Das ist XML-Standard. Die Schreibung der Abschnittsbezeichnungen der web.config entsprechen der so genannten Kamelnotation. Die Namen beginnen mit einem kleinen Buchstaben und haben zwischendrin große Buchstaben. Damit ergibt sich das Bild eines Kamels: Der Kopf bildet den Anfang und hängt nach unten. Der oder die Höcker ragen in die Höhe, so wie etwa in sessionState oder channelSinkProviders.

14.3.3 Der Aufbau von web.config 

Der Inhalt von web.config zerfällt in zwei Teile. Der erste Teil ist der Abschnitt configSections. Hier wird festgelegt, welche Konfigurationsabschnitte (sections) und Abschnittsgruppen es überhaupt gibt und welche Klassen welche Abschnitte auswerten. Damit bietet configSections so etwas wie ein Inhaltsverzeichnis von web.config.

Der übrige Teil von web.config enthält die eigentlichen Konfigurationsangaben. Hier gibt es zwei große Abschnittsgruppen und einzelne Einträge, die keinen Abschnittsgruppen zugeordnet sind. Die Abschnittsgruppe system.web enthält Angaben, die speziell ASP.NET betreffen, und in system.net liegen allgemeine .NET-Laufzeit-Konfigurationseinstellungen. Damit hat web.config folgenden grundlegenden Aufbau:

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

   <configSections>
      ' Deklaration der Handler
   </configSections>

   ' ...
   ' Abschnitte, die zu keiner Gruppe gehören
   ' ...

   ' system.web bildet eine eigene Abschnittsgruppe
   <system.web>
      ' ASP.NET-Konfiguration
   </system.web>

   ' auch system.net ist eine Abschnittsgruppe   
   <system.net>
      ' Konfiguration der Laufzeitumgebung
   </system.net>   

</configuration>

Die Reihenfolge der Abschnitte spielt dabei keine Rolle. Das gilt auch für configSections. Die Abschnitte, die hier definiert werden, müssen anschließend nicht in der gleichen Reihenfolge auftreten, in der sie in configSections definiert werden.

Der Abschnitt configSections enthält selbst keine Einstellungen für die Konfigurationsparameter x oder y, sondern bildet eine Art Meta-Abschnitt, der die möglichen Abschnitte beschreibt. Auf diese Weise lassen sich leicht weitere Konfigurationsabschnitte ergänzen. Ein Entwickler kann eigene Konfigurationsabschnitte definieren und auch festlegen, welche Klasse welche Konfigurationsabschnitte auswertet.

Im Abschnitt 14.3.5, Eigene Konfigurationen erstellen, wird demonstriert, wie Sie eigene Konfigurationsabschnitte definieren können. Dabei haben Sie nicht nur die Möglichkeit, einfache Schlüssel-Wert-Paare zu definieren, sondern Sie können mit Hilfe eines Schlüssels Objekte beliebigen Typs aus der Konfiguration beziehen.

Die Abschnittsgruppe system.net enthält in den Abschnitten defaultProxy, webRequestModules, authenticationModules und connectionManagement Angaben zur .NET-Laufzeitumgebung. Diese Abschnittsgruppe wird hier nicht näher erläutert.

Tabelle 14.2 verzeichnet die Konfigurationsabschnitte, die in der Abschnittsgruppe system.web standardmäßig verfügbar sind. Einige dieser Abschnitte werden im Anschluss näher vorgestellt.

Tabelle 14.2 Konfigurationsabschnitte im Abschnitt web.config

14.3.4 Konfigurationsabschnitte 

customErrors

<configuration>   
   <system.web>
      <customErrors defaultRedirect="url"
                    mode="On|Off|RemoteOnly">
         <error statusCode="statuscode"
                redirect="url"/>
      </customErrors>
   </system.web>
</configuration>

Der Abschnitt customErrors wird unterhalb des Abschnitts system.web platziert. Im Abschnitt customErrors definieren Sie die Reaktionsweise Ihrer Applikation bei Fehlern. Sie legen fest, welche selbst erstellte Seite im Fehlerfall aufgerufen wird. Für verschiedene Fehlerarten können Sie unterschiedliche Seiten definieren.

Das Element customErrors hat die Attribute defaultRedirect und mode. In defaultRedirect geben Sie die Seite an, die bei einem Fehler standardmäßig angezeigt werden soll, z. B. defaultRedirect="myError.aspx". In mode wählen Sie eine von drei Funktionsweisen. mode="on" schaltet die individuelle Fehlerbehandlung ein. mode="off" schaltet die individuelle Fehlerbehandlung aus.

Für einzelne Fehler können Sie mit dem error-Element außerdem spezielle Fehlerseiten vorsehen. Im Attribut statusCode geben Sie die Fehlernummer an, auf die reagiert werden soll, und im Attribut redirect die anzuzeigende Seite. Ein Beispiel:

<system.web>
  <customErrors mode="On" defaultRedirect="error.aspx">
     <error statusCode="404" redirect="error404.aspx"/>
  </customErrors>
</system.web>

Wenn eine aspx-Seite nicht gefunden werden kann, tritt der Fehler 404 auf. In diesem Fall wird die Seite error404.aspx angezeigt. Bei allen anderen Fehlern wird die Seite error.aspx angezeigt.

ASP.NET übergibt den virtuellen Pfad der Datei, die den Fehler ausgelöst hat, an Ihre selbst definierte Fehlerseite mit dem Parameter aspxerrorpath. Wenn beispielsweise die Seite hh.aspx nicht gefunden werden konnte, lautet der vollständige URL für die Anzeige der Fehlermeldung:

http://localhost/Testweb/error404.aspx?aspxerrorpath=/Testweb/hh.aspx

Auf diese Weise steht Ihnen innerhalb Ihrer selbst definierten Fehlerbehandlungsseite der Name der fehlerhaften Seite zur Verfügung. error404.aspx könnte beispielsweise diesen Code enthalten:

<h1>Seite nicht gefunden</h1>
<% = Request.QueryString("aspxerrorpath") %> 
konnte nicht gefunden werden.

pages

<pages buffer="true|false" 
       enableSessionState="true|false|ReadOnly"
       enableViewState="true|false"
       enableViewStateMac="true|false"
       autoEventWireup="true|false"
       smartNavigation="true|false"
       pageBaseType="typename, assembly"
       userControlBaseType="typename" />

Im pages-Abschnitt geben Sie seitenspezifische Konfigurationseinstellungen an. buffer schaltet die Antwortpufferung ein oder aus. enableSessionState kann den Sitzungsstatus einschalten, ausschalten oder auf Nur Lesen einstellen. enableViewState steuert, ob der Viewstate ein- oder ausgeschaltet ist. Bei dem Attribut enableViewStateMac steht das Mac für Machine Authentication Check. Standardmäßig steht der Wert auf false. Wenn er auf true gesetzt wird, findet eine zusätzliche Authentifizierungsüberprüfung statt, um erkennen zu können, ob die verborgenen Variablen, die den Anzeigestatus enthalten, modifiziert wurden. autoEventWireup regelt, ob Seitenereignisse automatisch weitergeleitet werden oder nicht. smartNavigation stellt die Unterstützung für die »intelligente Navigation« ein oder ab. pageBaseType gibt eine Code-Behind-Klasse an, die aspx-Seiten standardmäßig erben. userControlBaseType gibt eine Code-Behind-Klasse an, die Benutzersteuerelemente standardmäßig erben.

Die Werte aus dem pages-Abschnitt bilden die Voreinstellungen für alle aspx-Seiten. Die Page-Direktive der einzelnen Seite kann diese Voreinstellungen überschreiben.

sessionState

<sessionState mode="Off|Inproc|StateServer|SQLServer"
              cookieless="true|false"
              timeout="Anzahl Minuten"
              stateConnectionString="tcpip=server:port"
              sqlConnectionString="connection string" />

Im Abschnitt sessionState regeln Sie die Sitzungsverfolgung. Mit dem mode-Attribut können Sie die Sitzungsverfolgung ausschalten oder eine von drei Varianten auswählen: Inproc führt die Sitzungsverfolgung im Prozessraum des Webservers aus. Diese Option bietet die größte Performance. Mit mode="StateServer" verwenden Sie einen eigenen Server für die Sitzungsverfolgung. In diesem Fall müssen Sie bei stateConnectionString nähere Angaben machen. Mit mode="SQLServer" verwenden Sie einen SQL Server für die Sitzungsverfolgung und geben mit sqlConnectionString die benötigten Verbindungsdaten an. Die Sitzungsverfolgung kann über das Attribut cookieless mit oder ohne Cookies realisiert werden. timeout regelt die Zeit, nach der eine Sitzung verfällt.

Weitere Hinweise zur Verwendung der einzelnen Attribute finden Sie in Kapitel 11, Der Status von Seiten, Sitzungen und Applikationen.

location

Ein location-Abschnitt steht in der Hierarchie direkt unterhalb des configuration-Abschnitts, ist also nicht Teil des Konfigurationsabschnitts system.web.

Ein location-Abschnitt bietet die Möglichkeit, Konfigurationseinstellungen für einzelne Dateien oder Verzeichnisse vorzunehmen. Hierfür steht das Attribut path zur Verfügung. Im path-Attribut können Sie eine einzelne Datei oder ein Verzeichnis angeben. Wenn sich die Konfigurationseinstellungen eines location-Abschnitts auf ein Verzeichnis beziehen, dann hat dieser location-Abschnitt den gleichen Effekt, den eine web.config-Datei in diesem Verzeichnis hätte.

<configuration>
   <location path="myDir">
      <system.web>
         <authorization>
            <deny users="?" />
         </authorization>
      </system.web>
   </location>
</configuration>

Diese Konfiguration verhindert den Zugriff anonymer Anwender auf das Verzeichnis myDir.

Weil ein location-Abschnitt im Prinzip wie eine eigene web.config funktioniert, ist der Inhalt eines location-Abschnitts auch so aufgebaut wie eine web.config. Im Beispiel erkennen Sie, dass innerhalb des location-Abschnitts ein eigener system.web-Abschnitt beginnt, der dann entsprechende Abschnitte wie etwa den authorization-Abschnitt enthält.

14.3.5 Eigene Konfigurationen erstellen 

Ein Entwickler hat zwei Möglichkeiten, in der web.config eigene Angaben zu speichern. Im Abschnitt appSettings kann er eigene Schlüssel-Wert-Paare ergänzen. Außerdem besteht die Möglichkeit, eigene Abschnitte zu definieren und dabei auch einen individuellen Rückgabetyp festzulegen. Im Folgenden werden beide Möglichkeiten erläutert.

appSettings

Das appSettings-Element wird direkt unterhalb des configuration-Elements platziert. Im Konfigurationsabschnitt appSettings definieren Sie eigene Anwendungseinstellungen, indem Sie Elemente vom Typ add hinzufügen. Ein add-Element hat die Attribute key und value. Ein Beispiel:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
   ...
   <appSettings>
      <add key="Versionsnummer" value="1.00e" />
   </appSettings>
   ...   
</configuration>

Hiermit definieren Sie den Schlüsselwert Versionsnummer mit dem Wert 1.00e. Innerhalb Ihres Codes rufen Sie den Wert mit folgendem Ausdruck ab:

ConfigurationSettings.AppSettings("Versionsnummer")

Eigene Abschnitte definieren

Wenn Sie Einträge im appSettings-Abschnitt machen, können Sie nur Werte vom Typ String zurückgeben. ASP.NET bietet Ihnen eine weiter gehende Möglichkeit, eigene Konfigurationseinträge festzulegen. Sie können für web.config eigene Abschnitte definieren und dabei festlegen, wie ASP.NET die Inhalte dieser Abschnitte auswertet.

Dieses Verfahren lässt sich am besten an einem Beispiel demonstrieren. In Ihrer Webanwendung möchten Sie eine Nachricht des Tages verwenden. Diese Nachricht wird täglich aktualisiert und auf der Startseite angezeigt. In web.config möchten Sie festlegen, in welcher Datei ASP.NET diese Nachricht findet. Im Prinzip ließe sich das auch über einen Eintrag unter appSettings realisieren, indem Sie hier etwa über den Schlüssel NachrichtDesTages den jeweiligen Pfad zugänglich machen würden. Sie möchten es aber noch bequemer haben. Ihre Konfigurationseinstellung soll nicht den Dateipfad zurückgeben, sondern sofort ein Objekt vom Typ StreamReader.

In web.config benötigen Sie also etwa folgenden Eintrag:

<NachrichtDesTages file="c:\motd.txt" />

Das Problem ist nur, dass ASP.NET einen Abschnitt NachrichtDesTages zunächst nicht kennt und auch nicht weiß, dass es die angegebene Datei als StreamReader-Objekt zur Verfügung stellen soll.

Dafür müssen Sie ASP.NET Ihre Wünsche ausdrücklich mitteilen. Im Abschnitt <configuration><configSections><sectionGroup name="system.web" > definieren Sie mit einem <section>-Element Ihren eigenen Abschnitt, etwa so:

<configuration>   
   <configSections>
      <sectionGroup name="system.web" >
         <section name="NachrichtDesTages" 
                  type="meineAbschnittshandler.
          NachrichtDesTages, meineAbschnittshandler" />
      </sectionGroup>
   </configSections>
 <configuration>

Das name-Attribut des section-Elements legt den Namen fest, unter dem Ihr Konfigurationselement in web.config verwendet wird, das ist hier NachrichtDesTages. Das type-Attribut legt zwei Dinge fest (beachten Sie das Komma in dem String, der dem Attribut type zugewiesen wird): Zunächst legt es den Namen der Klasse einschließlich Namespace fest, die den Abschnitts-Handler enthält. Das soll hier meineAbschnittshandler.NachrichtDesTages sein. Und diese Klasse ist enthalten in der Assembly meineAbschnittshandler. Diese Information steht nach dem Komma. ASP.NET weiß, dass eine Assembly in einer entsprechenden Datei mit der Ergänzung dll enthalten ist.

Und nun müssen Sie noch diese Klasse meineAbschnittshandler.NachrichtDesTages erstellen.

Einen eigenen Abschnitts-Handler erstellen

Wenn Sie eine Klasse für Ihren eigenen Abschnitts-Handler erstellen, muss diese Klasse die Schnittstelle IConfigurationSectionHandler unterstützen. Diese Schnittstelle erfordert die Implementierung einer entsprechenden create-Methode. Als äußerer Rahmen für Ihre Klasse ergibt sich damit diese Form.

Imports System
Imports System.Configuration
Imports System.Xml

Namespace meineAbschnittshandler
   Public Class NachrichtDesTages
      Implements IConfigurationSectionHandler

      Public Function Create ( _
         ByVal parent As Object, _
         ByVal configContext As Object, _
         ByVal section As XmlNode) _
         As Object _
         Implements IConfigurationSectionHandler.Create
         
         '  ... Ihr individueller Code ...
         return x ' das Objekt, das zurückgegeben wird
          
      End Function    
   End Class 
End Namespace

Den Namen des Namespace können Sie beliebig wählen. Worauf es ankommt, ist der Hinweis Implements IConfigurationSectionHandler bei der Klassendefinition. Außerdem muss die Funktion Create mit der hier gezeigten Signatur und dem Hinweis Implements IConfigurationSectionHandler.Create definiert werden.

Ihre Klasse soll ein StreamReader-Objekt von der Datei zurückgeben, die bei der Konfiguration von NachrichtDesTages im Attribut file angegeben wird. Sie erinnern sich daran, wie der Abschnitt aussehen soll:

<NachrichtDesTages file="c:\motd.txt" />

Die Datei meineAbschnittshandler.vb realisiert diese Anforderung:

' meineAbschnittshandler.vb
Imports System
Imports System.Configuration
Imports System.Xml

Namespace meineAbschnittshandler
   Public Class NachrichtDesTages
      Implements IConfigurationSectionHandler

      Public Function Create ( _
         ByVal parent As Object, _
         ByVal configContext As Object, _
         ByVal section As XmlNode) _
         As Object _
         Implements IConfigurationSectionHandler.Create
         
         Dim datnam As String
         datnam = section.Attributes.Item(0).Value
         
         Dim reader As System.IO.StreamReader
         reader = new System.IO.StreamReader (datnam)
         
         return reader 
          
      End Function    
   End Class 
End Namespace

Die Funktion greift über die Eigenschaft Attributes auf das Attribut file zu. Nachdem die Funktion das gewünschte StreamReader-Objekt erzeugt hat, gibt sie das Objekt mit return reader zurück.

Kompilieren Sie diese Klasse mit folgendem Aufruf:

vbc /t:library /out:../bin/meineAbschnittshandler.dll /r:System.dll  
/r:System.xml.dll meineAbschnittshandler.vb

Je nachdem, wo Ihre Quelldatei liegt, müssen Sie den /out-Parameter so anpassen, dass die zu erzeugende dll-Datei im /bin-Verzeichnis der Webanwendung erstellt wird.

Wenn Sie so weit sind, bleibt nur noch die Aufgabe, die selbst erstellte Konfiguration aus einer aspx-Seite heraus aufzurufen. Hier ein entsprechendes Code-Fragment:

Dim myObject As Object
Dim myStream As System.IO.StreamReader
myObject = ConfigurationSettings.GetConfig _
                   ("system.web/NachrichtDesTages")
myStream = CType (myObject, System.IO.StreamReader)   
ausgabe.innerText = myStream.ReadToEnd()

Die zentrale Zeile ist

myObject = ConfigurationSettings.GetConfig _
                   ("system.web/NachrichtDesTages")

Hier wird die Konfiguration des Abschnitts system.web/NachrichtDesTages ausgelesen. Die Methode GetConfig gibt stets ein Objekt vom Typ Object zurück. Im Rahmen des Codes erfolgt daher eine ausdrückliche Umwandlung des zurückgegebenen Objekts in den Typ StreamReader.

14.3.6 Vorteile der hierarchischen Konfiguration 

Der entscheidende Vorteil der Konfiguration mit Hilfe der web.config-Dateien besteht darin, dass sich auch ein remote stehender Webserver auf diese Weise denkbar einfach steuern lässt. Wenn Sie FTP-Zugriff auf die Website haben, können Sie durch einfaches Austauschen der web.config-Dateien problemlos die Konfiguration anpassen. Durch diese Änderung wird die Webanwendung außerdem neu gestartet.