Passo a passo: atualizando as ferramentas de compilação do Microsoft C++ (MSVC) para o projeto de exemplo Hilo

Este passo a passo mostra como usar GitHub Copilot para modernizar o projeto de exemplo do Hilo atualizando-o para as ferramentas de build mais recentes do MSVC. Você usará o agente de modernização para identificar e resolver problemas e, em seguida, usar o agente de depurador para corrigir um problema de runtime.

Sobre Hilo

Hilo foi um projeto de exemplo desenvolvido pela Microsoft em 2012 para demonstrar a criação de aplicativos direcionados Windows 8 usando C++, XAML e Windows Runtime "modernos". O aplicativo Hilo é um aplicativo de navegação por fotos que também inclui recursos de anotação e compartilhamento. Paramos de atualizar o exemplo em 2015 e arquivamos o código-fonte para este exemplo e outras amostras de C++ enviadas anteriormente no VCSamples GitHub repositório.

Captura de tela da janela principal do aplicativo Hilo mostrando o conteúdo da pasta Imagens do usuário.

Desafios de modernização

Há vários problemas que o agente descobre e resolve depois de atualizar o Hilo para usar uma versão mais recente do MSVC Build Tools. Aqui estão os problemas na compilação com as Ferramentas de Compilação do Microsoft C++ (MSVC), versão 14.51.

  • O std::tr1::is_base_of modelo de classe é usado em vários locais, mas não está mais disponível na biblioteca padrão C++ do MSVC, pois is_base_of o modelo de classe foi promovido a fazer parte do padrão completo. Esse é um erro de bloqueio.
  • A ID2D1Factory::GetDesktopDpi função foi preterida.
  • A[uuid(_string_)]sintaxe para atributos ATL em tipos foi preterida.
  • Há um projeto que o Assistente de Instalação não consegue atualizar. Se você não tiver as Ferramentas de Build do MSVC v120 instaladas (o que é provável), esse será um erro de bloqueio.
  • Há um truncamento de ponteiro no código de manipulação de janelas que causa uma exceção de acesso à memória em tempo de execução.

Há alguns outros avisos que podem não estar estritamente relacionados à atualização, mas que o agente pode, opcionalmente, corrigir. Estes avisos incluem:

  • Restringir avisos em torno de cadeias de caracteres de vários bytes e cadeias de caracteres largas.
  • Um erro de digitação no nome de um arquivo de saída em uma etapa de build personalizada.

Configuração

Instalar ferramentas de desenvolvimento

Para concluir este passo a passo, você precisa seguir as instruções de instalação para o agente de modernização do GitHub Copilot para C++.

Clonar o repositório

Abra o Visual Studio e, na Janela Inicial, selecione Clonar um repositório. Se a Janela Inicial não aparecer, você pode abri-la em Arquivo>Janela Inicial.

Captura de tela da janela inicial do Visual Studio com o link Clonar um repositório destacado.

Para o local do repositório, insira: https://github.com/microsoft/VCSamples.git. Escolha um caminho apropriado em seu sistema para clonar o repositório e clique no botão Clonar

Captura de tela da janela

Iniciar a atualização

Carregar Hilo.sln em Visual Studio

Depois de clonar o repositório, carregue o arquivo de solução no <repo-root>/VC2013Samples/Hilo/C++/Hilo.sln. Estamos usando a versão fornecida com Visual Studio 2013 para este passo a passo.

Usar o Assistente de Instalação para atualizar arquivos de projeto

Se você não tiver as ferramentas v120 instaladas, Visual Studio deverá iniciar a janela do Assistente de Instalação para orientá-lo a lidar com os componentes ausentes. Quando vir essa janela, você deverá optar por redirecionar tudo e clicar em Aplicar. Se a janela não aparecer, você pode abri-la no menu Arquivo clicando em Project>Redefinir destino da solução.

Captura de tela da janela Assistente de Instalação mostrando os projetos do Hilo. Todos estão selecionados para redirecionamento e o botão Aplicar está realçado.

Iniciar o agente de modernização do Copilot

Depois que o Assistente de Instalação redirecionar o projeto, você deverá receber uma mensagem de barra de informações com um link para iniciar o agente de modernização. Clicar no link Run GitHub Copilot modernization for C++ inicia o processo de atualização.

Screenshot da mensagem da barra de informações em Visual Studio para iniciar o agente de modernização.

Se a barra de informações não aparecer, você poderá iniciar o agente clicando com o botão direito do mouse na solução no Gerenciador de Soluções e clicando em Modernize. Se você seguir essa rota, poderá iniciar a atualização enviando o prompt I just updated MSVC Build Tools. Resolve any upgrade issues. para Copilot Chat.

Trabalhando com o agente

Como interagir com o agente para obter os melhores resultados

O agente de modernização .NET compartilha o mesmo modelo de interação subjacente que o agente C++. A documentação Trabalhar com o agente de modernização para .NET aborda detalhadamente os padrões gerais. Tenha em mente que os exemplos e cenários nesse artigo são específicos .NET e não se aplicam diretamente ao C++.

Para atualizações do C++, mais algumas dicas podem ajudar o agente a ter um bom desempenho:

  • Seja específico quanto ao escopo. Em vez de pedir ao agente para atualizar tudo de uma vez, informe em quais projetos, bibliotecas ou diagnósticos se concentrar. Por exemplo: "Corrija os avisos de descontinuação do C4996 no projeto NetworkClient."
  • Descreva o diagnóstico que você espera que o agente corrija. Se você souber os códigos de aviso ou erro específicos introduzidos pela atualização do conjunto de ferramentas, informe o agente antecipadamente. Essas instruções adicionais ajudam o agente a priorizar e evita o tempo gasto em problemas não relacionados.
  • Verifique se as ferramentas de edição de código C/C++ estão habilitadas. Verifique se as ferramentas necessárias estão disponíveis na configuração antes de começar. Para obter detalhes, consulte as ferramentas de edição de código C/C++.
  • Codificar convenções de codificação usando instruções personalizadas. Codificar diretrizes, como convenções de nomenclatura, APIs preferenciais ou padrões a serem evitados, em instruções personalizadas. O agente lê e segue estas instruções durante a atualização. Exemplos úteis do C++ incluem convenções como "Preferir auto onde o tipo é óbvio" e "Seguir Regra de Zero (ou Regra de Três/Cinco em que a propriedade do recurso exige isso)."

Comportamentos esperados

Note

Devido à natureza dos agentes de IA baseados em LLM, as etapas que o agente executa e a saída que ele produz podem ser diferentes das mostradas aqui.

Pré-avaliação

O agente primeiro determina o ambiente em que está em execução, como seu sistema de controle do código-fonte, e para entender sua meta. Em nosso caso, ele detecta que você está tentando atualizar seu projeto para usar o MSVC mais recente e inicializa o cenário apropriado. Ele cria um scenario.md arquivo e um scenario-instructions.md arquivo para conter metadados sobre o cenário.

Esses arquivos contêm informações como se o agente deve operar no modo Automático ou Guiado , qual é a estratégia para fazer confirmações e outras informações que afetam como o agente deve continuar. Se você expressar as preferências posteriormente durante a operação do agente, o agente poderá adicionar essas preferências ao scenario-instructions.md arquivo.

Captura de tela do conteúdo de um arquivo scenario-instructions.md.

Assessment

Após a inicialização, o agente faz uma avaliação do projeto fazendo uma recompilação limpa do projeto e inspecionando a saída de build em busca de erros e avisos. Usando essas informações e o contexto que o agente coleta do repositório, ele produz um assessment.md arquivo que descreve os problemas encontrados e se ele os considera ou não no escopo ou fora do escopo da tarefa de atualização.

Captura de tela do conteúdo renderizado de um arquivo assessment.md.

Se o agente estiver no modo Guiado, ele para aqui e solicita que você revise a avaliação. Faça as alterações desejadas solicitando ao agente ou editando o arquivo Markdown diretamente e, em seguida, continue no estágio de Planejamento . Se o agente estiver operando no modo Automático , o agente continuará no próximo estágio automaticamente. Se você quiser alterar algo, precisará parar o agente pressionando o botão cancelar, fazer as alterações e retomar o agente digitando o prompt "Resume" na janela de chat Copilot.

A avaliação identifica vários dos problemas mencionados anteriormente no passo a passo. Alguns problemas não aparecem até mais tarde, pois estão ocultos por erros existentes. Não se preocupe, eles são descobertos mais tarde. Se você quiser que o agente pause para obter sua aprovação para quaisquer problemas descobertos tardiamente, você pode especificar essas instruções em seu scenario-instructions.md arquivo.

Planejamento

Depois que o agente inicia a etapa de planejamento, ele faz uma análise mais aprofundada das questões no escopo e propõe possíveis soluções em um arquivo plan.md gerado. Ele também gera um tasks.md arquivo que fornece etapas e instruções mais estruturadas para executar o plano.

Captura de tela do conteúdo renderizado de um arquivo de plan.md.

Assim como na Avaliação, o que o agente faz depende se ele estiver operando no modo Guiado ou Automático . Se estiver no modo Guiado, o agente dará a você a oportunidade de orientá-lo para corrigir problemas de maneiras específicas ou até mesmo pedir que ele proponha opções alternativas com descrições mais detalhadas das vantagens e desvantagens. Você também pode especificar outras restrições, como convenções de codificação ou etapas especiais de validação para alguns problemas.

Execution

Depois de aprovar o plano (ou quando o Planejamento for concluído no modo Automático ), o agente passará para o estágio de Execução. Aqui, ele começa a lidar com as tarefas que tem à sua frente, adaptando-se a novas informações descobertas durante a execução. Com uma observação cuidadosa, você verá que o agente descobre os problemas ocultos anteriormente e ajusta seu plano adequadamente.

Captura de tela do agente durante a fase de execução, reagindo a problemas descobertos recentemente.

O resultado final da fase de execução é uma série de commits no seu repositório que resolvem os problemas dentro do escopo e um projeto que agora pode ser compilado com sucesso. No entanto, uma compilação limpa é apenas uma das etapas para atualizar seu projeto. Ele também precisa ser executado corretamente.

Use o agente Depurador para resolver problemas em tempo de execução

Iniciar o navegador

No Gerenciador de Soluções, clique com o botão direito do mouse no projeto Browser e clique em Set como projeto de inicialização. Em seguida, inicie uma sessão de depurador do Navegador Hilo pressionando F5 ou selecionando Depurar>Iniciar Depuração no menu de arquivo.

A sessão de depuração deve ser interrompida quase imediatamente devido a uma exceção de acesso à memória sem tratamento.

Captura de tela da exceção de acesso de leitura de memória ao iniciar pela primeira vez o navegador Hilo.

Analisar a exceção de acesso de leitura à memória

Vamos usar o agente de depurador para analisar essa exceção e implementar uma correção. Clique no botão Analyze com Copilot na janela de informações de exceção para iniciar o agente do Depurador.

Screenshot da janela de exceção do navegador Hilo com o botão Analisar com Copilot realçado.

O agente de depurador usa informações de estado de depuração e de programa para determinar a causa raiz de erros de runtime e, em seguida, analisa o código-fonte para implementar uma solução. Nesse caso, o agente identifica que o acesso inválido à memória se deve a uma operação de conversão inadequada que truncou um ponteiro de 64 bits para apenas 32 bits. Esse ponteiro agora é inválido e aponta para um local de memória inválido, o que causa a exceção. Ele propõe um método diferente para obter o tipo correto e evita o truncamento.

Aplicar alterações

Aceite as alterações sugeridas, interrompa a sessão de depuração pressionando Shift + F5*e inicie uma nova sessão pressionando F5. O projeto é recompilado com a alteração e Visual Studio inicia o aplicativo atualizado. Agora você deve ver a janela do Navegador Hilo aparecer.

Captura de tela da janela principal do aplicativo Hilo mostrando o conteúdo da pasta Imagens do usuário.

Se você gastar tempo explorando o aplicativo, poderá descobrir mais problemas de runtime. Deixamos quaisquer outras questões como exercícios para o leitor. Lembre-se de usar suas novas ferramentas autônomas para alcançar seu objetivo final mais rapidamente.

Resumo

Este passo a passo demonstrou como GitHub Copilot agentes podem acelerar significativamente a modernização de projetos C++ mais antigos. O agente de modernização e o agente de depuração podem trabalhar juntos para agilizar o processo de atualização, desde a avaliação inicial até a validação em tempo de execução.

Principais benefícios

  • Detecção automatizada de problemas: os agentes identificam sistematicamente alterações incompatíveis, descontinuações e problemas de compatibilidade decorrentes de atualizações.
  • Soluções inteligentes: em vez de exigir correções manuais, os agentes analisam o contexto de código e propõem soluções apropriadas adaptadas à base de código.
  • Eficiência: o que pode levar dias ou semanas de trabalho manual é concluído em horas, com o agente tratando erros de build e problemas de runtime.
  • Modos guiados ou automáticos: escolha entre diretrizes práticas ou execução totalmente automatizada com base em seu nível de conforto e requisitos de projeto.
  • Aprendizado e adaptação: os agentes descobrem problemas ocultos à medida que avançam e ajustam sua abordagem adequadamente, garantindo uma cobertura abrangente.

Conteúdo relacionado

  • Last updated on