Estratégia de migração geral

  • Artigo

Introdução

O SDK de Aplicativo do Windows fornece um amplo conjunto de APIs do Windows com implementações que são separadas do sistema operacional e liberadas para desenvolvedores por meio de pacotes NuGet. Como desenvolvedor com um aplicativo da Plataforma Universal do Windows (UWP), você pode fazer ótimo uso do conjunto de habilidades e do código-fonte transferindo seu app para o SDK de Aplicativos do Windows.

Com o SDK de Aplicativos do Windows, você pode incorporar os mais atuais recursos de runtime, linguagem e plataforma ao seu aplicativo. 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 aplicativo. Mas a abordagem de alto nível e as alterações de código necessárias para várias áreas de recursos são semelhantes. Portanto, neste tópico, analisaremos as estratégias sobre como você pode abordar a migração de seu aplicativo e traremos informações (e limitações) sobre determinadas áreas de recursos. Portanto, consulte O que é suportado ao fazer a portabilidade da UWP para o WinUI 3.

A maioria das APIs do Windows Runtime (WinRT) pode ser usada por aplicativos com SDK de Aplicativos do Windows. Mas há alguns que não são suportados em aplicativos de desktop ou que têm restrições.

  • APIs que têm dependências em recursos de interface do usuário que foram projetados somente para uso em aplicativos UWP.
  • APIs que exigem o identificador de pacote. Essas APIs só têm suporte em aplicativos para desktop que são organizados em pacote usando o MSIX.

Para essas APIs, mostraremos quais alternativas usar. A maioria dessas alternativas está disponível no WinUI 3 ou por meio de interfaces COM do WinRT que estão disponíveis no SDK de Aplicativo do Windows.

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

Observação

Você também pode consultar APIs do Windows Runtime não são compatíveis com aplicativos de desktop. Os aplicativos do SDK de Aplicativos do Windows são um tipo de aplicativo de desktop. Outros tipos de aplicativo de desktop incluem .NET e Win32 C/C++. O público desse tópico são os desenvolvedores que desejam migrar para algo relacionado à união desses diferentes tipos de aplicativo de desktop, incluindo, entre outras coisas, aplicativos do SDK de Aplicativos do Windows.

Envie-nos seus comentários sobre este guia de migração e sua experiência de migração. Use a seção Feedback no fim desta página da seguinte maneira:

  • Para perguntas e feedbacks sobre o SDK de Aplicativos do Windows, ou apenas para começar uma conversa, use o botão Este produto. Você também pode iniciar uma discussão na guia Discussões do repositório GitHub do WindowsAppSDK. 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 enviar comentários sobre informações ausentes ou incorretas neste guia de migração, use o botão Esta página.

Por que migrar para o SDK de Aplicativos do Windows?

O SDK de Aplicativos do Windows oferece a oportunidade de aprimorar aplicativos com novos recursos de plataforma, bem como com a moderna Windows UI 3 Library (WinUI 3),, que foi desenvolvida e projetada para encantar seus usuários.

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

Há muita coisa útil em passar a usar o SDK de Aplicativos do Windows. Estas são algumas considerações:

  • Plataforma e controles de interface do usuário (UI) mais recentes, como WinUI 3 e WebView2.
  • Uma única superfície de API em todas as plataformas de aplicativo de desktop.
  • Cadência de lançamento mais frequente que lança separadamente do Windows.
  • Uma experiência consistente nas versões do Windows.
  • Compatibilidade para .NET.
  • Compatível com versões anteriores do Windows 10, versão 1809.
  • Ambiente de runtime aprimorado. Consulte Contêiner MSIX.

Para mais informações, confira SDK de Aplicativo do Windows.

Visão geral do processo de migração

Observação

Pense na versão UWP do aplicativo que você deseja migrar como a solução ou projeto de origem (é a origem do processo de migração). A versão do SDK de Aplicativos do Windows é a solução de destino (é o destino do processo de migração).

Instalar o VSIX do SDK de Aplicativos do Windows

Baixe e execute o instalador da extensão do Windows App SDK do Visual Studio (VSIX) do canal de versão estável para o SDK de Aplicativos do Windows.

Crie um novo projeto

No Visual Studio, crie seu primeiro projeto WinUI 3. Por exemplo, use o modelo de projeto Aplicativo em branco e em pacote (WinUI 3 do desktop). Esse modelo de projeto está na caixa de diálogo Criar um novo projeto. É só escolher a linguagem C# ou C++, a plataforma Windows App SDK e o tipo de projeto WinUI ou Desktop.

Você verá dois projetos no Solution Explorer: é qualificado como (Desktop) e o outro como (Package).

Migrar o código com o mínimo de dependências primeiro

Para ilustrar essa recomendação, vamos usar o estudo de caso do PhotoLab como exemplo. Para o aplicativo de exemplo PhotoLab, uma abordagem talvez óbvia pode ser começar migrando MainPage, já que essa é uma parte tão importante e proeminente do aplicativo. Mas logo perceberíamos que MainPage tem uma dependência de DetailPage e que DetailPage tem uma dependência do modelo Photo. Se este fosse o caminho, talvez teríamos que enfrentar interrupções constantemente, tendo que passar a trabalhar em cada dependência recentemente descoberta. Certamente não chegaríamos a uma versão limpa até que tivéssemos perseguido todas as dependências e, essencialmente, feito a portabilidade de todo o projeto em um esforço gigante.

Se, por outro lado, começássemos com a parte do projeto que não depende de mais nada, ou seja, prosseguindo em direção às peças com maior dependência, então poderíamos nos concentrar em cada peça uma de cada vez. E também poderíamos chegar a uma versão limpa após a migração de cada peça e, dessa forma, confirmar que o processo de migração está no caminho certo.

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

Copiar arquivos ou copiar conteúdo de arquivos?

Na hora de fazer a migração, é claro que você copiará arquivos e não conteúdos de arquivos. Mas e os arquivos de código-fonte? Como exemplo, vamos novamente usar a classe MainPage do estudo de caso do Photolab e do estudo de caso do Photo Editor.

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

C++/WinRT. Na versão C++/WinRT (Photo Editor), MainPage é composto pelos arquivos de código-fonteMainPage.xaml, MainPage.idl, MainPage.h e MainPage.cpp.

Dessa maneira, você pode escolher entre essas duas opções:

  • (Recomendado) Você pode copiar os próprios arquivos (usando o File Explorer) e, em seguida, adicionar as cópias ao projeto de destino. As exceções a essa recomendação são arquivos como App.xaml e App.xaml.cs, uma vez que já existem no projeto de destino e contêm código-fonte específico do SDK de Aplicativos do Windows. Para esses arquivos, você precisará mesclar o código-fonte que já está lá com o código-fonte do projeto de origem.
  • Ou você pode usar o Visual Studio para criar novos arquivos Page (como MainPage.xaml e MainPage.xaml.cs) no projeto de destino e, em seguida, copiar o conteúdo desses arquivos de código-fonte do projeto de origem para o projeto de destino. Para um projeto C++/WinRT, essa opção envolve muito mais etapas.

Consulte também a seção MainPage e MainWindow.

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

Em um projeto UWP C++/WinRT, os arquivos code-behind para modos de exibição XAML têm o nome do formulário MainPage.h e MainPage.cpp. Mas em um SDK de Aplicativo do Windows C++/WinRT, você precisará renomeá-los para MainPage.xaml.h e MainPage.xaml.cpp.

Em um projeto UWP C++/WinRT, ao migrar um modo de exibição XAML hipotético (no sentido de modelos, modos de exibição e modelos de exibição) chamado MyPage, MyPage.xaml.cpp você precisará adicionar #include "MyPage.g.cpp" imediatamente após #include "DetailPage.xaml.h". Para um modelo hipotético chamado MyModel, em MyModel.cpp adicione #include "MyModel.g.cpp" imediatamente após #include "MyModel.h". Para ver um exemplo, consulte Migrar o código-fonte do DetailPage.

Se você alterar o nome do projeto migrado

Durante a migração, você pode dar ao projeto de destino um nome diferente do projeto de origem. Isso afetará o namespace padrão no projeto de origem. À medida que você copia o código-fonte do projeto de origem para o projeto de destino, talvez seja necessário alterar os nomes de namespace mencionados no código-fonte.

Alterar o nome do projeto (e, consequentemente, o nome do namespace padrão) é algo que fazemos, por exemplo, no estudo de caso Uma migração do SDK de Aplicativos do Windows do app de exemplo UWP PhotoLab (C#). Nesse estudo de caso, em vez de copiar o conteúdo do arquivo do projeto de origem para o de destino, copiamos arquivos inteiros usando o File Explorer. O nome do projeto/namespace de origem é PhotoLab, e o nome do projeto/namespace de destino é PhotoLabWinUI3. Precisamos procurar PhotoLab no conteúdo de todos os arquivos de código-fonte que copiamos e mudar 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.cs e 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 projeto de origem tenha dependências. Em seguida, é preciso instalar esses mesmos pacotes NuGet no projeto de destino.

Por exemplo, no estudo de caso Uma migração do SDK de Aplicativos do Windows do aplicativo 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 de destino.