Gewusst wie: Erstellen von benutzerdefinierten Konfigurationsabschnitten mit ConfigurationSection

Artikel
10/22/2014

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:

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; }
        // }
    }
}

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:

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>


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

  

</configuration>
```

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

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

Freigeben über