Compartilhar via

Atualizando projetos

As alterações no modelo de projeto de uma versão do Visual Studio para a próxima podem exigir que projetos e soluções sejam atualizados para que possam ser executados na versão mais recente. O SDK do Visual Studio fornece interfaces que podem ser usadas para implementar o suporte de atualização em seus próprios projetos.

Estratégias de atualização

Para dar suporte a uma atualização, a implementação do sistema de projetos deve definir e implementar uma estratégia de atualização. Ao determinar sua estratégia, você pode optar por dar suporte ao backup lado a lado (SxS), backup de cópia, ou ambos.

  • O backup do SxS significa que um projeto copia apenas os arquivos que precisam ser atualizados no local, adicionando um sufixo de nome de arquivo adequado, por exemplo, ".old".

  • Copiar backup significa que um projeto copia todos os itens de projeto para um local de backup fornecido pelo usuário. Os arquivos relevantes no local do projeto original são atualizados.

Como funciona a atualização

Quando uma solução criada em uma versão anterior do Visual Studio é aberta em uma versão mais recente, o IDE verifica o arquivo de solução para determinar se ele precisa ser atualizado. Se a atualização for necessária, o Assistente de Atualização será iniciado automaticamente para orientar o usuário durante o processo de atualização.

Quando uma solução precisa ser atualizada, ela consulta cada fábrica de projetos para sua estratégia de atualização. A estratégia determina se a fábrica de projetos dá suporte à cópia de backup ou ao backup SxS. As informações são enviadas ao Assistente de Atualização, que coleta as informações necessárias para o backup e apresenta as opções aplicáveis ao usuário.

Soluções de vários projetos

Se uma solução contiver vários projetos e as estratégias de atualização forem diferentes, como quando um projeto C++ que dá suporte apenas ao backup do SxS e a um projeto Web que dá suporte apenas ao backup de cópia, as fábricas de projetos deverão negociar a estratégia de atualização.

A solução consulta cada fábrica de projetos sobre IVsProjectUpgradeViaFactory. Em seguida, ele chama UpgradeProject_CheckOnly para ver se os arquivos de projeto globais precisam ser atualizados e determinar as estratégias de atualização com suporte. Em seguida, o Assistente de Atualização é invocado.

Após o usuário terminar de usar o assistente, UpgradeProject será chamado em cada fábrica de projetos para realizar a atualização propriamente dita. Para facilitar o backup, os métodos IVsProjectUpgradeViaFactory fornecem o SVsUpgradeLogger serviço para registrar em log os detalhes do processo de atualização. Esse serviço não pode ser armazenado em cache.

Depois de atualizar todos os arquivos globais relevantes, cada fábrica de projetos pode optar por instanciar um projeto. A implementação do projeto deve dar suporte IVsProjectUpgrade. Então, o método UpgradeProject é chamado para atualizar todos os itens de projeto relevantes.

Observação

O UpgradeProject método não fornece o serviço SVsUpgradeLogger. Esse serviço pode ser obtido chamando QueryService.

Práticas recomendadas

Use o SVsQueryEditQuerySave serviço para verificar se você pode editar um arquivo antes de editá-lo e pode salvá-lo antes de salvá-lo. Isso ajudará suas implementações de backup e atualização a lidar com arquivos de projeto sob controle do código-fonte, arquivos com permissões insuficientes e assim por diante.

Use o SVsUpgradeLogger serviço durante todas as fases de backup e atualização para fornecer informações sobre o êxito ou falha do processo de atualização.

Para obter mais informações sobre como fazer backup e atualizar projetos, consulte os comentários de IVsProjectUpgrade em vsshell2.idl.

Atualizando projetos personalizados

Se você alterar as informações mantidas no arquivo de projeto entre diferentes versões do Visual Studio do seu produto, precisará dar suporte à atualização do arquivo de projeto do antigo para a nova versão. Para dar suporte à atualização que permite que você participe do Assistente de Conversão do Visual Studio, implemente a IVsProjectUpgradeViaFactory interface. Essa interface contém o único mecanismo disponível para atualização de cópia. A atualização do projeto ocorre quando uma parte da solução é aberta. A IVsProjectUpgradeViaFactory interface é implementada pela fábrica de projetos ou deve pelo menos ser obtida da fábrica de projetos.

O mecanismo antigo que usa a IVsProjectUpgrade interface ainda tem suporte, mas atualiza conceitualmente o sistema de projetos como parte do projeto aberto. Portanto, o ambiente do Visual Studio chama a interface IVsProjectUpgrade, mesmo que a interface IVsProjectUpgradeViaFactory seja chamada ou implementada. Essa abordagem permite que você use IVsProjectUpgradeViaFactory para implementar a cópia e projetar apenas partes da atualização, delegando o restante do trabalho para ser feito localmente (possivelmente no novo local) pela interface IVsProjectUpgrade.

Para obter uma implementação de exemplo, consulte exemplos do IVsProjectUpgradeVSSDK.

Os seguintes cenários surgem com atualizações de projeto:

  • Se o arquivo for de um formato mais recente do que o projeto pode dar suporte, ele deverá retornar um erro informando isso. Isso pressupõe que a versão mais antiga do produto inclua código para verificar a versão.

  • Se o sinalizador PUVFF_SXSBACKUP for especificado no método UpgradeProject, a atualização será implementada como uma atualização in-place antes da abertura do projeto.

  • Se o PUVFF_COPYBACKUP sinalizador for especificado no UpgradeProject método, a atualização será implementada como uma atualização de cópia.

  • Se o UPF_SILENTMIGRATE sinalizador for especificado na UpgradeProject chamada, o usuário foi solicitado pelo ambiente a atualizar o arquivo de projeto como uma atualização no local, depois que o projeto tenha sido aberto. Por exemplo, o ambiente solicita que o usuário atualize ao abrir uma versão anterior da solução.

  • Se o sinalizador UPF_SILENTMIGRATE não for especificado na função UpgradeProject, você deverá solicitar que o usuário atualize o arquivo de projeto.

    Veja a seguir um exemplo de mensagem de prompt de atualização:

    "O projeto '%1' foi criado com uma versão mais antiga do Visual Studio. Se você abri-lo com esta versão do Visual Studio, talvez não consiga abri-lo com versões mais antigas do Visual Studio. Deseja continuar e abrir este projeto?"

Para implementar IVsProjectUpgradeViaFactory

  1. Implemente o método da interface IVsProjectUpgradeViaFactory, especificamente o método UpgradeProject na implementação da fábrica de projetos, ou torne as implementações acessíveis a partir da implementação da fábrica de projetos.

  2. Se você quiser fazer uma atualização no local como parte da abertura da solução, forneça o sinalizador PUVFF_SXSBACKUP como parâmetro VSPUVF_FLAGS em sua UpgradeProject implementação.

  3. Se você quiser fazer uma atualização no local como parte da abertura da solução, forneça o sinalizador PUVFF_COPYBACKUP como parâmetro VSPUVF_FLAGS em sua implementação UpgradeProject.

  4. Para as etapas 2 e 3, as etapas reais de atualização de arquivo, usando IVsQueryEditQuerySave2, podem ser implementadas conforme descrito na seção "Implementando IVsProjectUpgade" abaixo ou você pode delegar a atualização real de arquivo para IVsProjectUpgrade.

  5. Use os métodos de IVsUpgradeLogger para postar mensagens relacionadas à atualização para o usuário usando o Assistente de Migração do Visual Studio.

  6. IVsFileUpgrade A interface é usada para implementar qualquer tipo de atualização de arquivo que precise acontecer como parte da atualização do projeto. Essa interface não é chamada de IVsProjectUpgradeViaFactory, mas é fornecida como um mecanismo para atualizar arquivos que fazem parte do sistema de projeto, embora o sistema de projeto principal possa não estar diretamente ciente deles. Por exemplo, essa situação poderá surgir se os arquivos e propriedades relacionados ao compilador não forem tratados pela mesma equipe de desenvolvimento que manipula o restante do sistema de projetos.

Implementação de IVsProjectUpgrade

Se o sistema de projeto implementar apenas IVsProjectUpgrade, ele não poderá participar do Assistente de Conversão do Visual Studio. No entanto, mesmo se você implementar a IVsProjectUpgradeViaFactory interface, ainda poderá delegar a atualização de arquivo à IVsProjectUpgrade implementação.

Para implementar IVsProjectUpgrade

  1. Quando um usuário tenta abrir um projeto, o UpgradeProject método é chamado pelo ambiente depois que o projeto é aberto e antes que qualquer outra ação do usuário possa ser tomada no projeto. Se o usuário já tiver sido solicitado a atualizar a solução, o flag UPF_SILENTMIGRATE será passado no parâmetro grfUpgradeFlags. Se o usuário abrir um projeto diretamente, como usando o comando Adicionar Projeto Existente, o sinalizador UPF_SILENTMIGRATE não é passado e o projeto precisará solicitar que o usuário atualize.

  2. Em resposta à UpgradeProject chamada, o projeto deve avaliar se o arquivo de projeto foi atualizado. Se o projeto não precisar atualizar o tipo de projeto para uma nova versão, ele poderá simplesmente retornar o S_OK sinalizador.

  3. Se o projeto precisar atualizar o tipo de projeto para uma nova versão, ele deverá determinar se o arquivo de projeto pode ser modificado chamando o QueryEditFiles método e passando um valor para tagVSQueryEditFlags o rgfQueryEdit parâmetro. Em seguida, o projeto precisa fazer o seguinte:

  4. Se a QueryEditFiles chamada no arquivo de projeto fizer com que o arquivo seja verificado e a versão mais recente seja recuperada, o projeto será descarregado e recarregado. O UpgradeProject método é chamado novamente quando outra instância do projeto é criada. Nesta segunda chamada, o arquivo de projeto pode ser gravado em disco; é recomendável que o projeto salve uma cópia do arquivo de projeto no formato anterior com uma extensão .OLD, faça as alterações de atualização necessárias e salve o arquivo de projeto no novo formato. Novamente, se qualquer parte do processo de atualização falhar, o método deverá indicar falha retornando VS_E_PROJECTMIGRATIONFAILED. Isso faz com que o projeto seja descarregado no Gerenciador de Soluções.

    É importante entender o processo completo que ocorre no ambiente para o caso em que a chamada ao QueryEditFiles método (especificando um valor de ReportOnly) retorna os sinalizadores QER_EditNotOK e QER_ReadOnlyUnderScc.

  5. O usuário tenta abrir o arquivo de projeto.

  6. O ambiente invoca sua CanCreateProject implementação.

  7. Se CanCreateProject retornar true, então o ambiente invocará sua implementação de CanCreateProject.

  8. O ambiente chama sua Load implementação para abrir o arquivo e inicializar o objeto de projeto, por exemplo, Project1.

  9. O ambiente chama sua IVsProjectUpgrade::UpgradeProject implementação para determinar se o arquivo de projeto precisa ser atualizado.

  10. Você chama QueryEditFiles e passa um valor de QEF_ReportOnly para o parâmetro rgfQueryEdit.

  11. O ambiente retorna QER_EditNotOK para VSQueryEditResult e o QER_ReadOnlyUnderScc bit é definido em VSQueryEditResultFlags.

  12. A sua implementação IVsProjectUpgrade chama IVsQueryEditQuerySave::QueryEditFiles (QEF_ForceEdit_NoPrompting, QEF_DisallowInMemoryEdits).

Essa chamada pode fazer com que uma nova cópia do arquivo de projeto seja verificada e a versão mais recente recuperada, bem como a necessidade de recarregar o arquivo de projeto. Neste ponto, uma das duas coisas acontecem:

  • Se você lidar com seu próprio recarregamento de projeto, o ambiente chamará sua ReloadItem implementação (VSITEMID_ROOT). Quando você receber essa chamada, recarregue a primeira instância do projeto (Project1) e continue atualizando seu arquivo de projeto. Se você retornar true para GetProperty (VSHPROPID_HandlesOwnReload), o ambiente saberá que você lida com o recarregamento do seu próprio projeto.

  • Se você não realizar seu próprio recarregamento do projeto, retornará false para GetProperty (VSHPROPID_HandlesOwnReload). Nesse caso, antesQueryEditFiles(QEF_ForceEdit_NoPrompting, QEF_DisallowInMemoryEdits) retornar, o ambiente cria outra instância do seu projeto, por exemplo, Project2, da seguinte maneira:

    1. O ambiente chama Close seu primeiro objeto de projeto, Project1, colocando esse objeto no estado inativo.

    2. O ambiente chama sua IVsProjectFactory::CreateProject implementação para criar uma segunda instância do projeto, o Project2.

    3. O ambiente chama sua IPersistFileFormat::Load implementação para abrir o arquivo e inicializar o segundo objeto de projeto, Project2.

    4. O ambiente exige IVsProjectUpgrade::UpgradeProject uma segunda vez para determinar se o objeto do projeto deve ser atualizado. No entanto, essa chamada é feita em uma nova instância, segunda, do projeto, o Project2. Esse é o projeto aberto na solução.

      Observação

      Na instância em que seu primeiro projeto, Project1, é colocado no estado inativo, você deve retornar S_OK da primeira chamada para sua UpgradeProject implementação.

    5. Você chama QueryEditFiles e passa um valor de QEF_ReportOnly para o parâmetro rgfQueryEdit.

    6. O ambiente retorna QER_EditOK e a atualização pode continuar porque o arquivo de projeto pode ser gravado.

Caso você não consiga atualizar, retorne VS_E_PROJECTMIGRATIONFAILED de IVsProjectUpgrade::UpgradeProject. Se nenhuma atualização for necessária ou você optar por não atualizar, trate a IVsProjectUpgrade::UpgradeProject chamada como um no-op. Se você retornar VS_E_PROJECTMIGRATIONFAILED, um nó de espaço reservado será adicionado à solução do seu projeto.

Atualizando itens do projeto

Se você adicionar ou gerenciar itens dentro de sistemas de projeto que não implementa, talvez seja necessário participar do processo de atualização do projeto. Crystal Reports é um exemplo de um item que pode ser adicionado ao sistema de projetos.

Normalmente, os implementadores de item de projeto desejam aproveitar um projeto já totalmente instanciado e atualizado porque precisam saber quais são as referências do projeto e quais outras propriedades de projeto estão lá para tomar uma decisão de atualização.

Para obter a notificação de atualização do projeto

  1. Defina o SolutionOrProjectUpgrading flag (definido em vsshell80.idl) na implementação do item de projeto. Isso faz com que o VSPackage do item de projeto carregue automaticamente quando o shell do Visual Studio determinar que um sistema de projeto está em processo de atualização.

  2. Aconselhe a interface IVsSolutionEventsProjectUpgrade através do método AdviseSolutionEvents.

  3. A IVsSolutionEventsProjectUpgrade interface é acionada depois que a implementação do sistema de projetos concluir suas operações de atualização e o novo projeto atualizado for criado. Dependendo do cenário, a interface IVsSolutionEventsProjectUpgrade é acionada após os métodos OnAfterOpenSolution, OnAfterOpenProject ou OnAfterLoadProject.

Para atualizar os arquivos de item do projeto

  1. Você deve gerenciar cuidadosamente o processo de backup de arquivo na implementação do item de projeto. Isso se aplica, em particular, a um backup lado a lado, em que o fUpgradeFlag parâmetro do UpgradeProject método é definido como PUVFF_SXSBACKUP, em que os arquivos que fazem parte do backup são colocados ao lado de arquivos designados como ".old". Os arquivos de backup mais antigos do que a hora do sistema quando o projeto foi atualizado podem ser designados como obsoletos. Além disso, eles podem ser substituídos, a menos que você execute etapas específicas para evitar isso.

  2. No momento em que o item do projeto recebe uma notificação da atualização do projeto, o Assistente de Conversão do Visual Studio ainda é exibido. Portanto, você deve usar os métodos da interface IVsUpgradeLogger para fornecer mensagens de atualização para a interface de usuário do assistente.

Conteúdo relacionado

  • Last updated on