IVsProjectUpgrade Interface

Definition

Namespace:

Microsoft.VisualStudio.Shell.Interop

Assembly:

Microsoft.VisualStudio.Interop.dll

Package:

Microsoft.VisualStudio.Interop v17.12.40391

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

public interface class IVsProjectUpgrade

public interface class IVsProjectUpgrade

__interface IVsProjectUpgrade

[System.Runtime.InteropServices.Guid("75661D39-F5DA-41B9-ABDA-9CF54C6B1AC9")]
[System.Runtime.InteropServices.InterfaceType(System.Runtime.InteropServices.ComInterfaceType.InterfaceIsIUnknown)]
public interface IVsProjectUpgrade

[<System.Runtime.InteropServices.Guid("75661D39-F5DA-41B9-ABDA-9CF54C6B1AC9")>]
[<System.Runtime.InteropServices.InterfaceType(System.Runtime.InteropServices.ComInterfaceType.InterfaceIsIUnknown)>]
type IVsProjectUpgrade = interface

Public Interface IVsProjectUpgrade

Attributes

GuidAttribute InterfaceTypeAttribute

Remarks

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:

  • Report the error to the user by calling ReportErrorInfo.

  • Return the VS_E_PROJECTMIGRATIONFAILED error code to UpgradeProject.

• 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(IVsProjectUpgrade | IVsProjectUpgrade,...).

• 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.

Note

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.

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.

Methods

UpgradeProject(UInt32)

Called by the environment to determine whether the project object needs to upgrade the project to a new version.