Migração de projeto UWP do Xamarin.Forms

  • Artigo

Para atualizar seu projeto UWP Xamarin.Forms para um projeto WinUI 3, você deve:

  • Atualize seu arquivo de projeto para ser no estilo SDK.
  • Atualizar namespaces
  • Resolva quaisquer alterações na API
  • Atualize ou substitua dependências incompatíveis com versões do .NET 8.
  • Compile e teste seu aplicativo.

Atualizar para um arquivo de projeto no estilo SDK

Seu projeto UWP Xamarin.Forms existente pode ser atualizado para um projeto WinUI 3 no estilo SDK. Um projeto de estilo SDK para um aplicativo .NET MAUI WinUI 3 é semelhante ao exemplo a seguir:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType> <!-- in Xamarin.Forms this was AppContainerExe -->
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
    <RootNamespace>YOUR_NAMESPACE_HERE.WinUI</RootNamespace>
    <ApplicationManifest>app.manifest</ApplicationManifest>
    <Platforms>x86;x64;ARM64</Platforms>
    <RuntimeIdentifiers>win10-x86;win10-x64;win10-arm64</RuntimeIdentifiers>
    <UseWinUI>true</UseWinUI>
    <EnableMsixTooling>true</EnableMsixTooling>
    <UseMaui>true</UseMaui>
    <!-- We do not want XAML files to be processed as .NET MAUI XAML -->
    <EnableDefaultMauiItems>false</EnableDefaultMauiItems>
  </PropertyGroup>
  ...
</Project>

Importante

O moniker da estrutura de destino (TFM) é o que denota o projeto como usando .NET, neste caso .NET 8. Para obter informações sobre estruturas de destino em projetos de estilo SDK, consulte Estruturas de destino em projetos de estilo SDK.

Você deve adicionar <UseMaui>true</UseMaui> ao arquivo de projeto para habilitar o suporte ao .NET MAUI. Além disso, verifique se você adicionou <EnableDefaultMauiItems>false</EnableDefaultMauiItems> ao arquivo de projeto. Isso impedirá que você receba erros de compilação sobre o InitializeComponent método que já está sendo definido.

Alterações nas propriedades do MSBuild

Ao atualizar seu projeto, é recomendável remover as seguintes propriedades UWP MSBuild do arquivo de projeto:

  • WindowsXamlEnableOverview
  • AppxPackageSigningEnabled
  • GenerateAssemblyInfo

Você também precisará garantir que as arquiteturas de plataforma no projeto de destino sejam especificadas com os seguintes identificadores de tempo de execução do .NET:

<PropertyGroup>
   <!-- Used in .NET MAUI WinUI projects -->
   <Platforms>x86;x64;ARM64</Platforms>
</PropertyGroup>

Para obter mais informações sobre identificadores de tempo de execução, consulte Catálogo de RID do .NET.

Alterações de namespace

Há diferenças nos nomes de namespaces entre UWP e WinUI 3. Em muitos casos, é tão fácil quanto alterar um nome de namespace e, em seguida, seu código será compilado. Por exemplo, você precisará substituir o Windows.UI.Xaml namespace pelo Microsoft.UI.Xaml namespace. Da mesma forma, você precisará substituir o Windows.UI.Xaml.Controls namespace pelo Microsoft.UI.Xaml.Controls namespace.

Outras vezes, o mapeamento dá um pouco mais de trabalho e, em casos raros, requer uma mudança de abordagem. Para obter mais informações, consulte Mapeando APIs e bibliotecas UWP para o SDK de Aplicativos Windows.

Alterações de API

Você precisará resolver quaisquer alterações na API que possam afetar seu aplicativo. Por exemplo, alguns tipos, métodos e propriedades podem ter sido renomeados, preteridos ou removidos. Para obter informações sobre o que é suportado ao atualizar seu projeto UWP para WinUI 3, consulte O que é suportado ao migrar da UWP para WinUI 3. Para obter informações sobre como mapear recursos e APIs UWP para WinUI 3, consulte Mapeando recursos UWP para o SDK de Aplicativos Windows e Mapeando APIs e bibliotecas UWP para o SDK de Aplicativos Windows.

Seu projeto pode ser compatível com versões anteriores do sistema operacional definindo a propriedade no arquivo de $(SupportedOSPlatformVersion) projeto:

<PropertyGroup>
   <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">10.0.19041.0</SupportedOSPlatformVersion>
</PropertyGroup>

A propriedade $(SupportedOSPlatformVersion) indica a versão mínima do sistema operacional necessária para executar seu aplicativo ou biblioteca. Se você não especificar explicitamente essa versão mínima do sistema operacional de tempo de execução em seu projeto, ela assumirá como padrão a versão da plataforma a partir do Target Framework Moniker (TFM).

Se o seu projeto tiver como alvo apenas o Windows, será suficiente omitir a condição de verificação da plataforma e definir a $(SupportedOSPlatformVersion) propriedade diretamente:

<PropertyGroup>
   <SupportedOSPlatformVersion>10.0.19041.0</SupportedOSPlatformVersion>
</PropertyGroup>

Para obter mais informações sobre a propriedade, consulte Suporte a versões mais antigas do $(SupportedOSPlatformVersion) sistema operacional.

Para que um aplicativo seja executado corretamente em uma versão mais antiga do sistema operacional, ele não pode chamar APIs que não existem nessa versão do sistema operacional. No entanto, você pode adicionar proteções em torno de chamadas a APIs mais recentes para que elas sejam chamadas somente ao executar em uma versão do sistema operacional que dê suporte a elas. Isto pode ser conseguido com o IsWindowsVersionAtLeast método:

if (OperatingSystem.IsWindowsVersionAtLeast(10))
{
    // Use the API here
}

Remover arquivos

Os seguintes arquivos, que estão presentes em projetos UWP Xamarin.Forms, não existem em projetos WinUI 3:

  • MainPage.xaml e MainPage.xaml.cs
  • AssemblyInfo.cs
  • Padrão.rd.xml

Portanto, você deve remover esses arquivos se eles estiverem em seu projeto WinUI 3. Qualquer lógica de negócios necessária contida nesses arquivos deve ser movida para outro lugar.

Alterações em Package.appxmanifest

As seguintes alterações devem ser feitas no arquivo Package.appxmanifest do projeto migrado:

  1. Defina o ponto de entrada do aplicativo como $targetentrypoint$. Para obter mais informações, consulte Ponto de entrada de destino.
  2. Adicione o runFullTrust recurso. Para obter mais informações, consulte Executar recurso de confiança total.
  3. Adicione as famílias de dispositivos e de Windows.UniversalWindows.Desktop destino. Para obter mais informações, consulte Família de dispositivos de destino universal e Família de dispositivos de destino da área de trabalho.

Fazer essas alterações corrige erros comuns de implantação para seu aplicativo no Windows.

Para obter um exemplo de um arquivo Package.appxmanifest compatível, consulte Package.appxmanifest.

Comportamento de tempo de execução

Há alterações comportamentais no String.IndexOf() método no .NET 5+ em diferentes plataformas. Para mais informações, confira Globalização do .NET e ICU.

Próximas etapas

Inicializar seu aplicativo

Confira também