Using .Net Settings? Hate it when you rev your app and the settings "go away"? Here's why and how to fix that (cough... "Settings.Upgrade()" cough)

John's Workshop - Automatically upgrading user settings after an application version change

Suppose you’re building a .NET desktop or console application and are using the standard Settings file to keep track of any user-specific settings, as well as providing their default values. Then, suppose you upgrade your application version and notice that all of the user settings have been reset to their default values! Why does this happen and what can you do about it?

What Seems to Be the Problem?

...

Here’s the important part: the application version number is part of the path to the settings file containing the user modified values! So, if you upgrade the version number of the application to 2.0.0.0 and run it again, the application would no longer see the user-made changes from version 1.0.0.0. This is because the application can’t find a folder containing the exact version number and it falls back to the embedded default settings.

The Solution

Luckily, there is a rather simple solution to the whole problem: call the Settings.Upgrade() method. This will actually collect and merge all user-modified settings from previous versions of your application and store them in a new user.config file, mapped to the current application version. So, you could basically call Settings.Upgrade() every time your application starts, or you could use…

A Smarter Solution

Here is a neat little trick I’ve come up with, which will help you detect whether a settings upgrade is required. Let’s see the code snippet first, and then I’ll explain:

...

And there you go! Here’s how the whole thing works: The first time your application starts, the UpgradeRequired flag will be set. This means that the Upgrade() method will be called (which won’t really do anything at this point) and the flag will be cleared. If you start the application again, the flag will be cleared and no upgrade will be performed. When you do upgrade the application version, however, the default settings will be used – and the default value of the UpgradeRequired flag is again True. So, the settings file will be upgraded and the flag will be cleared again. That’s it!

ApplicationSettingsBase.Upgrade Method

"...

The Upgrade method performs two actions to assure smooth transition to a new version of an application:

• It notifies all of the corresponding settings providers of the existence of the upgraded application through a call to their IApplicationSettingsProvider.Upgrade method, assuming they have implemented the IApplicationSettingsProvider interface. This action is not performed if the settings wrapper class is marked with NoSettingsVersionUpgradeAttribute.

• It reloads the values for all of the application settings.

You can override the default behavior of Upgrade to implement custom upgrading or merging behavior. Use the GetPreviousVersion method to retrieve individual values for a setting for the previous version of the application. Examples of custom upgrade behavior include:

• Using new policy defaults that override one or more of the previous user-specified values or previous defaults.

• Special translation of old values to be compatible with newer ranges, a different settings property group, and so on.

..."

sigh... I hate my old brain. I've been using Settings for forever and never knew about this feature (which was added in .Net 2.0). Now I knew the why, that the app version was in the file path, but never realized there was an upgrade method.

Anyway, John provides a great post on the how and why of it and how to build an even better upgrade code snippet.