LocalFileSettingsProvider.Upgrade Method

Reference

Definition

Namespace:: System.Configuration

Assembly:: System.Configuration.ConfigurationManager.dll

Assembly:: System.dll

Package:: System.Configuration.ConfigurationManager v6.0.0

Package:: System.Configuration.ConfigurationManager v7.0.0

Package:: System.Configuration.ConfigurationManager v8.0.0

Package:: System.Configuration.ConfigurationManager v9.0.0-preview.2.24128.5

Source:: LocalFileSettingsProvider.cs

Source:: LocalFileSettingsProvider.cs

Source:: LocalFileSettingsProvider.cs

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

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

public:
 virtual void Upgrade(System::Configuration::SettingsContext ^ context, System::Configuration::SettingsPropertyCollection ^ properties);

public void Upgrade (System.Configuration.SettingsContext context, System.Configuration.SettingsPropertyCollection properties);

abstract member Upgrade : System.Configuration.SettingsContext * System.Configuration.SettingsPropertyCollection -> unit
override this.Upgrade : System.Configuration.SettingsContext * System.Configuration.SettingsPropertyCollection -> unit

Public Sub Upgrade (context As SettingsContext, properties As SettingsPropertyCollection)

Parameters

context: SettingsContext

A SettingsContext describing the current application usage.

properties: SettingsPropertyCollection

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

Implements

Upgrade(SettingsContext, SettingsPropertyCollection)

Exceptions

ConfigurationErrorsException

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

-or-

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

Remarks

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.

Applies to