LocalFileSettingsProvider.Upgrade Method
Definition
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 -> unitPublic 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.
