Atualizar manualmente um aplicativo Xamarin.Forms para um aplicativo .NET MAUI de vários projetos

A atualização de um aplicativo Xamarin.Forms de vários projetos para um aplicativo .NET Multi-platform App UI (.NET MAUI) de vários projetos segue as mesmas etapas de um projeto Xamarin.Android e Xamarin.iOS, com etapas adicionais para aproveitar as alterações no .NET MAUI.

Este artigo descreve como migrar manualmente um projeto de biblioteca Xamarin.Forms para um projeto de biblioteca do .NET MAUI. Antes de fazer isso, você deve atualizar seus projetos de plataforma Xamarin.Forms para que sejam projetos no estilo SDK. Os projetos no estilo SDK são o mesmo formato de projeto usado por todas as cargas de trabalho do .NET e, em comparação com muitos projetos do Xamarin, são muito menos detalhados. Para obter informações sobre como atualizar seus projetos de aplicativos, consulte Atualizar projetos Xamarin.Android, Xamarin.iOS e Xamarin.Mac para .NET, Migração de projetos Xamarin.Android, Migração de projetos Xamarin Apple e Xamarin.Forms migração de projetos UWP.

Para migrar um projeto de biblioteca Xamarin.Forms para um projeto de biblioteca do .NET MAUI, você deve:

• Atualizar seu aplicativo Xamarin.Forms para usar Xamarin.Forms 5.
• Atualizar as dependências do aplicativo para as versões mais recentes.
• Garantir que o aplicativo ainda funcione.
• Atualizar seu arquivo de projeto para o estilo SDK.
• Atualizar os namespaces.
• Abordar todas as alterações de API.
• Configurar o .NET MAUI.
• Atualizar ou substituir dependências incompatíveis por versões do .NET 8.
• Compilar e testar seu aplicativo.

Para simplificar o processo de atualização, você deve criar um novo projeto de biblioteca do .NET MAUI com o mesmo nome do seu projeto de biblioteca Xamarin.Forms e, em seguida, copiar em seu código, configuração e recursos. Essa é a abordagem descrita abaixo.

Atualizar seu aplicativo Xamarin.Forms

Antes de atualizar o aplicativo Xamarin.Forms para o .NET MAUI, você deve primeiro atualizar o aplicativo Xamarin.Forms para usar o Xamarin.Forms 5 e garantir que ele ainda seja executado corretamente. Além disso, você deve atualizar as dependências que seu aplicativo usa para as versões mais recentes.

Isso ajudará a simplificar o restante do processo de migração, pois minimizará as diferenças de API entre Xamarin.Forms e o .NET MAUI e garantirá que você esteja usando versões compatíveis com .NET de suas dependências, caso existam.

Crie um novo projeto

No Visual Studio, crie um projeto de biblioteca de classes .NET MAUI com o mesmo nome do projeto de biblioteca Xamarin.Forms. Esse projeto hospedará o código do seu projeto de biblioteca Xamarin.Forms. A abertura do arquivo de projeto confirmará que você tem um projeto no estilo do SDK do .NET:

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <TargetFrameworks>net8.0;net8.0-android;net8.0-ios;net8.0-maccatalyst</TargetFrameworks>
        <TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">$(TargetFrameworks);net8.0-windows10.0.19041.0</TargetFrameworks>
        <!-- Uncomment to also build the tizen app. You will need to install tizen by following this: https://github.com/Samsung/Tizen.NET -->
        <!-- <TargetFrameworks>$(TargetFrameworks);net8.0-tizen</TargetFrameworks> -->
        <UseMaui>true</UseMaui>
        <SingleProject>true</SingleProject>
        <ImplicitUsings>enable</ImplicitUsings>

        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'">11.0</SupportedOSPlatformVersion>
        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'maccatalyst'">13.1</SupportedOSPlatformVersion>
        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'">21.0</SupportedOSPlatformVersion>
        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">10.0.17763.0</SupportedOSPlatformVersion>
        <TargetPlatformMinVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">10.0.17763.0</TargetPlatformMinVersion>
        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'tizen'">6.5</SupportedOSPlatformVersion>
    </PropertyGroup>

</Project>

Em seus projetos de plataforma, adicione uma referência a esse novo projeto de biblioteca. Em seguida, copie seus arquivos de biblioteca Xamarin.Forms para o projeto de biblioteca do .NET MAUI.

Alterações de namespace

Os namespaces foram alterados na migração do Xamarin.Forms para o .NET MAUI, e os recursos do Xamarin.Essentials agora fazem parte do .NET MAUI. Para fazer atualizações de namespace, execute uma localização e substituição para os seguintes namespaces:

Namespace Xamarin.Forms	Namespace(s) do .NET MAUI
Xamarin.Forms	Microsoft.Maui e Microsoft.Maui.Controls
Xamarin.Forms.DualScreen	Microsoft.Maui.Controls.Foldable
Xamarin.Forms.Maps	Microsoft.Maui.Controls.Maps e Microsoft.Maui.Maps
Xamarin.Forms.PlatformConfiguration	Microsoft.Maui.Controls.PlatformConfiguration
Xamarin.Forms.PlatformConfiguration.AndroidSpecific	Microsoft.Maui.Controls.PlatformConfiguration.AndroidSpecific
Xamarin.Forms.PlatformConfiguration.AndroidSpecific.AppCompat	Microsoft.Maui.Controls.PlatformConfiguration.AndroidSpecific.AppCompat
Xamarin.Forms.PlatformConfiguration.TizenSpecific	Microsoft.Maui.Controls.PlatformConfiguration.TizenSpecific
Xamarin.Forms.PlatformConfiguration.WindowsSpecific	Microsoft.Maui.Controls.PlatformConfiguration.WindowsSpecific
Xamarin.Forms.PlatformConfiguration.iOSSpecific	Microsoft.Maui.Controls.PlatformConfiguration.iOSSpecific
Xamarin.Forms.Shapes	Microsoft.Maui.Controls.Shapes
Xamarin.Forms.StyleSheets	Microsoft.Maui.Controls.StyleSheets
Xamarin.Forms.Xaml	Microsoft.Maui.Controls.Xaml

Os projetos do .NET MAUI fazem uso de diretivas global using implícitas. Esse recurso permite que você remova as diretivas using para o namespace Xamarin.Essentials, sem precisar substituí-las pelos namespaces do .NET MAUI equivalentes.

Além disso, o namespace XAML padrão foi alterado de http://xamarin.com/schemas/2014/forms em Xamarin.Forms para http://schemas.microsoft.com/dotnet/2021/maui no .NET MAUI. Portanto, você deve substituir todas as ocorrências de xmlns="http://xamarin.com/schemas/2014/forms" por xmlns="http://schemas.microsoft.com/dotnet/2021/maui".

Observação

Você pode atualizar rapidamente seus namespaces Xamarin.Forms para Microsoft.Maui usando Ações rápidas no Visual Studio, desde que tenha instalado o Assistente de Atualização.

Alterações de API

Algumas APIs foram alteradas na migração de Xamarin.Forms para o .NET MAUI. Isso se deve a vários motivos, incluindo a remoção de funcionalidades duplicadas causadas pelo fato de o Xamarin.Essentials ter se tornado parte do .NET MAUI e a garantia de que as APIs sigam as diretrizes de nomenclatura do .NET. As seções a seguir discutem essas alterações.

Alterações de cores

Em Xamarin.Forms, o estrutura Xamarin.Forms.Color permite que você construa objetos Color usando valores double e fornece cores nomeadas, como Xamarin.Forms.Color.AliceBlue. No .NET MAUI, essa funcionalidade foi separada na classe Microsoft.Maui.Graphics.Color e na classe Microsoft.Maui.Graphics.Colors.

A classe Microsoft.Maui.Graphics.Color, no namespace Microsoft.Maui.Graphics, permite que você construa objetos Color usando valores float, byte e int. A classe Microsoft.Maui.Graphics.Colors, que também está no namespace Microsoft.Maui.Graphics, fornece basicamente as mesmas cores nomeadas. Por exemplo, use Colors.AliceBlue para especificar a cor AliceBlue.

A tabela a seguir mostra as alterações de API entre a estrutura Xamarin.Forms.Color e a classe Microsoft.Maui.Graphics.Color:

Xamarin.Forms API	API do .NET MAUI	Comentário
Xamarin.Forms.Color.R	Microsoft.Maui.Graphics.Color.Red
Xamarin.Forms.Color.G	Microsoft.Maui.Graphics.Color.Green
Xamarin.Forms.Color.B	Microsoft.Maui.Graphics.Color.Blue
Xamarin.Forms.Color.A	Microsoft.Maui.Graphics.Color.Alpha
Xamarin.Forms.Color.Hue	Microsoft.Maui.Graphics.Color.GetHue	Propriedade Xamarin.Forms substituída por um método no .NET MAUI.
Xamarin.Forms.Color.Saturation	Microsoft.Maui.Graphics.Color.GetSaturation	Propriedade Xamarin.Forms substituída por um método no .NET MAUI.
Xamarin.Forms.Color.Luminosity	Microsoft.Maui.Graphics.Color.GetLuminosity	Propriedade Xamarin.Forms substituída por um método no .NET MAUI.
Xamarin.Forms.Color.Default		Nenhum equivalente no .NET MAUI. Em vez disso, os objetos Microsoft.Maui.Graphics.Color têm como padrão null.
Xamarin.Forms.Color.Accent		Nenhum equivalente no .NET MAUI.
Xamarin.Forms.Color.FromHex	Microsoft.Maui.Graphics.Color.FromArgb	Microsoft.Maui.Graphics.Color.FromHex está obsoleto e será removido em uma versão futura.

Além disso, todos os valores numéricos em um Microsoft.Maui.Graphics.Color são float, em vez de double como usado em Xamarin.Forms.Color.

Observação

Ao contrário de Xamarin.Forms, um Microsoft.Maui.Graphics.Color não tem uma conversão implícita para System.Drawing.Color.

Alterações de layout

A tabela a seguir lista as APIs de layout que foram removidas na migração de Xamarin.Forms para o .NET MAUI:

Xamarin.Forms API	API do .NET MAUI	Comentários
Xamarin.Forms.AbsoluteLayout.IAbsoluteList<T>.Add		A sobrecarga Add que aceita 3 argumentos não está presente no .NET MAUI.
Xamarin.Forms.Grid.IGridList<T>.AddHorizontal		Nenhum equivalente no .NET MAUI.
Xamarin.Forms.Grid.IGridList<T>.AddVertical		Nenhum equivalente no .NET MAUI.
Xamarin.Forms.RelativeLayout	Microsoft.Maui.Controls.Compatibility.RelativeLayout	No .NET MAUI, RelativeLayout existe apenas como um controle de compatibilidade para usuários que migram de Xamarin.Forms. Em vez disso, use Grid ou adicione o xmlns para o namespace de compatibilidade.

Além disso, adicionar filhos a um layout no código em Xamarin.Forms é feito adicionando os filhos à coleção Children do layout:

Grid grid = new Grid();
grid.Children.Add(new Label { Text = "Hello world" });

No .NET MAUI, a coleção Children é para uso interno do .NET MAUI e não deve ser manipulada diretamente. Portanto, no código, os elementos filho devem ser adicionados diretamente ao layout:

Grid grid = new Grid();
grid.Add(new Label { Text = "Hello world" });

Importante

Todos os métodos de extensão de layout Add, como GridExtensions.Add, são invocados no layout e não na coleção Children de layouts.

Você pode notar, ao executar o aplicativo .NET MAUI atualizado, que o comportamento do layout é diferente. Para obter mais informações, consulte Alterações de comportamento do layout em relação a Xamarin.Forms.

Alterações do layout personalizado

O processo de criação de um layout personalizado em Xamarin.Forms envolve a criação de uma classe que deriva de Layout<View> e a substituição dos métodos VisualElement.OnMeasure e Layout.LayoutChildren. Para obter mais informações, consulte Criar um layout personalizado em Xamarin.Forms.

No .NET MAUI, as classes de layout derivam da classe abstrata Layout. Essa classe delega o layout e a medição entre plataformas a uma classe de gerenciador de layout. Cada classe do gerenciador de layout implementa a interface ILayoutManager, que especifica que as implementações Measure e ArrangeChildren precisam ser fornecidas:

• A implementação Measure chama IView.Measure em cada exibição no layout e retorna o tamanho total do layout, dadas as delimitações.
• A implementação ArrangeChildren determina onde cada exibição deve ser colocada dentro dos limites do layout e chama Arrange em cada exibição com seus limites apropriados. O valor retornado é o tamanho real do layout.

Para obter mais informações, consulte Layouts personalizados.

Alterações no dispositivo

Xamarin.Forms tem uma classe Xamarin.Forms.Device que o ajuda a interagir com o dispositivo e a plataforma em que o aplicativo está sendo executado. A classe equivalente no .NET MAUI, Microsoft.Maui.Controls.Device, está obsoleta e sua funcionalidade foi substituída por vários tipos.

A tabela a seguir mostra as substituições do .NET MAUI para a funcionalidade na classe Xamarin.Forms.Device:

Xamarin.Forms API	API do .NET MAUI	Comentários
Xamarin.Forms.Device.Android	Microsoft.Maui.Devices.DevicePlatform.Android
Xamarin.Forms.Device.iOS	Microsoft.Maui.Devices.DevicePlatform.iOS
Xamarin.Forms.Device.GTK		Nenhum equivalente no .NET MAUI.
Xamarin.Forms.Device.macOS		Nenhum equivalente no .NET MAUI. Em vez disso, use Microsoft.Maui.Devices.DevicePlatform.MacCatalyst.
Xamarin.Forms.Device.Tizen	Microsoft.Maui.Devices.DevicePlatform.Tizen
Xamarin.Forms.Device.UWP	Microsoft.Maui.Devices.DevicePlatform.WinUI
Xamarin.Forms.Device.WPF		Nenhum equivalente no .NET MAUI.
Xamarin.Forms.Device.Flags		Nenhum equivalente no .NET MAUI.
Xamarin.Forms.Device.FlowDirection	Microsoft.Maui.ApplicationModel.AppInfo.RequestedLayoutDirection
Xamarin.Forms.Device.Idiom	Microsoft.Maui.Devices.DeviceInfo.Idiom
Xamarin.Forms.Device.IsInvokeRequired	Microsoft.Maui.Dispatching.Dispatcher.IsDispatchRequired
Xamarin.Forms.Device.OS	Microsoft.Maui.Devices.DeviceInfo.Platform
Xamarin.Forms.Device.RuntimePlatform	Microsoft.Maui.Devices.DeviceInfo.Platform
Xamarin.Forms.Device.BeginInvokeOnMainThread	Microsoft.Maui.ApplicationModel.MainThread.BeginInvokeOnMainThread
Xamarin.Forms.Device.GetMainThreadSynchronizationContextAsync	Microsoft.Maui.ApplicationModel.MainThread.GetMainThreadSynchronizationContextAsync
Xamarin.Forms.Device.GetNamedColor		Nenhum equivalente no .NET MAUI.
Xamarin.Forms.Device.GetNamedSize		Nenhum equivalente no .NET MAUI.
Xamarin.Forms.Device.Invalidate	Microsoft.Maui.Controls.VisualElement.InvalidateMeasure
Xamarin.Forms.Device.InvokeOnMainThreadAsync	Microsoft.Maui.ApplicationModel.MainThread.InvokeOnMainThreadAsync
Xamarin.Forms.Device.OnPlatform	Microsoft.Maui.Devices.DeviceInfo.Platform
Xamarin.Forms.Device.OpenUri	Microsoft.Maui.ApplicationModel.Launcher.OpenAsync
Xamarin.Forms.Device.SetFlags		Nenhum equivalente no .NET MAUI.
Xamarin.Forms.Device.SetFlowDirection	Microsoft.Maui.Controls.Window.FlowDirection
Xamarin.Forms.Device.StartTimer	Microsoft.Maui.Dispatching.DispatcherExtensions.StartTimer ou Microsoft.Maui.Dispatching.Dispatcher.DispatchDelayed

Alterações no mapa

Em Xamarin.Forms, o controle Map e os tipos associados estão no namespace Xamarin.Forms.Maps. No .NET MAUI, essa funcionalidade foi transferida para os namespaces Microsoft.Maui.Controls.Maps e Microsoft.Maui.Maps. Algumas propriedades foram renomeadas e alguns tipos foram substituídos por tipos equivalentes de Xamarin.Essentials.

A tabela a seguir mostra as substituições do .NET MAUI para a funcionalidade no namespace Xamarin.Forms.Maps:

Xamarin.Forms API	API do .NET MAUI	Comentário
Xamarin.Forms.Maps.Map.HasScrollEnabled	Microsoft.Maui.Controls.Maps.Map.IsScrollEnabled
Xamarin.Forms.Maps.Map.HasZoomEnabled	Microsoft.Maui.Controls.Maps.Map.IsZoomEnabled
Xamarin.Forms.Maps.Map.TrafficEnabled	Microsoft.Maui.Controls.Maps.Map.IsTrafficEnabled
Xamarin.Forms.Maps.Map.MoveToLastRegionOnLayoutChange		Nenhum equivalente no .NET MAUI.
Xamarin.Forms.Maps.Pin.Id	Microsoft.Maui.Controls.Maps.Pin.MarkerId
Xamarin.Forms.Maps.Pin.Position	Microsoft.Maui.Controls.Maps.Pin.Location
Xamarin.Forms.Maps.MapClickedEventArgs.Position	Microsoft.Maui.Controls.Maps.MapClickedEventArgs.Location
Xamarin.Forms.Maps.Position	Microsoft.Maui.Devices.Sensors.Location	Os membros do tipo Xamarin.Forms.Maps.Position foram alterados para o tipo Microsoft.Maui.Devices.Sensors.Location.
Xamarin.Forms.Maps.Geocoder	Microsoft.Maui.Devices.Sensors.Geocoding	Os membros do tipo Xamarin.Forms.Maps.Geocoder foram alterados para o tipo Microsoft.Maui.Devices.Sensors.Geocoding.

O .NET MAUI tem dois tipos Map - Microsoft.Maui.Controls.Maps.Map e Microsoft.Maui.ApplicationModel.Map. Como o namespace Microsoft.Maui.ApplicationModel é uma das diretivas global using do .NET MAUI, ao usar o controle Microsoft.Maui.Controls.Maps.Map no código, você terá que qualificar totalmente o uso de Map ou usar um alias usando.

No XAML, uma definição de namespace xmlns deve ser adicionada para o controle Map. Embora isso não seja obrigatório, evita uma colisão entre os tipos Polygon e Polyline, que existem nos namespaces Microsoft.Maui.Controls.Maps e Microsoft.Maui.Controls.Shapes. Para obter mais informações, confira Exibir um mapa.

Outras alterações

Um pequeno número de outras APIs foi consolidado na migração de Xamarin.Forms para o .NET MAUI. A tabela a seguir mostra essas alterações:

Xamarin.Forms API	API do .NET MAUI	Comentários
Xamarin.Forms.Application.Properties	Microsoft.Maui.Storage.Preferences
Xamarin.Forms.Button.Image	Microsoft.Maui.Controls.Button.ImageSource
Xamarin.Forms.Frame.OutlineColor	Microsoft.Maui.Controls.Frame.BorderColor
Xamarin.Forms.IQueryAttributable.ApplyQueryAttributes	Microsoft.Maui.Controls.IQueryAttributable.ApplyQueryAttributes	Em Xamarin.Forms, o método ApplyQueryAttributes aceita um argumento IDictionary<string, string>. No .NET MAUI, o método ApplyQueryAttributes aceita um argumento IDictionary<string, object>.
Xamarin.Forms.MenuItem.Icon	Microsoft.Maui.Controls.MenuItem.IconImageSource	Xamarin.Forms.MenuItem.Icon é a classe base para Xamarin.Forms.ToolbarItem e, portanto, ToolbarItem.Icon torna-se ToolbarItem.IconImageSource.
Xamarin.Forms.OrientationStateTrigger.Orientation	Microsoft.Maui.Controls.OrientationStateTrigger.Orientation	Em Xamarin.Forms, a propriedade OrientationStateTrigger.Orientation é do tipo Xamarin.Forms.Internals.DeviceOrientation. No .NET MAUI, a propriedade OrientationStateTrigger.Orientation é do tipo DisplayOrientation.
Xamarin.Forms.OSAppTheme	Microsoft.Maui.ApplicationModel.AppTheme
Xamarin.Forms.Span.ForegroundColor	Microsoft.Maui.Controls.Span.TextColor
Xamarin.Forms.ToolbarItem.Name	Microsoft.Maui.Controls.MenuItem.Text	Microsoft.Maui.Controls.MenuItem.Text é a classe base para Microsoft.Maui.Controls.ToolbarItem e, portanto, ToolbarItem.Name torna-se ToolbarItem.Text.

Além disso, no Xamarin.Forms, a substituição Page.OnAppearing é chamada no Android quando um aplicativo é enviado para o segundo plano e depois trazido para o primeiro plano. No entanto, essa substituição não é chamada no iOS nem no Windows na mesma situação. No .NET MAUI, a substituição OnAppearing() não é chamada em nenhuma das plataformas quando um aplicativo é colocado em segundo plano e, em seguida, trazido para o primeiro plano. Em vez disso, você deve escutar os eventos do ciclo de vida na Window para ser notificado quando um aplicativo retornar ao primeiro plano. Para obter mais informações, confira Janelas do .NET MAUI.

Alterações nos formulários nativos

Formulários nativos em Xamarin.Forms tornaram-se inserção nativa no .NET MAUI, e utilizam uma abordagem de inicialização diferente e métodos de extensão diferentes para converter controles multiplataforma em seus tipos nativos. Para obter mais informações, consulte Inserção nativa.

Faça a inicialização do aplicativo migrado

Ao atualizar manualmente um aplicativo Xamarin.Forms para o .NET MAUI, você precisará habilitar o suporte ao .NET MAUI em cada projeto de plataforma, atualizar a classe de ponto de entrada de cada projeto de plataforma e, em seguida, configurar a inicialização do aplicativo .NET MAUI.

Habilitar o .NET MAUI em projetos de plataforma

Antes de atualizar a classe de ponto de entrada de cada projeto de plataforma, você deve primeiro habilitar o suporte ao .NET MAUI. Isso pode ser feito definindo a propriedade de compilação $(UseMaui) como true em cada projeto de plataforma:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    ...
    <UseMaui>true</UseMaui>
  </PropertyGroup>
</Project>

Importante

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

Adicionar referências do pacote

No .NET 8, o .NET MAUI é fornecido como uma carga de trabalho .NET e vários pacotes NuGet. A vantagem dessa abordagem é que ela permite que fixar facilmente seus projetos em versões específicas, além de visualizar facilmente builds não lançados ou experimentais.

Você deve adicionar as seguintes referências explícitas de pacote a um <ItemGroup> em cada arquivo de projeto:

<PackageReference Include="Microsoft.Maui.Controls" Version="$(MauiVersion)" />
<PackageReference Include="Microsoft.Maui.Controls.Compatibility" Version="$(MauiVersion)" />

A variável $(MauiVersion) é referenciada a partir da versão do .NET MAUI que você instalou. Você pode substituir isso adicionando a propriedade de build $(MauiVersion) a cada arquivo de projeto:

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <UseMaui>True</UseMaui>
        <MauiVersion>8.0.3</MauiVersion>
    </PropertyGroup>
</Project>

Configuração do projeto Android

Em seu projeto Android .NET MAUI, atualize a classe MainApplication para corresponder ao código abaixo:

using System;
using Android.App;
using Android.Runtime;
using Microsoft.Maui;
using Microsoft.Maui.Hosting;
using YOUR_MAUI_CLASS_LIB_HERE;

namespace YOUR_NAMESPACE_HERE.Droid
{
    [Application]
    public class MainApplication : MauiApplication
    {
        public MainApplication(IntPtr handle, JniHandleOwnership ownership) : base(handle, ownership)
        {
        }

        protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
    }
}

Atualize também a classe MainActivity para herdar de MauiAppCompatActivity:

using System;
using Microsoft.Maui;
using Android.App;
using Android.Content.PM;
using Android.Runtime;
using Android.OS;

namespace YOUR_NAMESPACE_HERE.Droid
{
    [Activity(Label = "MyTitle", Icon = "@mipmap/icon", Theme = "@style/MainTheme", MainLauncher = true, ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation | ConfigChanges.UiMode | ConfigChanges.ScreenLayout | ConfigChanges.SmallestScreenSize)]
    public class MainActivity : MauiAppCompatActivity
    {
        protected override void OnCreate(Bundle savedInstanceState)
        {
            base.OnCreate(savedInstanceState);
        }
    }
}

Em seguida, atualize seu arquivo de manifesto para especificar que minSdKVersion é 21, que é a versão mínima do SDK do Android exigida pelo .NET MAUI. Isso pode ser feito modificando o nó <uses-sdk />, que é um filho do nó <manifest>:

<uses-sdk android:minSdkVersion="21" android:targetSdkVersion="32" />

Configuração do projeto iOS

Em seu projeto iOS do .NET MAUI, atualize a classe AppDelegate para herdar de MauiUIApplicationDelegate:

using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.Maui;
using Foundation;
using UIKit;
using YOUR_MAUI_CLASS_LIB_HERE;

namespace YOUR_NAMESPACE_HERE.iOS
{
    [Register("AppDelegate")]
    public partial class AppDelegate : MauiUIApplicationDelegate
    {
        protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
    }
}

Em seguida, atualize Info.plist para que MinimumOSVersion seja 11.0, que é a versão mínima do iOS exigida pelo .NET MAUI.

Configuração do projeto UWP

Em seu projeto WinUI 3 do .NET MAUI, atualize App.xaml para corresponder ao código abaixo:

<?xml version="1.0" encoding="utf-8"?>
<maui:MauiWinUIApplication
    x:Class="YOUR_NAMESPACE_HERE.WinUI.App"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:maui="using:Microsoft.Maui"
    xmlns:local="using:YOUR_NAMESPACE_HERE.WinUI">
    <maui:MauiWinUIApplication.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
                <!-- Other merged dictionaries here -->
            </ResourceDictionary.MergedDictionaries>
            <!-- Other app resources here -->
        </ResourceDictionary>
    </maui:MauiWinUIApplication.Resources>
</maui:MauiWinUIApplication>

Observação

Se o seu projeto incluiu recursos no App.xaml existente, você deverá migrá-los para a nova versão do arquivo.

Além disso, atualize App.xaml.cs para que corresponda ao código abaixo:

using Microsoft.Maui;
using Microsoft.Maui.Hosting;
using YOUR_MAUI_CLASS_LIB_HERE;

namespace YOUR_NAMESPACE_HERE.WinUI;

public partial class App : MauiWinUIApplication
{
    public App()
    {
        InitializeComponent();
    }

    protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
}

Observação

Se o seu projeto incluiu lógica de negócios em App.xaml.cs, você deve migrar essa lógica para a nova versão do arquivo.

Em seguida, adicione um arquivo launchSettings.json à pasta Propriedades do projeto e adicione o seguinte JSON ao arquivo:

{
  "profiles": {
    "Windows Machine": {
      "commandName": "MsixPackage",
      "nativeDebugging": true
    }
  }
}

Ponto de entrada do aplicativo

Os aplicativos .NET MAUI têm um único ponto de entrada de aplicativo multiplataforma. Cada ponto de entrada de plataforma chama um método CreateMauiApp na classe estática MauiProgram e retorna um MauiApp.

Portanto, adicione um novo nome da classe MauiProgram que contenha o seguinte código:

namespace YOUR_NAMESPACE_HERE;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>();

        return builder.Build();
    }
}

Observação

Para Xamarin.Forms projetos UWP, a referência App em builder.UseMauiApp<App>() pode ser encontrada no arquivo MainPage.xaml.cs.

Se houver serviços específicos da plataforma que precisem ser migrados para o .NET MAUI, use o método AddTransient(IServiceCollection, Type) para adicionar um serviço transitório do tipo especificado ao IServiceCollection especificado.

Observação

Você pode atualizar rapidamente seus namespaces Xamarin.Forms para Microsoft.Maui usando Ações rápidas no Visual Studio, desde que tenha instalado o Assistente de Atualização.

Alterações no AssemblyInfo

As propriedades que normalmente são definidas em um arquivo AssemblyInfo.cs agora estão disponíveis em seu projeto no estilo SDK. Recomendamos migrá-las de AssemblyInfo.cs para o arquivo de projeto em todos os projetos e remover o arquivo AssemblyInfo.cs.

Opcionalmente, você pode manter o arquivo AssemblyInfo.cs e definir a propriedade GenerateAssemblyInfo em seu arquivo de projeto como false:

<PropertyGroup>
  <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
</PropertyGroup>

Para obter mais informações sobre a propriedade GenerateAssemblyInfo, consulte GenerateAssemblyInfo.

Atualizar as dependências do aplicativo

Em geral, Xamarin.Forms Os pacotes NuGet não são compatíveis com o .NET 8, a menos que tenham sido recompilados usando Monikers da Estrutura de Destino (TFMs) do .NET. No entanto, os aplicativos Android podem usar pacotes NuGet direcionados para as estruturas monoandroid e monoandroidXX.X.

Para confirmar se um pacote é compatível com o .NET 8, consulte a guia Estruturas no NuGet para o pacote que você está usando e verifique se ele lista uma das estruturas compatíveis mostradas na tabela a seguir:

Estruturas compatíveis	Estruturas incompatíveis
net8.0-android, monoandroid, monoandroidXX.X
net8.0-ios	monotouch, xamarinios, xamarinios10
net8.0-macos	monomac, xamarinmac, xamarinmac20
net8.0-tvos	xamarintvos
	xamarinwatchos

Observação

As bibliotecas do .NET Standard que não têm dependências das estruturas incompatíveis listadas acima ainda são compatíveis com o .NET 8.

Se um pacote em NuGet indicar compatibilidade com qualquer uma das estruturas compatíveis acima, independentemente de também incluir estruturas incompatíveis, o pacote será compatível. Os pacotes NuGet compatíveis podem ser adicionados ao seu projeto de biblioteca do .NET MAUI usando o gerenciador de pacotes NuGet no Visual Studio.

Se você não conseguir encontrar uma versão compatível com o .NET 8 de um pacote NuGet, deverá:

• Recompilar o pacote com TFMs .NET, se você possuir o código.
• Procurar uma versão prévia de uma versão .NET 8 do pacote.
• Substituir a dependência por uma alternativa compatível com o .NET 8.

Compilar e solucionar problemas

Depois que as dependências forem resolvidas, você deverá compilar o projeto. Qualquer erro guiará você para as próximas etapas.

Dica

• Exclua todas as pastas bin e obj de todos os projetos antes de abrir e compilar projetos no Visual Studio, especialmente ao alterar as versões do .NET.
• Exclua o arquivo gerado Resource.designer.cs pelo projeto Android.

A tabela a seguir fornece diretrizes para superar problemas comuns de compilação ou runtime:

Problema	Dica
O namespace Xamarin.* não existe.	Atualize o namespace para seu equivalente no .NET MAUI. Para obter mais informações, consulte Alterações no namespace.
A API não existe.	Atualize o uso da API para seu equivalente no .NET MAUI. Para obter mais informações, consulte Alterações de API.
O aplicativo não está implantado.	Certifique-se de que o projeto de plataforma necessário esteja definido para implantação no Configuration Manager do Visual Studio.
O aplicativo não inicia.	Atualize a classe do ponto de entrada de cada projeto de plataforma e o ponto de entrada do aplicativo. Para obter mais informações, consulte Inicialização do seu aplicativo migrado.
CollectionView não faz rolagem.	Verifique o layout do contêiner e o tamanho medido do CollectionView. Por padrão, o controle ocupará todo o espaço que o contêiner permitir. Um Grid restringe os filhos ao seu próprio tamanho. Entretanto, um StackLayout permite que os filhos ocupem espaço além de seus limites.
O pop-up é exibido sob a página no iOS.	Em Xamarin.Forms, todos os pop-ups no iOS são UIWindow instâncias, mas no .NET MAUI os pop-ups são exibidos localizando a apresentação atual ViewController e exibindo o pop-up com PresentViewControllerAsync. Em plug-ins como o Mopups, para garantir que seus pop-ups sejam exibidos corretamente, você deve chamar DisplayAlert, DisplayActionSheet ou DisplayPromptAsync do ContentPage que é usado dentro do pop-up Mopup.
BoxView não está aparecendo.	O tamanho padrão de um BoxView em Xamarin.Forms é 40x40. O tamanho padrão de um BoxView no .NET MAUI é 0x0. Defina WidthRequest e HeightRequest como 40.
O layout está sem preenchimento, margem ou espaçamento.	Adicione valores padrão ao seu projeto com base no recurso de estilo do .NET MAUI. Para obter mais informações, consulte Alterações de valor padrão de Xamarin.Forms.
O layout personalizado não funciona.	O código de layout personalizado precisa ser atualizado para funcionar no .NET MAUI. Para obter mais informações, consulte Alterações do layout personalizado.
O renderizador personalizado não funciona.	O código do renderizador precisa ser atualizado para funcionar no .NET MAUI. Para obter mais informações, consulte Usar renderizadores personalizados no .NET MAUI.
O efeito não funciona.	O código do efeito precisa ser atualizado para funcionar no .NET MAUI. Para obter mais informações, consulte Usar efeitos no .NET MAUI.
O código SkiaSharp não funciona.	O código SkiaSharp precisa de pequenas atualizações para funcionar no .NET MAUI. Para obter mais informações, consulte Reutilizar o código SkiaSharp no .NET MAUI.
Não é possível acessar os dados de propriedades do aplicativo criados anteriormente.	Migre os dados de propriedades do aplicativo para as preferências do .NET MAUI. Para obter mais informações, consulte Migrar dados do dicionário de propriedades do aplicativo Xamarin.Forms para as preferências do .NET MAUI.
Não é possível acessar os dados do armazenamento seguro criados anteriormente.	Migre os dados do armazenamento seguro para o .NET MAUI. Para obter mais informações, consulte Migrar do armazenamento seguro Xamarin.Essentials para o armazenamento seguro do .NET MAUI.
Não é possível acessar dados de acompanhamento de versão criados anteriormente.	Migre os dados de controle de versão para o .NET MAUI. Para obter mais informações, consulte Migrar dados de acompanhamento de versão de um aplicativo Xamarin.Forms para um aplicativo .NET MAUI.

Confira também

• Transferência do .NET Framework para o .NET
• Assistente de Atualização do .NET