Support for Settings Migration
Visual Studio 2008 provides programming support to enable users to migrate settings from a previous installation of Visual Studio 2008 to a new installation on the same computer.
Registering for Migration (Native)
There are three supported options for migrating settings: do not migrate, migrate by using "blind pass through," and migrate by using an explicit interface. When a VSPackage registers, it specifies the options for each category that it implements with a VSSettingsMigration registry key. The registry key is added in one of the following two locations in the system registry:
If the category does not implement settings support, and relies instead on automation, then the VSSettingsMigration registry key should be a value of the AutomationProperties registry key for that category. For example, the Environment\Documents options page registry setting resembles this:
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0\AutomationProperties\Environment\Documents] "VSPackage"="{DA9FB551-C724-11d0-AE1F-00A0C90FFFC3}" "Name"="Environment.Documents" "ProfileSave"=dword:00000001 "Description"="#14892" @="#14562" "VSSettingsMigration"=dword:00000001
For a VSPackage that implements the IVsUserSettings interface explicitly, and does not rely on automation, the VSSettingsMigration key should be a value of the UserSettings registry key for that category. For example, the Environment\Aliases options page registry setting resembles this:
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0\UserSettings\Environment_Group\Environment_Aliases] "VSPackage"="{DA9FB551-C724-11d0-AE1F-00A0C90FFFC3}" "Category"="{AD334E74-368A-4c46-9AF8-F53ABF0775F2}" "SecurityLevel"=dword:00000002 "Description"="#14877" @="#14589" "VSSettingsMigration"=dword:00000001
Valid values for the VSSettingsMigration DWORD are as follows:
0 – do not migrate
1 – blind pass through
2 – explicit interface support for migration.
The first case, 0 (do not migrate), is the default. Do not migrate means that migrating settings may cause instability. Do not migrate can also mean that migration of settings is not desirable, for example, for security settings in the integrated development environment (IDE).
The second case, 1 (blind pass through), is useful for packages that are not changing in a significant way between Visual Studio 2005 and Visual Studio 2008, or that are only adding or removing options. If an option is removed, it has no migration effect. Most migrations will use the blind pass through option. For example, Fonts and Colors will migrate old settings because it is likely that older settings will be meaningful in the next release.
The third case, 2 (explicit interface), is for categories in which certain settings are migrated but not others. For example, Visual C++ project system paths may not be valid after migration and may cause compilation errors. If a category supports this kind of migration, then in addition to writing out the "VSSettingsMigration" registry key, the VSPackage that implements the category must implement the IVsUserSettingsMigration interface, defined in VsShell90.idl:
interface IVsUserSettingsMigration
{
HRESULT MigrateSettings(IVsSettingsReader* pSettingsReader, IVsSettingsWriter* pSettingsWriter, LPCWSTR pszGuidCategory );
}
If the settings migration interface is implemented on a VSPackage, not all categories must use the interface. For ease of implementation, each category may specify independently what type of migration it supports.
Registering for Migration (MPF)
If your VSPackage derives from Package, you can apply an attribute instead of setting the registry values explicitly. Your VSPackage should have a ProvideProfileAttribute or a ProvideOptionPageAttribute for each profile category or options page.
To register for migration, add the named parameter MigrationType to the attribute and give it a value from the ProfileMigrationType enum, specifically None, PassThrough, or Custom.
For example, to register MySettingsCategory settings migration for blind pass through, use this attribute:
[ProvideProfile(typeof(MySettingsCategory), "My Category", "My Page", 110, 111, false, MigrationType=ProfileMigrationType.PassThrough)]
class MyPackage : VSPackage { ... }
To register MyOptionPage options migration for blind pass through, use this attribute:
[ProvideOptionPage(typeof(MyOptionPage), "Option Category", "My Page", 110, 111, false, MigrationType=ProfileMigrationType.PassThrough)]
class MyPackage : VSPackage { ... }
Custom Migration Support (Managed)
If you apply a ProvideProfileAttribute or ProvideOptionPageAttribute to your VSPackage with MigrationType of ProfileMigrationType.Custom, the class that implements the category (whose type is passed as the first parameter to the attribute) must implement Microsoft.VisualStudio.Shell.IProfileMigrator. This interface has a single method, MigrateSettings, which takes two parameters:
an IVsSettingsReader (VsShell80.idl), which provides the earlier version settings.
an IVsSettingsWriter (VsShell80.idl), which the migration code will write the migrated settings to.
The third parameter of this method is a string that represents the category GUID. The category GUID is used by VSPackages that implement multiple categories to distinguish between the categories.
Settings to be migrated may come from different versions of the product. Therefore, the VSPackage migration code must be able to obtain product version information. The VSPackage can use one of the following methods to obtain this information:
Get the category version from IVsSettingsReader.ReadCategoryVersion.
Get the file version from IVsSettingsReader.ReadFileVersion. This is the same as the product version (8.0 for Visual Studio, 9.0 for Visual Studio 2008).
Examine the settings themselves.
After all categories in the imported settings file have been migrated or discarded, the migration is finished. The new settings file will then be imported by using the same import mechanism currently used for profiles.
If an error is encountered during the migration, it should be reported on the IVsSettingsWriter interface. If the error is fatal, then a failing HRESULT should be returned or otherwise handled.
See Also
Concepts
Migrating VSPackages to Visual Studio 2008