Freigeben über


Gewusst wie: Erstellen von benutzerdefinierten Konfigurationsabschnitten mit ConfigurationSection

Aktualisiert: November 2007

Sie können die standardmäßigen ASP.NET-Konfigurationseinstellungen durch eigene XML-Konfigurationselemente erweitern. Dazu erstellen Sie einfach einen eigenen Handler für Konfigurationsabschnitte.

Der Handler muss eine .NET Framework-Klasse sein, die die System.Configuration.ConfigurationSection-Klasse implementiert.

Hinweis:

In .NET Framework 1.0 und 1.1 musste ein Konfigurationsabschnittshandler noch die System.Configuration.IConfigurationSectionHandler-Schnittstelle implementieren, die inzwischen als veraltet gilt. Ein Codebeispiel finden Sie dennoch unter Gewusst wie: Erstellen von benutzerdefinierten Konfigurationsabschnitten mit IConfigurationSectionHandler.

Der Abschnittshandler interpretiert und verarbeitet die in den XML-Konfigurationselementen definierten Einstellungen innerhalb eines bestimmten Bereichs einer Datei Web.config und gibt das geeignete, auf den Konfigurationseinstellungen basierende Konfigurationsobjekt zurück. Das von der Handlerklasse zurückgegebene Konfigurationsobjekt kann eine beliebige Datenstruktur darstellen und ist auf keine Basiskonfigurationsklasse bzw. auf kein Konfigurationsformat beschränkt. In ASP.NET werden mithilfe des Konfigurationsobjekts Schreib- und Lesevorgänge für das benutzerdefinierte Konfigurationselement ausgeführt.

So erstellen Sie einen benutzerdefinierten Konfigurationsabschnittshandler:

  1. Erstellen Sie eine öffentliche Klasse, die die System.Configuration.ConfigurationSection-Klasse erbt, wie im folgenden Codebeispiel gezeigt.

    Imports System
    Imports System.Collections
    Imports System.Text
    Imports System.Configuration
    Imports System.Xml
    
    Namespace MyConfigSectionHandler
    
        Public Class MyHandler
            Inherits ConfigurationSection
    
            Public Sub New()
            End Sub
    
            ' Add declarations for child elements and attributes like this:
            '<ConfigurationProperty("<propertyName>", <named parameters>)> _
            'Public Property MyAttrib1() As <type>
            '    Get
            '        Return CStr(Me("<propertyName>"))
            '    End Get
            '    Set(ByVal value As <type>)
            '        Me("<propertyName>") = value
            '    End Set
            'End Property
    
        End Class
    End Namespace
    
    using System;
    using System.Collections;
    using System.Text;
    using System.Configuration;
    using System.Xml;
    
    namespace MyConfigSectionHandler
    {
        public class MyHandler : ConfigurationSection
        {
            public MyHandler()
            {
            }
    
            // Add declarations for child elements and attributes like this:
            // [ConfigurationProperty("<propertyName>", <named parameters>)]
            // public <type> <PropertyName>
            // {
            //     get { return (<type>)this["<propertyName>"]; }
            //     set { this["<propertyName>"] = value; }
            // }
        }
    }
    
  2. Fügen Sie eigenen Code hinzu, um die gewünschte Konfigurationsarbeit durchzuführen.

    Sie können z. B. den kommentierten Code durch den folgenden Code ersetzen, der die Werte aus dem benutzerdefinierten Abschnitt abruft.

    Imports System
    Imports System.Collections
    Imports System.Text
    Imports System.Configuration
    Imports System.Xml
    
    Namespace MyConfigSectionHandler
    
        Public Class MyHandler
            Inherits ConfigurationSection
    
            Public Sub New()
            End Sub
    
            Public Sub New(ByVal attribVal As String)
                MyAttrib1 = attribVal
            End Sub
    
            <ConfigurationProperty("myAttrib1", DefaultValue:="Clowns", IsRequired:=True)> _
            <StringValidator(InvalidCharacters:="~!@#$%^&*()[]{}/;'\|\\", MinLength:=1, MaxLength:=60)> _
            Public Property MyAttrib1() As String
                Get
                    Return CStr(Me("myAttrib1"))
                End Get
                Set(ByVal value As String)
                    Me("myAttrib1") = value
                End Set
            End Property
    
            <ConfigurationProperty("myChildSection")> _
            Public Property MyChildSection() As MyChildConfigElement
                Get
                    Return CType(Me("myChildSection"), MyChildConfigElement)
                End Get
                Set(ByVal value As MyChildConfigElement)
                    Me("myChildSection") = CType(value, MyChildConfigElement)
                End Set
            End Property
        End Class
    
        Public Class MyChildConfigElement
            Inherits ConfigurationElement
    
            Public Sub New()
            End Sub
    
            Public Sub New( _
            ByVal a1 As String, ByVal a2 As String)
                MyChildAttribute1 = a1
                MyChildAttribute2 = a2
            End Sub
    
            <ConfigurationProperty("myChildAttrib1", DefaultValue:="Zippy", IsRequired:=True)> _
            <StringValidator(InvalidCharacters:="~!@#$%^&*()[]{}/;'\|\\", MinLength:=1, MaxLength:=60)> _
            Public Property MyChildAttribute1() As String
                Get
                    Return CStr(Me("myChildAttrib1"))
                End Get
                Set(ByVal value As String)
                    Me("myChildAttrib1") = value
                End Set
            End Property
    
            <ConfigurationProperty("myChildAttrib2", DefaultValue:="Michael Zawondy", IsRequired:=True)> _
            <StringValidator(InvalidCharacters:="~!@#$%^&*()[]{}/;'\|\\", MinLength:=1, MaxLength:=60)> _
            Public Property MyChildAttribute2() As String
                Get
                    Return CStr(Me("myChildAttrib2"))
                End Get
                Set(ByVal value As String)
                    Me("myChildAttrib2") = value
                End Set
            End Property
    
        End Class
    End Namespace
    
    using System;
    using System.Collections;
    using System.Text;
    using System.Configuration;
    using System.Xml;
    
    namespace MyConfigSectionHandler
    {
        public class MyHandler : ConfigurationSection
        {
            public MyHandler()
            {
            }
    
            public MyHandler(String attribVal)
            {
                MyAttrib1 = attribVal;
            }
    
            [ConfigurationProperty("myAttrib1", DefaultValue = "Clowns", IsRequired = true)]
            [StringValidator(InvalidCharacters = "~!@#$%^&*()[]{}/;'\"|\\", MinLength = 1, MaxLength = 60)]
            public String MyAttrib1
            {
                get
                { return (String)this["myAttrib1"]; }
                set
                { this["myAttrib1"] = value; }
            }
    
            [ConfigurationProperty("myChildSection")]
            public MyChildConfigElement MyChildSection
            {
                get
                { return (MyChildConfigElement)this["myChildSection"]; }
                set
                { this["myChildSection"] = value; }
            }
        }
    
        public class MyChildConfigElement : ConfigurationElement
        {
            public MyChildConfigElement()
            {
            }
    
            public MyChildConfigElement(String a1, String a2)
            {
                MyChildAttribute1 = a1;
                MyChildAttribute2 = a2;
            }
    
            [ConfigurationProperty("myChildAttrib1", DefaultValue = "Zippy", IsRequired = true)]
            [StringValidator(InvalidCharacters = "~!@#$%^&*()[]{}/;'\"|\\", MinLength = 1, MaxLength = 60)]
            public String MyChildAttribute1
            {
                get
                { return (String)this["myChildAttrib1"]; }
                set
                { this["myChildAttrib1"] = value; }
            }
    
            [ConfigurationProperty("myChildAttrib2", DefaultValue = "Michael Zawondy", IsRequired = true)]
            [StringValidator(InvalidCharacters = "~!@#$%^&*()[]{}/;'\"|\\", MinLength = 1, MaxLength = 60)]
            public String MyChildAttribute2
            {
                get
                { return (String)this["myChildAttrib2"]; }
                set
                { this["myChildAttrib2"] = value; }
            }
        }
    }
    

    In diesem Beispiel wird das deklarative Modell verwendet. Die System.Configuration.ConfigurationSection-Klasse kann auch mit dem programmgesteuerten Modell implementiert werden. Ein Beispiel finden Sie im Thema zur Übersicht über die System.Configuration.ConfigurationSection-Klasse und unter Klassen zum Erstellen von benutzerdefinierten Abschnittshandlern.

    Um einen Vergleich ziehen zu können, ähnelt dieses Beispiel dem Code in Gewusst wie: Erstellen von benutzerdefinierten Konfigurationsabschnitten mit IConfigurationSectionHandler. Jedoch ermöglicht das Erben von der System.Configuration.ConfigurationSection-Klasse eine genauere Steuerung des Abschnittshandlers. So kann z. B. in der Konfigurationsdatei der nächsten Prozedur ein untergeordnetes Element mit dem Namen myChildSection verwendet werden, für das im vorherigen Code eine ConfigurationProperty deklariert und eine Klasse definiert wird, die sich von ConfigurationElement ableitet. Zusätzlich können durch die Kapselung der Auflistungsfunktionalität in der ConfigurationElementCollection-Klasse auf einfache Weise Auflistungselemente erstellt werden, die Elemente in einer Konfigurationsdatei hinzufügen, entfernen und löschen können. Weitere Informationen und Beispiele finden Sie unter ConfigurationElementCollection.

So fügen Sie einer ASP.NET-Konfigurationsdatei einen benutzerdefinierten Abschnittshandler hinzu:

  1. Fügen Sie der Datei Web.config im configSections-Element ein sectionGroup-Element und ein section-Element hinzu, wie im folgenden Codebeispiel veranschaulicht. Durch diese Deklaration wird der benutzerdefinierte Abschnittshandler dem Abschnittsnamen zugeordnet.

    Hinweis:

    Die Schachtelung eines section-Elements in einer sectionGroup ist zwar optional, wird zur besseren Organisation der Konfigurationsdaten jedoch empfohlen.

    Sie müssen die Abschnittshandlerdeklaration nicht zwangsläufig derjenigen Konfigurationsdatei hinzufügen, der Sie die benutzerdefinierten Konfigurationselemente hinzufügen. Voraussetzung ist jedoch, dass die Konfigurationsdatei, in der der Abschnittshandler deklariert wird, in der Konfigurationsdateihierarchie an höherer Stelle steht. Weitere Informationen hierzu finden Sie unter ASP.NET-Konfigurationsdateihierarchie und Vererbung.

    Das type-Attribut des section-Elements muss mit dem Manifest der Assembly übereinstimmen. Andernfalls tritt ein Konfigurationsfehler auf. Die Assemblydatei selbst muss sich im selben ASP.NET-Anwendungsverzeichnis befinden wie die Datei Web.config, durch die sie definiert ist.

    <configuration>
    
    <!-- Configuration section-handler declaration area. -->
      <configSections>
        <sectionGroup name="myCustomGroup">
          <section 
            name="myCustomSection" 
            type="MyConfigSectionHandler.MyHandler, MyCustomConfigurationHandler, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" 
            allowLocation="true" 
            allowDefinition="Everywhere"
          />
        </sectionGroup>
          <!-- Other <section> and <sectionGroup> elements. -->
      </configSections>
    
      <!-- Configuration section settings area. -->
    
    </configuration>
    
  2. Fügen Sie die benutzerdefinierten Konfigurationselemente dem Bereich mit den Einstellungen für den Konfigurationsabschnitt in der Datei Web.config hinzu.

    <configuration>
    
    <!-- Configuration section-handler declaration area. -->
    
      <!-- Configuration section settings area. -->
      <myCustomGroup>
        <myCustomSection myAttrib1="Clowns">
          <myChildSection 
              myChildAttrib1="Zippy" 
              myChildAttrib2="Michael Zawondy "/>
        </myCustomSection>
      </myCustomGroup>
    
      <!-- Other configuration settings, like <system.web> -->
    
    </configuration>
    

So greifen Sie programmgesteuert auf die benutzerdefinierten Konfigurationsdaten zu:

  • Rufen Sie eine Instanz des benutzerdefinierten Konfigurationsobjekts ab, und füllen Sie diese mithilfe der GetSection-Methode oder der GetSection-Methode auf.

    Das folgende Beispiel einer ASPX-Seite wird in Kombination mit den vorherigen Beispielen zum Auflisten der Attribute und untergeordneten Elemente des benutzerdefinierten Konfigurationsabschnitts verwendet.

    <%@ Page Language="C#" %>
    
    <script >
        protected void Button1_Click(object sender, EventArgs e)
        {
            MyConfigSectionHandler.MyHandler config =
                (MyConfigSectionHandler.MyHandler)System.Configuration.ConfigurationManager.GetSection(
                "myCustomGroup/myCustomSection");
    
            StringBuilder sb = new StringBuilder();
    
            sb.Append("<h2>Attributes in the myCustomSection Element:</h2>");
            sb.AppendFormat("myAttrib1 = {0}<br/>", config.MyAttrib1.ToString());
            sb.Append("<h2>Attributes in the myChildSection Element:</h2>");
            sb.AppendFormat("myChildAttrib1 = {0}<br/>", config.MyChildSection.MyChildAttribute1.ToString());
            sb.AppendFormat("myChildAttrib2 = {0}<br/>", config.MyChildSection.MyChildAttribute2.ToString());
    
            Label1.Text = sb.ToString();
            Label1.Visible = true;
        }
    </script>
    
    <html xmlns="http://www.w3.org/1999/xhtml" >
    <head >
        <title>Untitled Page</title>
    </head>
    <body>
        <form id="form1" >
        <div>
    
        <h1>Enumerate MyCustomSection</h1>
        <asp:Label ID="Label1"  
            Text="" />
        <br />
        <asp:Button ID="Button1"  
            Text="Get Custom Config Info" 
            OnClick="Button1_Click" />
    
        </div>
        </form>
    </body>
    </html>
    
    <%@ Page Language="VB" %>
    
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    
    <script >
        Protected Sub Button1_Click(ByVal sender As Object, ByVal e As System.EventArgs)
            Dim config As New MyConfigSectionHandler.MyHandler
            config = _
                System.Configuration.ConfigurationManager.GetSection("myCustomGroup/myCustomSection")
            Dim sb As New StringBuilder
            sb.Append("<h2>Attributes in the myCustomSection Element:</h2>")
            sb.AppendFormat("myAttrib1 = {0}<br/>", config.MyAttrib1.ToString())
            sb.Append("<h2>Attributes in the myChildSection Element:</h2>")
            sb.AppendFormat("myChildAttrib1 = {0}<br/>", config.MyChildSection.MyChildAttribute1.ToString())
            sb.AppendFormat("myChildAttrib2 = {0}<br/>", config.MyChildSection.MyChildAttribute2.ToString())
    
            Label1.Text = sb.ToString()
            Label1.Visible = True
    
        End Sub
    </script>
    
    <html xmlns="http://www.w3.org/1999/xhtml" >
    <head >
        <title>Untitled Page</title>
    </head>
    <body>
        <form id="form1" >
        <div>
    
        <h1>Enumerate MyCustomSection</h1>
        <asp:Label ID="Label1"  
            Text=""/>
        <br />
        <asp:Button ID="Button1"  
            Text="Get Custom Config Info" 
            OnClick="Button1_Click" />
    
        </div>
        </form>
    </body>
    </html>
    

Siehe auch

Konzepte

Struktur der ASP.NET-Konfigurationsdatei (Abschnitte und Abschnittshandler)

Übersicht über die ASP.NET-Konfiguration

Weitere Ressourcen

Verwalten von ASP.NET-Websites

Konfigurieren von .NET Framework-Anwendungen