Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

IVsProjectUpgrade Interface

Implemented by project objects that need to upgrade project file formats between different versions of Visual Studio.

Namespace: Microsoft.VisualStudio.Shell.Interop
Assembly: Microsoft.VisualStudio.Shell.Interop (in microsoft.visualstudio.shell.interop.dll)

[InterfaceTypeAttribute(1)] 
[GuidAttribute("75661D39-F5DA-41B9-ABDA-9CF54C6B1AC9")] 
public interface IVsProjectUpgrade
/** @attribute InterfaceTypeAttribute(1) */ 
/** @attribute GuidAttribute("75661D39-F5DA-41B9-ABDA-9CF54C6B1AC9") */ 
public interface IVsProjectUpgrade
InterfaceTypeAttribute(1) 
GuidAttribute("75661D39-F5DA-41B9-ABDA-9CF54C6B1AC9") 
public interface IVsProjectUpgrade

When a user attempts to open a project, UpgradeProject is called by the environment after the project is opened and before any other user action can be taken on the project. If the user had already been prompted to upgrade the solution, then the UPF_SILENTMIGRATE flag is passed in the grfUpgradeFlags parameter. If the user opens a project directly, as in Add Existing Project, then the UPF_SILENTMIGRATE flag is not passed and the project needs to prompt the user to upgrade.

In response to the UpgradeProject call, the project should evaluate whether the project file will be upgraded. If the project does not need to upgrade the project type to a new version, then it can simply return S_OK.

If the project needs to upgrade the project type to a new version, then it must determine whether the project file can be modified by calling QueryEditFiles and passing in a value of QEF_ReportOnly for the rgfQueryEdit parameter. The project then needs to do the following:

  • If the tagVSQueryEditResult value returned in the pfEditCanceled parameter is QER_EditOK, then the upgrade can proceed because the project file can be written.

  • If the tagVSQueryEditResult value returned in the pfEditCanceled parameter is QER_EditNotOK and the tagVSQueryEditResultFlags value has the QER_ReadOnlyNotUnderScc bit set, then UpgradeProject must return failure, because the user should resolve the permissions issue himself/herself. The project should then do the following:

  • If the tagVSQueryEditResult value is QER_EditNotOK and the tagVSQueryEditResultFlags value has the QER_ReadOnlyUnderScc bit set, then the project file should be checked out by calling QueryEditFiles(QEF_ForceEdit_NoPrompting | QEF_DisallowInMemoryEdits,...).

  • If the QueryEditFiles call on the project file causes a "check out" and a "get latest version", then the project will be unloaded and reloaded. UpgradeProject will be called again once another instance of the project is created. On this second call, the project file can be written to disk; the project should save a copy of the project file in the previous format (with an .OLD extension), make its necessary upgrade changes, and save the project file in the new format. Again, if any part of the upgrade process fails, the method should return failure (VS_E_PROJECTMIGRATIONFAILED). This will cause the project to be unloaded in Solution Explorer.

NoteNote

In the instance that your first project (Project1) is placed in the inactive state, then you must return S_OK from the first call to your UpgradeProject implementation.

For an example implementation of this interface, see Basic Project Sample.

Notes to Implementers Implement if you have changed the information persisted in the project file between older and current Visual Studio versions of your product. The environment retrieves this interface by calling QueryInterface from IVsHierarchy.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.