Partilhar via

Projetos de modernização

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 à 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 projeto deve definir e implementar uma estratégia de atualização. Ao determinar sua estratégia, você pode optar por oferecer suporte a backup lado a lado (SxS), backup de cópia ou ambos.

  • Backup SxS significa que um projeto copia apenas os arquivos que precisam de atualização no local, adicionando um sufixo de nome de arquivo adequado, por exemplo, ".old".

  • Copiar backup significa que um projeto copia todos os itens do projeto para um local de backup fornecido pelo usuário. Os arquivos relevantes no local original do projeto são entã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 pelo processo de atualização.

Quando uma solução precisa de atualização, ela consulta cada fábrica de projeto para obter sua estratégia de atualização. A estratégia determina se a fábrica do projeto suporta backup de cópia ou backup SxS. As informações são enviadas para o 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 Multi-Projeto

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

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

Depois que o usuário conclui o assistente, UpgradeProject é chamado em cada fábrica de projeto para executar a atualização real. Para facilitar o backup, os métodos IVsProjectUpgradeViaFactory fornecem o SVsUpgradeLogger serviço para registrar os detalhes do processo de atualização. Este serviço não pode ser armazenado em cache.

Depois de atualizar todos os arquivos globais relevantes, cada fábrica de projeto pode optar por instanciar um projeto. A execução do projeto deve apoiar IVsProjectUpgrade. O UpgradeProject método é então chamado para atualizar todos os itens relevantes do projeto.

Observação

O UpgradeProject método não fornece o serviço SVsUpgradeLogger. Este serviço pode ser obtido ligando para QueryService.

Melhores práticas

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 sucesso ou falha do processo de atualização.

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

Atualizando projetos personalizados

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

O mecanismo antigo que usa a IVsProjectUpgrade interface ainda é suportado, mas conceitualmente atualiza o sistema de projeto como parte do projeto aberto. A IVsProjectUpgrade interface é, portanto, chamada pelo ambiente do Visual Studio, mesmo se a IVsProjectUpgradeViaFactory interface é chamada ou implementada. Essa abordagem permite usar IVsProjectUpgradeViaFactory para implementar a cópia e projetar apenas partes específicas da atualização e delegar o restante do trabalho a ser feito no local atual (possivelmente no novo local) pela interface IVsProjectUpgrade.

Para obter um exemplo de implementação de IVsProjectUpgrade, consulte Exemplos do VSSDK.

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

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

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

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

  • Se o UPF_SILENTMIGRATE sinalizador for especificado na UpgradeProject chamada, o usuário é solicitado pelo ambiente a atualizar o arquivo de projeto como uma atualização in-situ, após a abertura do projeto. Por exemplo, o ambiente solicita que o usuário atualize quando o usuário abre uma versão mais antiga da solução.

  • Se o flag UPF_SILENTMIGRATE não for especificado na chamada UpgradeProject, deve solicitar ao utilizador que atualize o ficheiro de projeto.

    A seguir está 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 seja possível abri-lo com versões mais antigas do Visual Studio. Quer continuar e abrir este projeto?"

Para implementar IVsProjectUpgradeViaFactory

  1. Implemente o método da interface IVsProjectUpgradeViaFactory, especificamente o método UpgradeProject na sua implementação da fábrica do projeto, ou faça com que as implementações sejam chamáveis a partir da sua implementação da fábrica do projeto.

  2. Caso pretenda realizar uma atualização no local como parte da abertura da solução, forneça o sinalizador PUVFF_SXSBACKUP como o parâmetro VSPUVF_FLAGS na sua implementação UpgradeProject.

  3. Se pretender fazer uma atualização local como parte da abertura da solução, forneça o sinalizador PUVFF_COPYBACKUP como o parâmetro VSPUVF_FLAGS na sua implementação UpgradeProject.

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

  5. Use os métodos de IVsUpgradeLogger para enviar mensagens de atualização ao utilizador usando o Assistente de Migração do Visual Studio.

  6. IVsFileUpgrade interface é usada para implementar qualquer tipo de atualização de arquivo que precisa 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 principal do projeto possa não estar diretamente ciente deles. Por exemplo, essa situação pode surgir se os arquivos e propriedades relacionados ao compilador não forem manipulados pela mesma equipe de desenvolvimento que lida com o resto do sistema de projeto.

Implementação IVsProjectUpgrade

Se o sistema de IVsProjectUpgrade projeto implementar somente, ele não poderá participar do Assistente de Conversão do Visual Studio. No entanto, mesmo se você implementar a IVsProjectUpgradeViaFactory interface, você ainda pode delegar a atualização do arquivo para a 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 executada no projeto. Se o usuário já tiver sido solicitado a atualizar a solução, o UPF_SILENTMIGRATE sinalizador será passado no grfUpgradeFlags parâmetro. Se o utilizador abrir um projeto diretamente, como usando o comando Adicionar Projeto Existente, o UPF_SILENTMIGRATE sinalizador não será passado e o projeto precisará solicitar que o utilizador atualize.

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

  3. Se o projeto precisar atualizar o tipo de projeto para uma nova versão, ele deve determinar se o arquivo de projeto pode ser modificado chamando o QueryEditFiles método e passando um valor de tagVSQueryEditFlags para 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 submetido a check-out 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 no disco; É recomendável que o projeto salve uma cópia do arquivo de projeto no formato anterior com um arquivo . 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 deve 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 do método QueryEditFiles (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 chama sua CanCreateProject implementação.

  7. Se CanCreateProject retornar true, o ambiente chamará sua CanCreateProject implementação.

  8. O ambiente chama sua Load implementação para abrir o arquivo e inicializar o objeto do 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 rgfQueryEdit parâmetro.

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

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

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

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

  • Se você não lidar com sua própria recarga de projeto, então você retorna false para GetProperty (VSHPROPID_HandlesOwnReload). Antes de (QEF_ForceEdit_NoPrompting, QEF_DisallowInMemoryEdits) retornar, nesse caso, o ambiente cria outra nova 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 seu projeto, 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 pede IVsProjectUpgrade::UpgradeProject uma segunda vez para determinar se o objeto do projeto deve ser atualizado. No entanto, esta chamada é feita em uma nova segunda instância do projeto, o Project2. Este é o projeto que é aberto na solução.

      Observação

      No caso em que seu primeiro projeto, Project1, é colocado no estado inativo, então 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 rgfQueryEdit parâmetro.

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

Se você não conseguir atualizar, retorne VS_E_PROJECTMIGRATIONFAILED de IVsProjectUpgrade::UpgradeProject. Se nenhuma atualização for necessária ou se você optar por não atualizar, trate a IVsProjectUpgrade::UpgradeProject chamada como uma no-op. Caso devolvas VS_E_PROJECTMIGRATIONFAILED, um nó de marcador de posição será adicionado à solução para o teu projeto.

Atualizando itens de projeto

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

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 do 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 sinalizador (definido em vsshell80.idl) na implementação do item de projeto. Isso faz com que o item de projeto VSPackage se carregue automaticamente quando o shell do Visual Studio determina que um sistema de projeto está em processo de atualização.

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

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

Para atualizar os arquivos de item de projeto

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

  2. No momento em que o item de projeto recebe uma notificação da atualização do projeto, o Assistente de conversão do Visual Studio ainda é exibido. Portanto, deve utilizar os métodos da interface IVsUpgradeLogger para fornecer mensagens de atualização para a UI do assistente.

Conteúdo relacionado

  • Last updated on