Comment : systèmes de projet de mise à niveau
Si vous modifiez les informations rendues persistantes dans le fichier projet entre différentes versions de Visual Studio de votre produit, vous devez prendre en charge la mise à niveau votre fichier projet de l'ancien vers la nouvelle version. Pour prendre en charge la mise à niveau qui vous permet de participer à Assistant Conversion de Visual Studio, implémentez l'interface d' IVsProjectUpgradeViaFactory . cette interface contient le seul mécanisme disponible pour la mise à niveau de copie. La mise à niveau du projet se produit lorsqu'une partie de la solution s'ouvre. L'interface d' IVsProjectUpgradeViaFactory est implémentée par la fabrique de projet, ou doit au moins être disponible pour la fabrique de projet.
Le mécanisme ancien qui utilise l'interface d' IVsProjectUpgrade est toujours pris en charge, mais met à niveau conceptuellement le système de projet en tant que partie du projet ouvert. l'interface d' IVsProjectUpgrade est donc appelée par l'environnement de Visual Studio même si l'interface d' IVsProjectUpgradeViaFactory est appelée ou implémentée. Cette approche vous permet d'utiliser IVsProjectUpgradeViaFactory pour implémenter les parties de copie et de projet uniquement de la mise à niveau, puis délègue le reste du travail pour être visuelle fait (éventuellement au nouvel emplacement) par l'interface d' IVsProjectUpgrade .
Pour un exemple d'implémentation d' IVsProjectUpgrade, consultez Exemples d'extensibilité Visual Studio.
Les scénarios ci-après surviennent avec les mises à niveau de projet :
Si le fichier est d'un plus récent format que le projet peut prendre en charge, il doit retourner une erreur indiquant cela. Cela suppose que la version antérieure de votre produit (par exemple, Visual Studio .NET 2003 - inclut du code pour vérifier la version.
Si la balise d' PUVFF_SXSBACKUP est spécifiée dans la méthode d' UpgradeProject , la mise à niveau va être implémentée en tant que mise à niveau sur place avant l'ouverture du projet.
Si la balise d' PUVFF_COPYBACKUP est spécifiée dans la méthode d' UpgradeProject , la mise à niveau est implémentée sous la forme d'une mise à niveau de copie.
Si la balise d' UPF_SILENTMIGRATE est spécifiée dans l'appel d' UpgradeProject , l'utilisateur a été appelé par l'environnement à mettre à niveau le fichier projet en tant que mise à niveau sur place, une fois que le projet soit ouvert. Par exemple, l'environnement invite l'utilisateur à mettre à niveau lorsque l'utilisateur ouvre une version antérieure de la solution.
Si la balise d' UPF_SILENTMIGRATE n'est pas spécifiée dans l'appel d' UpgradeProject , vous devez demander l'utilisateur à mettre à niveau le fichier projet.
Voici un boîte de message d'invite de mise à niveau de l'exemple :
« Le projet « %1 " a été créé avec une version antérieure de Visual Studio. Si vous l'ouvrez avec cette version de Visual Studio, vous ne pouvez pas pouvoir l'ouvrir avec les versions antérieures de Visual Studio. vous souhaitez continuer et ouvrir ce projet ? »
pour implémenter IVsProjectUpgradeViaFactory
Implémentez la méthode de l'interface d' IVsProjectUpgradeViaFactory , spécifiquement la méthode d' UpgradeProject dans votre implémentation de fabrique de projet, ou rendre les implémentations être appelés de votre implémentation de fabrique de projet.
Si vous souhaitez effectuer une mise à niveau sur place en tant que partie de l'ouverture de la solution, fournissez la balise PUVFF_SXSBACKUP comme paramètre d' VSPUVF_FLAGS dans votre implémentation d' UpgradeProject .
Si vous souhaitez effectuer une mise à niveau sur place en tant que partie de l'ouverture de la solution, fournissez la balise PUVFF_COPYBACKUP comme paramètre d' VSPUVF_FLAGS dans votre implémentation d' UpgradeProject .
Pour les deux étapes 2 et 3, les étapes réelles de mise à niveau fichier, à l'aide de IVsQueryEditQuerySave2, peuvent être implémentées comme décrit dans la section « implémentant IVsProjectUpgade » ci-dessous, ou vous pouvez déléguer la mise à niveau réelle de fichier à IVsProjectUpgrade.
Utilisez les méthodes d' IVsUpgradeLogger pour publier les messages relatifs aux mise à niveau pour l'utilisateur à l'aide de l'Assistant Migration Visual Studio.
l'interface d'IVsFileUpgrade est utilisée pour implémenter tout type de mise à niveau de le fichier qui doit se produire dans le cadre de la mise à niveau de projet. Cette interface n'est pas appelée dans IVsProjectUpgradeViaFactory, mais est fournie en tant que mécanisme pour mettre à niveau les fichiers faisant partie du système de projet, mais le système de projet principal peut ne pas tenir directement en compte. Par exemple, cette situation peut survenir si les fichiers connexes et les propriétés de compilateur ne sont pas gérés par la même équipe de développement qui gère le reste du système de projet.
implémentation d'IVsProjectUpgrade
Si votre système de projet implémente IVsProjectUpgrade uniquement, il ne peut pas participer à Assistant Conversion de Visual Studio. Toutefois, même si vous implémentez l'interface d' IVsProjectUpgradeViaFactory , vous pouvez toujours déléguer la mise à niveau de le fichier à l'implémentation d' IVsProjectUpgrade .
pour implémenter IVsProjectUpgrade
Lorsque les un utilisateur tente d'ouvrir un projet, la méthode d' UpgradeProject est appelée par l'environnement après que le projet soit ouvert et avant toute autre action utilisateur peut être prise sur le projet. Si l'utilisateur avait déjà été invité à mettre à niveau la solution, la balise d' UPF_SILENTMIGRATE est passée dans le paramètre d' grfUpgradeFlags . Si l'utilisateur ouvre directement un projet, par exemple en utilisant la commande pour Ajouter un projet existant , puis de la balise d' UPF_SILENTMIGRATE n'est pas passé et les besoins de projet à inviter l'utilisateur à mettre à niveau.
en réponse à l'appel d' UpgradeProject , le projet doit évaluer si le fichier projet est mis à niveau. Si le projet n'a pas besoin de mettre à niveau le type de projet vers une nouvelle version, il peut simplement retourner la balise d' S_OK .
Si les besoins de projet de mettre à niveau le type de projet vers une nouvelle version, alors il doit déterminer si le fichier projet peut être modifié en appelant la méthode d' QueryEditFiles et en passant les valeurs d' QEF_ReportOnly pour le paramètre d' rgfQueryEdit . Le projet doit ensuite effectuer les opérations suivantes :
Si la valeur d' VSQueryEditResult retournée dans le paramètre d' pfEditCanceled est QER_EditOK, la mise à niveau peut continuer car il peut être écrit.
Si la valeur d' VSQueryEditResult retournée dans le paramètre d' pfEditCanceled est QER_EditNotOK et la valeur d' VSQueryEditResult a le bit d' QER_ReadOnlyNotUnderScc la valeur, alors UpgradeProject doit retourner l'échec, car les utilisateurs doivent résoudre le problème d'autorisations eux-mêmes. Le projet doit ensuite effectuer les opérations suivantes :
enregistrez l'erreur à l'utilisateur en appelant ReportErrorInfo. et retournent un code d'erreur d' VS_E_PROJECTMIGRATIONFAILED à IVsProjectUpgrade.
Si la valeur d' VSQueryEditResult est QER_EditNotOK et la valeur d' VSQueryEditResultFlags a le bit d' QER_ReadOnlyUnderScc défini, le fichier projet doit être vérifié par QueryEditFiles appelant (QEF_ForceEdit_NoPrompting, QEF_DisallowInMemoryEdits,…).
Si un appel d' QueryEditFiles au fichier projet entraîne le fichier à vérifier, et la version la plus récente à récupérer, le projet est déchargé puis rechargé. La méthode d' UpgradeProject est de nouveau appelée une fois qu'une autre instance du projet est créée. Sur ce deuxième appel, il peut être écrit sur le disque ; il est recommandé que la sauvegarde de projet une copie du fichier projet au format précédent avec une extension de .OLD, apportez les modifications nécessaires de mise à niveau, et enregistrez le fichier projet dans le nouveau format. De même, si une partie de la mise à niveau échoue, la méthode doit indiquer l'échec en retournant VS_E_PROJECTMIGRATIONFAILED. Cela provoque le projet comme dans l'explorateur de solutions déchargé.
Il est important de comprendre le processus complet qui se produit dans l'environnement pour le cas dans lequel l'appel à la méthode d' QueryEditFiles (en spécifiant une valeur de ReportOnly) retourne QER_EditNotOK et les balises d' QER_ReadOnlyUnderScc .
L'utilisateur essaie d'ouvrir le fichier projet.
l'environnement appelle votre implémentation d' CanCreateProject .
Si CanCreateProject retourne true, l'environnement appelle votre implémentation d' CanCreateProject .
l'environnement appelle votre implémentation d' Load pour ouvrir le fichier et pour initialiser l'objet de projet, par exemple, Project1.
l'environnement appelle votre implémentation d' IVsProjectUpgrade::UpgradeProject pour déterminer si le fichier projet doit être mis à niveau.
Vous appelez l' QueryEditFiles et passez la valeur d' QEF_ReportOnly pour le paramètre d' rgfQueryEdit .
L'environnement retourne QER_EditNotOK pour VSQueryEditResult et le bit d' QER_ReadOnlyUnderScc est défini dans VSQueryEditResultFlags.
votre implémentation d' IVsProjectUpgrade appelle IVsQueryEditQuerySave::QueryEditFiles (QEF_ForceEdit_NoPrompting, QEF_DisallowInMemoryEdits).
Cet appel peut provoquer une nouvelle copie de votre fichier projet pour rechercher et de la version la plus récente atteinte, ainsi qu'un besoin de recharger votre fichier projet. À ce stade, l'une des deux actions suivantes se produisent :
Si vous exécutez votre propre rechargement du projet, l'environnement appelle votre implémentation d' ReloadItem (VSITEMID_ROOT). Lorsque vous recevez cet appel, rechargez la première instance de votre projet (Project1) et continuez de mettre à niveau votre fichier projet. L'environnement sait que vous exécutez votre propre rechargement du projet si vous retournez true pour GetProperty (VSHPROPID_HandlesOwnReload).
Si vous ne gérez pas votre propre rechargement du projet, vous retournez false pour GetProperty (VSHPROPID_HandlesOwnReload). Dans ce cas, avant le retour d' QueryEditFiles(QEF_ForceEdit_NoPrompting, QEF_DisallowInMemoryEdits,), l'environnement crée un autre nouveau, l'instance de votre projet, par exemple, Project2, comme suit :
L'environnement appelle Close sur votre premier objet de projet, Project1, et plaçant cet objet dans l'état inactif.
l'environnement appelle votre implémentation d' IVsProjectFactory::CreateProject pour créer une deuxième instance de votre projet, Project2.
l'environnement appelle votre implémentation d' IPersistFileFormat::Load pour ouvrir le fichier et pour initialiser le deuxième objet de projet, Project2.
L'environnement appelle IVsProjectUpgrade::UpgradeProject pour une seconde fois pour déterminer si l'objet de projet doit être mis à niveau. Toutefois, cet appel est effectué sur un nouveau, la seconde, l'instance de projet, Project2. Il s'agit du projet ouvert dans la solution.
Notes
Dans l'instance que votre premier projet, Project1, est placé dans l'état inactif, puis vous devez retourner S_OK du premier appel à l'implémentation de UpgradeProject .Consultez Basic Project pour une implémentation d' IVsProjectUpgrade::UpgradeProject.
Vous appelez l' QueryEditFiles et passez la valeur d' QEF_ReportOnly pour le paramètre d' rgfQueryEdit .
Retourne QER_EditOK d'environnement et la mise à niveau peuvent continuer car il peut être écrit.
Si vous n'effectuez pas la mise à niveau, VS_E_PROJECTMIGRATIONFAILED de retour d' IVsProjectUpgrade::UpgradeProject. Si aucune mise à niveau n'est nécessaire ou vous choisissez de ne pas mettre à niveau, traitez l'appel d' IVsProjectUpgrade::UpgradeProject comme une absence d'opération. Si vous retournez VS_E_PROJECTMIGRATIONFAILED, un nœud d'espace réservé est ajouté à la solution pour votre projet.
Voir aussi
Tâches
Comment : éléments de projet de mise à niveau