Export (0) Print
Expand All
0 out of 4 rated this helpful - Rate this topic

Configuration Class

Represents a configuration file that is applicable to a particular computer, application, or resource. This class cannot be inherited.

System.Object
  System.Configuration.Configuration

Namespace:  System.Configuration
Assembly:  System.Configuration (in System.Configuration.dll)
'Declaration
Public NotInheritable Class Configuration

The Configuration type exposes the following members.

  NameDescription
Public propertyAppSettingsGets the AppSettingsSection object configuration section that applies to this Configuration object.
Public propertyAssemblyStringTransformerSpecifies a function delegate that is used to transform assembly strings in configuration files.
Public propertyConnectionStringsGets a ConnectionStringsSection configuration-section object that applies to this Configuration object.
Public propertyEvaluationContextGets the ContextInformation object for the Configuration object.
Public propertyFilePathGets the physical path to the configuration file represented by this Configuration object.
Public propertyHasFileGets a value that indicates whether a file exists for the resource represented by this Configuration object.
Public propertyLocationsGets the locations defined within this Configuration object.
Public propertyNamespaceDeclaredGets or sets a value indicating whether the configuration file has an XML namespace.
Public propertyRootSectionGroupGets the root ConfigurationSectionGroup for this Configuration object.
Public propertySectionGroupsGets a collection of the section groups defined by this configuration.
Public propertySectionsGets a collection of the sections defined by this Configuration object.
Public propertyTargetFrameworkSpecifies the targeted version of the .NET Framework when a version earlier than the current one is targeted.
Public propertyTypeStringTransformerSpecifies a function delegate that is used to transform type strings in configuration files.
Top
  NameDescription
Public methodEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Public methodGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodGetSectionReturns the specified ConfigurationSection object.
Public methodGetSectionGroupGets the specified ConfigurationSectionGroup object.
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodSaveWrites the configuration settings contained within this Configuration object to the current XML configuration file.
Public methodSave(ConfigurationSaveMode)Writes the configuration settings contained within this Configuration object to the current XML configuration file.
Public methodSave(ConfigurationSaveMode, Boolean)Writes the configuration settings contained within this Configuration object to the current XML configuration file.
Public methodSaveAs(String)Writes the configuration settings contained within this Configuration object to the specified XML configuration file.
Public methodSaveAs(String, ConfigurationSaveMode)Writes the configuration settings contained within this Configuration object to the specified XML configuration file.
Public methodSaveAs(String, ConfigurationSaveMode, Boolean)Writes the configuration settings contained within this Configuration object to the specified XML configuration file.
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Top

Configuration settings are stored in a hierarchy of configuration files. The Configuration class instance represents the merged view of the configuration settings from all of the configuration files that apply to a specific physical entity, such as a computer, or to a logical entity, such as an application or a Web site. The logical entity can exist on the local computer or on a remote server. For information about configuration files, see Configuration Files and ASP.NET Configuration Files.

When no configuration file exists for a specified entity, the Configuration object represents the default configuration settings as defined by the Machine.config file.

You can get a Configuration object by using the following classes:

The names of the methods that return a Configuration object begin with "Open".

You can also generate a configuration file that represents the configuration settings in a Configuration object. To do this, use one of the following methods:

  • Call the Save method to create a new configuration file.

  • Call the SaveAs method to generate a new configuration file at another location.

The names of the methods that create configuration files begin with "Save".

NoteNote

To enable access to configuration settings on a remote computer, use the Aspnet_regiis command-line tool. For more information about this tool, see ASP.NET IIS Registration Tool (Aspnet_regiis.exe). For information about creating and accessing custom configuration settings other than the intrinsic sections included in the .NET Framework, refer to ConfigurationSection.

Notes to Implementers

The Configuration class provides programmatic access for editing configuration files. You use one of the "Open" methods provided by the WebConfigurationManager class for Web applications or by the ConfigurationManager class for client applications. These methods return a Configuration object, which in turn provides the methods and properties that handle the underlying configuration files. You can access these files for reading or writing configuration information.

You use the GetSection method or the GetSectionGroup method to read configuration information. Note that the user or process that reads must have the following permissions:

  • Read permission on the configuration file at the current configuration hierarchy level.

  • Read permissions on all the parent configuration files.

If your application needs read-only access to its own configuration, it is recommended that you use the GetSection method overloads for Web applications. For client application, use the GetSection method.

These methods provide access to the cached configuration values for the current application, which has better performance than the Configuration class.

NoteNote

If you use a static GetSection method that takes a path parameter, the path parameter must refer to the application in which the code is running, otherwise the parameter is ignored and configuration information for the currently running application is returned.

You use one of the Save methods to write configuration information. Note that the user or process that writes must have the following permissions:

  • Write permission on the configuration file and directory at the current configuration hierarchy level.

  • Read permissions on all the configuration files.

The following code example demonstrates how to use the Configuration class to access configuration file elements.

Imports System.Text
Imports System.Configuration
Imports System.Globalization
Imports System.ComponentModel
Imports System.Collections.Specialized

' Before compiling this application,  
' remember to reference the System.Configuration assembly in your project. 
#Region "CustomSection class" 

' Define a custom section. This class is used to 
' populate the configuration file. 
' It creates the following custom section: 
'  <CustomSection name="Contoso" url="http://www.contoso.com" port="8080" />. 
Public NotInheritable Class CustomSection
    Inherits ConfigurationSection

    Public Sub New()

    End Sub


    <ConfigurationProperty("name", DefaultValue:="Contoso", IsRequired:=True, IsKey:=True)> _
    Public Property Name() As String 
        Get 
            Return CStr(Me("name"))
        End Get 
        Set(ByVal value As String)
            Me("name") = value
        End Set 
    End Property

    <ConfigurationProperty("url", DefaultValue:="http://www.contoso.com", IsRequired:=True), RegexStringValidator("\w+:\/\/[\w.]+\S*")> _
    Public Property Url() As String 
        Get 
            Return CStr(Me("url"))
        End Get 
        Set(ByVal value As String)
            Me("url") = value
        End Set 
    End Property

    <ConfigurationProperty("port", DefaultValue:=CInt(8080), IsRequired:=False), IntegerValidator(MinValue:=0, MaxValue:=8080, ExcludeRange:=False)> _
    Public Property Port() As Integer 
        Get 
            Return CInt(Fix(Me("port")))
        End Get 
        Set(ByVal value As Integer)
            Me("port") = value
        End Set 
    End Property 



End Class

#End Region

#Region "Using Configuration Class" 
Friend Class UsingConfigurationClass

    ' Show how to create an instance of the Configuration class 
    ' that represents this application configuration file.   
    Public Shared Sub CreateConfigurationFile()
        Try 

            ' Create a custom configuration section. 
            Dim customSection As New CustomSection()

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

            ' Create the section entry   
            ' in <configSections> and the  
            ' related target section in <configuration>. 
            If config.Sections("CustomSection") Is Nothing Then
                config.Sections.Add("CustomSection", customSection)
            End If 

            ' Create and add an entry to appSettings section. 

            Dim conStringname As String = "LocalSqlServer" 
            Dim conString As String = "data source=.\SQLEXPRESS;Integrated Security=SSPI;AttachDBFilename=|DataDirectory|aspnetdb.mdf;User Instance=true" 
            Dim providerName As String = "System.Data.SqlClient" 

            Dim connStrSettings As New ConnectionStringSettings()
            connStrSettings.Name = conStringname
            connStrSettings.ConnectionString = conString
            connStrSettings.ProviderName = providerName

            config.ConnectionStrings.ConnectionStrings.Add(connStrSettings)

            ' Add an entry to appSettings section. 
            Dim appStgCnt As Integer = ConfigurationManager.AppSettings.Count
            Dim newKey As String = "NewKey" & appStgCnt.ToString()

            Dim newValue As String = Date.Now.ToLongDateString() & " " & Date.Now.ToLongTimeString()

            config.AppSettings.Settings.Add(newKey, newValue)

            ' Save the configuration file.
            customSection.SectionInformation.ForceSave = True
            config.Save(ConfigurationSaveMode.Full)

            Console.WriteLine("Created configuration file: {0}", config.FilePath)

        Catch err As ConfigurationErrorsException
            Console.WriteLine("CreateConfigurationFile: {0}", err.ToString())
        End Try 

    End Sub 

    ' Show how to use the GetSection(string) method. 
    Public Shared Sub GetCustomSection()
        Try 

            Dim customSection As CustomSection

            ' Get the current configuration file. 
            Dim config As System.Configuration.Configuration = TryCast(ConfigurationManager.OpenExeConfiguration(ConfigurationUserLevel.None), Configuration)

            customSection = TryCast(config.GetSection("CustomSection"), CustomSection)

            Console.WriteLine("Section name: {0}", customSection.Name)
            Console.WriteLine("Url: {0}", customSection.Url)
            Console.WriteLine("Port: {0}", customSection.Port)

        Catch err As ConfigurationErrorsException
            Console.WriteLine("Using GetSection(string): {0}", err.ToString())
        End Try 

    End Sub 


    ' Show how to use different modalities to save  
    ' a configuration file. 
    Public Shared Sub SaveConfigurationFile()
        Try 

            ' Get the current configuration file. 
            Dim config As System.Configuration.Configuration = TryCast(ConfigurationManager.OpenExeConfiguration(ConfigurationUserLevel.None), Configuration)

            ' Save the full configuration file and force save even if the file was not modified.
            config.SaveAs("MyConfigFull.config", ConfigurationSaveMode.Full, True)
            Console.WriteLine("Saved config file as MyConfigFull.config using the mode: {0}", ConfigurationSaveMode.Full.ToString())

            config = TryCast(ConfigurationManager.OpenExeConfiguration(ConfigurationUserLevel.None), Configuration)

            ' Save only the part of the configuration file that was modified. 
            config.SaveAs("MyConfigModified.config", ConfigurationSaveMode.Modified, True)
            Console.WriteLine("Saved config file as MyConfigModified.config using the mode: {0}", ConfigurationSaveMode.Modified.ToString())

            config = TryCast(ConfigurationManager.OpenExeConfiguration(ConfigurationUserLevel.None), Configuration)

            ' Save the full configuration file.
            config.SaveAs("MyConfigMinimal.config")
            Console.WriteLine("Saved config file as MyConfigMinimal.config using the mode: {0}", ConfigurationSaveMode.Minimal.ToString())

        Catch err As ConfigurationErrorsException
            Console.WriteLine("SaveConfigurationFile: {0}", err.ToString())
        End Try 

    End Sub 


    ' Show how use the AppSettings and ConnectionStrings  
    ' properties. 
    Public Shared Sub GetSections(ByVal section As String)
        Try 

            ' Get the current configuration file. 
            Dim config As System.Configuration.Configuration = TryCast(ConfigurationManager.OpenExeConfiguration(ConfigurationUserLevel.None), Configuration)

            ' Get the selected section. 
            Select Case section
                Case "appSettings" 
                    Try 
                        Dim appSettings As AppSettingsSection = TryCast(config.AppSettings, AppSettingsSection)
                        Console.WriteLine("Section name: {0}", appSettings.SectionInformation.SectionName)

                        ' Get the AppSettings section elements.
                        Console.WriteLine()
                        Console.WriteLine("Using AppSettings property.")
                        Console.WriteLine("Application settings:")
                        ' Get the KeyValueConfigurationCollection  
                        ' from the configuration. 
                        Dim settings As KeyValueConfigurationCollection = config.AppSettings.Settings

                        ' Display each KeyValueConfigurationElement. 
                        For Each keyValueElement As KeyValueConfigurationElement In settings
                            Console.WriteLine("Key: {0}", keyValueElement.Key)
                            Console.WriteLine("Value: {0}", keyValueElement.Value)
                            Console.WriteLine()
                        Next keyValueElement
                    Catch e As ConfigurationErrorsException
                        Console.WriteLine("Using AppSettings property: {0}", e.ToString())
                    End Try 

                Case "connectionStrings" 
                    Dim conStrSection As ConnectionStringsSection = TryCast(config.ConnectionStrings, ConnectionStringsSection)
                    Console.WriteLine("Section name: {0}", conStrSection.SectionInformation.SectionName)

                    Try 
                        If conStrSection.ConnectionStrings.Count <> 0 Then
                            Console.WriteLine()
                            Console.WriteLine("Using ConnectionStrings property.")
                            Console.WriteLine("Connection strings:")

                            ' Get the collection elements. 
                            For Each connection As ConnectionStringSettings In conStrSection.ConnectionStrings
                                Dim name As String = connection.Name
                                Dim provider As String = connection.ProviderName
                                Dim connectionString As String = connection.ConnectionString

                                Console.WriteLine("Name:               {0}", name)
                                Console.WriteLine("Connection string:  {0}", connectionString)
                                Console.WriteLine("Provider:            {0}", provider)
                            Next connection
                        End If 
                    Catch e As ConfigurationErrorsException
                        Console.WriteLine("Using ConnectionStrings property: {0}", e.ToString())
                    End Try 

                Case Else
                    Console.WriteLine("GetSections: Unknown section (0)", section)
            End Select 

        Catch err As ConfigurationErrorsException
            Console.WriteLine("GetSections: (0)", err.ToString())
        End Try 

    End Sub 

    ' Show how to use the Configuration object properties  
    ' to obtain configuration file information. 
    Public Shared Sub GetConfigurationInformation()
        Try 

            ' Get the current configuration file. 
            Dim config As System.Configuration.Configuration = TryCast(ConfigurationManager.OpenExeConfiguration(ConfigurationUserLevel.None), Configuration)

            Console.WriteLine("Reading configuration information:")

            Dim evalContext As ContextInformation = TryCast(config.EvaluationContext, ContextInformation)
            Console.WriteLine("Machine level: {0}", evalContext.IsMachineLevel.ToString())

            Dim filePath As String = config.FilePath
            Console.WriteLine("File path: {0}", filePath)

            Dim hasFile As Boolean = config.HasFile
            Console.WriteLine("Has file: {0}", hasFile.ToString())


            Dim groups As ConfigurationSectionGroupCollection = config.SectionGroups
            Console.WriteLine("Groups: {0}", groups.Count.ToString())
            For Each group As ConfigurationSectionGroup In groups
                Console.WriteLine("Group Name: {0}", group.Name)
                ' Console.WriteLine("Group Type: {0}", group.Type); 
            Next group


            Dim sections As ConfigurationSectionCollection = config.Sections
            Console.WriteLine("Sections: {0}", sections.Count.ToString())


        Catch err As ConfigurationErrorsException
            Console.WriteLine("GetConfigurationInformation: {0}", err.ToString())
        End Try 

    End Sub 
End Class

#End Region

#Region "Application Main" 
'*** User Interaction Class ***// 

' Obtain user's input and provide feedback. 
' This class contains the application Main() function. 
' It calls the ConfigurationManager methods based  
' on the user's selection. 
Public Class ApplicationMain
    ' Display user's menu. 
    Public Shared Sub UserMenu()
        Dim applicationName As String = Environment.GetCommandLineArgs()(0) & ".exe" 
        Dim buffer As New StringBuilder()

        buffer.AppendLine("Application: " & applicationName)
        buffer.AppendLine("Please, make your selection.")
        buffer.AppendLine("?    -- Display help.")
        buffer.AppendLine("Q,q  -- Exit the application.")

        buffer.Append("1    -- Instantiate the")
        buffer.AppendLine(" Configuration class.")

        buffer.Append("2    -- Use GetSection(string) to read ")
        buffer.AppendLine(" a custom section.")

        buffer.Append("3    -- Use SaveAs methods")
        buffer.AppendLine(" to save the configuration file.")

        buffer.Append("4    -- Use AppSettings property to read")
        buffer.AppendLine(" the appSettings section.")
        buffer.Append("5    -- Use ConnectionStrings property to read")
        buffer.AppendLine(" the connectionStrings section.")

        buffer.Append("6    -- Use Configuration class properties")
        buffer.AppendLine(" to obtain configuration information.")

        Console.Write(buffer.ToString())
    End Sub 

    ' Obtain user's input and provide 
    ' feedback. 
    Shared Sub Main(ByVal args() As String)
        ' Define user selection string. 
        Dim selection As String 

        ' Get the name of the application. 
        Dim appName As String = Environment.GetCommandLineArgs()(0)


        ' Get user selection. 
        Do

            UserMenu()
            Console.Write("> ")
            selection = Console.ReadLine()
            If selection <> String.Empty Then 
                Exit Do 
            End If 
        Loop 

        Do While selection.ToLower() <> "q" 
            ' Process user's input. 
            Select Case selection
                Case "1" 
                    ' Show how to create an instance of the Configuration class.
                    UsingConfigurationClass.CreateConfigurationFile()

                Case "2" 
                    ' Show how to use GetSection(string) method.
                    UsingConfigurationClass.GetCustomSection()

                Case "3" 
                    ' Show how to use ConnectionStrings.
                    UsingConfigurationClass.SaveConfigurationFile()

                Case "4" 
                    ' Show how to use the AppSettings property.
                    UsingConfigurationClass.GetSections("appSettings")

                Case "5" 
                    ' Show how to use the ConnectionStrings property.
                    UsingConfigurationClass.GetSections("connectionStrings")

                Case "6" 
                    ' Show how to obtain configuration file information.
                    UsingConfigurationClass.GetConfigurationInformation()


                Case Else
                    UserMenu()
            End Select
            Console.Write("> ")
            selection = Console.ReadLine()
        Loop 
    End Sub 
End Class
#End Region

.NET Framework

Supported in: 4.5.1, 4.5, 4, 3.5, 3.0, 2.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

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

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.