Partager via


Comment : créer des sections de configuration personnalisées à l'aide de ConfigurationSection

Mise à jour : novembre 2007

Vous pouvez étendre le jeu standard des paramètres de configuration ASP.NET avec vos propres éléments de configuration XML. Pour cela, vous devez créer votre propre gestionnaire de section de configuration.

Le gestionnaire doit être une classe .NET Framework qui implémente la classe System.Configuration.ConfigurationSection.

Remarque :

Dans les versions 1.0 et 1.1 du .NET Framework, un gestionnaire de section de configuration devait implémenter l'interface System.Configuration.IConfigurationSectionHandler, qui est maintenant désapprouvée. Toutefois, il existe encore un exemple de code dans Comment : créer des sections de configuration personnalisées à l'aide de IConfigurationSectionHandler.

Le gestionnaire de section interprète et traite les paramètres définis dans les éléments de configuration XML dans une partie spécifique d'un fichier Web.config et retourne un objet de configuration approprié basé sur les paramètres de configuration. L'objet de configuration que la classe du gestionnaire retourne peut être n'importe quelle structure de données ; il n'est pas limité à une classe de configuration de base ni à un format de configuration. ASP.NET utilise l'objet de configuration pour lire et écrire à votre élément de configuration personnalisée.

Pour créer un gestionnaire de section de configuration personnalisée

  1. Créez une classe publique qui hérite de la classe System.Configuration.ConfigurationSection, comme illustré dans l'exemple de code suivant.

    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. Ajoutez votre propre code pour effectuer le travail de configuration que vous souhaitez.

    Par exemple, vous pouvez remplacer le code commenté par le code suivant, lequel obtient les valeurs de votre section personnalisée.

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

    Cet exemple utilise le modèle déclaratif. La classe System.Configuration.ConfigurationSection peut être également implémentée à l'aide du modèle de programmation. Pour obtenir un exemple, consultez la rubrique de vue d'ensemble de la classe System.Configuration.ConfigurationSection et Classes utilisées pour créer les gestionnaires de sections personnalisés.

    Aux fins de comparaison, cet exemple est semblable au code illustré dans Comment : créer des sections de configuration personnalisées à l'aide de IConfigurationSectionHandler. Toutefois, en héritant de la classe System.Configuration.ConfigurationSection, vous disposez d'un contrôle plus précis sur votre gestionnaire de section. Par exemple, le fichier de configuration dans la procédure suivante autorise un élément enfant appelé myChildSection pour lequel le code précédent déclare un ConfigurationProperty et qu'il définit comme une classe dérivée de ConfigurationElement. En outre, l'encapsulation de fonctionnalités de collection dans la classe ConfigurationElementCollection permet de créer facilement des éléments de collection qui peuvent employer des éléments add, remove et clear dans un fichier de configuration. Pour plus d'informations et d'exemples, consultez ConfigurationElementCollection.

Pour ajouter un gestionnaire de section personnalisé à un fichier de configuration ASP.NET

  1. Ajoutez un élément sectionGroup et un élément section à votre fichier Web.config à l'intérieur de l'élément configSections, comme illustré dans l'exemple de code suivant. C'est cette déclaration qui associe le gestionnaire de section personnalisé au nom de la section.

    Remarque :

    L'imbrication d'un élément section dans sectionGroup est facultative, mais recommandée pour aider à organiser les données de configuration.

    Vous pouvez ajouter la déclaration de gestionnaire de section dans un fichier de configuration différent de celui dans lequel vous ajoutez vos éléments de configuration personnalisés, pour autant que le fichier de configuration dans lequel le gestionnaire de section est déclaré soit à un niveau supérieur de la hiérarchie des fichiers de configuration. Pour plus d'informations, consultez Hiérarchie du fichier de configuration ASP.NET et héritage.

    L'attribut type de l'élément section doit correspondre au manifeste d'assembly ou une erreur de configuration se produira. Le fichier d'assembly lui-même doit se trouver dans le même répertoire de l'application ASP.NET que le fichier Web.config qui le définit.

    <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. Ajoutez vos éléments de configuration personnalisée dans la zone de paramètres de la section de configuration de votre fichier 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>
    

Pour accéder par programme à vos données de configuration personnalisée

  • Obtenez une instance de votre objet de configuration personnalisée et utilisez la méthode GetSection ou la méthode GetSection pour la remplir.

    L'exemple suivant d'une page ASPX fonctionne avec les exemples précédents afin d'énumérer les attributs et les éléments enfants de la section de configuration personnalisée.

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

Voir aussi

Concepts

Structure du fichier de configuration ASP.NET (sections et gestionnaires de sections)

Vue d'ensemble de la configuration ASP.NET

Autres ressources

Administration de sites Web ASP.NET

Configuration d'applications