This documentation is archived and is not being maintained.

ConfigurationProperty Class

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.

Represents an attribute or a child of a configuration element. This class cannot be inherited.

Namespace:  System.Configuration
Assembly:  System.Configuration (in System.Configuration.dll)

Public NotInheritable Class ConfigurationProperty
Dim instance As ConfigurationProperty

In the case of a simple ConfigurationElement, such as the CustomSection shown in the next example, the ConfigurationProperty objects represent attributes such as fileName.

In the case of more complex configuration elements such as a section containing subsections, for instance authentication, the ConfigurationProperty objects can represent ConfigurationElement objects as well as attributes.

The ConfigurationPropertyCollection class represents the collection of the ConfigurationProperty objects that can be either attributes or ConfigurationElement objects of a configuration element.

The ConfigurationProperty class represents an individual configuration setting. This class allows you to get or set the name, type, and default value for a particular configuration entity (attribute or element) and specify whether the attribute is required, is an element key, or represents a default element collection.

Notes to Implementers:

Every ConfigurationElement object creates an internal ConfigurationPropertyCollection collection of ConfigurationProperty objects that represents either the element attributes or a collection of child elements.

Non-customizable information and functionality is contained by an ElementInformation object provided by the ElementInformation property.

You can use a programmatic or a declarative (attributed) coding model to create a custom configuration element.

  • Programmatic Model. This model requires that you create a property for each element attribute to get and/or set its value and add it to the internal property bag of the underlying ConfigurationElement base class.

  • Declarative Model. This simpler model, also called attributed model, allows you to define an element attribute by using a property and decorate it with attributes. These attributes instruct the ASP.NET configuration system about the property types and their default values. With this information, obtained through reflection, the ASP.NET configuration system creates the element property objects for you and performs the required initialization.

  1. The following code example shows how to use the ConfigurationProperty when you create a custom section.

Imports System
Imports System.Configuration
Imports System.Collections
Imports System.ComponentModel

' Define a custom section. 
' Shows how to use the ConfigurationProperty 
' class when defining a custom section. 
Public NotInheritable Class CustomSection
    Inherits ConfigurationSection

    ' The collection (property bag) that contains  
    ' the section properties. 
    Private Shared _Properties As ConfigurationPropertyCollection

    ' The FileName property. 
    Private Shared _FileName As ConfigurationProperty

    ' The Alias property. 
    Private Shared _Alias As ConfigurationProperty

    ' The MasUsers property. 
    Private Shared _MaxUsers As ConfigurationProperty

    ' The MaxIdleTime property. 
    Private Shared _MaxIdleTime As ConfigurationProperty

    ' CustomSection constructor. 
    Shared Sub New()

        ' Initialize the _FileName property
        _FileName = New ConfigurationProperty( _
            "fileName", GetType(String), "default.txt")

        ' Initialize the _MaxUsers property
        _MaxUsers = New ConfigurationProperty( _
            "maxUsers", GetType(Long), 1000L, _

        ' Initialize the _MaxIdleTime property 
        Dim minTime As TimeSpan = TimeSpan.FromSeconds(30)
        Dim maxTime As TimeSpan = TimeSpan.FromMinutes(5)
        Dim _TimeSpanValidator = _
            New TimeSpanValidator(minTime, maxTime, False)

        _MaxIdleTime = New ConfigurationProperty( _
            "maxIdleTime", GetType(TimeSpan), _
            TimeSpan.FromMinutes(5), _
            TypeDescriptor.GetConverter(GetType(TimeSpan)), _
            _TimeSpanValidator, _
            ConfigurationPropertyOptions.IsRequired, _
            "[Description:This is the max idle time.]")

        ' Initialize the _Alias property
        _Alias = New ConfigurationProperty( _
            "alias", GetType(String), "alias.txt")

        ' Property collection initialization. 
        ' The collection (property bag) that contains  
        ' the properties is declared as: 
        ' ConfigurationPropertyCollection _Properties;
        _Properties = New ConfigurationPropertyCollection()

    End Sub 

    ' Return the initialized property bag 
    ' for the configuration element. 
    Protected Overrides ReadOnly Property Properties() _
    As ConfigurationPropertyCollection
            Return _Properties
        End Get 
    End Property

    <StringValidator(InvalidCharacters:= _
    " ~!@#$%^&*()[]{}/;'""|\", MinLength:=1, _
    MaxLength:=60)> _
    Public Property FileName() As String 
            Return CStr(Me("fileName"))
        End Get 
        Set(ByVal value As String)
            Me("fileName") = value
        End Set 
    End Property

    <StringValidator(InvalidCharacters:= _
    " ~!@#$%^&*()[]{}/;'""|\", MinLength:=1, _
    MaxLength:=60)> _
    Public Property [Alias]() As String 
            Return CStr(Me("alias"))
        End Get 
        Set(ByVal value As String)
            Me("alias") = value
        End Set 
    End Property

    <LongValidator(MinValue:=1, _
    MaxValue:=1000000, ExcludeRange:=False)> _
    Public Property MaxUsers() As Long
            Return Fix(Me("maxUsers"))
        End Get 
        Set(ByVal value As Long)
            Me("maxUsers") = value
        End Set 
    End Property 

    Public Property MaxIdleTime() As TimeSpan
            Return CType(Me("maxIdleTime"), TimeSpan)
        End Get 
        Set(ByVal value As TimeSpan)
            Me("maxIdleTime") = value
        End Set 
    End Property 
End Class

The following is an excerpt of the configuration file used by the code in the previous example.

    <section name="CustomSection" type="ConfigurationPropertyExample.CustomSection, ConfigurationPropertyExample" 
      allowDefinition="Everywhere" allowExeDefinition="MachineToApplication" 
      restartOnExternalChanges="true" />
  <CustomSection fileName="override.txt" alias="alias.txt" 
    maxUsers="1000" maxIdleTime="00:05:00" />

The following example shows how to create the previous section in code.

' Create a custom section. 
Shared Sub CreateSection()
        Dim customSection As CustomSection

        ' Get the current configuration file. 
        Dim config As System.Configuration.Configuration = _
            ConfigurationManager.OpenExeConfiguration( _

        ' Create the section entry   
        ' in the <configSections> and the  
        ' related target section in <configuration>. 
        ' Since the config file already has "CustomSection", 
        ' call this one "CustomSection2". 
        If config.Sections("CustomSection") Is Nothing Then
            customSection = New CustomSection()
            config.Sections.Add("CustomSection", customSection)
            customSection.SectionInformation.ForceSave = True
        End If 
    Catch err As ConfigurationErrorsException
    End Try 
End Sub


Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5, 3.0, 2.0