Upgrading Projects
Changes to the project model from one version of Visual Studio to the next may require that projects and solutions be upgraded so that they can run on the newer version. The Visual Studio SDK provides interfaces that can be used to implement upgrade support in your own projects.
Upgrade Strategies
To support an upgrade, your project system implementation must define and implement an upgrade strategy. In determining your strategy, you can choose to support side-by-side (SxS) backup, copy backup, or both.
SxS backup means that a project copies only those files that need upgrading in place, adding a suitable file name suffix, for example, ".old".
Copy backup means that a project copies all project items to a user-provided backup location. The relevant files at the original project location are then upgraded.
How Upgrade Works
When a solution created in an earlier version of Visual Studio is opened in a newer version, the IDE checks the solution file to determine if it needs to be upgraded. If upgrading is required, the Upgrade Wizard is automatically launched to walk the user through the upgrade process.
When a solution needs upgrading, it queries each project factory for its upgrade strategy. The strategy determines whether the project factory supports copy backup or SxS backup. The information is sent to the Upgrade Wizard, which collects the information required for the backup and presents the applicable options to the user.
Multi-Project Solutions
If a solution contains multiple projects and the upgrade strategies differ, such as when a C++ project that only supports SxS backup and a Web project that only support copy backup, the project factories must negotiate the upgrade strategy.
The solution queries each project factory for IVsProjectUpgradeViaFactory. It then calls UpgradeProject_CheckOnly to see if global project files need upgrading and to determine the supported upgrade strategies. The Upgrade Wizard is then invoked.
After the user completes the wizard, UpgradeProject is called on each project factory to perform the actual upgrade. To facilitate backup, IVsProjectUpgradeViaFactory methods provide the SVsUpgradeLogger service to log the details of the upgrade process. This service cannot be cached.
After updating all relevant global files, each project factory can choose to instantiate a project. The project implementation must support IVsProjectUpgrade. The UpgradeProject method is then called to upgrade all relevant project items.
Note
The UpgradeProject method does not provide the SVsUpgradeLogger service. This service can be obtained by calling QueryService.
Best Practices
Use the SVsQueryEditQuerySave service to check if you can edit a file before editing it, and can save it before saving it. This will help your backup and upgrade implementations handle project files under source control, files with insufficient permissions, and so forth.
Use the SVsUpgradeLogger service during all phases of backup and upgrade to provide information on the success or failure of the upgrade process.
For more information about backing up and upgrading projects, see the comments for IVsProjectUpgrade in vsshell2.idl.
See Also
Tasks
How to: Upgrade Project Systems