Estratégia global de migração

Introdução

O Windows App SDK 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 Universal Windows Platform (UWP), pode tirar grande partido das suas competências existentes e do seu código-fonte, movendo a sua aplicação para o Windows App SDK.

Com o Windows App SDK 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 Windows App SDK 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 Windows App SDK.

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 Windows App SDK, 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 Windows App SDK?

A Windows App SDK 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 Windows App SDK é 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 Windows App SDK é 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 Windows App SDK.

Visão geral do processo de migração

Instalar o Windows App SDK VSIX

Descarregue a versão mais recente Windows App SDK de Windows App SDK 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: Windows App SDK; project tipo: WinUI ou Desktop.

Verá dois projetos em Solution Explorer — 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 Windows App SDK. 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 Windows App SDK 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 Windows App SDK (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 Windows App SDK 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

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