プロジェクトのアップグレード

あるバージョンの Visual Studio から次のバージョンへのプロジェクトモデルの変更では、新しいバージョンで実行できるようにプロジェクトとソリューションをアップグレードする必要がある場合があります。 Visual Studio SDK には、独自のプロジェクトでアップグレードサポートを実装するために使用できるインターフェイスが用意されています。

アップグレード戦略

アップグレードをサポートするには、プロジェクトシステムの実装でアップグレード戦略を定義して実装する必要があります。戦略を決定する際に、サイドバイサイド (SxS) バックアップ、コピーバックアップ、またはその両方をサポートすることを選択できます。

SxS バックアップとは、アップグレードが必要なファイルのみをコピーし、適切なファイル名サフィックス ("old" など) を追加することを意味します。
バックアップのコピーとは、プロジェクトがユーザー指定のバックアップ場所にすべてのプロジェクト項目をコピーすることを意味します。その後、元のプロジェクトの場所にある関連ファイルがアップグレードされます。

アップグレードのしくみ

以前のバージョンの Visual Studio で作成されたソリューションが新しいバージョンで開かれると、IDE はソリューションファイルをチェックして、アップグレードが必要かどうかを判断します。アップグレードが必要な場合は、 アップグレードウィザード が自動的に起動され、アップグレードプロセスがユーザーに表示されます。

ソリューションでアップグレードが必要な場合は、各プロジェクトファクトリに対してアップグレード戦略のクエリを実行します。この戦略では、プロジェクトファクトリがコピーバックアップと SxS バックアップのどちらをサポートしているかを決定します。この情報は アップグレードウィザードに送信され、バックアップに必要な情報が収集され、該当するオプションがユーザーに表示されます。

マルチプロジェクトソリューション

ソリューションに複数のプロジェクトが含まれており、アップグレード戦略が異なる場合 (SxS バックアップのみをサポートする C++ プロジェクトと、コピーバックアップのみをサポートする Web プロジェクトがある場合など)、プロジェクトファクトリはアップグレード戦略をネゴシエートする必要があります。

ソリューションは、各プロジェクトファクトリに対して IVsProjectUpgradeViaFactoryのクエリを実行します。その後、 UpgradeProject_CheckOnly を呼び出して、グローバルプロジェクトファイルのアップグレードが必要かどうかを確認し、サポートされているアップグレード戦略を決定します。その後、 アップグレードウィザード が呼び出されます。

ユーザーがウィザードを完了すると、各プロジェクトファクトリで UpgradeProject が呼び出され、実際のアップグレードが実行されます。バックアップを容易にするために、IVsProjectUpgradeViaFactory メソッドは、アップグレードプロセスの詳細をログに記録する SVsUpgradeLogger サービスを提供します。このサービスはキャッシュできません。

関連するすべてのグローバルファイルを更新した後、各プロジェクトファクトリはプロジェクトのインスタンス化を選択できます。プロジェクトの実装では、 IVsProjectUpgradeをサポートする必要があります。その後、 UpgradeProject メソッドが呼び出され、関連するすべてのプロジェクト項目がアップグレードされます。

注

UpgradeProject メソッドは、SVsUpgradeLogger サービスを提供しません。このサービスは、 QueryServiceを呼び出すことによって取得できます。

ベストプラクティス

SVsQueryEditQuerySave サービスを使用して、ファイルを編集する前に編集できるかどうかを確認し、保存する前に保存できます。これにより、バックアップとアップグレードの実装では、ソース管理下のプロジェクトファイル、アクセス許可が不十分なファイルなどを処理できます。

バックアップとアップグレードのすべてのフェーズで SVsUpgradeLogger サービスを使用して、アップグレードプロセスの成功または失敗に関する情報を提供します。

プロジェクトのバックアップとアップグレードの詳細については、vsshell2.idl の IVsProjectUpgrade のコメントを参照してください。

カスタムプロジェクトのアップグレード

製品の異なる Visual Studio バージョン間でプロジェクトファイルに保存されている情報を変更する場合は、プロジェクトファイルを古いバージョンから新しいバージョンにアップグレードするサポートが必要です。 Visual Studio 変換ウィザードに参加できるアップグレードをサポートするには、IVsProjectUpgradeViaFactory インターフェイスを実装します。このインターフェイスには、コピーのアップグレードに使用できる唯一のメカニズムが含まれています。プロジェクトのアップグレードは、ソリューションの一部が開くと発生します。 IVsProjectUpgradeViaFactory インターフェイスはプロジェクトファクトリによって実装されるか、少なくともプロジェクトファクトリから取得できる必要があります。

IVsProjectUpgrade インターフェイスを使用する古いメカニズムは引き続きサポートされていますが、概念的にはプロジェクトシステムが開いているプロジェクトの一部としてアップグレードされます。そのため、 IVsProjectUpgrade インターフェイスは、 IVsProjectUpgradeViaFactory インターフェイスが呼び出されたり実装されたりした場合でも、Visual Studio 環境によって呼び出されます。このアプローチでは、IVsProjectUpgradeViaFactory を使用してアップグレードの一部であるコピーとプロジェクトを実装し、残りの作業を IVsProjectUpgrade インターフェイスに委任して、その場で（場合によっては新しい場所で）実行させることができます。

IVsProjectUpgradeの実装例については、VSSDK サンプルを参照してください。

プロジェクトのアップグレードでは、次のシナリオが発生します。

プロジェクトがサポートできるより新しい形式のファイルの場合は、これを示すエラーを返す必要があります。これは、製品の古いバージョンにバージョンを確認するコードが含まれていることを前提としています。
PUVFF_SXSBACKUP フラグが UpgradeProject メソッドで指定されている場合、アップグレードはプロジェクトを開く前にインプレースアップグレードとして実装されます。
PUVFF_COPYBACKUP メソッドで UpgradeProject フラグが指定されている場合、アップグレードはコピーアップグレードとして実装されます。
UPF_SILENTMIGRATE呼び出しで UpgradeProject フラグが指定されている場合、ユーザーは、プロジェクトを開いた後、プロジェクトファイルをインプレースアップグレードとしてアップグレードするように環境から求められます。たとえば、環境では、ユーザーが古いバージョンのソリューションを開いたときに、ユーザーにアップグレードを求めるメッセージが表示されます。
UPF_SILENTMIGRATE呼び出しでUpgradeProject フラグが指定されていない場合は、プロジェクトファイルをアップグレードするようにユーザーに求める必要があります。

アップグレードプロンプトメッセージの例を次に示します。

"プロジェクト '%1' は、以前のバージョンの Visual Studio で作成されました。このバージョンの Visual Studio で開くと、古いバージョンの Visual Studio で開くことができない場合があります。このプロジェクトを続行して開いてみませんか?

IVsProjectUpgradeViaFactory を実装するには

IVsProjectUpgradeViaFactory インターフェイスのメソッド、特にプロジェクトファクトリの実装で UpgradeProject メソッドを実装するか、プロジェクトファクトリの実装から実装を呼び出し可能にします。
ソリューションオープンの一部としてインプレースアップグレードを実行する場合は、PUVFF_SXSBACKUP実装のVSPUVF_FLAGS パラメーターとしてフラグ UpgradeProjectを指定します。
ソリューションオープンの一部としてインプレースアップグレードを実行する場合は、PUVFF_COPYBACKUP実装のVSPUVF_FLAGS パラメーターとしてフラグ UpgradeProjectを指定します。
手順 2 と 3 の両方で、 IVsQueryEditQuerySave2を使用した実際のファイルアップグレード手順は、以下の「 IVsProjectUpgadeの実装」セクションの説明に従って実装することも、実際のファイルアップグレードを IVsProjectUpgradeに委任することもできます。
IVsUpgradeLoggerのメソッドを使用して、Visual Studio 移行ウィザードを使用してユーザーのアップグレード関連メッセージを投稿します。
IVsFileUpgrade インターフェイスは、プロジェクトアップグレードの一環として行う必要があるあらゆる種類のファイルアップグレードを実装するために使用されます。このインターフェイスは IVsProjectUpgradeViaFactoryから呼び出されませんが、プロジェクトシステムの一部であるファイルをアップグレードするためのメカニズムとして提供されますが、メインプロジェクトシステムが直接認識していない可能性があります。たとえば、この状況は、コンパイラ関連のファイルとプロパティが、プロジェクトシステムの残りの部分を処理する同じ開発チームによって処理されない場合に発生する可能性があります。

IVsProjectUpgrade の実装

プロジェクトシステムが IVsProjectUpgrade のみを実装している場合、 Visual Studio 変換ウィザードには参加できません。ただし、 IVsProjectUpgradeViaFactory インターフェイスを実装した場合でも、ファイルのアップグレードを IVsProjectUpgrade 実装に委任できます。

IVsProjectUpgrade を実装するには

ユーザーがプロジェクトを開こうとすると、 UpgradeProject メソッドは、プロジェクトを開いた後、およびプロジェクトに対して他のユーザーアクションを実行する前に、環境によって呼び出されます。ユーザーが既にソリューションのアップグレードを求められた場合は、 UPF_SILENTMIGRATE フラグが grfUpgradeFlags パラメーターに渡されます。ユーザーが [既存のプロジェクトの追加 ] コマンドを使用するなどしてプロジェクトを直接開いた場合、 UPF_SILENTMIGRATE フラグは渡されず、プロジェクトはユーザーにアップグレードを求める必要があります。
UpgradeProject呼び出しに応答して、プロジェクトファイルがアップグレードされているかどうかを評価する必要があります。プロジェクトの種類を新しいバージョンにアップグレードする必要がない場合は、 S_OK フラグを返すだけです。
プロジェクトの種類を新しいバージョンにアップグレードする必要がある場合は、QueryEditFiles メソッドを呼び出し、tagVSQueryEditFlags パラメーターにrgfQueryEditの値を渡すことによって、プロジェクトファイルを変更できるかどうかを判断する必要があります。その後、プロジェクトで次の操作を行う必要があります。
- VSQueryEditResult パラメーターで返されるpfEditCanceled値がQER_EditOK場合は、プロジェクトファイルを書き込むことができるため、アップグレードを続行できます。
- VSQueryEditResult パラメーターで返されるpfEditCanceled値がQER_EditNotOKされ、VSQueryEditResult値にQER_ReadOnlyNotUnderScc ビットが設定されている場合は、ユーザーがアクセス許可の問題を自分で解決する必要があるため、UpgradeProjectはエラーを返す必要があります。その後、プロジェクトで次の操作を行う必要があります。
  
  ReportErrorInfoを呼び出してユーザーにエラーを報告し、VS_E_PROJECTMIGRATIONFAILEDエラーコードをIVsProjectUpgradeに返します。
- VSQueryEditResult値がQER_EditNotOKされ、VSQueryEditResultFlags値にQER_ReadOnlyUnderScc ビットが設定されている場合は、QueryEditFiles (QEF_ForceEdit_NoPrompting、QEF_DisallowInMemoryEdits,...) を呼び出してプロジェクトファイルをチェックアウトする必要があります。
プロジェクトファイルの QueryEditFiles 呼び出しによってファイルがチェックアウトされ、最新バージョンが取得された場合、プロジェクトはアンロードされ、再読み込みされます。プロジェクトの別のインスタンスが作成されると、 UpgradeProject メソッドが再度呼び出されます。この 2 回目の呼び出しでは、プロジェクトファイルをディスクに書き込むことができます。プロジェクトは、前の形式でプロジェクトファイルのコピーを保存することをお勧めします。OLD 拡張機能を使用して、必要なアップグレードを変更し、プロジェクトファイルを新しい形式で保存します。ここでも、アップグレードプロセスのいずれかの部分が失敗した場合、メソッドは VS_E_PROJECTMIGRATIONFAILEDを返すことによってエラーを示す必要があります。これにより、ソリューションエクスプローラーでプロジェクトがアンロードされます。

QueryEditFiles メソッドの呼び出し (ReportOnly の値を指定) がQER_EditNotOKフラグとQER_ReadOnlyUnderScc フラグを返す場合に、環境内で発生する完全なプロセスを理解することが重要です。
ユーザーがプロジェクトファイルを開こうとします。
環境は、 CanCreateProject 実装を呼び出します。
CanCreateProjectがtrueを返す場合、環境はCanCreateProject実装を呼び出します。
環境は、 Load 実装を呼び出してファイルを開き、プロジェクトオブジェクト (Project1 など) を初期化します。
環境は IVsProjectUpgrade::UpgradeProject 実装を呼び出して、プロジェクトファイルをアップグレードする必要があるかどうかを判断します。
QueryEditFilesを呼び出し、QEF_ReportOnly パラメーターに rgfQueryEdit の値を渡します。
環境はVSQueryEditResultのQER_EditNotOKを返し、VSQueryEditResultFlagsでQER_ReadOnlyUnderSccビットが設定されます。
IVsProjectUpgrade実装では、IVsQueryEditQuerySave::QueryEditFiles (QEF_ForceEdit_NoPrompting、QEF_DisallowInMemoryEdits) が呼び出されます。

この呼び出しにより、プロジェクトファイルの新しいコピーがチェックアウトされ、最新バージョンが取得される可能性があります。また、プロジェクトファイルを再読み込みする必要があります。この時点で、次の 2 つのいずれかが発生します。

独自のプロジェクトの再読み込みを処理する場合、環境は ReloadItem (VSITEMID_ROOT) 実装を呼び出します。この呼び出しを受け取ったら、プロジェクトの最初のインスタンス (Project1) を再読み込みし、プロジェクトファイルのアップグレードを続行します。環境は、GetProperty (VSHPROPID_HandlesOwnReload) にtrueを返すと、自分のプロジェクトの再読み込みを処理することを認識しています。
自分のプロジェクトの再読み込みを管理しない場合は、GetProperty (VSHPROPID_HandlesOwnReload) に対してfalseを返します。この場合、 QueryEditFiles(QEF_ForceEdit_NoPrompting、QEF_DisallowInMemoryEdits) が返される前に、次のようにプロジェクトの別の新しいインスタンス (Project2 など) が作成されます。
1. 環境は、最初のプロジェクトオブジェクト Project1 で Close を呼び出し、このオブジェクトを非アクティブ状態にします。
2. 環境は、プロジェクト Project2 の 2 番目のインスタンスを作成するために、 IVsProjectFactory::CreateProject 実装を呼び出します。
3. 環境は、 IPersistFileFormat::Load 実装を呼び出してファイルを開き、2 番目のプロジェクトオブジェクト Project2 を初期化します。
4. 環境は IVsProjectUpgrade::UpgradeProject をもう一度呼び出して、プロジェクトオブジェクトをアップグレードする必要があるかどうかを判断します。ただし、この呼び出しは、プロジェクト Project2 の新しい 2 番目のインスタンスで行われます。これは、ソリューションで開かれるプロジェクトです。
  
  注
  
  最初のプロジェクト Project1 が非アクティブな状態になっている場合は、最初の呼び出しからS_OK実装へのUpgradeProjectを返す必要があります。
5. QueryEditFilesを呼び出し、QEF_ReportOnly パラメーターに rgfQueryEdit の値を渡します。
6. 環境は QER_EditOK を返し、プロジェクトファイルを書き込むことができるため、アップグレードを続行できます。

アップグレードに失敗した場合は、VS_E_PROJECTMIGRATIONFAILEDからIVsProjectUpgrade::UpgradeProject返します。アップグレードが必要ない場合、またはアップグレードしない場合は、 IVsProjectUpgrade::UpgradeProject 呼び出しを no-opとして扱います。 VS_E_PROJECTMIGRATIONFAILEDを返すと、プレースホルダーノードがプロジェクトのソリューションに追加されます。

プロジェクト項目のアップグレード

実装していないプロジェクトシステム内の項目を追加または管理する場合は、プロジェクトのアップグレードプロセスに参加することが必要になる場合があります。 Crystal Reports は、プロジェクトシステムに追加できる項目の例です。

通常、プロジェクト項目の実装者は、既に完全にインスタンス化され、アップグレードされたプロジェクトを活用したいと考えています。アップグレードの決定を行うには、プロジェクト参照の内容とその他のプロジェクトプロパティを把握する必要があるためです。