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

Article
10/22/2014

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

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

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

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>


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

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

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

Partager via