Upgrade projektů

  • Článek

Změny modelu projektu z jedné verze sady Visual Studio na další můžou vyžadovat upgrade projektů a řešení, aby mohly běžet v novější verzi. Sada Visual Studio SDK poskytuje rozhraní, která lze použít k implementaci podpory upgradu ve vašich vlastních projektech.

Strategie upgradu

Pro podporu upgradu musí implementace systému projektu definovat a implementovat strategii upgradu. Při určování strategie můžete zvolit podporu souběžného zálohování (SxS), zálohování kopírování nebo obojího.

  • Zálohování SxS znamená, že projekt kopíruje jenom ty soubory, které potřebují provést upgrade, a přidá odpovídající příponu názvu souboru, například ".old".

  • Zálohování kopírování znamená, že projekt zkopíruje všechny položky projektu do umístění zálohy poskytnutého uživatelem. Příslušné soubory v původním umístění projektu se pak upgradují.

Jak funguje upgrade

Když se řešení vytvořené ve starší verzi sady Visual Studio otevře v novější verzi, integrované vývojové prostředí zkontroluje soubor řešení a určí, jestli je potřeba upgradovat. Pokud je upgrade nutný, průvodce upgradem se automaticky spustí a provede uživatele procesem upgradu.

Když řešení potřebuje upgrade, dotazuje se na každou projektovou továrnu na strategii upgradu. Strategie určuje, jestli projektová továrna podporuje zálohování kopírování nebo zálohování SxS. Informace se odesílají do Průvodce upgradem, který shromažďuje informace potřebné pro zálohování a zobrazuje příslušné možnosti pro uživatele.

Řešení pro více projektů

Pokud řešení obsahuje více projektů a strategie upgradu se liší, například pokud projekt C++, který podporuje pouze zálohování SxS, a webový projekt, který podporuje pouze zálohování kopírování, musí projektové továrny vyjednat strategii upgradu.

Řešení se dotazuje na každou továrnu projektu pro IVsProjectUpgradeViaFactory. Potom zavolá UpgradeProject_CheckOnly , aby zjistili, jestli globální soubory projektu potřebují upgradovat a určit podporované strategie upgradu. Průvodce upgradem se pak vyvolá.

Jakmile uživatel průvodce dokončí, UpgradeProject zavolá se v každé projektové továrně, aby provedl skutečný upgrade. Pro usnadnění zálohování poskytují metody IVsProjectUpgradeViaFactory službě SVsUpgradeLogger protokolovat podrobnosti procesu upgradu. Tuto službu nelze uložit do mezipaměti.

Po aktualizaci všech relevantních globálních souborů se každá továrna projektu může rozhodnout vytvořit instanci projektu. Implementace projektu musí podporovat IVsProjectUpgrade. Metoda UpgradeProject se pak zavolá k upgradu všech relevantních položek projektu.

Poznámka:

Metoda UpgradeProject neposkytuje službu SVsUpgradeLogger. Tuto službu lze získat voláním QueryService.

Osvědčené postupy

SVsQueryEditQuerySave Pomocí služby zkontrolujte, jestli můžete před úpravami upravit soubor a před uložením ho uložit. To pomůže implementaci zálohování a upgradu zpracovávat soubory projektu ve správě zdrojového kódu, soubory s nedostatečnými oprávněními atd.

SVsUpgradeLogger Pomocí služby ve všech fázích zálohování a upgradu můžete poskytnout informace o úspěchu nebo selhání procesu upgradu.

Další informace o zálohování a upgradu projektů naleznete v komentářích pro IVsProjectUpgrade vsshell2.idl.

Upgrade vlastních projektů

Pokud změníte informace trvalé v souboru projektu mezi různými verzemi produktu sady Visual Studio, budete muset podporovat upgrade souboru projektu ze starého na novou verzi. Pokud chcete podporovat upgrade, který vám umožní účastnit se Průvodce převodem sady Visual Studio, implementujte IVsProjectUpgradeViaFactory rozhraní. Toto rozhraní obsahuje jediný mechanismus, který je k dispozici pro upgrade kopírování. Při otevření řešení probíhá upgrade projektu. Rozhraní IVsProjectUpgradeViaFactory je implementováno objektem pro vytváření projektů nebo by mělo být alespoň možné získat z projektové továrny.

Starý mechanismus, který používá IVsProjectUpgrade rozhraní, je stále podporován, ale koncepčně upgraduje systém projektu jako součást otevřeného projektu. Rozhraní IVsProjectUpgrade je proto volána prostředím sady Visual Studio, i když IVsProjectUpgradeViaFactory je rozhraní volána nebo implementována. Tento přístup umožňuje implementovat IVsProjectUpgradeViaFactory kopie a projekt pouze části upgradu a delegovat zbytek práce na místě (pravděpodobně v novém umístění) rozhraním IVsProjectUpgrade .

Ukázkovou implementaci IVsProjectUpgradenajdete v tématu Ukázky sady VSSDK.

Při upgradech projektů vznikají následující scénáře:

  • Pokud je soubor novějšího formátu, než může projekt podporovat, musí vrátit chybu s oznámením, že se jedná. Předpokládá se, že starší verze produktu obsahuje kód ke kontrole verze.

  • PUVFF_SXSBACKUP Pokud je příznak zadán v UpgradeProject metodě, upgrade se implementuje jako místní upgrade před otevřením projektu.

  • PUVFF_COPYBACKUP Pokud je příznak zadán v UpgradeProject metodě, upgrade se implementuje jako upgrade kopírování.

  • UPF_SILENTMIGRATE Pokud je příznak zadán ve UpgradeProject volání, po otevření projektu se uživateli zobrazí výzva k upgradu souboru projektu jako místního upgradu. Prostředí například vyzve uživatele k upgradu, když uživatel otevře starší verzi řešení.

  • UPF_SILENTMIGRATE Pokud není příznak zadán ve UpgradeProject volání, musíte uživatele vyzvat k upgradu souboru projektu.

    Následuje příklad zprávy s výzvou k upgradu:

    Projekt %1 byl vytvořen se starší verzí sady Visual Studio. Pokud ji otevřete v této verzi sady Visual Studio, možná ji nebudete moct otevřít ve starších verzích sady Visual Studio. Chcete pokračovat a otevřít tento projekt?"

Implementace IVsProjectUpgradeViaFactory

  1. Implementujte metodu IVsProjectUpgradeViaFactory rozhraní, konkrétně metodu UpgradeProject v implementaci projektové továrny, nebo proveďte volání implementací z implementace objektu pro vytváření projektů.

  2. Pokud chcete provést místní upgrade jako součást otevření řešení, zadejte příznak PUVFF_SXSBACKUP jako VSPUVF_FLAGS parametr v implementaci UpgradeProject .

  3. Pokud chcete provést místní upgrade jako součást otevření řešení, zadejte příznak PUVFF_COPYBACKUP jako VSPUVF_FLAGS parametr v implementaci UpgradeProject .

  4. V případě kroků 2 i 3 je možné provést vlastní kroky upgradu souborů pomocí , jak IVsQueryEditQuerySave2je popsáno v části Implementace IVsProjectUpgadeníže, nebo můžete delegovat skutečný upgrade souboru na IVsProjectUpgrade.

  5. Pomocí metod IVsUpgradeLogger odesílání zpráv souvisejících s upgradem pro uživatele pomocí Průvodce migrací sady Visual Studio.

  6. IVsFileUpgrade rozhraní se používá k implementaci jakéhokoli druhu upgradu souborů, který se musí provést v rámci upgradu projektu. Toto rozhraní není volána z IVsProjectUpgradeViaFactory, ale je poskytována jako mechanismus pro upgrade souborů, které jsou součástí systému projektu, ale hlavní systém projektu nemusí být přímo vědom. Tato situace může nastat například v případě, že soubor a vlastnosti související s kompilátorem nezpracovává stejný vývojový tým, který zpracovává zbytek systému projektu.

Implementace IVsProjectUpgrade

Pokud projektový systém implementuje IVsProjectUpgrade pouze, nemůže se účastnit Průvodce převodem sady Visual Studio. I když však implementujete IVsProjectUpgradeViaFactory rozhraní, můžete upgrade souboru delegovat na IVsProjectUpgrade implementaci.

Implementace IVsProjectUpgrade

  1. Když se uživatel pokusí otevřít projekt, UpgradeProject volá se metoda prostředím po otevření projektu a před provedením jakékoli jiné akce uživatele v projektu. Pokud už byl uživatel vyzván k upgradu řešení, UPF_SILENTMIGRATE příznak se předá v parametru grfUpgradeFlags . Pokud uživatel otevře projekt přímo, například pomocí příkazu Přidat existující projekt , UPF_SILENTMIGRATE příznak se nepředá a projekt musí vyzvat uživatele k upgradu.

  2. V reakci na UpgradeProject volání musí projekt vyhodnotit, jestli je soubor projektu upgradován. Pokud projekt nemusí upgradovat typ projektu na novou verzi, může jednoduše vrátit S_OK příznak.

  3. Pokud projekt potřebuje upgradovat typ projektu na novou verzi, musí určit, zda je možné soubor projektu upravit voláním QueryEditFiles metody a předáním hodnoty tagVSQueryEditFlags parametru rgfQueryEdit . Projekt pak musí provést následující:

  4. QueryEditFiles Pokud volání souboru projektu způsobí rezervaci souboru a načtení nejnovější verze, projekt se uvolní a znovu načte. Metoda UpgradeProject se znovu volá, jakmile se vytvoří jiná instance projektu. Při tomto druhém volání lze soubor projektu zapsat na disk; Doporučuje se, aby projekt uložil kopii souboru projektu v předchozím formátu s příponou . STARÉ rozšíření, proveďte potřebné změny upgradu a uložte soubor projektu v novém formátu. Znovu, pokud jakákoli část procesu upgradu selže, metoda musí indikovat selhání vrácením VS_E_PROJECTMIGRATIONFAILED. To způsobí uvolnění projektu v Průzkumník řešení.

    Je důležité pochopit celý proces, který se vyskytuje v prostředí pro případ, kdy volání QueryEditFiles metody (určení hodnoty ReportOnly) vrátí QER_EditNotOK a QER_ReadOnlyUnderScc příznaky.

  5. Uživatel se pokusí otevřít soubor projektu.

  6. Prostředí volá vaši CanCreateProject implementaci.

  7. Pokud CanCreateProject se vrátí true, pak prostředí volá vaši CanCreateProject implementaci.

  8. Prostředí volá vaši Load implementaci, aby soubor otevřel a inicializoval objekt projektu, například Project1.

  9. Prostředí volá vaši IVsProjectUpgrade::UpgradeProject implementaci, aby určilo, jestli je potřeba upgradovat soubor projektu.

  10. Zavoláte QueryEditFiles a předáte hodnotu QEF_ReportOnly parametru rgfQueryEdit .

  11. Prostředí se vrátí QER_EditNotOK a VSQueryEditResult bit QER_ReadOnlyUnderScc je nastaven v VSQueryEditResultFlags.

  12. Vaše IVsProjectUpgrade volání IVsQueryEditQuerySave::QueryEditFiles implementace (QEF_ForceEdit_NoPrompting, QEF_DisallowInMemoryEdits).

Toto volání může způsobit rezervaci nové kopie souboru projektu a načtení nejnovější verze a také nutnost opětovného načtení souboru projektu. V tuto chvíli se stane jedna ze dvou věcí:

  • Pokud zpracujete opětovné načtení vlastního projektu, prostředí zavolá implementaci ReloadItem (VSITEMID_ROOT). Po přijetí tohoto volání znovu načtěte první instanci projektu (Project1) a pokračujte v upgradu souboru projektu. Prostředí ví, že při vrácení (VSHPROPID_HandlesOwnReload) zpracujete true GetProperty opětovné načtení vlastního projektu.

  • Pokud nezpracujete vlastní opětovné načtení projektu, vrátíte hodnotu false (GetPropertyVSHPROPID_HandlesOwnReload). V takovém případě se prostředí před QueryEditFilesvrácením (QEF_ForceEdit_NoPrompting, QEF_DisallowInMemoryEdits) vytvoří další novou instanci projektu, například Project2, takto:

    1. Prostředí volá Close první objekt projektu Project1, čímž umístí tento objekt do neaktivního stavu.

    2. Prostředí volá vaši IVsProjectFactory::CreateProject implementaci a vytvoří druhou instanci projektu Project2.

    3. Prostředí volá vaši IPersistFileFormat::Load implementaci k otevření souboru a inicializaci druhého objektu projektu Project2.

    4. Prostředí volá IVsProjectUpgrade::UpgradeProject podruhé, aby určilo, jestli má být objekt projektu upgradován. Toto volání se však provádí u nové, druhé instance projektu Project2. Toto je projekt, který je otevřen v řešení.

      Poznámka:

      V případě, že váš první projekt Project1 je umístěn v neaktivním stavu, pak se musíte vrátit S_OK z prvního volání vaší UpgradeProject implementace.

    5. Zavoláte QueryEditFiles a předáte hodnotu QEF_ReportOnly parametru rgfQueryEdit .

    6. Prostředí se vrátí QER_EditOK a upgrade může pokračovat, protože soubor projektu lze zapsat.

Pokud se vám nedaří provést upgrade, vraťte se VS_E_PROJECTMIGRATIONFAILED z IVsProjectUpgrade::UpgradeProject. Pokud není upgrade nutný nebo se rozhodnete neupgradovat, zacházejte s IVsProjectUpgrade::UpgradeProject voláním jako s no-op. Pokud se vrátíte VS_E_PROJECTMIGRATIONFAILED, přidá se do řešení pro váš projekt zástupný uzel.

Upgrade položek projektu

Pokud přidáte nebo spravujete položky v projektových systémech, které neimplementujete, budete se možná muset účastnit procesu upgradu projektu. Crystal Reports je příkladem položky, kterou lze přidat do systému projektu.

Implementátoři položek projektu obvykle chtějí využít již plně připravený a upgradovaný projekt, protože potřebují vědět, co jsou odkazy na projekt a jaké jsou další vlastnosti projektu k provedení rozhodnutí o upgradu.

Získání oznámení o upgradu projektu

  1. SolutionOrProjectUpgrading Nastavte příznak (definovaný vsshell80.idl) v implementaci položky projektu. To způsobí, že se položka projektu VSPackage automaticky načte, když prostředí sady Visual Studio určí, že se v procesu upgradu nachází systém projektu.

  2. IVsSolutionEventsProjectUpgrade Poraďte rozhraní prostřednictvím AdviseSolutionEvents metody.

  3. Rozhraní IVsSolutionEventsProjectUpgrade se aktivuje poté, co implementace systému projektu dokončí operace upgradu a vytvoří se nový upgradovaný projekt. V závislosti na scénáři se IVsSolutionEventsProjectUpgrade rozhraní aktivuje po OnAfterOpenSolution, OnAfterOpenProjectnebo OnAfterLoadProject metody.

Upgrade souborů položek projektu

  1. Při implementaci položky projektu musíte pečlivě spravovat proces zálohování souborů. To platí zejména pro souběžné zálohování, kde fUpgradeFlag parametr UpgradeProject metody je nastaven na PUVFF_SXSBACKUP, kde soubory, které byly zálohovány, jsou umístěny podél bočních souborů, které jsou určeny jako ".old". Zálohované soubory starší než systémový čas při upgradu projektu je možné určit jako zastaralé. Kromě toho se můžou přepsat, pokud neuděláte konkrétní kroky, abyste tomu zabránili.

  2. V době, kdy položka projektu obdrží oznámení o upgradu projektu, se průvodce převodem sady Visual Studio stále zobrazí. Proto byste měli použít metody IVsUpgradeLogger rozhraní k poskytování zpráv o upgradu do uživatelského rozhraní průvodce.

Související obsah