UserConfigMigrator 1.5.0

User configuration migrator

Supported Frameworks

A helper utility for migrating user-scoped application settings between different versions of a .NET application.

Useful when:

• Application version upgrades should reuse settings from older versions.
• Stand-alone application should reuse most recent settings when being moved to another execution directory.
• Application company, root namespace or assembly name has changed.
• Supports downgrades by allowing import of settings from future versions.

⚠️ Scope: This is a minimal utility tailored for internal use in .NET desktop applications that store settings using SettingsBase and user.config.
It does not support roaming profiles, custom configuration files, or non-standard config structures.

Features

• Finds the most recent valid user.config file from previous application versions.
• Exports settings from a user.config file.
• Applies exported settings from a user.config file into the current application settings, skipping unknown fields.

📦 NuGet

Install via NuGet Package Manager:

Install-Package UserConfigMigrator

Or via .NET CLI:

dotnet add package UserConfigMigrator

Usage examples

Direct upgrading of user settings

// Upgrade settings from latest user configuration file
UserConfigMigrator.UpgradeSettings(Properties.Settings.Default);

// Store the upgraded settings on hard drive
Properties.Settings.Default.Save();

Upgrading of user settings with support for previous app versions

string assemblyName = Assembly.GetExecutingAssembly().GetName().Name;
string oldCompanyName = "oldCompanyName";

IReadOnlyCollection<UserConfigMigrator.AppInfo> previousAppInfos =
    new ReadOnlyCollection<UserConfigMigrator.AppInfo>(
        new List<UserConfigMigrator.AppInfo>()
        {
            new UserConfigMigrator.AppInfo(
                company: new UserConfigMigrator.Filename(oldCompanyName),
                assembly_name: new UserConfigMigrator.Filename(assemblyName))
        });

UserConfigMigrator.UpgradeSettings(Properties.Settings.Default, previous_app_infos: previousAppInfos);
Properties.Settings.Default.Save();

Step-by-step upgrading of user settings

ConfigurationUserLevel userLevelConf = ConfigurationUserLevel.PerUserRoamingAndLocal;

Version appVersion;
UserConfigMigrator.AppInfo appInfo =
    UserConfigMigrator.GetAppInfoFromCurrentUserConfig(out appVersion, userLevelConf);

string userConfigPath;
if (UserConfigMigrator.TryFindLatestUserConfig(appVersion, appInfo, out userConfigPath))
{
    IDictionary<string, object> exportedSettings =
        UserConfigMigrator.ExportSettings(userConfigPath, Properties.Settings.Default);

    UserConfigMigrator.ApplySettings(exportedSettings, Properties.Settings.Default);
}
Properties.Settings.Default.Save();