LocalFileSettingsProvider.Upgrade(SettingsContext, SettingsPropertyCollection) Method

Definition

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

Exceptions

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

See also