Estratégia global de migração

Introdução

O SDK de Aplicações Windows fornece um conjunto alargado de APIs do Windows — com implementações que são desacopladas do sistema operativo e lançadas aos programadores através de pacotes NuGet. Como programador com uma aplicação Plataforma Universal do Windows (UWP), pode tirar grande partido das suas competências existentes e do seu código-fonte, movendo a sua aplicação para o SDK de Aplicações Windows.

Com o SDK de Aplicações Windows pode incorporar as funcionalidades mais recentes de runtime, linguagem e plataforma na sua aplicação. Como cada aplicativo é diferente, assim como seus requisitos e preferências, há muitas maneiras diferentes de abordar o processo de migração do código-fonte do seu aplicativo. Mas a abordagem de alto nível e as alterações de código necessárias para várias áreas funcionais são semelhantes. Portanto, neste tópico, analisaremos estratégias sobre como você pode abordar a migração de seu aplicativo, bem como mais informações (e limitações) sobre determinadas áreas de recursos. Portanto, consulte também O que é suportado ao migrar da UWP para o WinUI 3.

A maioria das APIs Windows Runtime (WinRT) pode ser usada por SDK de Aplicações Windows aplicações. Mas há alguns que não são suportados em aplicações de ambiente de trabalho ou têm restrições.

• APIs que têm dependências em recursos de interface do usuário que foram projetados para uso somente em aplicativos UWP.
• APIs que exigem identidade de pacote. Essas APIs são suportadas apenas em aplicativos da área de trabalho que são empacotados usando MSIX.

Para essas APIs, mostraremos quais alternativas usar. A maioria dessas alternativas está disponível em WinUI, ou através de interfaces COM WinRT que estão disponíveis no SDK de Aplicações Windows.

Por exemplo, veremos certos cenários de interface do utilizador em que precisará monitorizar o seu objeto de janela principal e usar várias APIs baseadas em HWND e padrões de interoperação, como IInitializeWithWindow::Initialize.

Gostaríamos muito de ouvir os seus comentários sobre este guia de migração e sobre a sua própria experiência de migração. Use a seção Feedback bem no pé desta página desta forma:

• Para perguntas e feedback sobre o SDK de Aplicações Windows, ou apenas para iniciar uma discussão, use o botão Este produto. Também pode iniciar uma discussão no separador Discussões do repositório WindowsAppSDK GitHub. Usando esses canais, você também pode nos dizer qual problema está tentando resolver, como tentou resolvê-lo até agora e qual seria a solução ideal para seu aplicativo.
• Para obter comentários sobre informações ausentes ou incorretas neste guia de migração, use o botão Esta página.

Porque migrar para o SDK de Aplicações Windows?

A SDK de Aplicações Windows oferece-lhe a oportunidade de melhorar a sua aplicação com novas funcionalidades da plataforma, bem como com a moderna Windows UI 3 Library (WinUI), desenvolvida e concebida para encantar os seus utilizadores.

Além disso, o SDK de Aplicações Windows é compatível com versões anteriores; suporta aplicações até ao Windows 10, versão 1809 (10.0; Build 17763)—também conhecida como Atualização de Outubro de 2018 do Windows 10.

A proposta de valor de mover o SDK de Aplicações Windows é múltipla. Aqui estão algumas considerações:

• Plataforma de interface do usuário (UI) mais recente e controles como WinUI 3 e WebView2.
• Uma única superfície de API em todas as plataformas de aplicações desktop.
• Cadência de lançamento mais frequente que é lançada separadamente do Windows.
• Uma experiência consistente em todas as versões do Windows.
• Compatibilidade .NET.
• Compatível com versões anteriores até ao Windows 10, versão 1809.
• Ambiente de tempo de execução melhorado. Consulte contêiner MSIX.

Para mais informações, consulte SDK de Aplicações Windows.

Visão geral do processo de migração

Instalar o SDK de Aplicações Windows VSIX

Descarregue a versão mais recente SDK de Aplicações Windows de SDK de Aplicações Windows downloads, e execute a instalação.

Crie um novo project

Em Visual Studio, Cria o teu primeiro WinUI project. Por exemplo, use o modelo de projeto WinUI Blank App (Packaged ). Pode encontrar esse modelo de project no diálogo Criar um novo project escolhendo a linguagem: C# ou C++; plataforma: SDK de Aplicações Windows; project tipo: WinUI ou Desktop.

Verá dois projetos em Explorador de Soluções — um é qualificado como (Desktop), e o outro como (Pacote).

Migrar código com menos dependências primeiro

Para ilustrar esta recomendação, vamos tomar o estudo de caso PhotoLab como exemplo. Para a aplicação de exemplo PhotoLab, uma abordagem talvez óbvia seja começar por migrar MainPage— uma vez que é um componente tão importante e proeminente da aplicação. Mas se fizéssemos isso, rapidamente perceberíamos que PáginaPrincipal tem uma dependência na visão PáginaDeDetalhe; e depois que PáginaDeDetalhe tem uma dependência do modelo Foto. Se fôssemos seguir esse caminho, poderíamos estar constantemente nos interrompendo (mudando para trabalhar em cada dependência recém-descoberta). Certamente não esperaríamos obter uma compilação limpa até termos resolvido todas as dependências e, essencialmente, portado todo o projeto num salto gigante.

Se, por outro lado, começássemos pela parte do project que não depende de mais nada, e trabalhássemos a partir daí (da parte menos para a mais dependente), então conseguiríamos focar-nos em cada peça uma de cada vez. E também poderíamos obter um build limpo depois de migrarmos cada componente e, dessa forma, confirmar que o processo de migração está a correr como planeado.

Portanto, quando você estiver migrando seus próprios aplicativos, recomendamos que você migre o código com menos dependências primeiro.

Copiar ficheiros ou copiar conteúdo de ficheiros?

Ao migrar, você estará, é claro, copiando os arquivos de ativos (e não os conteúdos dos arquivos de ativos ). Mas e os arquivos de código-fonte? Como exemplo, vamos novamente pegar a classe MainPage do estudo de caso do PhotoLab e do estudo de caso do Photo Editor.

C#. Na versão C# (PhotoLab), MainPage é composta pelos arquivos de código-fonte MainPage.xaml e MainPage.xaml.cs.

C++/WinRT. Na versão C++/WinRT (Photo Editor), MainPage é composta pelos arquivos de código-fonte MainPage.xaml, MainPage.idl, MainPage.he MainPage.cpp.

Assim, pode escolher entre estas duas opções:

• (Recomendado) pode copiar os próprios ficheiros (usando Explorador de Ficheiros) e depois adicionar as cópias ao projeto de destino. Exceções a esta recomendação são ficheiros como App.xaml e App.xaml.cs, uma vez que esses ficheiros já existem na project de destino e contêm código-fonte específico do SDK de Aplicações Windows. Para esses, terá de mesclar o código-fonte que já está lá com o código-fonte do projeto.
• Ou pode usar o Visual Studio para criar novos ficheiros Page (como MainPage.xaml e MainPage.xaml.cs) no projeto alvo, e depois copiar os conteúdos desses ficheiros de código-fonte do projeto de origem para o projeto de destino. Para um project C++/WinRT, esta opção envolve muito mais passos.

Veja também a secção MainPage e MainWindow.

Diferenças de nome de pasta e arquivo (C++/WinRT)

Num projeto UWP C++/WinRT, os ficheiros de código subjacente para vistas XAML são nomeados no formato MainPage.h e MainPage.cpp. Mas numa SDK de Aplicações Windows C++/WinRT, terás de renomear esses nomes para MainPage.xaml.h e MainPage.xaml.cpp.

Num projeto UWP C++/WinRT, ao migrar uma vista XAML hipotética (no sentido de modelos, vistas e modelos de visualização) chamada MyPage, em MyPage.xaml.cpp terá de adicionar #include "MyPage.g.cpp" imediatamente após #include "DetailPage.xaml.h". E para um modelo hipotético chamado MyModel, em MyModel.cpp adicione #include "MyModel.g.cpp" imediatamente após #include "MyModel.h". Para obter um exemplo, consulte código-fonte de migração DetailPage.

Se mudares o nome do teu project migrado

Durante a migração, pode optar por dar ao seu project-alvo um nome diferente do do project de origem. Se o fizeres, isso afetará o namespace predefinido dentro do project de origem. Ao copiares o código-fonte do projeto-fonte para o projeto-alvo, poderás necessitar de alterar os nomes dos namespaces mencionados no código-fonte.

Alterar o nome do projeto (e, consequentemente, o nome do namespace por defeito) é algo que fazemos, por exemplo, no estudo de caso A migração da aplicação de exemplo UWP PhotoLab para o SDK de Aplicações Windows (C#). Nesse estudo de caso, em vez de copiar o ficheiro contents da fonte para o project alvo, copiamos ficheiros inteiros usando File Explorer. O nome do project/namespace de origem é PhotoLab, e o nome do project/namespace do alvo é PhotoLabWinUI3. Portanto, precisamos procurar por PhotoLab no conteúdo de todos os ficheiros de código-fonte que copiámos e alterá-lo para PhotoLabWinUI3.

Nesse estudo de caso específico, fizemos essas alterações em App.xaml, App.xaml.cs, MainPage.xaml, MainPage.xaml.cs, DetailPage.xaml, DetailPage.xaml.cs, ImageFileInfo.cse LoadedImageBrush.cs.

Instale os mesmos pacotes NuGet que foram instalados no projeto de origem

Uma tarefa durante o processo de migração é identificar quaisquer pacotes NuGet dos quais o project fonte tenha dependências. Depois, instale esses mesmos pacotes NuGet no projeto alvo.

Por exemplo, no estudo de caso uma migração do SDK de Aplicações Windows da aplicação de exemplo UWP PhotoLab (C#), o projeto de origem contém referências ao pacote NuGet Microsoft.Graphics.Win2D. Nesse estudo de caso, adicionamos uma referência ao mesmo pacote NuGet ao projeto alvo.

Tópicos relacionados

• SDK de Aplicações Windows e versões suportadas para Windows
• APIs Windows Runtime (WinRT)
• WinUI
• Estudo de caso do PhotoLab
• Estudo de caso do Photo Editor
• Suporte para APIs WinRT em aplicações de ambiente de trabalho