Migrar da UWP para o SDK de Aplicativos do Windows com o Assistente de Atualização do .NET

  • Artigo

O Assistente de Atualização do .NET (confira Visão geral do Assistente de Atualização do .NET) é uma extensão do Visual Studio (recomendada) e uma ferramenta de linha de comando, que pode ajudar na migração de um aplicativo da Plataforma Universal do Windows (UWP) em C# para um aplicativo da Biblioteca de Interface do Usuário do Windows (WinUI) 3 que usa o SDK de Aplicativo do Windows.

Nosso roteiro para suporte à UWP no Assistente de Atualização do .NET inclui melhorias de ferramentas adicionais e adição de suporte à migração para novos recursos. Se você encontrar problemas relacionados ao Assistente de Atualização do .NET, poderá registrá-los no Visual Studio selecionando Ajuda>Enviar comentários>Relatar um problema.

Confira também o repositório GitHub do Assistente de atualização. As opções para executar a ferramenta na linha de comando estão documentadas lá.

Instalar o Assistente de Atualização do .NET

Você pode instalar o Assistente de Atualização do .NET como uma extensão do Visual Studio ou como uma ferramenta de linha de comando do .NET. Para obter mais informações, confira Instalar o Assistente de Atualização do .NET.

Resumo

Quando você usa o Assistente de Atualização do .NET para migrar seu aplicativo da UWP, aqui estão as etapas e estágios de alto nível no processo de migração que a ferramenta executa.

  • Opcionalmente, copia seu projeto e migra a cópia; deixando seu projeto original inalterado.
  • Opcionalmente, migra o projeto no local (nas mesmas pastas e arquivos, sem renomear pastas); e não faz uma cópia.
  • Atualiza seu projeto do formato de projeto do .NET Framework para o formato de projeto mais recente do SDK do .NET.
  • Limpa as referências do pacote NuGet. Além dos pacotes referenciados pelo aplicativo, o arquivo packages.config contém referências às dependências desses pacotes. Por exemplo, se você adicionou referência ao pacote A, que depende do pacote B, ambos os pacotes serão referenciados no arquivo packages.config. No novo sistema de projeto, apenas a referência ao pacote A é necessária. Portanto, esta etapa analisa as referências do pacote e remove aquelas que não são necessárias. O aplicativo ainda está fazendo referência a assemblies do .NET Framework. Alguns desses assemblies podem estar disponíveis como pacotes NuGet. Portanto, esta etapa analisa esses assemblies e faz referência ao pacote NuGet apropriado.
  • Direciona o .NET 6 e o SDK de Aplicativo do Windows.
  • Altera o moniker da estrutura de destino (TFM) (confira estruturas de destino em projetos no estilo SDK) do .NET Framework para o SDK sugerido. Por exemplo, net6.0-windows.
  • Migra o código-fonte da UWP do WinUI 2 para o WinUI 3, executando alterações de código específicas da origem.
  • Adiciona/atualiza qualquer modelo, configuração e arquivos de código. Por exemplo, adicionando perfis de publicação necessários, App.xaml.cs, MainWindow.xaml.cs, MainWindow.xaml e outros.
  • Atualize namespaces e adicione a navegação MainPage.
  • Tenta detectar e corrigir APIs diferentes entre o UWP e o SDK de Aplicativos do Windows e usa tarefas de Lista de Tarefas para marcar APIs que não têm mais suporte.

À medida que é executada, a ferramenta também visa fornecer diretrizes de migração na forma de mensagens de aviso na saída da ferramenta e tarefas de Lista de Tarefas na forma de comentários no código-fonte do projeto (por exemplo, para casos em que a migração completamente automatizada do código-fonte da UWP não é possível). Uma tarefa de Lista de Tarefas típica inclui um link para um tópico nesta documentação de migração. Como desenvolvedor, você está sempre no controle do processo de migração.

Dica

Para ver todas as tarefas geradas pela ferramenta, examine a Lista de Tarefas no Visual Studio.

Observação

Depois que a ferramenta terminar de ser executada, há algumas etapas de acompanhamento que você pode optar por realizar se necessário. Você pode mover seu código de App.xaml.old.cs para App.xaml.cs; e você pode restaurar AssemblyInfo.cs do backup que a ferramenta cria.

Ao que a ferramenta dá suporte

Esta versão do Assistente de Atualização do .NET está atualmente em versão prévia e está recebendo atualizações frequentes. Atualmente, a ferramenta dá suporte apenas à linguagem de programação C#; não C++. E, na maioria dos casos com esta versão, seu projeto exigirá esforço adicional de você para concluir a migração.

A ferramenta visa migrar seu projeto e código para que ele seja compilado. Mas alguns recursos exigem que você os investigue e corrija (por meio de tarefas de Lista de Tarefas). Para obter mais informações sobre o que considerar antes de migrar, confira O que é compatível ao migrar da UWP para o WinUI 3.

Devido às seguintes limitações da versão atual do Assistente de Atualização do .NET, você pode optar por aguardar uma versão futura antes de migrar seu aplicativo:

  • Não há suporte para a migração de APIs ApplicationView.
  • Não há suporte para a migração de APIs relacionadas a AppWindow.

Sempre que possível, a ferramenta tenta gerar um aviso; e isso intencionalmente faz com que seu código não seja compilado até que você o altere.

  • Não há suporte para exibições personalizadas. Por exemplo, você não receberá um aviso ou uma correção para uma caixa de diálogo personalizada que estende MessageDialog e chama uma API incorretamente.
  • Não há suporte para componentes do Windows Runtime.
  • Aplicativos de várias janelas podem não ser migrados corretamente.
  • Um projeto que segue uma estrutura de arquivos não padrão (como tendo App.xaml e App.xaml.cs fora na pasta raiz) pode não ser migrado corretamente.

O repositório do GitHub do Assistente de Atualização documenta dicas de solução de problemas e problemas conhecidos. Se você encontrar problemas ao usar a ferramenta, denuncie-os nesse mesmo repositório do GitHub, marcando-os com uma marca de área de UWP. Agradecemos!

Observação

Para obter diretrizes sobre o processo de migração e as diferenças entre os recursos e APIs do SDK de Aplicativo do Windows e UWP, confira Migrar da UWP para o SDK de Aplicativo do Windows.

Dica

É possível conferir qual versão da ferramenta você tem emitindo o comando upgrade-assistant --version.

Test-drive da ferramenta com o exemplo PhotoLab da UWP

Vamos usar o Assistente de Atualização do .NET para um test-drive.

Como material de origem, migraremos o aplicativo de exemplo do PhotoLab UWP. O PhotoLab é um aplicativo de exemplo para exibir e editar arquivos de imagem. Ele demonstra o layout XAML, a associação de dados e os recursos de personalização da interface do usuário.

Observação

Você pode ver um estudo de caso da amostra do PhotoLab sendo migrada manualmente em uma migração do SDK de Aplicativo do Windows do aplicativo de exemplo PhotoLab da UWP.

  1. Comece clonando ou baixando o código-fonte de exemplo do PhotoLab no link acima.

Dica

Lembre-se de que, depois de usarmos a ferramenta para automatizar a migração do aplicativo, serão necessários esforços manuais adicionais para concluir a migração.

  1. Abra a solução PhotoLab no Visual Studio.

  2. Depois de instalar a extensão do Assistente de Atualização do .NET (confira Instalar o Assistente de Atualização do .NET anteriormente neste tópico), clique com o botão direito do mouse no projeto no Gerenciador de Soluções e clique em Atualizar.

  3. Escolha a opção Atualizar o projeto de atualização para uma versão mais recente do .NET.

  4. Escolha a opção de atualização de projeto in-loco.

  5. Escolha uma estrutura de destino.

  6. Clique em Atualizar seleção.

  7. O Assistente de Atualização do .NET é executado e usa a janela Saída do Visual Studio para imprimir informações e status durante a execução.

Você pode monitorar a barra de progresso até que a operação de atualização seja concluída.

A migração de código para o aplicativo de exemplo PhotoLab inclui:

  • Alterações na Caixa de Diálogo de Conteúdo e APIs do seletor de Salvamento de Arquivos.
  • Atualização XAML para o pacote Animações.
  • Mostrar mensagens de aviso e adicionar tarefas de Lista de Tarefas em DetailPage.xaml, DetailPage.xaml.cs e MainPage.xaml.cs para o botão voltar personalizado.
  • Implementar a funcionalidade do botão Voltar e adicionar uma tarefa de Lista de Tarefas para personalizar o botão XAML.
  • Um link para a documentação é fornecido que você pode usar para saber mais sobre a implementação do botão Voltar.

Os números de versão em seu .csproj resultante serão ligeiramente diferentes, mas, essencialmente, ele terá esta aparência (com alguns dos grupos de propriedades de configuração de build removidos para brevidade):

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
    <Platform Condition=" '$(Platform)' == '' ">x86</Platform>
    <OutputType>WinExe</OutputType>
    <DefaultLanguage>en-US</DefaultLanguage>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
    <RuntimeIdentifiers>win10-x86;win10-x64;win10-arm64</RuntimeIdentifiers>
    <UseWinUI>true</UseWinUI>
    <ApplicationManifest>app.manifest</ApplicationManifest>
    <EnableMsixTooling>true</EnableMsixTooling>
    <Platforms>x86;x64;arm64</Platforms>
    <PublishProfile>win10-$(Platform).pubxml</PublishProfile>
  </PropertyGroup>
  <ItemGroup>
    <AppxManifest Include="Package.appxmanifest">
      <SubType>Designer</SubType>
    </AppxManifest>
  </ItemGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.1.0" />
    <PackageReference Include="Microsoft.Graphics.Win2D" Version="1.0.0.30" />
    <PackageReference Include="Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers" Version="0.4.346201">
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.Windows.Compatibility" Version="6.0.0" />
    <PackageReference Include="CommunityToolkit.WinUI.UI.Animations" Version="7.1.2" />
  </ItemGroup>
  <ItemGroup>
    <Compile Remove="App.xaml.old.cs" />
  </ItemGroup>
  <ItemGroup>
    <None Include="App.xaml.old.cs" />
  </ItemGroup>
</Project>

Como você pode ver, o projeto agora está referenciando o SDK de Aplicativo do Windows, o WinUI 3 e o .NET 6. Agora que o PhotoLab foi migrado, você pode aproveitar todos os novos recursos que os aplicativos do WinUI 3 têm a oferecer e aumentar seu aplicativo com a plataforma.

Além disso, o Assistente de Atualização do .NET adiciona analisadores ao projeto que ajudam a continuar com o processo de atualização. Por exemplo, o pacote NuGet Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers.

Acompanhamento da migração manual

Neste ponto, você pode abrir a solução ou o projeto do PhotoLabmigrado e ver as alterações que foram feitas no código-fonte. O projeto precisa de um pouco mais de trabalho para concluir a conexão antes que a versão do WinUI 3 crie, execute e se comporte como a versão UWP.

Confira a Lista de Tarefas no Visual Studio (Exibir>Lista de Tarefas) para tarefas que você deve realizar para concluir manualmente a migração.

É possível que a versão da UWP (.NET Framework) do seu aplicativo contenha referências de biblioteca que seu projeto não está realmente usando. Você precisará analisar cada referência e determinar se ela é necessária ou não. A ferramenta também pode ter adicionado ou atualizado uma referência de pacote NuGet à versão errada.

O Assistente de Atualização não edita o Package.appxmanifest, que precisará de algumas edições para que o aplicativo seja iniciado:

  1. Adicione esse namespace no elemento <Package> raiz:
xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"

  1. Editar o elemento <Application> de EntryPoint="appnamehere.App" para EntryPoint="$targetentrypoint$"

  2. Substitua qualquer Capability especificado pelo seguinte:

<rescap:Capability Name="runFullTrust" />

No arquivo .csproj, talvez seja necessário editar o arquivo de projeto para definir <OutputType>WinExe</OutputType> e <UseMaui>False</UseMaui>.

Para usar muitos dos controles XAML, certifique-se de que o arquivo app.xaml inclua o <XamlControlsResources>, como neste exemplo:

<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
            <!-- Other merged dictionaries here -->
        </ResourceDictionary.MergedDictionaries>
        <!-- Other app resources here -->
    </ResourceDictionary>
</Application.Resources>

Dicas de solução de problemas

Há vários problemas conhecidos que podem ocorrer ao usar o Assistente de Atualização do .NET. Em alguns casos, esses são problemas com a ferramenta try-convert que o Assistente de Atualização do .NET usa internamente.

Mas para obter mais dicas de solução de problemas e problemas conhecidos, confira o repositório GitHub do Assistente de Atualização.