section-Element für configSections (allgemeines Einstellungsschema)

Artikel
09/03/2008

Aktualisiert: November 2007

Definiert eine Zuordnung zwischen einem Konfigurationsabschnittshandler und einem Konfigurationselement.

configuration-Element (allgemeines Einstellungsschema)
  configSections-Element (allgemeines Einstellungsschema)
    section-Element für configSections (allgemeines Einstellungsschema)
      configuration-Element (allgemeines Einstellungsschema)
        configSections-Element (allgemeines Einstellungsschema)
          sectionGroup-Element für configSections (allgemeines Einstellungsschema)
            section-Element für configSections (allgemeines Einstellungsschema)

<section 
   name="section name"
   type="configuration section handler class, assembly file name, version, culture, public key token"
   allowDefinition= "Everywhere|MachineOnly|MachineToApplication|MachineToWebRoot" 
   allowLocation="True|False" 
   restartOnExternalChanges="True|False" 
/>

Attribute und Elemente

In den folgenden Abschnitten werden Attribute, untergeordnete Elemente sowie übergeordnete Elemente beschrieben.

Attribute

Attribut

Beschreibung

allowDefinition

Optionales Enum-Attribut.

Gilt nur für ASP.NET-Anwendungen.

Gibt an, in welcher Konfigurationsdatei der Abschnitt verwendet werden kann.

Dieses Attribut kann einen der in der ConfigurationAllowDefinition-Enumeration definierten Werte annehmen, die im Folgenden nach abnehmendem Gültigkeitsbereich aufgeführt sind.

Wert	Beschreibung
Everywhere	Ermöglicht die Konfiguration des Abschnitts in jeder der folgenden Konfigurationsdateien und in jedem der folgenden Verzeichnisse: Machine.config Stammdatei Web.config Web.config einer Anwendung Virtuelles Verzeichnis physisches Unterverzeichnis der Anwendung Wenn das allowDefinition-Attribut nicht angegeben wird, wird Everywhere angenommen. Dies ist die Standardeinstellung.
MachineToApplication	Ermöglicht die Konfiguration des Abschnitts in einer der folgenden Dateien: Machine.config Stammdatei Web.config Web.config einer Anwendung Dies schließt alle Dateien Web.config aus, die sich in virtuellen Verzeichnissen oder in einem physischen Unterverzeichnis der Anwendung befinden.
MachineToWebRoot	Ermöglicht die Konfiguration des Abschnitts in einer der folgenden Dateien: Machine.config Stammdatei Web.config Sowohl die Datei Machine.config als auch die Stammdatei Web.config befinden sich in %SystemRoot%\Microsoft.NET\Framework\versionNumber\CONFIG.
MachineOnly	Ermöglicht die Konfiguration des Abschnitts nur in der Datei Machine.config, die sich in %SystemRoot%\Microsoft.NET\Framework\versionNumber\CONFIG befindet.

allowExeDefinition

Optionales Enum-Attribut.

Gilt nur für .NET Framework-Clientanwendungen.

Gibt an, in welcher Konfigurationsdatei der Abschnitt verwendet werden kann.

Dieses Attribut kann einen der in der ConfigurationAllowExeDefinition-Enumeration definierten Werte annehmen, die im Folgenden nach abnehmendem Gültigkeitsbereich aufgeführt sind.

Wert	Beschreibung
MachineToApplication	Ermöglicht die Konfiguration des Abschnitts in einer der folgenden Dateien: Machine.config Anwendungskonfiguration
MachineToRoamingUser
MachineToLocalUser
MachineOnly	Ermöglicht die Konfiguration des Abschnitts nur in der Datei Machine.config, die sich in %SystemRoot%\Microsoft.NET\Framework\versionNumber\CONFIG befindet.

allowLocation

Optionales Boolean-Attribut.

Gilt nur für ASP.NET-Anwendungen.

Gibt an, ob der Abschnitt innerhalb des location-Elements verwendet werden kann.

Der Standardwert ist True.

name

Erforderliches String-Attribut.

Gibt den Namen des Konfigurationsabschnitts oder -elements an, der/das dem im type-Attribut angegebenen Konfigurationsabschnittshandler zugeordnet ist. Der Elementname muss genau so angegeben werden, wie er auch im Bereich der Abschnittseinstellungen der Konfigurationsdatei verwendet wird.

restartOnExternalChanges

Optionales Boolean-Attribut.

Gilt nicht für ASP.NET-Anwendungen.

Gibt an, ob bei Änderungen der Konfigurationsdaten für den Abschnitt ein Neustart der Anwendung vorgenommen werden soll.

type

Erforderliches String-Attribut.

Gibt den Namen der Konfigurationsabschnitts-Handlerklasse für die Verarbeitung der Konfigurationseinstellungen an, die in dem im name-Attribut angegebenen Abschnitt oder Element enthalten sind. Verwenden Sie folgendes Format:

type="Vollqualifizierter Klassenname, Name der Assemblydatei, version, Kultur, öffentliches Schlüsseltoken"

Die Definition muss mit dem Assemblyverweis übereinstimmen. Wenn beispielsweise die in der folgenden Beispielsyntax angegebene Versionsnummer nicht mit der Assembly übereinstimmt, tritt ein Fehler auf.

type="MyConfigSectionHandler.MyHandler,MyCustomConfigurationHandler,Version=1.0.0.0,Culture=neutral,PublicKeyToken=null"

Die Assemblydatei muss sich in demselben Anwendungsverzeichnis wie die Datei Web.config befinden, durch die sie definiert ist. Falls es sich dabei um die Stammdatei Web.config oder die Datei Machine.config handelt, muss sich die Assemblydatei in %SystemRoot%\Microsoft.NET\Framework\Version befinden.

Untergeordnete Elemente

Keine.

Übergeordnete Elemente

Element	Beschreibung
configuration	Gibt das erforderliche Stammelement in jeder Konfigurationsdatei an, die von der Common Language Runtime und den .NET Framework-Anwendungen verwendet wird.
configSections	Legt Konfigurationsabschnitts- und Namespacedeklarationen fest.
sectionGroup	Definiert eine Zuordnung zwischen einem Konfigurationsabschnittshandler und einem Konfigurationsabschnitt.

Hinweise

Ein section-Element stellt die Zuordnung zwischen einem Konfigurationsabschnittshandler und einem Konfigurationselement oder -abschnitt her. Dies ist erforderlich, da ASP.NET keine Annahmen zur Behandlung der Einstellungen in einer Konfigurationsdatei trifft. Stattdessen überlässt ASP.NET die Verarbeitung der Konfigurationsdaten den Konfigurationsabschnittshandlern. Jedes section-Element bezeichnet einen Konfigurationsabschnitt oder ein Konfigurationselement sowie die zugeordnete Klasse, die von ConfigurationSection abgeleitet ist und den Konfigurationsabschnitt oder das Konfigurationselement bearbeitet. Die section-Elemente können mithilfe von sectionGroup-Elementen logisch gruppiert werden, um sie zu ordnen und Namenskonflikte zu vermeiden. Das section-Element und das sectionGroup-Element sind im configSections-Element enthalten.

Standardkonfiguration

Die Konfigurationsabschnitte für die .NET Framework-Konfigurationselemente werden in der Datei Machine.config definiert und sind zu zahlreich, um an dieser Stelle aufgelistet zu werden. Im folgenden Ausschnitt aus der Datei Machine.config wird der Konfigurationsabschnittshandler für das authentication-Element des system.web-Abschnitts definiert. Anschließend werden die Konfigurationseinstellungen für das authentication-Element festgelegt.

Wenn ein Konfigurationsabschnittshandler keinem Konfigurationselement zugeordnet wurde, zeigt ASP.NET den Serverfehler "Unbekannter Konfigurationsabschnitt element_name" an.

<configuration>
    <configSections>
        <sectionGroup name="system.web" type="System.Web.Configuration.SystemWebSectionGroup, System.Web, Version=%ASSEMBLY_VERSION%, Culture=neutral, PublicKeyToken=%MICROSOFT_PUBLICKEY%">
            <section name="authentication" type="System.Web.Configuration.AuthenticationSection, System.Web, Version=2.0.3600.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" allowDefinition="MachineToApplication" />
            <!-- Other system.web sections -->
        </sectionGroup>
        <!-- Other configuration sections -->
    </configSections>

    <system.web>
        <authentication mode="Windows">
            <forms name=".ASPXAUTH" 
                   loginUrl="login.aspx" defaultUrl="default.aspx" 
                   protection="All" 
                   timeout="30" 
                   path="/" 
                   requireSSL="False" 
                   slidingExpiration="True" 
                   cookieless="UseCookies" 
                   domain="" 
                   enableCrossAppRedirects="False">
                <credentials passwordFormat="SHA1" />
            </forms>
            <passport redirectUrl="internal" />
        </authentication>
        <!-- Other system.web elements -->
    </system.web>
    <!-- Other configuration settings -->
</configuration>

Beispiel

Das folgende Codebeispiel veranschaulicht das Einrichten eines benutzerdefinierten Konfigurationsabschnitts und das Festlegen der Einstellungen für diesen Abschnitt.

<configuration>

   <configSections>
      <section name="sampleSection"
               type="System.Configuration.SingleTagSectionHandler" />
   </configSections>

   <sampleSection setting1="Value1" 
                  setting2="value two" 
                  setting3="third value" />

</configuration>

Elementinformationen

Konfigurationsabschnittshandler	Nicht vorhanden.
Konfigurationsmember	ConfigurationSection
Konfigurierbare Speicherorte	Machine.config Web.config auf der Stammebene Web.config auf der Anwendungsebene Web.config auf der Ebene virtueller oder physischer Verzeichnisse
Anforderungen	Microsoft Internetinformationsdienste (IIS), Version 5.0, 5.1 oder 6.0 .NET Framework, Version 1.0, 1.1 oder 2.0 Microsoft Visual Studio 2003 oder Visual Studio 2005

Siehe auch

Freigeben über