How to store and retrieve custom information from an application configuration file by using Visual Basic .NET or Visual Basic 2005 (313405)


The information in this article applies to:

  • Microsoft Visual Basic 2005
  • Microsoft Visual Basic .NET (2003)
  • Microsoft Visual Basic .NET (2002)
This article was previously published under Q313405
For a Microsoft Microsoft Visual C# .NET version of this article, see 815786.

IN THIS TASK

SUMMARY

This article demonstrates how to store custom information in a configuration (.config) file that you can retrieve later during run time by its associated application. This is a helpful when you need to define data that is associated with an application.

back to the top

Requirements

The following list outlines the recommended hardware, software, network infrastructure, and service packs that you need:
  • Microsoft Windows 2000, Microsoft Windows XP, or Microsoft Windows Server 2003
  • Microsoft Visual Studio .NET (2002) or Microsoft Visual Studio .NET (2003) or Microsoft Visual Studio 2005
This article assumes that you are familiar with the following topics:
  • Extensible Markup Language (XML)
  • .NET configuration files
back to the top

Create Console Application That Reads Content of Configuration File

You can store application settings within the configuration file that is associated with the application. Configuration files are saved in XML format. The System.Configuration and the System.Collections.Specialized namespaces in the Microsoft .NET Framework include the necessary classes to retrieve information from a .NET application configuration file during run time.

To create a console application that reads the contents of an associated configuration file during run time, follow these steps:
  1. Start Visual Studio .NET or Visual Studio 2005.
  2. Create a new Console Application project named ConConfig in Visual Basic .NET or Visual Basic 2005. Visual Basic .NET or Visual Basic 2005 creates a module named Module1 by default.
  3. Right-click the ConConfig Project folder, point to Add, and then click Add New Item.

    Note In Visual Studio 2005, right-click the ConConfig Project folder, point to Add, and then click New Item.
  4. In the Add New Item dialog box, select the Application Configuration File template, click Open, and then add the App.config file to the project.

    NoteThe Visual Studio .NET or Visual Studio 2005 IDE copies App.Config to the folder where the executable file is compiled and renames it in <ApplicationName>.<Application Type>.config format.
  5. You can use an application configuration file to collect custom application settings that you save in key/value format. You can include <add> elements in the <appSettings> section of an associated configuration file. Each key/value pair has one <add> element. An <add> element has the following format: 
    <add key="theKey" value="theValue" />
    Add an <appSettings> section with <add> elements to the configuration file between the <configuration> and </configuration> tags. For example, the following configuration file includes an <appSettings> section that specifies three key/value pairs:
    <?xml version="1.0" encoding="utf-8" ?>
<configuration>
	<appSettings>
		<add key="Key0" value="0" />
		<add key="Key1" value="1" />
		<add key="Key2" value="2" />
	</appSettings>
</configuration>
  6. In Solution Explorer, double-click Module1.vb to display the Module1 code window. Add the following statements to your code module:

    Note These statements must appear before any other statements in the file.
    Imports System.Configuration
Imports System.Collections.Specialized
  7. In the Sub Main procedure, dimension a string variable to hold the value from a configuration file key in the <appSettings> section of the configuration file:
    Dim sAttr As String
  8. To retrieve a value for a specified key from the <appSettings> section of the configuration file, use the AppSettings method of the ConfigurationSettings class. The ConfigurationSettings class is in the System.Configuration namespace. When the AppSettings method receives a string input parameter that contains a key, the application retrieves the value that is associated with the key.

    The following code retrieves the value for the Key0 attribute from the associated configuration file. The code then places this value in the string variable, sAttr. If a key does not exist for this value, Nothing is stored in sAttr.
    sAttr = ConfigurationSettings. AppSettings("Key0")
  9. To display the value that the application retrieves in the Console window, use Console.WriteLine:
    Console.WriteLine("The value of Key0: " & sAttr)
  10. You can use one reference to the AppSettings property to retrieve all of the key/value pairs in the <appSettings> section. If you do not specify any parameters when you use the AppSettings property, the application returns all associated key/value pairs. These pairs are stored in a NameValueCollection type, which contains key/value entries for each key that the application retrieves. The NameValueCollection class is in the System.Collections.Specialized namespace.
    Dim sAll As NameValueCollection
sAll = ConfigurationSettings.AppSettings()
  11. The AllKeys property of NameValueCollection references a string array that has an entry for each key that the application retrieves. Use a For Next construction to iterate through the AllKeys array to access each key that the application retrieves. Each key entry in AllKeys is a string data type.
    Dim s As String
For Each s In sAll.AllKeys
  12. Inside the For Each construction, use Console.WriteLine to display the key and its associated value in the Console window. The current key that the application processes is in "s." Use this as an index in the sAllNameValueCollection to obtain its associated value.

    For example, if the application processes the Key0 key, sAll("Key0") retrieves its associated value. The Console.Readline statement pauses the console. You can press ENTER to end the application.
        Console.WriteLine("Key: " & s & " Value: " & sAll(s))
Next
Console.Readline
back to the top

Verify That It Works

Press the F5 key to run the code. The Console window should display the key/value pairs from the <appSettings> section of the associated configuration file as follows: 

The value of Key0: 0
Key: Key0 Value:0
Key: Key1 Value:1
Key: Key2 Value:2

back to the top

Complete Code Listing

Imports System.Configuration
Imports System.Collections.Specialized

Module Module1

    Sub Main()
        Dim sAttr As String

        sAttr = ConfigurationSettings.AppSettings("Key0")
        Console.WriteLine("The value of Key0: " & sAttr)
        
        Dim sAll As NameValueCollection
        sAll = ConfigurationSettings.AppSettings()

        Dim s As String
        For Each s In sAll.AllKeys
            Console.WriteLine("Key: " & s & " Value: " & sAll(s))
        Next
		  Console.ReadLine()
    End Sub

End Module
back to the top

Complete Configuration File Listing (ConConfig.exe.config)

<configuration>
	<appSettings>
		<add key="Key0" value="0"/>
		<add key="Key1" value="1"/>
		<add key="Key2" value="2"/>
	</appSettings>
</configuration>
back to the top

Troubleshooting

  • The configuration file is saved in XML format. Make sure that you follow all XML syntax rules. Remember that XML is case sensitive. If the XML is not well formed, or if an element is misspelled, you receive a System.Configuration.Configuration exception.

    For example, if you add the key attribute of an <add> element with an uppercase "K" instead of a lowercase "k," or if the <appSettings> section appears as <AppSettings> (with an uppercase "A" instead of a lowercase "a"), you receive an error message.
  • The configuration file must be included in the project.
  • You must use the following syntax for the configuration file name when the file is created outside of the Visual Studio environment and it must reside in the same folder as its associated application:

    ApplicationName.ApplicationType.config

    where ApplicationName is the name of the application, ApplicationType is the type of application (for example, exe), and .config is the required suffix.
back to the top

REFERENCES

For more information, visit the following MSDN Web sites:

ConfigurationSettings.AppSettings Property
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfSystemConfigurationConfigurationSettingsClassAppSettingsTopic.asp

System.Configuration Namespace
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfSystemConfiguration.asp

back to the top
Modification Type:MinorLast Reviewed:10/3/2006
Keywords:kbvs2005swept kbvs2005applies kbConfig kbHOWTOmaster KB313405 kbAudDeveloper
©2004 Microsoft Corporation. All rights reserved.