Практическое руководство. Создание пользовательских разделов конфигурации с помощью класса ConfigurationSection

Статья
10/22/2014

Обновлен: Ноябрь 2007

При необходимости можно дополнить стандартный набор параметров конфигурации ASP.NET собственными элементами конфигурации XML. Для этого необходимо создать собственный обработчик разделов конфигурации.

В качестве обработчика следует использовать класс .NET Framework, в котором реализуется класс System.Configuration.ConfigurationSection.

Примечание.
В платформе .NET Framework версий 1.0 и 1.1 в обработчике разделов конфигурации также необходимо реализовать интерфейс System.Configuration.IConfigurationSectionHandler (в последующих версиях использование этого интерфейса не рекомендуется). Пример реализации этого интерфейса см. в разделе Практическое руководство. Создание пользовательских разделов конфигураций с помощью IConfigurationSectionHandler.

В платформе .NET Framework версий 1.0 и 1.1 в обработчике разделов конфигурации также необходимо реализовать интерфейс System.Configuration.IConfigurationSectionHandler (в последующих версиях использование этого интерфейса не рекомендуется). Пример реализации этого интерфейса см. в разделе Практическое руководство. Создание пользовательских разделов конфигураций с помощью IConfigurationSectionHandler.

Обработчик разделов интерпретирует и обрабатывает параметры, определенные в элементах конфигурации XML указанной части файла Web.config, и возвращает соответствующие объекты конфигурации, полученные на основе этих параметров. Объект конфигурации, возвращаемый классом обработчика, может быть любой структурой данных и не ограничен каким-либо базовым классом или форматом конфигурации. В ASP.NET объекты конфигурации используются для чтения и записи пользовательских элементов конфигурации.

Создание обработчика пользовательского раздела конфигурации

Создайте открытый класс, который наследуется от класса System.Configuration.ConfigurationSection, как показано в следующем примере кода.

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

Добавьте собственный код настройки параметров конфигурации.

Например, можно заменить закомментированный код следующим кодом, в котором выполняется получение значений из пользовательского раздела.

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

В этом примере применяется декларативная модель. Класс System.Configuration.ConfigurationSection также может быть реализован с применением программной модели. Пример см. в разделе System.Configuration.ConfigurationSection и разделе Классы, использующиеся для создания обработчиков определенных разделов.

Этот пример аналогичен коду, приведенному в разделе Практическое руководство. Создание пользовательских разделов конфигураций с помощью IConfigurationSectionHandler, и предназначен для сравнения. Обратите внимание, что наследование от класса System.Configuration.ConfigurationSection обеспечивает более точное управление обработчиком раздела. Например, в приведенной ниже процедуре в файле конфигурации допускается использование дочернего элемента myChildSection, для которого в предшествующем коде объявляется класс ConfigurationProperty, определяемый как производный от класса ConfigurationElement. Кроме того, благодаря инкапсуляции функций коллекций класса ConfigurationElementCollection поддерживается создание коллекций, обеспечивающих добавление, удаление и очистку элементов файла конфигурации. Дополнительные сведения и примеры см. в описании класса ConfigurationElementCollection.

Добавление обработчика пользовательского раздела в файл конфигурации ASP.NET

Добавьте элементы sectionGroup и section в элемент configSections файла Web.config, как показано в следующем примере. Это объявление используется для связывания обработчика пользовательского раздела с именем раздела.

Примечание.
Для лучшего упорядочения данных конфигурации рекомендуется (но не обязательно) определять элемент section как вложенный в элемент sectionGroup.

Можно добавлять объявление обработчика раздела в файл конфигурации, отличный от того, в который добавлены пользовательские элементы конфигурации, при условии, что файл, в котором объявляется обработчик, располагается на более высоком уровне иерархии файлов конфигурации. Дополнительные сведения см. в разделе Иерархия и наследование файла конфигурации ASP.NET.

Атрибут type элемента section должен соответствовать манифесту сборки. В противном случае возникает ошибка конфигурации. Файл сборки должен находиться в одном каталоге приложения ASP.NET с файлом Web.config, в котором он определяется.

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

Добавьте пользовательские элементы настройки в область параметров раздела конфигурации файла Web.config.

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

Программный доступ к данным пользовательской конфигурации

Получите экземпляр объекта пользовательской конфигурации и заполните его с помощью метода GetSection или GetSection.

В следующем примере на странице ASPX используются предыдущие примеры для перечисления атрибутов и дочерних элементов пользовательского раздела конфигурации.

<%@ Page Language="C#" %>

<script runat="server">
    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 runat="server">
    <title>Untitled Page</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>

    <h1>Enumerate MyCustomSection</h1>
    <asp:Label ID="Label1" runat="server" 
        Text="" />
    <br />
    <asp:Button ID="Button1" runat="server" 
        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 runat="server">
    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 runat="server">
    <title>Untitled Page</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>

    <h1>Enumerate MyCustomSection</h1>
    <asp:Label ID="Label1" runat="server" 
        Text=""/>
    <br />
    <asp:Button ID="Button1" runat="server" 
        Text="Get Custom Config Info" 
        OnClick="Button1_Click" />

    </div>
    </form>
</body>
</html>

См. также

Основные понятия

Структура файла конфигурации ASP.NET (разделы и обработчики разделов)

Общие сведения о конфигурационном ASP.NET

Другие ресурсы

Администрирование веб-узлов ASP.NET

Настройка приложений

Поделиться через