Uppgradera projekt

2025-10-31

Ändringar i projektmodellen från en version av Visual Studio till nästa kan kräva att projekt och lösningar uppgraderas så att de kan köras på den nyare versionen. Visual Studio SDK innehåller gränssnitt som kan användas för att implementera uppgraderingsstöd i dina egna projekt.

Uppgraderingsstrategier

För att stödja en uppgradering måste projektsystemimplementeringen definiera och implementera en uppgraderingsstrategi. När du fastställer din strategi kan du välja att stödja säkerhetskopiering sida vid sida (SxS), kopieringsbackup eller båda.

SxS-säkerhetskopiering innebär att ett projekt endast kopierar de filer som behöver uppgraderas på plats och lägger till ett lämpligt filnamnssuffix, till exempel ".old".
Kopia backup innebär att ett projekt kopierar alla projektobjekt till en användarspecificerad plats för säkerhetskopiering. Relevanta filer på den ursprungliga projektplatsen uppgraderas sedan.

Så här fungerar uppgraderingen

När en lösning som skapats i en tidigare version av Visual Studio öppnas i en nyare version kontrollerar IDE-lösningen filen för att avgöra om den behöver uppgraderas. Om uppgradering krävs startas uppgraderingsguiden automatiskt för att vägleda användaren genom uppgraderingsprocessen.

När en lösning behöver uppgraderas frågar den varje projektfabrik efter uppgraderingsstrategin. Strategin avgör om projektfabriken stöder kopieringssäkerhetskopiering eller SxS-säkerhetskopiering. Informationen skickas till uppgraderingsguiden, som samlar in den information som krävs för säkerhetskopieringen och visar de tillämpliga alternativen för användaren.

Lösningar för flera projekt

Om en lösning innehåller flera projekt och uppgraderingsstrategierna skiljer sig åt, till exempel när ett C++-projekt som endast stöder SxS-säkerhetskopiering och ett webbprojekt som endast stöder kopieringssäkerhetskopiering, måste projektfabrikerna förhandla om uppgraderingsstrategin.

Lösningen frågar varje projektfabrik efter IVsProjectUpgradeViaFactory. Den anropar UpgradeProject_CheckOnly sedan för att se om globala projektfiler behöver uppgraderas och för att fastställa vilka uppgraderingsstrategier som stöds. Uppgraderingsguiden anropas sedan.

När användaren har slutfört guiden, UpgradeProject anropas varje projektfabrik för att utföra den faktiska uppgraderingen. För att underlätta säkerhetskopiering tillhandahåller IVsProjectUpgradeViaFactory-metoder SVsUpgradeLogger tjänsten för att logga information om uppgraderingsprocessen. Den här tjänsten kan inte cachelagras.

När du har uppdaterat alla relevanta globala filer kan varje projektfabrik välja att instansiera ett projekt. Projektimplementeringen måste stödja IVsProjectUpgrade. Metoden UpgradeProject anropas sedan för att uppgradera alla relevanta projektobjekt.

Anmärkning

Metoden UpgradeProject tillhandahåller inte tjänsten SVsUpgradeLogger. Den här tjänsten kan hämtas genom att anropa QueryService.

Metodtips

Använd tjänsten SVsQueryEditQuerySave för att kontrollera om du kan redigera en fil innan du redigerar den och kan spara den innan du sparar den. Detta hjälper dina implementeringar av säkerhetskopiering och uppgradering att hantera projektfiler under källkontroll, filer med otillräcklig behörighet och så vidare.

SVsUpgradeLogger Använd tjänsten under alla faser av säkerhetskopiering och uppgradering för att ge information om hur uppgraderingsprocessen lyckades eller misslyckades.

Mer information om hur du säkerhetskopierar och uppgraderar projekt finns i kommentarerna för IVsProjectUpgrade i vsshell2.idl.

Uppgradera anpassade projekt

Om du ändrar informationen som finns kvar i projektfilen mellan olika Visual Studio-versioner av produkten måste du ha stöd för uppgradering av projektfilen från den gamla till den nya versionen. Implementera gränssnittet för att stödja uppgradering som gör att du kan delta i Visual Studio-konverteringsguidenIVsProjectUpgradeViaFactory. Det här gränssnittet innehåller den enda mekanism som är tillgänglig för kopieringsgradering. Uppgraderingen av projektet sker när en del av lösningen öppnas. Gränssnittet IVsProjectUpgradeViaFactory implementeras av projektfabriken eller bör åtminstone kunna hämtas från projektfabriken.

Den gamla mekanismen som använder IVsProjectUpgrade-gränssnittet stöds fortfarande, men uppgraderar projektsystemet konceptuellt under projektöppnandet. Gränssnittet IVsProjectUpgrade anropas därför av Visual Studio-miljön även om IVsProjectUpgradeViaFactory gränssnittet anropas eller implementeras. Med den här metoden kan du använda IVsProjectUpgradeViaFactory för att implementera kopiering och projekt endast delar av uppgraderingen och delegera resten av arbetet som ska utföras på plats (eventuellt på den nya platsen) av IVsProjectUpgrade gränssnittet.

En exempelimplementering av IVsProjectUpgradefinns i VSSDK-exempel.

Följande scenarier uppstår med projektuppgraderingar:

Om filen har ett nyare format än vad projektet kan stödja måste den returnera ett fel som anger detta. Detta förutsätter att den äldre versionen av produkten innehåller kod för att söka efter versionen.
PUVFF_SXSBACKUP Om flaggan anges i UpgradeProject -metoden implementeras uppgraderingen som en uppgradering på plats innan projektet öppnas.
PUVFF_COPYBACKUP Om flaggan anges i UpgradeProject metoden implementeras uppgraderingen som en kopieringsuppgradering.
Om flaggan UPF_SILENTMIGRATE anges i anropet UpgradeProject uppmanas användaren av miljön att efter projektfilen har öppnats uppgradera den som en direkt uppgradering. Miljön uppmanar till exempel användaren att uppgradera när användaren öppnar en äldre version av lösningen.
UPF_SILENTMIGRATE Om flaggan inte anges i anropet UpgradeProject måste du uppmana användaren att uppgradera projektfilen.

Följande är ett exempel på ett meddelande om uppgraderingsprompt:

Projektet%1skapades med en äldre version av Visual Studio. Om du öppnar den med den här versionen av Visual Studio kanske du inte kan öppna den med äldre versioner av Visual Studio. Vill du fortsätta och öppna det här projektet?"

Implementera IVsProjectUpgradeViaFactory

Implementera metoden i IVsProjectUpgradeViaFactory-gränssnittet, särskilt metoden UpgradeProject i ditt projektfabrikens implementation, eller gör implementeringarna anropbara från projektfabrikens implementation.
Om du vill göra en uppgradering på plats vid öppningen av en lösning, specificera flaggan PUVFF_SXSBACKUP som parameter VSPUVF_FLAGS i din implementering UpgradeProject.
Om du vill göra en uppgradering på plats som en del av lösningens öppning, du anger flaggan PUVFF_COPYBACKUP som VSPUVF_FLAGS-parametern i din UpgradeProject-implementering.
För både steg 2 och 3 kan de faktiska filuppgraderingsstegen, med hjälp av IVsQueryEditQuerySave2, implementeras enligt beskrivningen i avsnittet "Implementering IVsProjectUpgade" nedan, eller så kan du delegera den faktiska filuppgraderingen till IVsProjectUpgrade.
Använd metoderna för att publicera uppgraderingsrelaterade meddelanden för användaren med hjälp av IVsUpgradeLogger Visual Studio Migration Wizard.
IVsFileUpgrade gränssnittet används för att implementera alla typer av filuppgradering som måste ske som en del av projektuppgradering. Det här gränssnittet anropas inte från IVsProjectUpgradeViaFactory, men tillhandahålls som en mekanism för att uppgradera filer som ingår i projektsystemet, men huvudprojektsystemet kanske inte är direkt medvetet om. Den här situationen kan till exempel uppstå om kompilatorrelaterade filer och egenskaper inte hanteras av samma utvecklingsteam som hanterar resten av projektsystemet.

Implementering av IVsProjectUpgrade

Om ditt projektsystem endast implementerar IVsProjectUpgrade, kan det inte delta i Visual Studio-konverteringsguiden. Men även om du implementerar IVsProjectUpgradeViaFactory gränssnittet kan du fortfarande delegera filuppgraderingen till IVsProjectUpgrade implementeringen.

Implementera IVsProjectUpgrade

När en användare försöker öppna ett projekt UpgradeProject anropas metoden av miljön efter att projektet har öppnats och innan någon annan användaråtgärd kan vidtas i projektet. Om användaren redan har uppmanats att uppgradera lösningen UPF_SILENTMIGRATE skickas flaggan i parametern grfUpgradeFlags . Om användaren öppnar ett projekt direkt, till exempel genom att använda kommandot Lägg till befintligt projekt , UPF_SILENTMIGRATE skickas inte flaggan och projektet måste uppmana användaren att uppgradera.
Som svar på anropet UpgradeProject måste projektet utvärdera om projektfilen har uppgraderats. Om projektet inte behöver uppgradera projekttypen till en ny version kan det helt enkelt returnera S_OK flaggan.
Om projektet behöver uppgradera projekttypen till en ny version måste det avgöra om projektfilen kan ändras genom att anropa QueryEditFiles metoden och skicka in värdet tagVSQueryEditFlags för för parametern rgfQueryEdit . Projektet måste sedan göra följande:
- Om värdet VSQueryEditResult som returneras i parametern pfEditCanceled är QER_EditOKkan uppgraderingen fortsätta eftersom projektfilen kan skrivas.
- Om värdet VSQueryEditResult som returneras i parametern pfEditCanceled är QER_EditNotOK och VSQueryEditResult värdet har bituppsättningen QER_ReadOnlyNotUnderScc måste det UpgradeProject returnera fel eftersom användarna själva bör lösa behörighetsproblemet. Projektet bör sedan göra följande:
  
  Rapportera felet till användaren genom att anropa ReportErrorInfo och returnera VS_E_PROJECTMIGRATIONFAILED felkoden till IVsProjectUpgrade.
- Om värdet VSQueryEditResult är QER_EditNotOK och VSQueryEditResultFlags värdet har bituppsättningen QER_ReadOnlyUnderScc bör projektfilen checkas ut genom att anropa QueryEditFiles (QEF_ForceEdit_NoPrompting,... QEF_DisallowInMemoryEdits).
Om anropet QueryEditFiles på projektfilen gör att filen checkas ut och den senaste versionen hämtas, avlastas projektet och läses in igen. Metoden UpgradeProject anropas igen när en annan instans av projektet har skapats. I det här andra anropet kan projektfilen skrivas till disk. Vi rekommenderar att projektet sparar en kopia av projektfilen i föregående format med . OLD-tillägget gör nödvändiga uppgraderingsändringar och sparar projektfilen i det nya formatet. Om någon del av uppgraderingsprocessen misslyckas måste metoden återigen indikera fel genom att VS_E_PROJECTMIGRATIONFAILEDreturnera . Detta gör att projektet tas bort i Solution Explorer.

Det är viktigt att förstå den fullständiga processen som sker i miljön för det fall då anropet QueryEditFiles till metoden (ange värdet ReportOnly) returnerar flaggorna QER_EditNotOK QER_ReadOnlyUnderScc och .
Användaren försöker öppna projektfilen.
Miljön anropar din CanCreateProject-implementering.
Om CanCreateProject returnerar trueanropar miljön implementeringen CanCreateProject .
Miljön anropar implementeringen Load för att öppna filen och initiera projektobjektet, till exempel Project1.
Miljön anropar implementeringen IVsProjectUpgrade::UpgradeProject för att avgöra om projektfilen behöver uppgraderas.
Du anropar QueryEditFiles och skickar in värdet QEF_ReportOnly för för parametern rgfQueryEdit .
Miljön returnerar QER_EditNotOK för VSQueryEditResult och biten QER_ReadOnlyUnderScc anges i VSQueryEditResultFlags.
Din IVsProjectUpgrade-implementering anropar IVsQueryEditQuerySave::QueryEditFiles (QEF_ForceEdit_NoPrompting, QEF_DisallowInMemoryEdits).

Det här anropet kan leda till att en ny kopia av projektfilen checkas ut och att den senaste versionen hämtas samt att du behöver läsa in projektfilen igen. I det här läget händer en av två saker:

Om du hanterar din egen projektuppdatering, anropar miljön din implementering av ReloadItem (VSITEMID_ROOT). När du får det här anropet läser du in den första instansen av projektet igen (Project1) och fortsätter att uppgradera projektfilen. Miljön vet att du hanterar din egen projektomladdning om du returnerar true för GetProperty (VSHPROPID_HandlesOwnReload).
Om du inte hanterar din egen projektomläsning, returnerar du false för GetProperty (VSHPROPID_HandlesOwnReload). I det här fallet, innan QueryEditFiles(QEF_ForceEdit_NoPrompting, QEF_DisallowInMemoryEdits) returnerar, skapar miljön en annan ny instans av projektet, till exempel Project2, enligt följande:
1. Miljön anropar Close ditt första projektobjekt, Project1, vilket placerar objektet i inaktivt tillstånd.
2. Miljön anropar implementeringen IVsProjectFactory::CreateProject för att skapa en andra instans av projektet, Project2.
3. Miljön anropar implementeringen IPersistFileFormat::Load för att öppna filen och initiera det andra projektobjektet, Project2.
4. Miljön anropar IVsProjectUpgrade::UpgradeProject för en andra gång för att avgöra om projektobjektet ska uppgraderas. Det här anropet görs dock på en ny, andra, instans av projektet, Project2. Det här är projektet som öppnas i lösningen.
  
  Anmärkning
  
  I det fall ditt första projekt, Project1, är placerat i det inaktiva tillståndet måste du returnera S_OK från det första anropet till din UpgradeProject-implementation.
5. Du anropar QueryEditFiles och skickar in värdet QEF_ReportOnly för för parametern rgfQueryEdit .
6. Miljön returnerar QER_EditOK och uppgraderingen kan fortsätta eftersom projektfilen kan skrivas.

Om du inte uppgraderar returnerar VS_E_PROJECTMIGRATIONFAILED från IVsProjectUpgrade::UpgradeProject. Om ingen uppgradering krävs eller om du väljer att inte uppgradera behandlar du anropet IVsProjectUpgrade::UpgradeProject som en no-op. Om du returnerar VS_E_PROJECTMIGRATIONFAILEDläggs en platshållarnod till i lösningen för projektet.