Estratégia de migração geral

Introdução

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

Com o SDK do Aplicativo Windows você pode incorporar os recursos de runtime, idioma e plataforma mais recentes em 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 funcionalidades 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 Windows Runtime (WinRT) pode ser usada por aplicativos SDK do Aplicativo 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 em WinUI ou por meio de interfaces COM do WinRT disponíveis no SDK do Aplicativo 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.

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 obter perguntas e comentários sobre o SDK do Aplicativo Windows ou apenas para iniciar uma discussão, use o botão Esso produto. Você também pode iniciar uma discussão sobre a guia Discussions 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 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 do Aplicativo Windows?

O SDK do Aplicativo Windows oferece uma oportunidade de aprimorar seu aplicativo com novos recursos de plataforma, bem como com a biblioteca moderna A biblioteca da interface do usuário (WinUI), que é desenvolvida e projetada para encantar seus usuários.

Além disso, o SDK do Aplicativo Windows é compatível com versões anteriores; ele dá suporte a aplicativos até Windows 10, versão 1809 (10.0; Build 17763)— também conhecido como atualização de outubro de 2018 Windows 10.

A proposta de valor de mover o SDK do Aplicativo Windows é múltipla. 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 plataformas de aplicativos da área de trabalho.
• Cadência de lançamento mais frequente que lança separadamente do Windows.
• Uma experiência consistente nas versões do Windows.
• .NET compatibilidade.
• Compatível com versões anteriores até Windows 10, versão 1809.
• Ambiente de runtime aprimorado. Consulte Contêiner MSIX.

Para obter mais informações, consulte SDK do Aplicativo Windows.

Visão geral do processo de migração

Instalar o SDK do Aplicativo Windows VSIX

Baixe a versão mais recente do SDK do Aplicativo Windows de SDK do Aplicativo Windows downloads e execute para instalá-la.

Criar um novo project

Em Visual Studio, Crie seu primeiro projeto WinUI. Por exemplo, use o modelo de projeto WinUI Blank App (Empacotado). Você pode encontrar esse modelo de projeto na Janela de criar novo projeto escolhendo o idioma: C# ou C++; plataforma: SDK do Aplicativo Windows; tipo de projeto: WinUI ou Desktop.

Você verá dois projetos em Gerenciador de Soluções — um é 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 se fizéssemos isso, logo perceberíamos que MainPage tem uma dependência da exibição DetailPage, e perceberíamos também 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 esperaríamos obter um build limpo até que tivéssemos resolvido todas as dependências e, essencialmente, portado todo o projeto em um salto gigante.

Se, por outro lado, começarmos com a parte do projeto que não depende de mais nada, e trabalharmos a partir daí para fora (da parte menos para a mais dependente), então seríamos capazes de nos concentrar em cada peça individualmente. 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?

Ao migrar, você, naturalmente, copiará os arquivos de ativos (e não os 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 Explorador de Arquivos) e, em seguida, adicionar as cópias ao projeto de destino. Exceções a essa recomendação são arquivos como App.xaml e App.xaml.cs, já que esses arquivos já existem no project de destino e contêm código-fonte específico ao SDK do Aplicativo Windows. Para isso, 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 então copiar o conteúdo desses arquivos de código-fonte do projeto de origem para o projeto de destino. Para um project 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 do C++/WinRT, arquivos no code-behind para exibições XAML são nomeados no formato MainPage.h e MainPage.cpp. Mas em um SDK do Aplicativo Windows C++/WinRT, você precisará renomeá-los para MainPage.xaml.h e MainPage.xaml.cpp.

Em um projeto UWP do C++/WinRT, ao migrar uma visão XAML hipotética (no sentido de models, views e viewmodels) denominada MyPage, em 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 que foi migrado

Durante a migração, você pode optar por dar ao seu projeto de destino um nome diferente do do projeto de origem. Se você fizer isso, isso afetará o namespace padrão no project de origem. À medida que você copia o código-fonte do project de origem para o project 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 realizamos, por exemplo, no estudo de caso uma migração do SDK do Aplicativo Windows do aplicativo de exemplo PhotoLab UWP (C#). Nesse estudo de caso, em vez de copiar o arquivo contents da origem para o project de destino, copiamos arquivos inteiros usando File Explorer. O nome do project/namespace de origem é PhotoLab e o nome do project/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 instalados no project de origem

Uma tarefa durante o processo de migração é identificar todos os pacotes NuGet nos quais o project de origem tem dependências. Em seguida, instale esses mesmos pacotes NuGet no projeto de destino.

Por exemplo, no estudo de caso Uma migração do SDK do Aplicativo Windows do aplicativo de exemplo UWP PhotoLab (C#), o projeto de origem contém referências ao pacote NuGet Microsoft.Graphics.Win2D. Portanto, nesse estudo de caso, adicionamos uma referência ao mesmo pacote NuGet ao projeto de destino.

Tópicos relacionados

• SDK do Aplicativo Windows e versões do Windows com suporte
• APIs Windows Runtime (WinRT)
• WinUI
• Estudo de caso do PhotoLab
• Estudo de caso do Photo Editor
• Suporte para APIs do WinRT em aplicativos da área de trabalho