ConfigurationProperty Class

This class 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)

'Declaration
Public NotInheritable Class ConfigurationProperty
'Usage
Dim instance As ConfigurationProperty

public final class ConfigurationProperty
public final class ConfigurationProperty
Not applicable.

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 creating a custom section.

' Define a custom section.
' It shows how to use the ConfigurationProperty
' class when defining a custom section
' programmatically. 
' The variables prefixed with the
' _ sign are ConfigurationProperty types.

NotInheritable Public Class CustomSection
   Inherits ConfigurationSection
   
   
   ' CustomSection constructor.
   Shared Sub New()
      
      ' Initialize the _FileName
         _FileName = New ConfigurationProperty( _
         "fileName", GetType(String), _
         "default.txt")
      ' Initialize the _MaxUsers
         _MaxUsers = New ConfigurationProperty( _
         "maxUsers", GetType(Long), _
         Fix(1000), ConfigurationPropertyOptions.None)
      ' Initialize the _MaxIdleTime
         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
         _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()
      ' The collection (property bag) that contains 
      ' the properties is declared as:
      ' ConfigurationPropertyCollection _Properties;
      _Properties.Add(_FileName)
      _Properties.Add(_Alias)
      _Properties.Add(_MaxUsers)
         _Properties.Add(_MaxIdleTime)

     End Sub 'New 
   
   ' Return the initialized property bag
   ' for the configuration element.
   ' The collection (property bag) that contains 
   ' the properties is declared as:
   ' ConfigurationPropertyCollection _Properties;
   
     Protected Overrides ReadOnly Property Properties() _
     As ConfigurationPropertyCollection
         Get
             Return _Properties
         End Get
     End Property
   
   
   ' Clear the property.
   ' It deletes all the attributes of the
   ' configuration element represented by
   ' the property.
   Public Sub ClearCollection()
      Properties.Clear()
   End Sub 'ClearCollection
   
   ' Remove an element from the property collection.
   ' It deletes the specified attribute from the
   ' configuration element represented by
   ' the property.
   Public Sub RemoveCollectionElement(elName As String)
      Properties.Remove(elName)
   End Sub 'RemoveCollectionElement
   
   ' Get the property collection enumerator.
   Public Function GetCollectionEnumerator() As IEnumerator
      Return Properties.GetEnumerator()
   End Function 'GetCollectionEnumerator
   
   
   
     <StringValidator(InvalidCharacters:= _
     " ~!@#$%^&*()[]{}/;'""|\", MinLength:=1, _
     MaxLength:=60)> _
     Public Property FileName() As String
         Get
             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
         Get
             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
         Get
             Return Fix(Me("maxUsers"))
         End Get
         Set(ByVal value As Long)
             Me("maxUsers") = Value
         End Set
     End Property
   
   
   
   Public Property MaxIdleTime() As TimeSpan
      Get
         Return CType(Me("maxIdleTime"), TimeSpan)
      End Get
      Set
         Me("maxIdleTime") = value
      End Set
   End Property
End Class 'CustomSection
 

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

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <section name="CustomSection" type="Samples.AspNet, ConfigurationProperty, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" allowDefinition="Everywhere" allowExeDefinition="MachineToApplication" restartOnExternalChanges="true" />
  </configSections>
  <CustomSection fileName="default.txt" alias="alias.txt" maxUsers="1000"
    maxIdleTime="00:05:00" />
</configuration>

The following example shows how to create the above section.

' Create a custom section.
Shared Sub CreateSection()
   Try
      
      Dim customSection As CustomSection
      
      ' Get the current configuration file.
         Dim config As System.Configuration.Configuration = _
         ConfigurationManager.OpenExeConfiguration( _
         ConfigurationUserLevel.None)
      
      ' Create the section entry  
      ' in the <configSections> and the 
      ' related target section in <configuration>.
      If config.Sections("CustomSection") Is Nothing Then
         customSection = New CustomSection()
         config.Sections.Add("CustomSection", customSection)
         customSection.SectionInformation.ForceSave = True
         config.Save(ConfigurationSaveMode.Full)
      End If
   Catch err As ConfigurationErrorsException
      Console.WriteLine(err.ToString())
   End Try
End Sub 'CreateSection
 

System.Object
  System.Configuration.ConfigurationProperty

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 98, Windows Server 2000 SP4, Windows Millennium Edition, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0, 2.0

Community Additions

ADD
Show: