Passo a passo: Atualizar as Ferramentas de Build Microsoft C++ (MSVC) para o projeto de exemplo Hilo

Esta explicação mostra como usar o GitHub Copilot para modernizar o projeto de exemplo do Hilo, atualizando-o para as mais recentes Ferramentas de Build do MSVC. Vais usar o agente de modernização para identificar e resolver problemas, depois usar o agente Debugger para corrigir um problema em tempo de execução.

Sobre Hilo

Hilo foi um projeto de exemplo desenvolvido pela Microsoft em 2012 para demonstrar a criação de aplicações direcionadas para o Windows 8 usando C++ "moderno", XAML e o Windows Runtime. A aplicação Hilo é uma aplicação de navegação de fotografias que também inclui funcionalidades de anotação e partilha. Deixámos de atualizar o exemplo em 2015 e arquivámos o código-fonte deste exemplo e de outros exemplos C++ anteriormente enviados no repositório GitHub VCSamples.

Captura de ecrã da janela principal da aplicação Hilo mostrando o conteúdo da pasta Imagens do utilizador.

Desafios de modernização

Existem vários problemas que o agente descobre e resolve após atualizar o Hilo para usar uma versão mais recente do MSVC Build Tools. Aqui estão os problemas ao compilar com as Ferramentas de Build do Microsoft C++ (MSVC) versão 14.51.

  • O std::tr1::is_base_of modelo de classe é utilizado em vários locais, mas já não está disponível na biblioteca padrão C++ da MSVC, uma vez que is_base_of o template de classe foi promovido para fazer parte do padrão completo. Isto é um erro de bloqueio.
  • A ID2D1Factory::GetDesktopDpi função está obsoleta.
  • A[uuid(_string_)]sintaxe dos atributos ATL nos tipos está obsoleta.
  • Há um projeto que o Assistente de Configuração não consegue atualizar. Se não tens instalado o MSVC Build Tools v120 (o que é provável), então isto é um erro de bloqueio.
  • Existe um truncamento de ponteiro no código de gestão de janelas que causa uma exceção de acesso à memória em tempo de execução.

Existem alguns outros avisos que podem não estar estritamente relacionados com a atualização, mas que o agente pode corrigir opcionalmente. Estes avisos incluem:

  • Restringir avisos em relação a cadeias de caracteres de vários bytes e cadeias largas de caracteres.
  • Um erro tipográfico no nome de um ficheiro de saída numa etapa de construção personalizada.

Configuração

Instalar ferramentas de desenvolvimento

Para completar esta explicação, é necessário seguir as instruções de instalação para o agente de modernização GitHub Copilot para C++.

Clonar o repositório

Abrir Visual Studio e, a partir da Janela de Inicio, selecionar Clone a repository. Se a Janela Inicial não apareceu, podes abri-la através de Ficheiro>Janela Inicial.

Captura de ecrã da Janela Inicial do Visual Studio com a ligação “Clonar um repositório” destacada.

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

Captura de ecrã do Visual Studio Clone, uma janela de repositório com os campos necessários concluídos e o botão Clone destacado.

Iniciar a atualização

Carrega Hilo.sln em Visual Studio

Depois de clonares o repositório, carrega o ficheiro de solução em <repo-root>/VC2013Samples/Hilo/C++/Hilo.sln. Estamos a usar a versão que veio com o Visual Studio 2013 para esta explicação.

Use o Assistente de Configuração para atualizar ficheiros de projeto

Se não tiveres as ferramentas v120 instaladas, o Visual Studio deverá abrir a janela do assistente de configuração para te orientar como lidar com os componentes em falta. Quando vires esta janela, deves escolher Redirecionar todos e clicar em Aplicar. Se a janela não aparecer, pode abri-la no menu Ficheiro clicando em Project>Redefinir o destino da solução.

Captura de ecrã da janela do assistente de configuração a mostrar os projetos do Hilo. Todos são selecionados para retargeting e o botão Aplicar está destacado.

Lançar o agente de modernização Copilot

Depois de o assistente de configuração redirecionar o projeto, deverá receber uma mensagem infobar 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.

Captura de ecrã da mensagem infobar em Visual Studio para o lançamento do agente de modernização.

Se a barra de informação não aparecer, podes iniciar o agente clicando com o botão direito na solução no Explorador de Soluções e clicando em Modernizar. Se optares por esse caminho, podes iniciar a atualização enviando o prompt I just updated MSVC Build Tools. Resolve any upgrade issues. para Copilot Chat.

Trabalhar com o agente

Como interagir com o agente para obter os melhores resultados

O agente de modernização .NET partilha o mesmo modelo de interação subjacente que o agente C++. A documentação Work with the modernization agent sobre o .NET aborda em detalhe os padrões gerais. Tenha em mente que os exemplos e cenários desse artigo são específicos do .NET e não se aplicam diretamente ao C++.

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

  • Seja específico quanto ao âmbito. Em vez de pedir ao agente para atualizar tudo de uma vez, diga-lhe em que projetos, bibliotecas ou diagnósticos deve focar-se. Por exemplo: "Corrigir os avisos de obsolescência C4996 no projeto NetworkClient."
  • Descreva os diagnósticos que espera que o agente resolva. Se souber o aviso específico ou os códigos de erro introduzidos pela atualização do conjunto de ferramentas, informe o agente desde o início. Estas instruções adicionais ajudam o agente a priorizar e a evitar que o tempo seja gasto em questões não relacionadas.
  • Certifica-te de que as ferramentas de edição de código C/C++ estão ativadas. Verifica se as ferramentas necessárias estão disponíveis na tua configuração antes de começar. Para mais detalhes, consulte ferramentas de edição de código em 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 evitar, em instruções personalizadas. O agente lê e segue estas instruções ao longo de toda a atualização. Exemplos úteis em C++ incluem convenções como "Preferir auto onde o tipo é óbvio" e "Seguir a Regra do Zero (ou Regra do Três/Cinco quando a posse de recursos o exigir)."

Comportamentos esperados

Observação

Devido à natureza dos agentes de IA baseados em LLM, os passos que o agente dá e o resultado que produz podem diferir do que aqui é mostrado.

Pré-avaliação

O agente determina primeiro o ambiente em que está a ser executado, por exemplo, o seu sistema de controlo de versões, e procura compreender o seu objetivo. No nosso caso, deteta que está a tentar atualizar o seu projeto para usar o MSVC mais recente e inicializa o cenário apropriado. Cria um scenario.md ficheiro e um scenario-instructions.md ficheiro para conter metadados sobre o cenário.

Estes ficheiros contêm informações como se o agente deve operar em modo Automático ou Guiado , qual é a estratégia para fazer commits e outras informações que afetam a forma como o agente deve proceder. Se expressar alguma preferência mais tarde durante a operação do agente, o agente pode adicionar essas preferências ao scenario-instructions.md ficheiro.

Captura de ecrã do conteúdo de um ficheiro scenario-instructions.md.

Assessment

Após a inicialização, o agente faz uma avaliação do projeto, fazendo uma reconstrução limpa do projeto e inspecionando a saída da compilação em busca de erros e avisos. Usando essa informação, e o contexto que o agente recolhe do repositório, produz um assessment.md ficheiro que descreve os problemas encontrados e se os considera dentro ou fora do âmbito da tarefa de atualização.

Captura de ecrã do conteúdo renderizado de um ficheiro assessment.md.

Se o agente estiver a operar em modo Guiado , o agente para aqui e solicita a sua revisão da avaliação. Faça as alterações desejadas solicitando o agente ou editando diretamente o ficheiro Markdown, e depois continue para a fase de Planeamento . Se o agente estiver a operar em modo Automático , o agente avança automaticamente para a próxima etapa. Se quiseres mudar algo, tens de parar o agente pressionando o botão de cancelar, fazer as alterações e retomar o agente escrevendo o prompt "Retomar" na janela do chat Copilot.

A avaliação identifica várias das questões mencionadas anteriormente na explicação. Alguns problemas só aparecem mais tarde, pois estão ocultos por erros existentes. Não te preocupes, eles são descobertos mais tarde. Se quiser que o agente pare para obter a sua aprovação relativamente a quaisquer problemas detetados mais tarde, pode especificar essas instruções no seu ficheiro scenario-instructions.md.

Planning

Assim que o agente inicia a fase de Planeamento, faz uma análise mais aprofundada das questões dentro do âmbito e propõe possíveis soluções num ficheiro gerado plan.md . Também gera um tasks.md ficheiro que fornece passos e instruções mais estruturadas para executar o plano.

Captura de ecrã do conteúdo renderizado de um ficheiro plan.md.

Tal como na Avaliação, o que o agente faz depende se está a operar em modo Guiado ou Automático . Se estiver a executar em modo Guiado, o agente dá-lhe a possibilidade de o orientar para corrigir problemas de determinadas formas ou até de lhe pedir que proponha opções alternativas com descrições mais detalhadas das vantagens e desvantagens. Também pode especificar outras restrições, como convenções de codificação ou passos especiais de validação para algumas questões.

Execution

Depois de aprovar o plano (ou quando o Planeamento está concluído em modo Automático ), o agente passa para a fase de Execução. Aqui, começa a tratar das tarefas que tem pela frente, adaptando-se à nova informação descoberta durante a execução. Com uma observação cuidadosa, verá que o agente descobre os problemas anteriormente ocultos e ajusta o seu plano em conformidade.

Captura de ecrã do agente no meio da fase de Execução, a reagir a problemas recém-descobertos.

O resultado final da fase de Execução é uma série de commits no seu repositório que resolvem os problemas dentro do âmbito, e um projeto que agora pode ser construído com sucesso. No entanto, uma compilação limpa é apenas um dos passos para melhorar o seu projeto. Também precisa de funcionar corretamente.

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

Iniciar o Navegador

No Explorador de Soluções, clique com o botão direito no projeto Browser e clique em Set como projeto de arranque. Depois, inicia uma sessão de depuração no Navegador Hilo pressionando F5 ou selecionando Debug>Start Debugging no menu de ficheiros.

A sessão de depuração deve interromper-se quase imediatamente devido a uma exceção de acesso à memória não tratada.

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

Analisar exceção de acesso de leitura da memória

Vamos usar o agente Debugger para analisar esta exceção e implementar uma correção. Clique no botão Analyze com Copilot na janela de informação de exceções para lançar o agente Debugger.

Captura de ecrã da janela de exceções para o navegador Hilo com o botão Analisar com Copilot destacado.

O agente Debugger utiliza informações de depuração e estado do programa para determinar a causa raiz dos erros em tempo de execução e depois analisa o código-fonte para implementar uma solução. Neste caso, o agente identifica que o acesso inválido à memória se deve a uma operação de conversão de tipo inadequada que truncou um ponteiro de 64 bits para apenas 32 bits. Esse ponteiro está agora inválido e aponta para uma localização de memória inválida, o que causa a exceção. Propõe um método diferente para obter o tipo correto e evita o truncamento.

Aplicar alterações

Aceita as alterações que sugere, interrompe a sessão de depuração pressionando Shift + F5*, e depois inicia uma nova sessão pressionando F5. O projeto é recompilado com a alteração e o Visual Studio lança a aplicação atualizada. Agora deves ver a janela do Navegador Hilo a aparecer.

Captura de ecrã da janela principal da aplicação Hilo mostrando o conteúdo da pasta Imagens do utilizador.

Se dedicar algum tempo a explorar a aplicação, poderá descobrir mais problemas de execução. Deixamos quaisquer outros problemas como exercícios para o leitor. Lembra-te apenas de usar as tuas novas ferramentas agentic para alcançares o teu objetivo final mais depressa.

Resumo

Esta apresentação demonstrou como os agentes GitHub Copilot podem acelerar significativamente a modernização de projetos C++ mais antigos. O agente de modernização e o agente de depuração podem trabalhar em conjunto para simplificar o processo de atualização desde a avaliação inicial até à validação em tempo de execução.

Principais benefícios

  • Deteção automática de problemas: Os agentes identificam sistematicamente alterações incompatíveis, depreciações e problemas de compatibilidade decorrentes das atualizações.
  • Soluções inteligentes: Em vez de exigirem correções manuais, os agentes analisam o contexto do código e propõem soluções adequadas adaptadas à sua base de código.
  • Eficiência: O que pode demorar dias ou semanas de trabalho manual é concluído em horas, com o agente a tratar tanto de erros de compilação como de problemas de execução.
  • Modos guiados ou automáticos: Escolha entre orientação prática ou execução totalmente automatizada, consoante o seu nível de conforto e os requisitos do projeto.
  • Aprendizagem e adaptação: Os agentes descobrem problemas ocultos à medida que progridem e ajustam a sua abordagem em conformidade, garantindo uma cobertura abrangente.

Conteúdo relacionado

  • Last updated on