System.Configuration Namesp ...


.NET Framework Class Library
ConfigurationPropertyAttribute Class

Declaratively instructs the .NET Framework to instantiate a configuration property. This class cannot be inherited.

Namespace:  System.Configuration
Assembly:  System.Configuration (in System.Configuration.dll)
Syntax
Visual Basic (Declaration) 
<AttributeUsageAttribute(AttributeTargets.Property)> _
Public NotInheritable Class ConfigurationPropertyAttribute _
    Inherits Attribute
Visual Basic (Usage) 
Dim instance As ConfigurationPropertyAttribute
C# 
[AttributeUsageAttribute(AttributeTargets.Property)]
public sealed class ConfigurationPropertyAttribute : Attribute
Visual C++ 
[AttributeUsageAttribute(AttributeTargets::Property)]
public ref class ConfigurationPropertyAttribute sealed : public Attribute
JScript 
public final class ConfigurationPropertyAttribute extends Attribute
Remarks

You use the ConfigurationPropertyAttribute to decorate a configuration property, which will instruct the .NET Framework to instantiate and to initialize the property using the value of the decorating parameter.

NoteNote:

The simplest way to create a custom configuration element is to use the attributed (declarative) model. You declare the custom public properties and decorate them with the ConfigurationPropertyAttribute attribute. For each property marked with this attribute, the .NET Framework uses reflection to read the decorating parameters and create a related ConfigurationProperty instance. You can also use the programmatic model, in which case it is your responsibility to declare the custom public properties and return their collection.

The .NET Framework configuration system provides attribute types that you can use during the creation of custom configuration elements. There are two kinds of attribute types:

  1. The types instructing the .NET Framework how to instantiate the custom configuration-element properties. These types include:

  2. The types instructing the .NET Framework how to validate the custom configuration-element properties. These types include:
Examples

The following example shows how to decorate the properties of a custom ConfigurationSection object using the ConfigurationPropertyAttribute attribute.

Visual Basic 
Public Class SampleSection
   Inherits ConfigurationSection

   Public Sub New()
   End Sub 'New


    <ConfigurationProperty("fileName", _
    DefaultValue:="default.txt", _
    IsRequired:=True, _
    IsKey:=False), _
    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


    <ConfigurationProperty("maxUsers", _
    DefaultValue:=10000, _
    IsRequired:=False), _
    LongValidator(MinValue:=1, _
    MaxValue:=10000000, _
    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

    <ConfigurationProperty("maxIdleTime", _
    DefaultValue:="0:10:0", _
    IsRequired:=False), _
    TimeSpanValidator(MinValueString:="0:0:30", _
    MaxValueString:="5:00:0", _
    ExcludeRange:=False)> _
    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 'SampleSection
C# 
public class SampleSection : 
    ConfigurationSection
{
    public SampleSection()
    {
    }

    [ConfigurationProperty("fileName", DefaultValue = "default.txt",
        IsRequired = true, IsKey = false)]
    [StringValidator(InvalidCharacters = " ~!@#$%^&*()[]{}/;'\"|\\",
        MinLength = 1, MaxLength = 60)]
    public string FileName
    {
        get
        {
            return (string)this["fileName"];
        }
        set
        {
            this["fileName"] = value;
        }
    }

    [ConfigurationProperty("maxUsers", DefaultValue = (long)10000,  
        IsRequired=false)]
    [LongValidator(MinValue = 1, MaxValue = 10000000,
        ExcludeRange = false)]
    public long MaxUsers
    {
        get
        {
            return (long)this["maxUsers"];
        }
        set
        {
            this["maxUsers"] = value;
        }
    }

    [ConfigurationProperty("maxIdleTime",
        DefaultValue = "0:10:0",
        IsRequired = false)]
    [TimeSpanValidator(MinValueString = "0:0:30", 
        MaxValueString = "5:00:0",
        ExcludeRange = false)]
    public TimeSpan MaxIdleTime
    {
        get
        {
            return (TimeSpan)this["maxIdleTime"];
        }
        set
        {
            this["maxIdleTime"] = value;
        }
    }
}

The following is an excerpt of the configuration file containing the custom section as defined in the previous sample.

<configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0">
  <configSections>
    <section name="custom" type="Samples.AspNet.SampleSection, ConfigurationPropertyAttribute" />
  </configSections>
  <custom fileName="Default.txt" 
    maxUsers="2500" maxIdleTime="00:10:00" />
</configuration>
Inheritance Hierarchy
System..::.Object
  System..::.Attribute
    System.Configuration..::.ConfigurationPropertyAttribute
Thread Safety
Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Platforms

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.
Version Information

.NET Framework

Supported in: 3.5, 3.0, 2.0
See Also

Reference

ConfigurationPropertyAttribute Members
System.Configuration Namespace
ConfigurationProperty
ConfigurationCollectionAttribute
IntegerValidatorAttribute
LongValidatorAttribute
RegexStringValidatorAttribute
StringValidatorAttribute
TimeSpanValidatorAttribute
Tags :


Community Content

TaylorMichaelL
IsRequired does not work when applied to a ConfigurationElement

The IsRequired member of ConfigurationPropertyAttribute does not work when applied to a child object (deriving from ConfigurationElement). When the subsystem reflects over the attributes of the parent section/element to determine which configuration properties are defined it will create a new instance (of the appropriate type) for each child element and store it in the parent's value list. Later, when it validates whether all required properties have been specified or not, it cannot differentiate between a default initialized child element and one that was explicitly contained in the configuration file.

The most ideal workaround would be to programmatically declare the required elements through the ConfigurationProperty class. This requires substantial more work than the declarative approach. An alternative approach would be to ensure that the required element contains a required property of its own. However in this case the user may become confused because any errors from the subsystem will reference an element that does not exist in the configuration file.

Tags :

Page view tracker