ConfigurationProperty Class
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Represents an attribute or a child of a configuration element. This class cannot be inherited.
This API supports the product infrastructure and is not intended to be used directly from your code.
public ref class ConfigurationProperty sealedpublic sealed class ConfigurationPropertytype ConfigurationProperty = classPublic NotInheritable Class ConfigurationProperty- Inheritance
-
ConfigurationProperty
Examples
- The following code example shows how to use the ConfigurationProperty when you create a custom section.
using System;
using System.Configuration;
using System.Collections;
using System.ComponentModel;
namespace ConfigurationPropertyExample
{
// Define a custom section.
// Shows how to use the ConfigurationProperty
// class when defining a custom section.
public sealed class CustomSection : ConfigurationSection
{
// The collection (property bag) that contains
// the section properties.
private static ConfigurationPropertyCollection _Properties;
// The FileName property.
private static ConfigurationProperty _FileName;
// The Alias property.
private static ConfigurationProperty _Alias;
// The MaxUsers property.
private static ConfigurationProperty _MaxUsers;
// The MaxIdleTime property.
private static ConfigurationProperty _MaxIdleTime;
// CustomSection constructor.
static CustomSection()
{
// Initialize the _FileName property
_FileName =
new ConfigurationProperty("fileName",
typeof(string), "default.txt");
// Initialize the _MaxUsers property
_MaxUsers =
new ConfigurationProperty("maxUsers",
typeof(long), (long)1000,
ConfigurationPropertyOptions.None);
// Initialize the _MaxIdleTime property
TimeSpan minTime = TimeSpan.FromSeconds(30);
TimeSpan maxTime = TimeSpan.FromMinutes(5);
ConfigurationValidatorBase _TimeSpanValidator =
new TimeSpanValidator(minTime, maxTime, false);
_MaxIdleTime =
new ConfigurationProperty("maxIdleTime",
typeof(TimeSpan), TimeSpan.FromMinutes(5),
TypeDescriptor.GetConverter(typeof(TimeSpan)),
_TimeSpanValidator,
ConfigurationPropertyOptions.IsRequired,
"[Description:This is the max idle time.]");
// Initialize the _Alias property
_Alias =
new ConfigurationProperty("alias",
typeof(string), "alias.txt");
// Initialize the Property collection.
_Properties = new ConfigurationPropertyCollection();
_Properties.Add(_FileName);
_Properties.Add(_Alias);
_Properties.Add(_MaxUsers);
_Properties.Add(_MaxIdleTime);
}
// Return the initialized property bag
// for the configuration element.
protected override ConfigurationPropertyCollection Properties
{
get
{
return _Properties;
}
}
// Clear the property.
public void ClearCollection()
{
Properties.Clear();
}
// Remove an element from the property collection.
public void RemoveCollectionElement(string elName)
{
Properties.Remove(elName);
}
// Get the property collection enumerator.
public IEnumerator GetCollectionEnumerator()
{
return (Properties.GetEnumerator());
}
[StringValidator(InvalidCharacters = " ~!@#$%^&*()[]{}/;'\"|\\",
MinLength = 1, MaxLength = 60)]
public string FileName
{
get
{
return (string)this["fileName"];
}
set
{
this["fileName"] = value;
}
}
[StringValidator(InvalidCharacters = " ~!@#$%^&*()[]{}/;'\"|\\",
MinLength = 1, MaxLength = 60)]
public string Alias
{
get
{
return (string)this["alias"];
}
set
{
this["alias"] = value;
}
}
[LongValidator(MinValue = 1, MaxValue = 1000000,
ExcludeRange = false)]
public long MaxUsers
{
get
{
return (long)this["maxUsers"];
}
set
{
this["maxUsers"] = value;
}
}
public TimeSpan MaxIdleTime
{
get
{
return (TimeSpan)this["maxIdleTime"];
}
set
{
this["maxIdleTime"] = value;
}
}
}
}
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, _
ConfigurationPropertyOptions.None)
' 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()
_Properties.Add(_FileName)
_Properties.Add(_Alias)
_Properties.Add(_MaxUsers)
_Properties.Add(_MaxIdleTime)
End Sub
' Return the initialized property bag
' for the configuration element.
Protected Overrides ReadOnly Property Properties() _
As ConfigurationPropertyCollection
Get
Return _Properties
End Get
End Property
<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(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.
<configuration>
<configSections>
<section name="CustomSection" type="ConfigurationPropertyExample.CustomSection, ConfigurationPropertyExample"
allowDefinition="Everywhere" allowExeDefinition="MachineToApplication"
restartOnExternalChanges="true" />
</configSections>
<CustomSection fileName="override.txt" alias="alias.txt"
maxUsers="1000" maxIdleTime="00:05:00" />
</configuration>
The following example shows how to create the previous section in code.
// Define a custom section programmatically.
static void CreateSection()
{
try
{
CustomSection customSection;
// Get the current configuration file.
System.Configuration.Configuration config =
ConfigurationManager.OpenExeConfiguration(
ConfigurationUserLevel.None);
// Create the section entry
// in the <configSections> and the
// related target section in <configuration>.
// Call it "CustomSection2" since the file in this
// example already has "CustomSection".
if (config.Sections["CustomSection"] == null)
{
customSection = new CustomSection();
config.Sections.Add("CustomSection2", customSection);
customSection.SectionInformation.ForceSave = true;
config.Save(ConfigurationSaveMode.Full);
}
}
catch (ConfigurationErrorsException err)
{
Console.WriteLine(err.ToString());
}
}
' 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>.
' 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
config.Save(ConfigurationSaveMode.Full)
End If
Catch err As ConfigurationErrorsException
Console.WriteLine(err.ToString())
End Try
End Sub
Remarks
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 Inheritors
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.
Constructors
| ConfigurationProperty(String, Type) |
This API supports the product infrastructure and is not intended to be used directly from your code. Initializes a new instance of the ConfigurationProperty class. |
| ConfigurationProperty(String, Type, Object) |
This API supports the product infrastructure and is not intended to be used directly from your code. Initializes a new instance of the ConfigurationProperty class. |
| ConfigurationProperty(String, Type, Object, ConfigurationPropertyOptions) |
This API supports the product infrastructure and is not intended to be used directly from your code. Initializes a new instance of the ConfigurationProperty class. |
| ConfigurationProperty(String, Type, Object, TypeConverter, ConfigurationValidatorBase, ConfigurationPropertyOptions) |
This API supports the product infrastructure and is not intended to be used directly from your code. Initializes a new instance of the ConfigurationProperty class. |
| ConfigurationProperty(String, Type, Object, TypeConverter, ConfigurationValidatorBase, ConfigurationPropertyOptions, String) |
This API supports the product infrastructure and is not intended to be used directly from your code. Initializes a new instance of the ConfigurationProperty class. |
Properties
| Converter |
This API supports the product infrastructure and is not intended to be used directly from your code. Gets the TypeConverter used to convert this ConfigurationProperty into an XML representation for writing to the configuration file. |
| DefaultValue |
This API supports the product infrastructure and is not intended to be used directly from your code. Gets the default value for this ConfigurationProperty property. |
| Description |
This API supports the product infrastructure and is not intended to be used directly from your code. Gets the description associated with the ConfigurationProperty. |
| IsAssemblyStringTransformationRequired |
This API supports the product infrastructure and is not intended to be used directly from your code. Indicates whether the assembly name for the configuration property requires transformation when it is serialized for an earlier version of the .NET Framework. |
| IsDefaultCollection |
This API supports the product infrastructure and is not intended to be used directly from your code. Gets a value that indicates whether the property is the default collection of an element. |
| IsKey |
This API supports the product infrastructure and is not intended to be used directly from your code. Gets a value indicating whether this ConfigurationProperty is the key for the containing ConfigurationElement object. |
| IsRequired |
This API supports the product infrastructure and is not intended to be used directly from your code. Gets a value indicating whether this ConfigurationProperty is required. |
| IsTypeStringTransformationRequired |
This API supports the product infrastructure and is not intended to be used directly from your code. Indicates whether the type name for the configuration property requires transformation when it is serialized for an earlier version of the .NET Framework. |
| IsVersionCheckRequired |
This API supports the product infrastructure and is not intended to be used directly from your code. Indicates whether the configuration property's parent configuration section is queried at serialization time to determine whether the configuration property should be serialized into XML. |
| Name |
This API supports the product infrastructure and is not intended to be used directly from your code. Gets the name of this ConfigurationProperty. |
| Type |
This API supports the product infrastructure and is not intended to be used directly from your code. Gets the type of this ConfigurationProperty object. |
| Validator |
This API supports the product infrastructure and is not intended to be used directly from your code. Gets the ConfigurationValidatorAttribute, which is used to validate this ConfigurationProperty object. |
Methods
| Equals(Object) |
Determines whether the specified object is equal to the current object. (Inherited from Object) |
| GetHashCode() |
Serves as the default hash function. (Inherited from Object) |
| GetType() |
Gets the Type of the current instance. (Inherited from Object) |
| MemberwiseClone() |
Creates a shallow copy of the current Object. (Inherited from Object) |
| ToString() |
Returns a string that represents the current object. (Inherited from Object) |
