Edit

Share via

Application Settings schema

  • Article

Application settings allow a Windows Forms or ASP.NET application to store and retrieve application-scoped and user-scoped settings. In this context, a setting is any piece of information that may be specific to the application or specific to the current user — anything from a database connection string to the user's preferred default window size.

By default, application settings in a Windows Forms application uses the LocalFileSettingsProvider class, which uses the .NET configuration system to store settings in an XML configuration file. For more information about the files used by application settings, see Application Settings Architecture.

Important

Most configuration sections defined by .NET Framework are no longer functional in .NET 6+ and .NET Core versions. ConfigurationManager is only provided for compatibility. Instead of app.config, modern .NET uses the appsettings.json file for app settings. See Modernize after upgrading to .NET from .NET Framework.

Consider removing the usage in app.config and calling the corresponding API, if available, to make the same setting. For more information, see Configuration in .NET.

Application settings defines the following elements as part of the configuration files it uses.

Element Description
<applicationSettings> Contains all <setting> tags specific to the application.
<userSettings> Contains all <setting> tags specific to the current user.
<setting> Defines a setting. Child of either <applicationSettings> or <userSettings>.
<value> Defines a setting's value. Child of <setting>.

<applicationSettings> element

This element contains all <setting> tags that are specific to an instance of the application on a client computer. It defines no attributes.

<userSettings> element

This element contains all <setting> tags that are specific to the user who is currently using the application. It defines no attributes.

<setting> element

This element defines a setting. It has the following attributes.

Attribute Description
name Required. The unique ID of the setting. Settings created through Visual Studio are saved with the name ProjectName.Properties.Settings.
serializeAs Required. The format to use for serializing the value to text. Valid values are:

- string. The value is serialized as a string using a TypeConverter.
- xml. The value is serialized using XML serialization.
- binary. The value is serialized as text-encoded binary using binary serialization.
- custom. The settings provider has inherent knowledge of this setting and serializes and de-serializes it.

Add the names for settings that you create in <applicationSettings> as entries under the <configSections> element at the top of the file. For example:

<configuration>
    <configSections>
        <sectionGroup name="userSettings" type="System.Configuration.UserSettingsGroup, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" >
            <section name="WindowsFormsApp1.Properties.Settings" type="System.Configuration.ClientSettingsSection, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" allowExeDefinition="MachineToLocalUser" requirePermission="false" />
            <section name="WindowsFormsApp1.Properties.MyCustomSettings" type="System.Configuration.ClientSettingsSection, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" allowExeDefinition="MachineToLocalUser" requirePermission="false" />
        </sectionGroup>
    </configSections>
    ...
</configuration>

<value> element

This element contains the value of a setting.

Example

The following example shows an application settings file that defines two application-scoped settings and two user-scoped settings:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <sectionGroup name="applicationSettings" type="System.Configuration.ApplicationSettingsGroup, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089">
      <section name="WindowsApplication1.Properties.Settings" type="System.Configuration.ClientSettingsSection, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />
    </sectionGroup>
    <sectionGroup name="userSettings" type="System.Configuration.UserSettingsGroup, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089">
      <section name="WindowsApplication1.Properties.Settings" type="System.Configuration.ClientSettingsSection, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" allowExeDefinition="MachineToLocalUser" />
    </sectionGroup>
  </configSections>
  <applicationSettings>
    <WindowsApplication1.Properties.Settings>
      <setting name="Cursor" serializeAs="String">
        <value>Default</value>
      </setting>
      <setting name="DoubleBuffering" serializeAs="String">
        <value>False</value>
      </setting>
    </WindowsApplication1.Properties.Settings>
  </applicationSettings>
  <userSettings>
    <WindowsApplication1.Properties.Settings>
      <setting name="FormTitle" serializeAs="String">
        <value>Form1</value>
      </setting>
      <setting name="FormSize" serializeAs="String">
        <value>595, 536</value>
      </setting>
    </WindowsApplication1.Properties.Settings>
  </userSettings>
</configuration>

See also