LocalFileSettingsProvider.Upgrade Method (SettingsContext, SettingsPropertyCollection)


The .NET API Reference documentation has a new home. Visit the .NET API Browser on docs.microsoft.com to see the new experience.

Attempts to migrate previous user-scoped settings from a previous version of the same application.

Namespace:   System.Configuration
Assembly:  System (in System.dll)

public void Upgrade(
	SettingsContext context,
	SettingsPropertyCollection properties


Type: System.Configuration.SettingsContext

A SettingsContext describing the current application usage.

Type: System.Configuration.SettingsPropertyCollection

A SettingsPropertyCollection containing the settings property group whose values are to be retrieved.

Exception Condition

A user-scoped setting was encountered but the current configuration only supports application-scoped settings.


The previous version of the configuration file could not be accessed.

LocalFileSettingsProvider migrates the local and roaming settings in separate operations.

The Upgrade method is suppressed for every application setting that has the NoSettingsVersionUpgradeAttribute applied to it, or to the entire settings wrapper class, derived from ApplicationSettingsBase.

This way this method is called depends on the type of application that is being upgraded:

  • Each version of a ClickOnce application is stored in its own isolated installation directory. After a new version of a ClickOnce application is installed, and when the new version is first run, internal logic will automatically call Upgrade to migrate all common application settings to the new version. For more information, see ClickOnce and Application Settings.

  • Standard Windows Forms and console applications must manually call Upgrade, because there is not a general, automatic way to determine when such an application is first run. The two common ways to do this are either from the installation program or using from the application itself, using a persisted property, often named something like IsFirstRun.

Note that for the newer version to migrate application settings, it must be able to also load and read the older version of the application settings. Therefore, it must contain wrapper classes compatible with both the new and previous versions of the application.

.NET Framework
Available since 2.0
Return to top