Freigeben über

Aktualisieren von Projekten

  • Artikel

Änderungen am Projektmodell von einer Version von Visual Studio zur nächsten können es erforderlich machen, dass Projekte und Lösungen aktualisiert werden müssen, damit sie in der neueren Version ausgeführt werden können. Das Visual Studio SDK bietet Schnittstellen, mit denen Sie die Upgrade-Unterstützung in Ihren eigenen Projekten implementieren können.

Upgrade-Strategien

Um ein Upgrade zu unterstützen, muss Ihr Projektsystem eine Upgrade-Strategie definieren und umsetzen. Bei der Festlegung Ihrer Strategie können Sie wählen, ob Sie Side-by-Side-Backup (SxS), Copy-Backup oder beides unterstützen wollen.

  • SxS-Backup bedeutet, dass ein Projekt nur die Dateien kopiert, die an Ort und Stelle aktualisiert werden müssen, wobei ein geeignetes Dateinamenssuffix hinzugefügt wird, zum Beispiel „.old“.

  • Backup kopieren bedeutet, dass ein Projekt alle Projektelemente an einen vom Benutzer festgelegten Sicherungsort kopiert. Die relevanten Dateien am ursprünglichen Projektstandort werden dann aktualisiert.

Funktionsweise des Upgrades

Wenn eine in einer früheren Version von Visual Studio erstellte Projektmappe in einer neueren Version geöffnet wird, prüft die IDE die Projektmappendatei, um festzustellen, ob sie aktualisiert werden muss. Wenn ein Upgrade erforderlich ist, wird der Upgrade-Assistent automatisch gestartet, um den Benutzer durch den Upgrade-Prozess zu führen.

Wenn eine Lösung aktualisiert werden muss, fragt sie jede Projektfabrik nach ihrer Aktualisierungsstrategie ab. Die Strategie legt fest, ob der Projektzuordnungssatz Kopiersicherungen oder SxS-Backups 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.

Multiprojekt-Lösungen

Wenn eine Lösung mehrere Projekte enthält und die Upgrade-Strategien unterschiedlich sind, z. B. wenn ein C++-Projekt nur SxS-Backup und ein Web-Projekt nur Copy-Backup unterstützt, müssen die Projektzuordnungssätze die Upgrade-Strategie aushandeln.

Die Lösung fragt jeden Projektzuordnungssatz nach IVsProjectUpgradeViaFactory ab. Anschließend wird UpgradeProject_CheckOnly aufgerufen, um festzustellen, ob globale Projektdateien ein Upgrade benötigen und um die unterstützten Upgradestrategien zu ermitteln. Danach wird der Upgrade-Assistent aufgerufen.

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

Nach dem Aktualisieren aller relevanten globalen Dateien kann jeder Projektzuordnungssatz auswählen, ob ein Projekt instanziieren soll. Die Projektimplementierung muss dabei IVsProjectUpgrade unterstützen. Dann wir die UpgradeProject-Methode hinzugezogen, um alle relevanten Projektelemente zu aktualisieren.

Hinweis

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

Bewährte Methoden

Verwenden Sie den SVsQueryEditQuerySave-Dienst, um zu prüfen, ob Sie eine Datei bearbeiten können, bevor Sie sie bearbeiten, und ob Sie sie speichern können, bevor Sie sie speichern. Dies hilft Ihren Backup- und Upgrade-Implementierungen bei der Handhabung von Projektdateien unter Versionskontrolle, Dateien mit unzureichenden Berechtigungen usw.

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

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

Aktualisieren von benutzerdefinierten Projekten

Wenn Sie die in der Projektdatei dauerhaft gespeicherten Informationen zwischen verschiedenen Visual Studio-Versionen Ihres Produkts ändern, müssen Sie das Durchführen eines Upgrades der Projektdatei von der alten auf die neue Version unterstützen. Um ein Upgrade zu unterstützen, das Ihnen die Teilnahme am Visual Studio Wechselassistenten ermöglicht, implementieren Sie die IVsProjectUpgradeViaFactory-Schnittstelle. Diese Schnittstelle stellt das einzige verfügbare Verfahren zum Durchführen von Kopierupgrades dar. Das Upgrade des Projekts erfolgt im Rahmen des Öffnens der Projektmappe. Die IVsProjectUpgradeViaFactory-Schnittstelle wird von der Projektfactory implementiert oder sollte zumindest über diese verfügbar sein.

Der alte Mechanismus, der die IVsProjectUpgrade-Schnittstelle verwendet, wird noch unterstützt, doch wird dabei das abweichende Konzept verfolgt, das Upgrade des Projektsystems beim Öffnen des Projekts vorzunehmen. Die IVsProjectUpgrade-Schnittstelle wird daher von der Visual Studio-Umgebung auch dann aufgerufen, wenn die IVsProjectUpgradeViaFactory-Schnittstelle aufgerufen wird oder implementiert ist. Aufgrund dieses Ansatzes können Sie IVsProjectUpgradeViaFactory verwenden, um die Kopie zu implementieren und nur Teile des Upgrades zu projizieren, wobei der Rest der Arbeit für die Ausführung an Ort und Stelle (also möglichst dem neuen Speicherort) durch die IVsProjectUpgrade-Schnittstelle delegiert wird.

Eine IVsProjectUpgrade-Beispielimplementierung finden Sie unter VSSDK-Beispiele.

Im Rahmen von Projektupgrades stellen sich die folgenden Szenarien dar:

  • Wenn die Datei ein neueres Format aufweist, als es vom Projekt unterstützt werden kann, muss eine Fehlermeldung zurückgegeben werden, aus der dieser Umstand hervorgeht. Dabei wird vorausgesetzt, dass die ältere Version Ihres Produkts Code zum Überprüfen der Version enthält.

  • Wenn das PUVFF_SXSBACKUP-Flag in der UpgradeProject-Methode angegeben ist, wird das Upgrade vor dem Öffnen des Projekts als Upgrade an Ort und Stelle ausgeführt.

  • 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, wurde der Benutzer von der Umgebung aufgefordert, nach dem Öffnen des Projekts ein Upgrade der Projektdatei an Ort und Stelle auszuführen. Beispielsweise fordert die Umgebung den Benutzer zum Upgrade auf, wenn der Benutzer eine ältere Version der Lösung öffnet.

  • Wenn das UPF_SILENTMIGRATE-Flag nicht im UpgradeProject-Aufruf angegeben ist, müssen Sie den Benutzer auffordern, ein Upgrade der Projektdatei auszuführen.

    Die folgende Aufforderungsnachricht stellt ein Beispiel dar:

    "Das Projekt '%1' wurde in einer älteren Version von Visual Studio erstellt. Wenn Sie es mit dieser Version von Visual Studio öffnen, können Sie es möglicherweise nicht mehr mit älteren Versionen von Visual Studio öffnen. Möchten Sie fortfahren und dieses Projekt ö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 von Ihrer Projektfactoryimplementierung aus aufrufbar.

  2. Wenn Sie ein Upgrade an Ort und Stelle als Teil des Öffnens der Projektmappe ausführen möchten, geben Sie das Flag PUVFF_SXSBACKUP als Parameter von VSPUVF_FLAGS in Ihrer UpgradeProject-Implementierung an.

  3. Wenn Sie ein Upgrade an Ort und Stelle als Teil des Öffnens der Projektmappe ausführen möchten, geben Sie das Flag PUVFF_COPYBACKUP als Parameter von VSPUVF_FLAGS in Ihrer UpgradeProject-Implementierung an.

  4. Für die Schritte 2 und 3, die eigentlichen Dateiupgradeschritte, kann die Verwendung von IVsQueryEditQuerySave2 wie im Abschnitt "Implementierung von IVsProjectUpgade" im Abschnitt unten beschrieben implementiert werden; alternativ können Sie das eigentliche Dateiupgrade an IVsProjectUpgrade delegieren.

  5. Verwenden Sie die Methoden von IVsUpgradeLogger, um mit Upgrades zusammenhängende Nachrichten für Benutzer mithilfe des Visual Studio-Migrations-Assistenten zu veröffentlichen.

  6. Die IVsFileUpgrade-Schnittstelle wird verwendet, um jede Art von Dateiupgrade zu implementieren, die im Rahmen eines Projektupgrades erfolgen muss. Diese Schnittstelle wird nicht von IVsProjectUpgradeViaFactory aufgerufen, sondern als Mechanismus für das Upgrade von Dateien bereitgestellt, die zum Projektsystem gehören, von denen das Projekthauptsystem jedoch möglicherweise keine unmittelbare Kenntnis hat. Diese Situation kann beispielsweise eintreten, wenn die compilerbezogenen Dateien und Eigenschaften nicht vom gleichen Entwicklungsteam wie der Rest des Projektsystems betreut werden.

IVsProjectUpgrade-Implementierung

Wenn Ihr Projektsystem nur IVsProjectUpgrade implementiert, kann es nicht am Visual Studio Wechselassistenten teilnehmen. Aber selbst wenn Sie die IVsProjectUpgradeViaFactory-Schnittstelle implementieren, können Sie 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 andere Benutzeraktionen für das Projekt ausgeführt werden können. Wenn der Benutzer bereits aufgefordert wurde, ein Upgrade der Projektmappe auszuführen, wird im grfUpgradeFlags-Parameter das UPF_SILENTMIGRATE-Flag übergeben. Wenn der Benutzer ein Projekt direkt öffnet, z. B. mit dem Befehl Vorhandenes Projekt hinzufügen, wird das UPF_SILENTMIGRATE-Flag nicht mitübergeben und das Projekt muss den Benutzer zum Upgrade auffordern.

  2. In Reaktion auf den UpgradeProject-Aufruf muss das Projekt bewerten, ob für die Projektdatei ein Upgrade ausgeführt werden muss. Wenn das Projekt für den Projekttyp kein Upgrade auf eine neue Version ausführen muss, kann es einfach das S_OK-Flag zurückgeben.

  3. Wenn das Projekt ein Upgrade des Projekttyps auf eine neue Version vornehmen muss, muss es bestimmen, ob die Projektdatei durch Aufrufen der QueryEditFiles-Methode und Übergeben des Werts tagVSQueryEditFlags für den rgfQueryEdit-Parameter geändert werden kann. In diesem Fall muss das Projekt folgendes ausführen:

  4. Wenn der QueryEditFiles-Aufruf der Projektdateien zum Auschecken der Datei und zum Abrufen der letzten Version führt, wird das Projekt entladen und erneut geladen. Die UpgradeProject-Methode wird erneut aufgerufen, sobald eine weitere 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 einer OLD-Erweiterung speichert, die für das Upgrade erforderlichen Änderungen vornimmt und die Projektdatei anschließend im neuen Format speichert. Wenn bei irgendeinem Teil des Upgradevorgangs ein Fehler auftritt muss auch hier die Methode den Fehler durch Zurückgeben von VS_E_PROJECTMIGRATIONFAILED anzeigen. Dadurch wird das Projekt aus dem Projektmappen-Explorer entladen.

    Für den Fall, dass der Aufruf der QueryEditFiles-Methode (mit dem Wert „ReportOnly“) die Flags QER_EditNotOK und QER_ReadOnlyUnderScc zurückgibt, ist es wichtig, den gesamten Prozess zu verstehen, der in der Umgebung geschieht.

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

  6. Die Umgebung ruft Ihre CanCreateProject-Implementierung auf.

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

  8. Die Umgebung ruft Ihre Load-Implementierung auf, um die Datei zu öffnen und das Projektobjekt zu initialisieren z. B. „Projekt1“.

  9. Die Umgebung ruft Ihre IVsProjectUpgrade::UpgradeProject -Implementierung auf, um zu bestimmen, ob ein Upgrade der Projektdatei erforderlich ist.

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

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

  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 und die neueste Version abgerufen wird, wodurch es erforderlich wird, die Projektdatei neu zu laden. An diesem Punkt geschieht eins von zwei Dingen:

  • Wenn Sie das erneute Laden des Projekts selbst vornehmen, ruft die Umgebung Ihre ReloadItem-Implementierung (VSITEMID_ROOT) auf. Wenn Sie diesen Aufruf empfangen, laden Sie die erste Instanz des Projekts (Projekt1) erneut, und fahren Sie mit dem Upgrade Ihrer Projektdatei fort. Die Umgebung weiß, dass Sie das erneute Laden des Projekts selbst übernehmen, wenn Sie für GetProperty (VSHPROPID_HandlesOwnReload) true zurückgeben.

  • Wenn Sie das erneute Laden des Projekts nicht selbst ausführen, geben Sie für GetProperty (VSHPROPID_HandlesOwnReload) false zurück. In diesem Fall erstellt die Umgebung, bevor QueryEditFiles (QEF_ForceEdit_NoPrompting, QEF_DisallowInMemoryEdits) zurückkehrt, eine weitere neue Instanz Ihres Projekts, z. B. Project2, wie folgt:

    1. Die Umgebung ruft Close für Ihr erstes Projektobjekt „Project1“ auf und versetzt dieses Objekt dadurch in den inaktiven Zustand.

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

    3. Die Umgebung ruft Ihre IPersistFileFormat::Load -Implementierung auf, um die Datei zu öffnen und das zweite Projektobjekt, „Projekt2“, zu initialisieren.

    4. Die Umgebung ruft IVsProjectUpgrade::UpgradeProject ein zweites Mal auf, um zu bestimmen, ob für das Projektobjekt ein Upgrade ausgeführt werden soll. Dieser Aufruf erfolgt jedoch für eine neue, zweite Instanz des Projekts, „Projekt2“. Dies ist das Projekt, das in der Projektmappe geöffnet ist.

      Hinweis

      Wenn die Instanz Ihres ersten Projekts, „Projekt1“, in den inaktiven Status versetzt wurde, müssen Sie vom ersten Aufruf S_OK an Ihre UpgradeProject-Implementierung zurückgeben.

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

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

Wenn Sie das Upgrade versäumen, geben Sie VS_E_PROJECTMIGRATIONFAILED aus IVsProjectUpgrade::UpgradeProject zurück. Wenn für Sie kein Upgrade erforderlich ist oder Sie sich gegen das Upgrade entscheiden, behandeln Sie den IVsProjectUpgrade::UpgradeProject -Aufruf als nicht erfolgten Vorgang (No-Op). Wenn Sie VS_E_PROJECTMIGRATIONFAILED zurückgeben, wird dem Projektmappe für Ihr Projekt ein Platzhalterknoten hinzugefügt.

Aktualisieren von Projektelementen

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

In der Regel möchten die Implementierer von Projektelementen ein bereits vollständig instanziiertes und aktualisiertes Projekt nutzen, da sie wissen müssen, welche Projektreferenzen und welche anderen Projekteigenschaften vorhanden sind, um eine Entscheidung über ein Upgrade zu treffen.

So erhalten Sie die Projekt-Upgrade-Benachrichtigung

  1. Setzen Sie das SolutionOrProjectUpgrading-Flag (definiert in vsshell80.idl) in Ihrer Projekt-Implementierung. Dies bewirkt, dass Ihr Projektelement VSPackage automatisch geladen wird, wenn die Visual Studio Shell feststellt, dass ein Projektsystem gerade aktualisiert wird.

  2. Informieren Sie die IVsSolutionEventsProjectUpgrade-Schnittstelle über die AdviseSolutionEvents-Methode.

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

So aktualisieren Sie die Projektelementdateien

  1. Sie müssen den Dateisicherungsprozess in Ihrer Projektelementimplementierung sorgfältig verwalten. Dies gilt insbesondere für eine parallele Sicherung, auf die der fUpgradeFlag-Parameter der UpgradeProject-Methode auf PUVFF_SXSBACKUP festgelegt ist, wobei Dateien, die gesichert wurden, neben Dateien platziert werden, die als „.old“ bezeichnet werden. Die gesicherten Dateien, die älter sind als der Systemzeitpunkt, an dem das Projekt aktualisiert wurde, können als veraltet bezeichnet werden. Außerdem könnten sie überschrieben werden, es sei denn, Sie ergreifen spezielle Maßnahmen, um dies zu verhindern.

  2. Zu dem Zeitpunkt, an dem Ihr Projektelement eine Benachrichtigung über das Projekt-Upgrade erhält, wird der Visual Studio-Wechselassistent noch angezeigt. Daher sollten Sie die Methoden der IVsUpgradeLogger-Schnittstelle verwenden, um Upgrade-Meldungen für die Benutzeroberfläche des Assistenten bereitzustellen.

Zugehöriger Inhalt