Partager via

Mise à niveau de projets

Les modifications apportées au modèle de projet d’une version de Visual Studio à la suivante peuvent nécessiter la mise à niveau de projets et de solutions afin qu’elles puissent s’exécuter sur la version la plus récente. Le Kit de développement logiciel (SDK) Visual Studio fournit des interfaces qui peuvent être utilisées pour implémenter la prise en charge de la mise à niveau dans vos propres projets.

Stratégies de mise à niveau

Pour prendre en charge une mise à niveau, l’implémentation de votre système de projet doit définir et implémenter une stratégie de mise à niveau. Pour déterminer votre stratégie, vous pouvez choisir de prendre en charge la sauvegarde côte à côte (SxS), la sauvegarde de copie ou les deux.

  • La sauvegarde SxS signifie qu’un projet copie uniquement les fichiers qui ont besoin d’une mise à niveau en place, en ajoutant un suffixe de nom de fichier approprié, par exemple . old ».

  • La sauvegarde de copie signifie qu’un projet copie tous les éléments de projet vers un emplacement de sauvegarde fourni par l’utilisateur. Les fichiers pertinents à l’emplacement du projet d’origine sont ensuite mis à niveau.

Fonctionnement de la mise à niveau

Lorsqu’une solution créée dans une version antérieure de Visual Studio est ouverte dans une version plus récente, l’IDE vérifie le fichier de solution pour déterminer s’il doit être mis à niveau. Si la mise à niveau est nécessaire, l’Assistant Mise à niveau est automatiquement lancé pour guider l’utilisateur dans le processus de mise à niveau.

Lorsqu’une solution a besoin d’une mise à niveau, elle interroge chaque fabrique de projets pour sa stratégie de mise à niveau. La stratégie détermine si l'usine à projets prend en charge la sauvegarde de copie ou la sauvegarde SxS. Les informations sont envoyées à l’Assistant Mise à niveau, qui collecte les informations requises pour la sauvegarde et présente les options applicables à l’utilisateur.

Solutions multi-projets

Si une solution contient plusieurs projets et que les stratégies de mise à niveau diffèrent, par exemple lorsqu’un projet C++ qui prend uniquement en charge la sauvegarde SxS et un projet Web qui prend uniquement en charge la sauvegarde de copie, les fabriques de projets doivent négocier la stratégie de mise à niveau.

La solution interroge chaque usine de projet pour IVsProjectUpgradeViaFactory. Il appelle UpgradeProject_CheckOnly ensuite pour voir si les fichiers projet globaux doivent être mis à niveau et déterminer les stratégies de mise à niveau prises en charge. L’Assistant Mise à niveau est ensuite appelé.

Une fois que l’utilisateur a terminé l’assistant, UpgradeProject est appelé sur chaque fabrique de projets pour effectuer la mise à niveau réelle. Pour faciliter la sauvegarde, les méthodes IVsProjectUpgradeViaFactory fournissent le service SVsUpgradeLogger pour journaliser les détails du processus de mise à niveau. Ce service ne peut pas être mis en cache.

Après avoir mis à jour tous les fichiers globaux pertinents, chaque fabrique de projet peut choisir d’instancier un projet. L’implémentation du projet doit prendre en charge IVsProjectUpgrade. La UpgradeProject méthode est ensuite appelée pour mettre à niveau tous les éléments de projet pertinents.

Note

La UpgradeProject méthode ne fournit pas le service SVsUpgradeLogger. Ce service peut être obtenu en appelant QueryService.

Meilleures pratiques

Utilisez le service SVsQueryEditQuerySave pour vérifier si vous pouvez modifier un fichier et l'enregistrer avant de procéder à ces actions. Cela aidera vos implémentations de sauvegarde et de mise à niveau à gérer les fichiers projet sous contrôle de code source, les fichiers avec des autorisations insuffisantes, etc.

Utilisez le SVsUpgradeLogger service pendant toutes les phases de sauvegarde et de mise à niveau pour fournir des informations sur la réussite ou l’échec du processus de mise à niveau.

Pour plus d’informations sur la sauvegarde et la mise à niveau de projets, consultez les commentaires pour IVsProjectUpgrade dans vsshell2.idl.

Mise à niveau de projets personnalisés

Si vous modifiez les informations conservées dans le fichier projet entre différentes versions de Visual Studio de votre produit, vous devez prendre en charge la mise à niveau de votre fichier projet de l’ancienne vers la nouvelle version. Pour prendre en charge la mise à niveau qui vous permet de participer à l’Assistant Conversion de Visual Studio, implémentez l’interface IVsProjectUpgradeViaFactory . Cette interface contient le seul mécanisme disponible pour la mise à niveau de copie. La mise à niveau du projet se produit dans le cadre de l’ouverture de la solution. L’interface IVsProjectUpgradeViaFactory est implémentée par la fabrique de projet ou doit au moins être obtenue à partir de la fabrique de projet.

L’ancien mécanisme qui utilise l’interface IVsProjectUpgrade est toujours pris en charge, mais met à niveau conceptuellement le système de projet dans le cadre du projet ouvert. L’interface IVsProjectUpgrade est donc appelée par l’environnement Visual Studio, même si l’interface IVsProjectUpgradeViaFactory est appelée ou implémentée. Cette approche vous permet d'utiliser IVsProjectUpgradeViaFactory pour implémenter uniquement les parties de copie et de projet de la mise à niveau, et de déléguer le reste du travail à effectuer sur place (éventuellement au nouvel emplacement) par l'interface IVsProjectUpgrade.

Pour obtenir un exemple d’implémentation, IVsProjectUpgradeconsultez les exemples VSSDK.

Les scénarios suivants se produisent avec les mises à niveau de projet :

  • Si le fichier est d’un format plus récent que le projet peut prendre en charge, il doit retourner une erreur indiquant ceci. Cela suppose que l’ancienne version de votre produit inclut du code pour rechercher la version.

  • Si l’indicateur PUVFF_SXSBACKUP est spécifié dans la UpgradeProject méthode, la mise à niveau sera implémentée en tant que mise à niveau sur place avant l’ouverture du projet.

  • Si l’indicateur PUVFF_COPYBACKUP est spécifié dans la UpgradeProject méthode, la mise à niveau est implémentée en tant que mise à niveau de copie.

  • Si l’indicateur UPF_SILENTMIGRATE est spécifié dans l’appel UpgradeProject , l’utilisateur a été invité par l’environnement à mettre à niveau le fichier projet en tant que mise à niveau sur place, une fois le projet ouvert. Par exemple, l’environnement invite l’utilisateur à effectuer une mise à niveau lorsque l’utilisateur ouvre une version antérieure de la solution.

  • Si l’indicateur UPF_SILENTMIGRATE n’est pas spécifié dans l’appel UpgradeProject , vous devez inviter l’utilisateur à mettre à niveau le fichier projet.

    Voici un exemple de message d’invite de mise à niveau :

    « Le projet%1a été créé avec une version antérieure de Visual Studio. Si vous l’ouvrez avec cette version de Visual Studio, vous ne pourrez peut-être pas l’ouvrir avec des versions antérieures de Visual Studio. Voulez-vous continuer et ouvrir ce projet ? »

Pour implémenter IVsProjectUpgradeViaFactory

  1. Implémentez la méthode de l’interface IVsProjectUpgradeViaFactory, notamment la méthode UpgradeProject dans votre implémentation de fabrique de projet, ou rendez les implémentations appelables depuis votre implémentation de fabrique de projet.

  2. Si vous souhaitez effectuer une mise à niveau sur place dans le cadre de l’ouverture de la solution, indiquez l’indicateur PUVFF_SXSBACKUPVSPUVF_FLAGS comme paramètre dans votre UpgradeProject implémentation.

  3. Si vous souhaitez effectuer une mise à niveau directe dans le cadre de l’ouverture de la solution, spécifiez le drapeau PUVFF_COPYBACKUP comme paramètre VSPUVF_FLAGS dans votre implémentation UpgradeProject.

  4. Pour les étapes 2 et 3, les étapes de mise à niveau de fichier réelles, à l’aide IVsQueryEditQuerySave2de , peuvent être implémentées comme décrit dans la section « Implémentation IVsProjectUpgade» ci-dessous, ou vous pouvez déléguer la mise à niveau réelle du fichier à IVsProjectUpgrade.

  5. Utilisez les méthodes de IVsUpgradeLogger pour publier les messages associés à la mise à niveau pour l’utilisateur avec l’Assistant de migration de Visual Studio.

  6. IVsFileUpgrade l’interface est utilisée pour implémenter tout type de mise à niveau de fichier qui doit se produire dans le cadre de la mise à niveau du projet. Cette interface n’est pas appelée à partir de IVsProjectUpgradeViaFactory, mais elle est fournie en tant que mécanisme de mise à niveau des fichiers qui font partie du système de projet, mais le système de projet principal peut ne pas être directement informé. Par exemple, cette situation peut survenir si les fichiers et propriétés associés au 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 de IVsProjectUpgrade

Si votre système de projet implémente IVsProjectUpgrade uniquement, il ne peut pas participer à l’Assistant Conversion de Visual Studio. Toutefois, même si vous implémentez l’interface IVsProjectUpgradeViaFactory, vous pouvez toujours déléguer la mise à niveau du fichier à l’implémentation IVsProjectUpgrade.

Pour implémenter IVsProjectUpgrade

  1. Lorsqu’un utilisateur tente d’ouvrir un projet, la UpgradeProject méthode est appelée par l’environnement une fois le projet ouvert et avant que toute autre action utilisateur puisse être effectuée sur le projet. Si l’utilisateur a déjà été invité à mettre à niveau la solution, l’indicateur UPF_SILENTMIGRATE est passé dans le grfUpgradeFlags paramètre. Si l’utilisateur ouvre directement un projet, par exemple à l’aide de la commande Ajouter un projet existant , l’indicateur UPF_SILENTMIGRATE n’est pas passé et le projet doit inviter l’utilisateur à effectuer la mise à niveau.

  2. En réponse à l’appel 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 l’indicateur S_OK .

  3. Si le projet doit mettre à niveau le type de projet vers une nouvelle version, il doit déterminer si le fichier projet peut être modifié en appelant la QueryEditFiles méthode et en transmettant une valeur pour tagVSQueryEditFlags le rgfQueryEdit paramètre. Le projet doit ensuite effectuer les opérations suivantes :

  4. Si l’appel sur le fichier QueryEditFiles du projet entraîne l’extraction du fichier et que la dernière version soit récupérée, alors le projet est déchargé et rechargé. La UpgradeProject méthode est appelée à nouveau une fois qu’une autre instance du projet est créée. Lors de ce deuxième appel, le fichier projet peut être écrit sur le disque ; il est recommandé que le projet enregistre une copie du fichier projet au format précédent avec une extension .OLD, apporte les modifications nécessaires pour la mise à niveau, et sauvegarde le fichier projet dans le nouveau format. Là encore, si une partie du processus de mise à niveau échoue, la méthode doit indiquer l’échec en retournant VS_E_PROJECTMIGRATIONFAILED. Cela entraîne le déchargement du projet dans l’Explorateur de solutions.

    Il est important de comprendre le processus complet qui se produit dans l’environnement pour le cas où l’appel à la méthode QueryEditFiles (en spécifiant une valeur de ReportOnly) retourne les indicateurs QER_EditNotOK et QER_ReadOnlyUnderScc.

  5. L’utilisateur tente d’ouvrir le fichier projet.

  6. L’environnement appelle votre CanCreateProject implémentation.

  7. Si CanCreateProject retourne true, l’environnement appelle votre implémentation CanCreateProject.

  8. L’environnement appelle votre Load implémentation pour ouvrir le fichier et initialiser l’objet projet, par exemple Project1.

  9. L’environnement appelle votre IVsProjectUpgrade::UpgradeProject implémentation pour déterminer si le fichier projet doit être mis à niveau.

  10. Vous appelez QueryEditFiles et passez une valeur de QEF_ReportOnly pour le paramètre rgfQueryEdit.

  11. L’environnement retourne QER_EditNotOK pour VSQueryEditResult, et le bit QER_ReadOnlyUnderScc est défini dans VSQueryEditResultFlags.

  12. Votre implémentation IVsProjectUpgrade appelle IVsQueryEditQuerySave::QueryEditFiles (QEF_ForceEdit_NoPrompting, QEF_DisallowInMemoryEdits).

Cet appel peut entraîner l’extraction d’une nouvelle copie de votre fichier projet et la récupération de la dernière version, ainsi que de recharger votre fichier projet. À ce stade, l’une des deux choses se produit :

  • Si vous gérez votre propre rechargement de projet, l’environnement appelle votre ReloadItem implémentation (VSITEMID_ROOT). Lorsque vous recevez cet appel, rechargez la première instance de votre projet (Project1) et poursuivez la mise à niveau de votre fichier projet. L’environnement sait que vous gérez le rechargement de votre propre projet si vous retournez true pour GetProperty (VSHPROPID_HandlesOwnReload).

  • Si vous ne gérez pas le rechargement de votre propre projet, vous retournez false pour GetProperty (VSHPROPID_HandlesOwnReload). Dans ce cas, l’environnement crée une autre instance de votre projet, par exemple Project2, avant que QueryEditFiles(QEF_ForceEdit_NoPrompting, QEF_DisallowInMemoryEdits) ne renvoie, comme suit :

    1. L’environnement appelle Close votre premier objet de projet, Project1, ce qui place cet objet dans l’état inactif.

    2. L’environnement appelle votre IVsProjectFactory::CreateProject implémentation pour créer une deuxième instance de votre projet, Project2.

    3. L’environnement appelle votre IPersistFileFormat::Load implémentation pour ouvrir le fichier et initialiser le deuxième objet de projet, Project2.

    4. L’environnement appelle IVsProjectUpgrade::UpgradeProject une seconde fois pour déterminer si l’objet projet doit être mis à niveau. Toutefois, cet appel est effectué sur une nouvelle instance, deuxième, du projet, Project2. Il s’agit du projet ouvert dans la solution.

      Note

      Dans le cas où votre premier projet, Project1, est placé dans l’état inactif, vous devez retourner S_OK du premier appel à votre implémentation UpgradeProject.

    5. Vous appelez QueryEditFiles et passez une valeur de QEF_ReportOnly pour le paramètre rgfQueryEdit.

    6. L’environnement retourne QER_EditOK et la mise à niveau peut continuer, car le fichier projet peut être écrit.

Si vous ne parvenez pas à effectuer la mise à niveau, revenez VS_E_PROJECTMIGRATIONFAILED à partir de IVsProjectUpgrade::UpgradeProject. Si aucune mise à niveau n’est nécessaire ou si vous choisissez de ne pas effectuer de mise à niveau, traitez l’appel IVsProjectUpgrade::UpgradeProject en tant que no-op. Si vous retournez VS_E_PROJECTMIGRATIONFAILED, un nœud de remplacement est ajouté à la solution pour votre projet.

Mise à niveau des éléments de projet

Si vous ajoutez ou gérez des éléments à l’intérieur des systèmes de projet que vous n’implémentez pas, vous devrez peut-être participer au processus de mise à niveau du projet. Crystal Reports est un exemple d’élément qui peut être ajouté au système de projet.

En règle générale, les implémenteurs d’éléments de projet souhaitent tirer parti d’un projet déjà instancié et mis à niveau, car ils doivent savoir quels sont les références du projet et quelles autres propriétés de projet sont là pour prendre une décision de mise à niveau.

Pour obtenir la notification de mise à niveau du projet

  1. Définissez l’indicateur SolutionOrProjectUpgrading (défini dans vsshell80.idl) dans l’implémentation de votre élément de projet. Cela entraîne le chargement automatique de l’élément de projet VSPackage lorsque l’interpréteur de commandes Visual Studio détermine qu’un système de projet est en cours de mise à niveau.

  2. Conseiller l’interface IVsSolutionEventsProjectUpgrade via la AdviseSolutionEvents méthode.

  3. L’interface IVsSolutionEventsProjectUpgrade est déclenchée une fois que l’implémentation du système de projet a terminé ses opérations de mise à niveau et que le nouveau projet mis à niveau est créé. Selon le scénario, l’interface IVsSolutionEventsProjectUpgrade est déclenchée après le OnAfterOpenSolution, le OnAfterOpenProjectou les OnAfterLoadProject méthodes.

Pour mettre à niveau les fichiers d’élément de projet

  1. Vous devez gérer soigneusement le processus de sauvegarde de fichiers dans l’implémentation de l’élément de projet. Cela s’applique en particulier à une sauvegarde simultanée, où le paramètre de la méthode UpgradeProject est défini à PUVFF_SXSBACKUP, où les fichiers qui ont été sauvegardés sont placés à côté des fichiers désignés en tant que ".old". Les fichiers sauvegardés antérieurs à l’heure système pendant laquelle le projet a été mis à niveau peuvent être désignés comme obsolètes. En outre, elles peuvent être remplacées, sauf si vous prenez des mesures spécifiques pour éviter cela.

  2. Au moment où votre élément de projet reçoit une notification de la mise à niveau du projet, l’Assistant Conversion de Visual Studio s’affiche toujours. Par conséquent, vous devez utiliser les méthodes de l’interface IVsUpgradeLogger pour transmettre des messages de mise à niveau à l'interface utilisateur de l'assistant.

Contenu connexe

  • Last updated on