Aggiornamento dei progetti

  • Articolo

Le modifiche apportate al modello di progetto da una versione di Visual Studio a quella successiva potrebbero richiedere l'aggiornamento di progetti e soluzioni in modo che possano essere eseguiti nella versione più recente. Visual Studio SDK fornisce interfacce che possono essere usate per implementare il supporto per l'aggiornamento nei propri progetti.

Strategie di aggiornamento

Per supportare un aggiornamento, l'implementazione del sistema di progetto deve definire e implementare una strategia di aggiornamento. Per determinare la strategia, è possibile scegliere di supportare il backup side-by-side (SxS), il backup di copia o entrambi.

  • Il backup di SxS significa che un progetto copia solo i file che richiedono l'aggiornamento sul posto, aggiungendo un suffisso di nome file appropriato, ad esempio ".old".

  • Il backup della copia significa che un progetto copia tutti gli elementi del progetto in un percorso di backup fornito dall'utente. I file pertinenti nel percorso originale del progetto vengono quindi aggiornati.

Funzionamento dell'aggiornamento

Quando una soluzione creata in una versione precedente di Visual Studio viene aperta in una versione più recente, l'IDE controlla il file della soluzione per determinare se deve essere aggiornato. Se è necessario eseguire l'aggiornamento, l'Aggiornamento guidato viene avviato automaticamente per illustrare all'utente il processo di aggiornamento.

Quando una soluzione richiede l'aggiornamento, esegue una query su ogni factory di progetto per la strategia di aggiornamento. La strategia determina se la factory del progetto supporta il backup di copia o il backup SxS. Le informazioni vengono inviate all'Aggiornamento guidato, che raccoglie le informazioni necessarie per il backup e presenta le opzioni applicabili all'utente.

Soluzioni multiprogetto

Se una soluzione contiene più progetti e le strategie di aggiornamento differiscono, ad esempio quando un progetto C++ che supporta solo il backup SxS e un progetto Web che supporta solo il backup della copia, le factory di progetto devono negoziare la strategia di aggiornamento.

La soluzione esegue una query su ogni factory del progetto per IVsProjectUpgradeViaFactory. Chiama quindi UpgradeProject_CheckOnly per verificare se i file di progetto globali richiedono l'aggiornamento e per determinare le strategie di aggiornamento supportate. Viene quindi richiamato l'Aggiornamento guidato .

Al termine della procedura guidata, UpgradeProject viene chiamato in ogni factory del progetto per eseguire l'aggiornamento effettivo. Per facilitare il backup, i metodi IVsProjectUpgradeViaFactory forniscono al SVsUpgradeLogger servizio di registrare i dettagli del processo di aggiornamento. Questo servizio non può essere memorizzato nella cache.

Dopo aver aggiornato tutti i file globali pertinenti, ogni factory di progetto può scegliere di creare un'istanza di un progetto. L'implementazione del progetto deve supportare IVsProjectUpgrade. Viene quindi chiamato il UpgradeProject metodo per aggiornare tutti gli elementi del progetto pertinenti.

Nota

Il UpgradeProject metodo non fornisce il servizio SVsUpgradeLogger. Questo servizio può essere ottenuto chiamando QueryService.

Consigli per iniziare

Usare il SVsQueryEditQuerySave servizio per verificare se è possibile modificare un file prima di modificarlo e salvarlo prima di salvarlo. In questo modo le implementazioni di backup e aggiornamento gestiranno i file di progetto sotto il controllo del codice sorgente, i file con autorizzazioni insufficienti e così via.

Usare il SVsUpgradeLogger servizio durante tutte le fasi di backup e aggiornamento per fornire informazioni sull'esito positivo o negativo del processo di aggiornamento.

Per altre informazioni sul backup e l'aggiornamento dei progetti, vedere i commenti per IVsProjectUpgrade in vsshell2.idl.

Aggiornamento di progetti personalizzati

Se si modificano le informazioni rese persistenti nel file di progetto tra diverse versioni di Visual Studio del prodotto, è necessario supportare l'aggiornamento del file di progetto dalla versione precedente a quella nuova. Per supportare l'aggiornamento che consente di partecipare alla Conversione guidata di Visual Studio, implementare l'interfaccia IVsProjectUpgradeViaFactory . Questa interfaccia contiene l'unico meccanismo disponibile per l'aggiornamento della copia. L'aggiornamento del progetto viene eseguito all'apertura di una parte della soluzione. L'interfaccia IVsProjectUpgradeViaFactory è implementata dalla factory del progetto o almeno deve poter essere ottenuta dalla factory del progetto.

Il meccanismo precedente che usa l'interfaccia IVsProjectUpgrade è ancora supportato, ma concettualmente aggiorna il sistema del progetto come parte del progetto aperto. L'interfaccia IVsProjectUpgrade viene quindi chiamata dall'ambiente di Visual Studio anche se l'interfaccia IVsProjectUpgradeViaFactory viene chiamata o implementata. Questo approccio consente di usare IVsProjectUpgradeViaFactory per implementare solo le parti della copia e del progetto dell'aggiornamento e delegare il resto del lavoro da eseguire sul posto (possibilmente nella nuova posizione) tramite l'interfaccia IVsProjectUpgrade.

Per un'implementazione di esempio di IVsProjectUpgrade, vedere Esempi di VSSDK.

Con gli aggiornamenti di progetti si verificano i seguenti scenari:

  • Se il file è di un formato più recente rispetto a quelli supportati dal progetto, deve restituire un errore che segnala il problema. Ciò presuppone che la versione precedente del prodotto includa il codice per verificare la versione.

  • Se è specificato il flag PUVFF_SXSBACKUP nel metodo UpgradeProject, l'aggiornamento verrà implementato come un aggiornamento sul posto prima dell'apertura del progetto.

  • Se è specificato il flag PUVFF_COPYBACKUP nel metodo UpgradeProject, l'aggiornamento viene implementato come un aggiornamento della copia.

  • Se è specificato il flag UPF_SILENTMIGRATE nella chiamata UpgradeProject, all'utente è stato richiesto dall'ambiente di aggiornare il file di progetto come un aggiornamento sul posto, dopo l'apertura del progetto. Ad esempio, l'ambiente richiede all'utente di eseguire l'aggiornamento all'apertura di una versione precedente della soluzione.

  • Se non è specificato il flag UPF_SILENTMIGRATE nella chiamata UpgradeProject, è necessario richiedere all'utente di aggiornare il file di progetto.

    Di seguito è riportato un esempio di messaggio di richiesta dell'aggiornamento:

    "Il progetto '%1' è stato creato con una versione precedente di Visual Studio. Se si apre il progetto con la versione in uso, potrebbe risultare impossibile aprirlo con le versioni precedenti di Visual Studio. Continuare e aprire il progetto?"

Per implementare IVsProjectUpgradeViaFactory

  1. Implementare il metodo dell'interfaccia IVsProjectUpgradeViaFactory, in particolare il metodo UpgradeProject nell'implementazione della factory del progetto, o rendere le implementazioni richiamabili dall'implementazione della factory del progetto.

  2. Se si vuole eseguire un aggiornamento sul posto come parte dell'apertura della soluzione, specificare il flag PUVFF_SXSBACKUP come parametro VSPUVF_FLAGS nell'implementazione di UpgradeProject.

  3. Se si vuole eseguire un aggiornamento sul posto come parte dell'apertura della soluzione, specificare il flag PUVFF_COPYBACKUP come parametro VSPUVF_FLAGS nell'implementazione di UpgradeProject.

  4. Per entrambi i passaggi 2 e 3, le operazioni per l'aggiornamento effettivo dei file tramite IVsQueryEditQuerySave2 possono essere implementate come descritto di seguito nella sezione "Implementazione di IVsProjectUpgade" oppure è possibile delegare l'aggiornamento effettivo dei file a IVsProjectUpgrade.

  5. Usare i metodi di IVsUpgradeLogger per inviare i messaggi relativi all'aggiornamento per l'utente tramite la Migrazione guidata di Visual Studio.

  6. L'interfaccia IVsFileUpgrade viene usata per implementare qualsiasi tipo di aggiornamento dei file che deve essere eseguito come parte dell'aggiornamento del progetto. Questa interfaccia non viene chiamata da IVsProjectUpgradeViaFactory, ma viene fornita come meccanismo per aggiornare i file che fanno parte del sistema del progetto, ma di cui il sistema del progetto principale potrebbe non essere direttamente a conoscenza. Questa situazione può ad esempio verificarsi se i file e le proprietà relativi al compilatore non vengono gestiti dallo stesso team di sviluppo che gestisce il resto del sistema del progetto.

Implementazione di IVsProjectUpgrade

Se il sistema di progetto viene IVsProjectUpgrade implementato solo, non può partecipare alla Conversione guidata di Visual Studio. Tuttavia, anche se si implementa l'interfaccia IVsProjectUpgradeViaFactory, è comunque possibile delegare l'aggiornamento dei file all'implementazione di IVsProjectUpgrade.

Per implementare IVsProjectUpgrade

  1. Quando un utente tenta di aprire un progetto, il metodo UpgradeProject è chiamato dall'ambiente dopo che il progetto viene aperto e prima che qualsiasi altra azione dell'utente possa essere eseguita sul progetto. Se all'utente era già stato richiesto di aggiornare la soluzione, viene passato il flag UPF_SILENTMIGRATE nel parametro grfUpgradeFlags. Se l'utente apre direttamente un progetto, ad esempio usando il comando Aggiungi progetto esistente, il UPF_SILENTMIGRATE flag non viene passato e il progetto deve richiedere all'utente di eseguire l'aggiornamento.

  2. In risposta alla chiamata UpgradeProject, il progetto deve valutare se il file di progetto deve essere aggiornato. Se il progetto non deve aggiornare il tipo di progetto a una nuova versione, può semplicemente restituire il flag S_OK.

  3. Se il progetto deve aggiornare il tipo di progetto a una nuova versione, deve determinare se il file di progetto può essere modificato chiamando il metodo QueryEditFiles e passando un valore tagVSQueryEditFlags per il parametro rgfQueryEdit. Il progetto deve quindi eseguire le operazioni seguenti:

  4. Se la chiamata QueryEditFiles sul file di progetto determina l'estrazione del file e il recupero della versione più recente, il progetto viene scaricato e ricaricato. Il metodo UpgradeProject viene chiamato nuovamente dopo la creazione di un'altra istanza del progetto. In questa seconda chiamata, il file di progetto può essere scritto sul disco. È consigliabile che il progetto salvi una copia del file di progetto nel formato precedente con un'estensione OLD, apporti le modifiche necessarie per l'aggiornamento e salvi il file di progetto nel nuovo formato. Anche in questo caso, se qualsiasi parte del processo di aggiornamento non riesce, il metodo deve indicare l'errore restituendo VS_E_PROJECTMIGRATIONFAILED. Questo determina lo scaricamento del progetto da Esplora soluzioni.

    È importante comprendere l'intero processo che si verifica nell'ambiente qualora la chiamata al metodo QueryEditFiles (che specifica un valore di ReportOnly) restituisca i flag QER_EditNotOK e QER_ReadOnlyUnderScc.

  5. L'utente tenta di aprire il file di progetto.

  6. L'ambiente chiama l'implementazione di CanCreateProject.

  7. Se CanCreateProject restituisce true, l'ambiente chiama l'implementazione di CanCreateProject.

  8. L'ambiente chiama l'implementazione di Load per aprire il file e inizializzare l'oggetto di progetto, ad esempio Project1.

  9. L'ambiente chiama l'implementazione di IVsProjectUpgrade::UpgradeProject per determinare se il file di progetto deve essere aggiornato.

  10. Si chiama QueryEditFiles e si passa un valore QEF_ReportOnly per il parametro rgfQueryEdit.

  11. L'ambiente restituisce QER_EditNotOK per VSQueryEditResult e il bit QER_ReadOnlyUnderScc è impostato in VSQueryEditResultFlags.

  12. L'implementazione di IVsProjectUpgrade chiama IVsQueryEditQuerySave::QueryEditFiles (QEF_ForceEdit_NoPrompting, QEF_DisallowInMemoryEdits).

Questa chiamata può causare l'estrazione di una nuova copia del file di progetto e il recupero della versione più recente, nonché rendere necessario ricaricare il file di progetto. A questo punto, può verificarsi una delle due situazioni seguenti:

  • Se si gestisce autonomamente il ricaricamento del progetto, l'ambiente chiama l'implementazione di ReloadItem (VSITEMID_ROOT). Quando si riceve questa chiamata, ricaricare la prima istanza del progetto (Project1) e continuare l'aggiornamento del file di progetto. L'ambiente è consapevole del fatto che si gestisce autonomamente il ricaricamento del progetto se si restituisce true per GetProperty (VSHPROPID_HandlesOwnReload).

  • Se non si gestisce autonomamente il ricaricamento del progetto, si restituisce false per GetProperty (VSHPROPID_HandlesOwnReload). In questo caso, prima QueryEditFilesche (QEF_ForceEdit_NoPrompting, QEF_DisallowInMemoryEdits) restituisca, l'ambiente crea un'altra nuova istanza del progetto, ad esempio Project2, come indicato di seguito:

    1. L'ambiente chiama Close sul primo oggetto di progetto, Project1, impostando così questo oggetto nello stato inattivo.

    2. L'ambiente chiama l'implementazione di IVsProjectFactory::CreateProject per creare una seconda istanza del progetto, Project2.

    3. L'ambiente chiama l'implementazione di IPersistFileFormat::Load per aprire il file e inizializzare il secondo oggetto di progetto, Project2.

    4. L'ambiente chiama IVsProjectUpgrade::UpgradeProject una seconda volta per determinare se l'oggetto di progetto deve essere aggiornato. Tuttavia, questa chiamata viene eseguita su una nuova, seconda, istanza del progetto, Project2. Si tratta del progetto aperto nella soluzione.

      Nota

      Nel caso il primo progetto, Project1, sia impostato nello stato inattivo, è necessario restituire S_OK dalla prima chiamata nell'implementazione di UpgradeProject.

    5. Si chiama QueryEditFiles e si passa un valore QEF_ReportOnly per il parametro rgfQueryEdit.

    6. L'ambiente restituisce QER_EditOK e l'aggiornamento può continuare perché è possibile eseguire la scrittura del file di progetto.

Se non è possibile eseguire l'aggiornamento, restituire VS_E_PROJECTMIGRATIONFAILED da IVsProjectUpgrade::UpgradeProject. Se non è necessario eseguire l'aggiornamento o si sceglie di non eseguirlo, gestire la chiamata IVsProjectUpgrade::UpgradeProject come un'operazione che non produce effetti. Se si restituisce VS_E_PROJECTMIGRATIONFAILED, viene aggiunto un nodo segnaposto alla soluzione per il progetto.

Aggiornamento degli elementi di progetto

Se si aggiungono o si gestiscono elementi all'interno dei sistemi di progetto non implementati, potrebbe essere necessario partecipare al processo di aggiornamento del progetto. Crystal Reports è un esempio di elemento che può essere aggiunto al sistema di progetto.

In genere, gli implementatori di elementi di progetto vogliono sfruttare un progetto già completamente creato e aggiornato perché devono conoscere i riferimenti al progetto e quali altre proprietà del progetto sono disponibili per prendere una decisione di aggiornamento.

Per ottenere la notifica di aggiornamento del progetto

  1. Impostare il SolutionOrProjectUpgrading flag (definito in vsshell80.idl) nell'implementazione dell'elemento di progetto. In questo modo il vsPackage dell'elemento del progetto viene caricato automaticamente quando la shell di Visual Studio determina che un sistema di progetto è in corso di aggiornamento.

  2. Consigliare l'interfaccia IVsSolutionEventsProjectUpgrade tramite il AdviseSolutionEvents metodo .

  3. L'interfaccia IVsSolutionEventsProjectUpgrade viene attivata dopo che l'implementazione del sistema di progetto ha completato le operazioni di aggiornamento e viene creato il nuovo progetto aggiornato. A seconda dello scenario, l'interfaccia IVsSolutionEventsProjectUpgrade viene attivata dopo i OnAfterOpenSolutionmetodi , OnAfterOpenProjecto OnAfterLoadProject .

Per aggiornare i file degli elementi del progetto

  1. È necessario gestire attentamente il processo di backup dei file nell'implementazione dell'elemento del progetto. Questo vale in particolare per un backup side-by-side, in cui il fUpgradeFlag parametro del metodo è impostato su PUVFF_SXSBACKUP, dove i file di cui è stato eseguito il UpgradeProject backup vengono posizionati lungo i file side designati come "old". I file di cui è stato eseguito il backup precedenti all'ora di sistema in cui il progetto è stato aggiornato possono essere designati come non aggiornati. Inoltre, potrebbero essere sovrascritti a meno che non si eseguano passaggi specifici per evitare questo problema.

  2. Al momento in cui l'elemento del progetto riceve una notifica dell'aggiornamento del progetto, la Conversione guidata di Visual Studio viene ancora visualizzata. Pertanto, è consigliabile usare i metodi dell'interfaccia IVsUpgradeLogger per fornire messaggi di aggiornamento all'interfaccia utente della procedura guidata.

Contenuto correlato