Freigeben über

Aktualisieren von Projekten

Änderungen am Projektmodell von einer Version von Visual Studio zum nächsten erfordern möglicherweise, dass Projekte und Lösungen aktualisiert werden, damit sie auf der neueren Version ausgeführt werden können. Das Visual Studio SDK stellt Schnittstellen bereit, die zum Implementieren der Upgradeunterstützung in Ihren eigenen Projekten verwendet werden können.

Upgrade-Strategien

Um ein Upgrade zu unterstützen, muss ihre Projektsystemimplementierung eine Upgradestrategie definieren und implementieren. Bei der Festlegung Ihrer Strategie können Sie auswählen, ob Sie die Sicherung nebeneinander (SxS) unterstützen, die Kopiersicherung verwenden oder beides.

  • Die SxS-Sicherung bedeutet, dass ein Projekt nur die Dateien kopiert, die ein Upgrade erfordern, indem ein geeignetes Dateinamensuffix hinzugefügt wird, z. B. ".old".

  • Eine Sicherungskopie bedeutet, dass ein Projekt alle Projektelemente an einen vom Benutzer bereitgestellten Sicherungsspeicherort kopiert. Die relevanten Dateien am ursprünglichen Projektspeicherort werden dann aktualisiert.

So funktioniert das Upgrade

Wenn eine in einer früheren Version von Visual Studio erstellte Lösung in einer neueren Version geöffnet wird, überprüft die IDE die Lösungsdatei, um festzustellen, ob ein Upgrade erforderlich ist. Wenn ein Upgrade erforderlich ist, wird der Upgrade-Assistent automatisch gestartet, um den Benutzer durch den Upgradeprozess zu führen.

Wenn eine Lösung ein Upgrade benötigt, fragt sie jede Projektfactory nach ihrer Upgradestrategie ab. Die Strategie bestimmt, ob die Projektfabrik Copy-Backup oder SxS-Backup unterstützt. Die Informationen werden an den Upgrade-Assistenten gesendet, der die für die Sicherung erforderlichen Informationen sammelt und dem Benutzer die entsprechenden Optionen anzeigt.

Multiprojektlösungen

Wenn eine Lösung mehrere Projekte enthält und sich die Upgradestrategien unterscheiden, z. B. wenn ein C++-Projekt, das nur SxS-Sicherung unterstützt, und ein Webprojekt, das nur Kopiersicherung unterstützt, müssen die Projektfabriken die Upgradestrategie aushandeln.

Die Lösung fragt jede Projektfabrik für IVsProjectUpgradeViaFactory ab. Anschließend wird aufgerufen UpgradeProject_CheckOnly , um festzustellen, ob globale Projektdateien ein Upgrade benötigen und um die unterstützten Upgradestrategien zu ermitteln. Der Upgrade-Assistent wird dann aufgerufen.

Nachdem der Benutzer den Assistenten abgeschlossen hat, wird UpgradeProject bei jeder Projektfabrik aufgerufen, um das tatsächliche Upgrade auszuführen. Um die Sicherung zu vereinfachen, stellen IVsProjectUpgradeViaFactory-Methoden den SVsUpgradeLogger Dienst bereit, um die Details des Upgradeprozesses zu protokollieren. Dieser Dienst kann nicht zwischengespeichert werden.

Nach dem Aktualisieren aller relevanten globalen Dateien kann jede Projektfabrik auswählen, ob ein Projekt instanziiert werden soll. Die Projektimplementierung muss IVsProjectUpgrade unterstützen. Die UpgradeProject Methode wird dann aufgerufen, um alle relevanten Projektelemente zu aktualisieren.

Hinweis

Die UpgradeProject Methode stellt den SVsUpgradeLogger-Dienst nicht bereit. Dieser Dienst kann durch Aufrufen QueryServiceabgerufen werden.

Bewährte Methoden

Verwenden Sie den SVsQueryEditQuerySave Dienst, um zu überprüfen, ob Sie eine Datei vor der Bearbeitung bearbeiten können, und sie vor dem Speichern speichern können. Auf diese Weise können Sie Ihre Sicherungs- und Upgradeimplementierungen bei der Verarbeitung von Projektdateien unter Quellcodeverwaltung, Dateien mit unzureichenden Berechtigungen usw. unterstützen.

Verwenden Sie den SVsUpgradeLogger Dienst in allen Phasen der Sicherung und des Upgrades, um Informationen zum Erfolg oder Fehler des Upgradeprozesses bereitzustellen.

Weitere Informationen zum Sichern und Aktualisieren von Projekten finden Sie in den Kommentaren für IVsProjectUpgrade in vsshell2.idl.

Aktualisieren von benutzerdefinierten Projekten

Wenn Sie die in der Projektdatei gespeicherten Informationen zwischen verschiedenen Visual Studio-Versionen Ihres Produkts ändern, müssen Sie das Upgrade der Projektdatei von der alten auf die neue Version unterstützen. Um das Upgrade zu unterstützen, mit dem Sie am Visual Studio-Konvertierungs-Assistenten teilnehmen können, implementieren Sie die IVsProjectUpgradeViaFactory Schnittstelle. Diese Schnittstelle enthält den einzigen Mechanismus, der für das Kopieren von Upgrades verfügbar ist. Das Upgrade des Projekts erfolgt, wenn ein Teil der Projektmappe geöffnet wird. Die IVsProjectUpgradeViaFactory Schnittstelle wird von der Projektfabrik implementiert oder sollte zumindest von der Projektfabrik bezogen werden können.

Der alte Mechanismus, der die IVsProjectUpgrade Schnittstelle verwendet, wird weiterhin unterstützt, aber konzeptionell aktualisiert das Projektsystem als Teil des geöffneten Projekts. Die IVsProjectUpgrade Schnittstelle wird daher von der Visual Studio-Umgebung aufgerufen, auch wenn die IVsProjectUpgradeViaFactory Schnittstelle aufgerufen oder implementiert wird. Mit diesem Ansatz können Sie IVsProjectUpgradeViaFactory verwenden, um nur bestimmte Teile des Upgrades zu kopieren und projizieren, und die restlichen Arbeiten können an die IVsProjectUpgrade Schnittstelle delegiert werden, die diese direkt (möglicherweise am neuen Speicherort) ausführt.

Eine Beispielimplementierung von IVsProjectUpgrade, finden Sie unter VSSDK-Beispiele.

Die folgenden Szenarien ergeben sich bei Projektupgrades:

  • Wenn die Datei ein neueres Format aufweist, als das Projekt unterstützen kann, muss ein Fehler zurückgegeben werden, der dies angibt. Dabei wird davon ausgegangen, dass die ältere Version Ihres Produkts Code enthält, um nach der Version zu suchen.

  • Wenn das PUVFF_SXSBACKUP-Flag in der UpgradeProject-Methode angegeben ist, wird das Upgrade als In-Place-Upgrade implementiert, bevor das Projekt geöffnet wird.

  • Wenn das PUVFF_COPYBACKUP Flag in der UpgradeProject Methode angegeben ist, wird das Upgrade als Kopierupgrade implementiert.

  • Wenn das UPF_SILENTMIGRATE Flag im UpgradeProject Aufruf angegeben ist, wird der Benutzer von der Umgebung aufgefordert, die Projektdatei nach dem Öffnen des Projekts als Upgrade vor Ort zu aktualisieren. Beispielsweise fordert die Umgebung den Benutzer auf, ein Upgrade durchzuführen, wenn der Benutzer eine ältere Version der Lösung öffnet.

  • Wenn das UPF_SILENTMIGRATE Flag im UpgradeProject Aufruf nicht angegeben ist, müssen Sie den Benutzer auffordern, die Projektdatei zu aktualisieren.

    Im Folgenden sehen Sie eine Beispiel für eine Upgradeaufforderungsmeldung:

    Das Projekt "%1" wurde mit einer älteren Version von Visual Studio erstellt. Wenn Sie es mit dieser Version von Visual Studio öffnen, können Sie es möglicherweise nicht mit älteren Versionen von Visual Studio öffnen. Möchten Sie dieses Projekt fortsetzen und öffnen?"

So implementieren Sie IVsProjectUpgradeViaFactory

  1. Implementieren Sie die Methode der IVsProjectUpgradeViaFactory Schnittstelle, insbesondere die UpgradeProject Methode in ihrer Projektfactoryimplementierung, oder machen Sie die Implementierungen aus der Projektfactoryimplementierung aufrufbar.

  2. Wenn Sie ein direktes Upgrade als Teil der Lösungsöffnung durchführen möchten, geben Sie das Flag PUVFF_SXSBACKUP als VSPUVF_FLAGS Parameter in Ihrer UpgradeProject Implementierung an.

  3. Wenn Sie ein direktes Upgrade als Teil der Lösungsöffnung durchführen möchten, geben Sie das Flag PUVFF_COPYBACKUP als VSPUVF_FLAGS Parameter in Ihrer UpgradeProject Implementierung an.

  4. Für die Schritte 2 und 3 können die tatsächlichen Datei-Upgradeschritte mittels IVsQueryEditQuerySave2, wie im Abschnitt "Implementieren IVsProjectUpgade" unten beschrieben, implementiert werden, oder das tatsächliche Datei-Upgrade kann an IVsProjectUpgrade delegiert werden.

  5. Verwenden Sie die Methoden von IVsUpgradeLogger, um dem Benutzer mithilfe des Visual Studio-Migrations-Assistenten Upgrademeldungen bereitzustellen.

  6. IVsFileUpgrade Die Schnittstelle wird verwendet, um jede Art von Dateiupgrade zu implementieren, die als Teil des Projektupgrades erfolgen muss. Diese Schnittstelle wird nicht von IVsProjectUpgradeViaFactory aufgerufen, sondern als Mechanismus bereitgestellt, um Dateien zu aktualisieren, die zwar Teil des Projektsystems sind, von dem Hauptprojektsystem jedoch möglicherweise nicht direkt erkannt werden. Diese Situation kann beispielsweise auftreten, wenn die compilerbezogenen Dateien und Eigenschaften nicht von demselben Entwicklungsteam behandelt werden, das den Rest des Projektsystems behandelt.

IVsProjectUpgrade-Implementierung

Wenn Ihr Projektsystem nur IVsProjectUpgrade implementiert, kann es nicht am Visual Studio-Konvertierungs-Assistent teilnehmen. Selbst wenn Sie die IVsProjectUpgradeViaFactory Schnittstelle implementieren, können Sie jedoch das Dateiupgrade trotzdem an die IVsProjectUpgrade Implementierung delegieren.

So implementieren Sie IVsProjectUpgrade

  1. Wenn ein Benutzer versucht, ein Projekt zu öffnen, wird die UpgradeProject Methode von der Umgebung aufgerufen, nachdem das Projekt geöffnet wurde, und bevor eine andere Benutzeraktion für das Projekt ausgeführt werden kann. Wenn der Benutzer bereits aufgefordert wurde, die Lösung zu aktualisieren, wird das UPF_SILENTMIGRATE Flag im grfUpgradeFlags Parameter übergeben. Wenn der Benutzer ein Projekt direkt öffnet, z. B. mithilfe des Befehls " Vorhandenes Projekt hinzufügen ", wird das UPF_SILENTMIGRATE Flag nicht übergeben, und das Projekt muss den Benutzer zum Upgrade auffordern.

  2. Als Reaktion auf den UpgradeProject Aufruf muss das Projekt auswerten, ob die Projektdatei aktualisiert wird. Wenn das Projekt den Projekttyp nicht auf eine neue Version aktualisieren muss, kann es einfach die S_OK Kennzeichnung zurückgeben.

  3. Wenn das Projekt den Projekttyp auf eine neue Version aktualisieren muss, muss sie bestimmen, ob die Projektdatei geändert werden kann, indem sie die QueryEditFiles Methode aufruft und einen Wert für tagVSQueryEditFlags den rgfQueryEdit Parameter übergibt. Das Projekt muss dann folgendes ausführen:

  4. Wenn der QueryEditFiles Aufruf der Projektdatei bewirkt, dass die Datei ausgecheckt und die neueste Version abgerufen wird, wird das Projekt entladen und neu geladen. Die UpgradeProject Methode wird erneut aufgerufen, sobald eine andere Instanz des Projekts erstellt wird. Bei diesem zweiten Aufruf kann die Projektdatei auf den Datenträger geschrieben werden. Es wird empfohlen, dass das Projekt eine Kopie der Projektdatei im vorherigen Format mit der Erweiterung .OLD speichert, die erforderlichen Aktualisierungsänderungen vornimmt und die Projektdatei im neuen Format speichert. Wenn ein Teil des Upgradeprozesses fehlgeht, muss die Methode einen Fehler anzeigen, indem sie VS_E_PROJECTMIGRATIONFAILED zurückgibt. Dadurch wird das Projekt im Solution Explorer entladen.

    Es ist wichtig, den vollständigen Prozess zu verstehen, der in der Umgebung für den Fall auftritt, dass der Aufruf der QueryEditFiles Methode, der einen Wert von ReportOnly angibt, die QER_EditNotOK- und QER_ReadOnlyUnderScc-Flags zurückgibt.

  5. Der Benutzer versucht, die Projektdatei zu öffnen.

  6. Die Umgebung ruft Ihre CanCreateProject Implementierung auf.

  7. Wenn CanCreateProjecttrue zurückgibt, dann ruft die Umgebung Ihre CanCreateProject-Implementierung auf.

  8. Die Umgebung ruft Die Load Implementierung auf, um die Datei zu öffnen und das Projektobjekt zu initialisieren, z. B. Project1.

  9. Die Umgebung ruft Ihre IVsProjectUpgrade::UpgradeProject Implementierung auf, um festzustellen, ob die Projektdatei aktualisiert werden muss.

  10. Sie rufen QueryEditFiles auf und übergeben einen Wert von QEF_ReportOnly für den Parameter rgfQueryEdit.

  11. Die Umgebung gibt QER_EditNotOK für VSQueryEditResult zurück, und das QER_ReadOnlyUnderScc-Bit wird in VSQueryEditResultFlags gesetzt.

  12. Ihre IVsProjectUpgrade Implementierung ruft IVsQueryEditQuerySave::QueryEditFiles (QEF_ForceEdit_NoPrompting, QEF_DisallowInMemoryEdits) auf.

Dieser Aufruf kann dazu führen, dass eine neue Kopie Ihrer Projektdatei ausgecheckt wird und die neueste Version abgerufen wird, und dass Ihr Projekt möglicherweise erneut geladen werden muss. An diesem Punkt passiert eines von zwei Dingen:

  • Wenn Sie Ihr eigenes Projekt neu laden, ruft die Umgebung die ReloadItem-Implementierung (VSITEMID_ROOT) auf. Wenn Sie diesen Aufruf erhalten, laden Sie die erste Instanz Ihres Projekts (Project1) neu, und fahren Sie mit dem Aktualisieren der Projektdatei fort. Die Umgebung weiß, dass Sie das Neuladen Ihres Projekts selbstständig handhaben, wenn Sie für true (GetPropertyVSHPROPID_HandlesOwnReload) zurückkehren.

  • Wenn Sie Ihr eigenes Projekt nicht selbst neu laden, geben Sie false für GetProperty (VSHPROPID_HandlesOwnReload) zurück. In diesem Fall erstellt die Umgebung, bevor QueryEditFiles(QEF_ForceEdit_NoPrompting, QEF_DisallowInMemoryEdits) beendet wird, eine weitere neue Instanz Ihres Projekts, zum Beispiel Project2, und zwar folgendermaßen:

    1. Die Umgebung ruft Close ihr erstes Projektobjekt, Project1, auf, wodurch dieses Objekt in den inaktiven Zustand versetzt wird.

    2. Die Umgebung ruft Ihre IVsProjectFactory::CreateProject Implementierung auf, um eine zweite Instanz Ihres Projekts, Project2, zu erstellen.

    3. Die Umgebung ruft Ihre IPersistFileFormat::Load Implementierung auf, um die Datei zu öffnen und das zweite Projektobjekt ( Project2) zu initialisieren.

    4. Die Umgebung ruft ein zweites Mal auf IVsProjectUpgrade::UpgradeProject , um festzustellen, ob das Projektobjekt aktualisiert werden soll. Dieser Aufruf erfolgt jedoch für eine neue, zweite Instanz des Projekts, Project2. Dies ist das Projekt, das in der Lösung geöffnet wird.

      Hinweis

      Für den Fall, dass Ihr erstes Projekt, Project1, in den Ruhezustand versetzt wird, müssen Sie bei der ersten Ausführung Ihrer S_OK Implementierung UpgradeProject zurückgeben.

    5. Sie rufen QueryEditFiles auf und übergeben einen Wert von QEF_ReportOnly für den Parameter rgfQueryEdit.

    6. Die Umgebung gibt QER_EditOK zurück, und das Upgrade kann fortgesetzt werden, da die Projektdatei geschrieben werden kann.

Wenn Sie kein Upgrade durchführen können, kehren Sie VS_E_PROJECTMIGRATIONFAILED von IVsProjectUpgrade::UpgradeProject zurück. Wenn kein Upgrade erforderlich ist oder Sie kein Upgrade durchführen möchten, behandeln Sie den IVsProjectUpgrade::UpgradeProject Anruf als no-op. Wenn Sie VS_E_PROJECTMIGRATIONFAILED zurückgeben, wird der Projektmappe ein Platzhalterknoten hinzugefügt.

Aktualisieren von Projektelementen

Wenn Sie Elemente innerhalb von Projektsystemen hinzufügen oder verwalten, die Sie nicht implementieren, müssen Sie möglicherweise am Projektupgradeprozess teilnehmen. Crystal Reports ist ein Beispiel für ein Element, das dem Projektsystem hinzugefügt werden kann.

In der Regel möchten Projektelementimplementierer ein bereits vollständig instanziiertes und aktualisiertes Projekt nutzen, da sie wissen müssen, was die Projektverweise sind und welche anderen Projekteigenschaften vorhanden sind, um eine Upgradeentscheidung zu treffen.

Um die Benachrichtigung über das Projektupgrade zu erhalten

  1. Legen Sie das SolutionOrProjectUpgrading Flag (definiert in vsshell80.idl) in Ihrer Projektelementimplementierung fest. Dies bewirkt, dass das Projektelement VSPackage automatisch geladen wird, wenn die Visual Studio-Shell bestimmt, dass sich ein Projektsystem während des Upgrades befindet.

  2. Steuern Sie die IVsSolutionEventsProjectUpgrade Schnittstelle über die AdviseSolutionEvents Methode.

  3. Die IVsSolutionEventsProjectUpgrade Schnittstelle wird ausgelöst, nachdem die Projektsystemimplementierung ihre Upgradevorgänge abgeschlossen hat und das neue aktualisierte Projekt erstellt wird. Je nach Szenario wird die IVsSolutionEventsProjectUpgrade Schnittstelle nach dem OnAfterOpenSolution, den OnAfterOpenProject Methoden oder den OnAfterLoadProject Methoden ausgelöst.

So aktualisieren Sie die Projektelementdateien

  1. Sie müssen den Dateisicherungsprozess in Ihrer Projektelementimplementierung sorgfältig verwalten. Dies gilt insbesondere für eine nebeneinander liegende Sicherung, bei der der fUpgradeFlag Parameter der UpgradeProject Methode auf PUVFF_SXSBACKUP gesetzt ist, wobei Dateien, die gesichert wurden, neben Dateien platziert werden, die als ".old" bezeichnet sind. Die gesicherten Dateien, die älter sind als die Systemzeit, zu der das Projekt aktualisiert wurde, können als veraltet festgelegt werden. Darüber hinaus können sie überschrieben werden, es sei denn, Sie ergreifen bestimmte Schritte, um dies zu verhindern.

  2. Zum Zeitpunkt, zu dem Ihr Projektelement eine Benachrichtigung über das Projektupgrade erhält, wird der Visual Studio-Konvertierungs-Assistent weiterhin angezeigt. Daher sollten Sie die Methoden der IVsUpgradeLogger-Schnittstelle verwenden, um Upgrademeldungen an die Benutzeroberfläche des Assistenten zu übermitteln.

Verwandte Inhalte

  • Last updated on