Compartilhar via

Atualizar manualmente um aplicativo Xamarin.Forms para um aplicativo .NET MAUI de projeto único.

Para migrar um aplicativo Xamarin.Forms para um aplicativo de Interface de Usuário Multiplataforma .NET (.NET MAUI) de projeto único, você deve:

  • Atualize seu Xamarin.Forms aplicativo para usar Xamarin.Forms 5.
  • Atualize as dependências do aplicativo para as versões mais recentes.
  • Verifique se o aplicativo ainda funciona.
  • Crie um aplicativo .NET MAUI.
  • Copie o código e a configuração do Xamarin.Forms aplicativo para o aplicativo MAUI do .NET.
  • Copie os recursos do aplicativo Xamarin.Forms para o aplicativo MAUI do .NET.
  • Atualizar namespaces.
  • Tratar de quaisquer alterações na API.
  • Atualize ou substitua dependências incompatíveis por versões do .NET 8.
  • Compile e teste seu aplicativo.

Para simplificar o processo de atualização, você deve criar um novo aplicativo .NET MAUI com o mesmo nome que seu Xamarin.Forms aplicativo e copiar o seu código, configuração e recursos para dentro dele. Esta é a abordagem descrita abaixo.

Atualizar seu Xamarin.Forms aplicativo

Antes de atualizar seu Xamarin.Forms aplicativo para o .NET MAUI, primeiro você deve atualizar seu Xamarin.Forms aplicativo para usar 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 irá ajudar a simplificar o restante do processo de migração, pois minimizará as diferenças de API entre Xamarin.Forms e .NET MAUI e garantirá que você esteja usando versões compatíveis com .NET de suas dependências, caso elas existam.

Criar um aplicativo .NET MAUI

No Visual Studio, crie um novo aplicativo MAUI do .NET usando o mesmo nome que seu Xamarin.Forms aplicativo:

Captura de tela da criação de um aplicativo MAUI do .NET no Visual Studio.

Abrir o arquivo de projeto confirmará que você tem um projeto no estilo SDK do .NET.

Copiar código para o aplicativo MAUI do .NET

Todo o código multiplataforma do seu Xamarin.Forms projeto de biblioteca deve ser copiado para seu projeto de aplicativo MAUI do .NET em arquivos e pastas nomeadas de forma idêntica.

Renderizadores personalizados podem ser reutilizados em um aplicativo MAUI do .NET ou migrados para um manipulador .NET MAUI. Para obter mais informações, consulte Reutilizar renderizadores personalizados no .NET MAUI e migrar um Xamarin.Forms renderizador personalizado para um manipulador .NET MAUI.

Os efeitos podem ser reutilizados em um aplicativo MAUI do .NET. Para obter mais informações, consulte Reutilizar efeitos.

Observação

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

Código específico da plataforma

Um projeto de aplicativo .NET MAUI contém uma pasta Platforms, cada subpasta representando uma plataforma que o .NET MAUI pode direcionar.

Captura de tela das pastas da plataforma.

As pastas de cada plataforma contêm recursos específicos da plataforma e código que inicia o aplicativo em cada plataforma:

Captura de tela de código específica da plataforma.

O código e suas pastas contendo, de seus Xamarin.Forms projetos principais, devem ser copiados para estas pastas:

  • O código do projeto Xamarin.Forms principal do Android deve ser copiado para a pasta Platform\Android do seu projeto de aplicativo .NET MAUI. Além disso, copie qualquer código personalizado de suas Xamarin.FormsMainActivity classes e MainApplication classes para as mesmas classes em seu projeto de aplicativo .NET MAUI.

  • O código do projeto Xamarin.Forms principal do iOS deve ser copiado para a pasta Platforms\iOS do seu projeto de aplicativo .NET MAUI. Além disso, copie qualquer código personalizado de sua Xamarin.FormsAppDelegate classe para a mesma classe em seu projeto de aplicativo .NET MAUI.

    Observação

    Para obter uma lista de alterações significativas no .NET para iOS, consulte Alterações significativas no .NET para iOS.

  • O código do projeto Xamarin.Forms principal da UWP deve ser copiado para a pasta Platforms\Windows do seu projeto de aplicativo .NET MAUI. Além disso, copie qualquer código personalizado de sua Xamarin.FormsApp classe para a mesma classe em seu projeto de aplicativo .NET MAUI.

Durante o processo de construção, o sistema de construção inclui apenas o código de cada pasta ao compilar para aquela plataforma específica. Por exemplo, quando você desenvolver para Android, os arquivos na pasta Plataformas\Android serão integrados ao pacote do aplicativo, mas os arquivos nas pastas das outras plataformas não serão. Esta abordagem utiliza multi-targeting para atingir várias plataformas a partir de um único projeto. Os aplicativos .NET MAUI também podem ser direcionados a múltiplos alvos com base em seus próprios critérios de nome de arquivo e pasta. Isso permite estruturar seu projeto de aplicativo .NET MAUI para que você não precise colocar o código da plataforma em pastas filho da pasta Plataformas . Para obter mais informações, confira Configurar multi-direcionamento.

Copiar a configuração para o aplicativo MAUI do .NET

Cada plataforma usa seu próprio arquivo de manifesto de aplicativo nativo para especificar informações como o título do aplicativo, a ID, a versão e muito mais. O projeto único do .NET MAUI permite que você especifique esses dados comuns do aplicativo em um único local no arquivo de projeto.

Para especificar os dados de manifesto do aplicativo compartilhado para um projeto, abra o menu de atalho do projeto no Gerenciador de Soluções e escolha Propriedades. O título do aplicativo, a ID e a versão podem ser especificados no MAUI Shared > General:

Captura de tela do manifesto do aplicativo .NET MAUI.

Durante a compilação, os dados do manifesto aplicativo compartilhado são mesclados com dados específicos da plataforma no arquivo de manifesto do aplicativo nativo, produzindo o arquivo de manifesto do pacote de aplicativos. Para obter mais informações, consulte a configuração do Project no .NET MAUI – MAUI Shared.

Os dados restantes dos manifestos do seu aplicativo Xamarin.Forms devem ser copiados para o manifesto do aplicativo .NET MAUI:

  • No Android, copie quaisquer dados adicionais do arquivo AndroidManifest.xml em seu projeto principal do Android para o arquivo de plataformas \Android\AndroidManifest.xml em seu projeto de aplicativo .NET MAUI.
  • No iOS, copie quaisquer dados adicionais do arquivo Info.plist em seu Xamarin.Forms projeto principal do iOS para o arquivo Platforms\iOS\Info.plist em seu projeto de aplicativo .NET MAUI. Além disso, copie o arquivo Entitlements.plist em seu Xamarin.Forms projeto principal do iOS para a pasta Platforms\iOS em seu projeto de aplicativo .NET MAUI.
  • No Windows, copie dados adicionais do arquivo Package.appxmanifest em seu Xamarin.Forms projeto principal UWP, para o arquivo Platforms\Windows\Package.appxmanifest em seu projeto de aplicativo .NET MAUI.

Copiar recursos para o aplicativo MAUI do .NET

O projeto único do .NET MAUI permite que os arquivos de recursos sejam armazenados em um único local enquanto são consumidos em cada plataforma. Isso inclui fontes, imagens, o ícone do aplicativo, a tela inicial, ativos brutos e arquivos CSS para estilizar aplicativos .NET MAUI.

Os arquivos de recurso normalmente devem ser colocados na pasta Recursos do seu projeto de aplicativo .NET MAUI ou pastas filho da pasta Recursos e devem ter a ação de build definida corretamente. A tabela a seguir mostra as ações de build para cada tipo de arquivo de recurso:

Recurso Ação de construção
Ícone do aplicativo MauiIcon
Fontes MauiFont
Imagens MauiImage
Tela inicial MauiSplashScreen
Ativos brutos MauiAsset
Ficheiros CSS MauiCss

Observação

Os arquivos XAML também são armazenados em seu projeto de aplicativo .NET MAUI e são atribuídos automaticamente à ação de build MauiXaml . No entanto, somente dicionários de recursos XAML normalmente serão colocados na pasta Recursos do projeto de aplicativo.

A captura de tela a seguir mostra uma pasta recursos típica que contém pastas filho para cada tipo de recurso:

Captura de tela de recursos de imagem e fonte.

A ação de build de um arquivo de recurso será definida corretamente, se o recurso tiver sido adicionado à pasta filho recursos correta.

Importante

Os recursos específicos da plataforma substituirão seus equivalentes de recursos compartilhados. Por exemplo, se você tiver uma imagem específica do Android localizada no Platforms\Android\Resources\drawable-xhdpi\logo.pnge também fornecer uma imagem de Recursos\Imagens\logo.svg compartilhada, o arquivo SVG (Gráficos vetoriais escalonáveis) será usado para gerar as imagens do Android necessárias, exceto para a imagem XHDPI que já existe como uma imagem específica da plataforma.

Ícones de aplicativos

O Xamarin.Forms ícone do aplicativo deve ser adicionado ao seu projeto de aplicativo .NET MAUI arrastando a imagem para a pasta Resources\AppIcon do projeto, onde sua ação de build será automaticamente definida como MauiIcon. No momento do build, o ícone do aplicativo é redimensionado para os tamanhos corretos para a plataforma e o dispositivo de destino. Os ícones do aplicativo são redimensionados para várias resoluções porque têm vários usos, incluindo ser usados para representar o aplicativo no dispositivo e na loja de aplicativos.

Para obter mais informações, consulte Adicionar um ícone de aplicativo a um projeto de aplicativo MAUI do .NET.

Tela inicial

Se o Xamarin.Forms aplicativo tiver uma tela inicial, ele deverá ser adicionado ao seu projeto de aplicativo MAUI do .NET arrastando a imagem para a pasta Resources\Splash do projeto, onde sua ação de build será automaticamente definida como MauiSplashScreen. No momento do build, a imagem da tela inicial é redimensionada para o tamanho correto para a plataforma e o dispositivo de destino.

Para obter mais informações, consulte Adicionar uma tela inicial a um projeto de aplicativo MAUI do .NET.

Imagens

Os dispositivos têm um intervalo de tamanhos de tela e densidades e cada plataforma tem funcionalidade para exibir imagens dependentes de densidade. Em Xamarin.Forms, as imagens dependentes de densidade normalmente são colocadas em projetos de cabeçalho e adotam uma convenção de nomenclatura específica da plataforma. Há duas abordagens que podem ser tomadas para migrar essas imagens para o MAUI do .NET.

A abordagem recomendada é copiar a versão de maior resolução de cada imagem de sua Xamarin.Forms solução para seu projeto de aplicativo .NET MAUI arrastando-a para a pasta Recursos\Imagens do projeto, onde sua ação de build será definida automaticamente como MauiImage. Também será necessário definir o BaseSize atributo de cada imagem de bitmap para garantir que o redimensionamento ocorra. Isso elimina a necessidade de ter várias versões de cada imagem, em cada plataforma. No momento da compilação, todas as imagens serão redimensionadas em imagens dependentes de densidade múltipla que atendam aos requisitos da plataforma. Para obter mais informações, consulte Adicionar imagens a um projeto de aplicativo MAUI do .NET.

Como alternativa, você pode copiar imagens dependentes de densidade de sua Xamarin.Forms solução para pastas nomeadas de forma idêntica na pasta Platforms\{Platform} do seu projeto de aplicativo .NET MAUI e definir suas ações de build para as ações de build usadas em sua Xamarin.Forms solução. A tabela a seguir lista exemplos de locais de imagem para uma solução Xamarin.Forms, e suas localizações equivalentes em um projeto de app .NET MAUI:

Xamarin.Forms local da imagem Local da imagem do .NET MAUI Ação de build de imagem na plataforma .NET MAUI
{MyApp.Android}\Resources\drawable-xhdpi\image.png Plataformas\Android\Resources\drawable-xhdpi\image.png AndroidResource
{MyApp.iOS}\image.jpg Plataformas\iOS\Resources\image.jpg BundleResource
{MyApp.UWP}\Assets\Images\image.gif *Plataformas\Windows\Assets\Images\image.gif Conteúdo

Desde que você tenha adotado a mesma convenção de nomenclatura de imagem usada em sua Xamarin.Forms solução, a imagem apropriada será escolhida em runtime com base nos recursos do dispositivo. A desvantagem dessa abordagem é que você ainda tem várias versões de cada imagem em cada plataforma.

Fontes

Todas as fontes da sua Xamarin.Forms solução podem ser adicionadas à sua solução MAUI do .NET arrastando-as para a pasta Resources\Fonts do projeto de aplicativo .NET MAUI, em que a ação de build será automaticamente definida como MauiFont.

Para obter mais informações, consulte Fontes.

Ficheiros CSS

Todos os arquivos CSS da sua Xamarin.Forms solução podem ser adicionados à sua solução MAUI do .NET arrastando-os para uma pasta nomeada de forma idêntica e definindo a ação de build para MauiCss na janela Propriedades .

Para obter mais informações sobre como usar arquivos CSS em um aplicativo .NET MAUI, consulte aplicativos style usando folhas de estilo em cascata.

Ativos brutos

Todos os arquivos de ativo bruto, como HTML, JSON e vídeo, devem ser copiados de sua Xamarin.Forms solução para seu projeto de aplicativo .NET MAUI arrastando-os para a pasta Resources\Raw do seu projeto, onde sua ação de build será automaticamente definida como MauiAsset.

Recursos localizados

Em um aplicativo .NET MAUI, as cadeias de caracteres são localizadas usando a mesma abordagem que em um Xamarin.Forms aplicativo. Portanto, seus arquivos de recursos do .NET (.resx) devem ser copiados de sua Xamarin.Forms solução para uma pasta nomeada de forma idêntica em sua solução MAUI do .NET. Em seguida, o idioma neutro do aplicativo .NET MAUI deve ser especificado. Para obter mais informações, consulte Especifique o idioma neutro do aplicativo.

Observação

Os arquivos de recursos do .NET não precisam ser colocados na pasta Recursos do seu projeto de aplicativo .NET MAUI.

Em um aplicativo .NET MAUI, as imagens são localizadas usando a mesma abordagem que em um Xamarin.Forms aplicativo. Portanto, suas imagens localizadas e as pastas nas quais residem devem ser copiadas da solução Xamarin.Forms para o projeto de aplicativo .NET MAUI:

  • No Android, a pasta raiz em seu projeto de aplicativo .NET MAUI para imagens localizadas é Platforms\Android\Resources.
  • No iOS, a pasta raiz em seu projeto de aplicativo .NET MAUI para imagens localizadas é Platforms\iOS\Resources.
  • No Windows, a pasta raiz em seu projeto de aplicativo .NET MAUI para imagens localizadas é Platforms\Windows\Assets\Images.

As imagens localizadas devem ter suas ações de build configuradas nas ações de build usadas em sua Xamarin.Forms solução. Para obter mais informações, consulte Localização de imagens.

Em um aplicativo .NET MAUI, os nomes de aplicativos são localizados usando a mesma abordagem que em um Xamarin.Forms aplicativo:

  • No Android, o nome do aplicativo localizado pode ser armazenado usando uma convenção de nomenclatura baseada em pasta na pasta Platforms\Android\Resources . Pastas e arquivos de localização de nome de aplicativo devem ser copiados para essa pasta da sua Xamarin.Forms solução.
  • No iOS, o nome do aplicativo localizado é armazenado usando uma convenção de nomenclatura baseada em pasta na pasta Platforms\iOS\Resources . Pastas e arquivos de localização do nome do aplicativo devem ser copiados para esta pasta da sua Xamarin.Forms solução.
  • No Windows, o nome do aplicativo localizado é armazenado no manifesto do pacote do aplicativo.

Para obter mais informações, consulte Localize o nome do aplicativo. Para obter mais informações sobre a localização do aplicativo .NET MAUI, consulte Localização.

Alterações de namespace

Os namespaces foram alterados na mudança de Xamarin.Forms para .NET MAUI, e recursos Xamarin.Essentials agora fazem parte de .NET MAUI. Para fazer atualizações de namespace, faça uma busca e substituição nos seguintes namespaces:

Namespace Xamarin.Forms Namespaces 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 MAUI do .NET usam diretivas implícitas global using . Esse recurso permite que você remova using as diretivas para o Xamarin.Essentials namespace, sem precisar substituí-las pelos namespaces .NET MAUI equivalentes.

Além disso, o namespace XAML padrão foi alterado de http://xamarin.com/schemas/2014/forms dentro Xamarin.Forms para http://schemas.microsoft.com/dotnet/2021/maui no MAUI do .NET. 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 Xamarin.Forms namespaces para Microsoft.Maui usando Ações Rápidas no Visual Studio, desde que você tenha o Assistente de Atualização instalado.

Alterações de API

Algumas APIs foram alteradas na transição de Xamarin.Forms para o .NET MAUI. Esses são vários motivos, incluindo a remoção da funcionalidade duplicada causada por Xamarin.Essentials se tornar parte do .NET MAUI e garantir que as APIs sigam as diretrizes de nomenclatura do .NET. As seções a seguir discutem essas alterações.

Alterações de cor

Em Xamarin.Forms, o Xamarin.Forms.Color Struct permite que se construam objetos Color com valores double e fornece cores com nomes, como Xamarin.Forms.Color.AliceBlue. No .NET MAUI, essa funcionalidade foi separada na Microsoft.Maui.Graphics.Color classe e na Microsoft.Maui.Graphics.Colors classe.

A Microsoft.Maui.Graphics.Color classe, no Microsoft.Maui.Graphics namespace, permite construir Color objetos usando float valores, byte valores e int valores. A Microsoft.Maui.Graphics.Colors classe, que também está no Microsoft.Maui.Graphics namespace, fornece em grande parte 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 o Xamarin.Forms.Color struct e a Microsoft.Maui.Graphics.Color classe:

API Xamarin.Forms API MAUI do .NET 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 Xamarin.Forms propriedade substituída por um método no .NET MAUI.
Xamarin.Forms.Color.Saturation Microsoft.Maui.Graphics.Color.GetSaturation Xamarin.Forms propriedade substituída por um método no .NET MAUI.
Xamarin.Forms.Color.Luminosity Microsoft.Maui.Graphics.Color.GetLuminosity Xamarin.Forms propriedade substituída por um método no .NET MAUI.
Xamarin.Forms.Color.Default Nenhum equivalente para o .NET MAUI. Em vez disso, Microsoft.Maui.Graphics.Color os objetos se definem por padrão como null.
Xamarin.Forms.Color.Accent Nenhum equivalente para o .NET MAUI.
Xamarin.Forms.Color.FromHex Microsoft.Maui.Graphics.Color.FromArgb Microsoft.Maui.Graphics.Color.FromHex é 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 usados 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 transição do Xamarin.Forms para o .NET MAUI.

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

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

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

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

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

Importante

Qualquer método de extensão de layout Add, como GridExtensions.Add, é invocado no layout em vez de na coleção de layouts Children.

Você pode observar ao executar seu aplicativo .NET MAUI atualizado que o comportamento de layout é diferente. Para mais informações, veja as alterações de comportamento de layout de Xamarin.Forms.

Alterações de layout personalizadas

O processo de criação de um layout Xamarin.Forms personalizado envolve a criação de uma classe que deriva de Layout<View> e a sobrescrita 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 são derivadas da classe abstrata Layout. Essa classe delega o layout e a medição entre plataformas a uma classe de gerente de layout. Cada classe do gerenciador de layout implementa a interface ILayoutManager, que especifica que as implementações Measure e ArrangeChildren devem ser fornecidas.

  • A Measure implementação chama IView.Measure em cada visualização no layout e retorna o tamanho total do layout dadas as restrições.
  • A ArrangeChildren implementação determina onde cada exibição deve ser colocada dentro dos limites do layout e chama Arrange 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 Xamarin.Forms.Device classe que ajuda você a interagir com o dispositivo e a plataforma em que o aplicativo está em execução. A classe equivalente no .NET MAUI Microsoft.Maui.Controls.Devicefoi preterida e sua funcionalidade é 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.

API Xamarin.Forms API MAUI do .NET 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 para o .NET MAUI.
Xamarin.Forms.Device.macOS Nenhum equivalente para o .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 para o .NET MAUI.
Xamarin.Forms.Device.Flags Nenhum equivalente para o .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 para o .NET MAUI.
Xamarin.Forms.Device.GetNamedSize Nenhum equivalente para o .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 para o .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 de mapa

Em Xamarin.Forms, o controle e os Map tipos associados estão no Xamarin.Forms.Maps namespace. No .NET MAUI, essa funcionalidade foi movida 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 os substitutos do .NET MAUI para a funcionalidade no espaço de nomes Xamarin.Forms.Maps.

API Xamarin.Forms API MAUI do .NET 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 para o .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 mudaram para tipo Microsoft.Maui.Devices.Sensors.Location.
Xamarin.Forms.Maps.Geocoder Microsoft.Maui.Devices.Sensors.Geocoding Os membros do tipo Xamarin.Forms.Maps.Geocoder mudaram para tipo Microsoft.Maui.Devices.Sensors.Geocoding.

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

No XAML, uma xmlns definição de namespace deve ser adicionada para o Map controle. Embora isso não seja necessário, isso impede 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, consulte Exibir um mapa.

Outras alterações

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

API Xamarin.Forms API MAUI do .NET 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 ApplyQueryAttributes método aceita um IDictionary<string, string> argumento. No .NET MAUI, o ApplyQueryAttributes método aceita um IDictionary<string, object> argumento.
Xamarin.Forms.MenuItem.Icon Microsoft.Maui.Controls.MenuItem.IconImageSource Xamarin.Forms.MenuItem.Icon é a classe base para Xamarin.Forms.ToolbarItem, e assim ToolbarItem.Icon se torna ToolbarItem.IconImageSource.
Xamarin.Forms.OrientationStateTrigger.Orientation Microsoft.Maui.Controls.OrientationStateTrigger.Orientation Em Xamarin.Forms, a OrientationStateTrigger.Orientation propriedade é do tipo Xamarin.Forms.Internals.DeviceOrientation. No .NET MAUI, a OrientationStateTrigger.Orientation propriedade é 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 assim ToolbarItem.Name se torna ToolbarItem.Text.

Além disso, no Xamarin.Forms, a substituição de Page.OnAppearing é chamada no Android quando um aplicativo é colocado em segundo plano e, em seguida, trazido para o primeiro plano. No entanto, essa substituição não é chamada no iOS e no Windows no mesmo cenário. No .NET MAUI, a OnAppearing() substituição não é chamada em nenhuma plataforma quando um aplicativo é colocado em segundo plano e, em seguida, trazido para o primeiro plano. Em vez disso, você deve ouvir os eventos de ciclo de vida em Window para ser notificado quando um aplicativo retornar ao primeiro plano. Para obter mais informações, consulte as janelas MAUI do .NET.

Alterações de formulários nativos

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

Alterações de 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 migrar as informações do AssemblyInfo.cs para o arquivo de projeto em cada projeto, e remover o arquivo AssemblyInfo.cs.

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

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

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

Atualizar dependências do aplicativo

Geralmente, Xamarin.Forms os pacotes NuGet não são compatíveis com o .NET 8, a menos que tenham sido recompilados usando TFMs (monikers da estrutura de destino do .NET). No entanto, os aplicativos Android podem usar pacotes NuGet direcionados aos frameworks monoandroid e monoandroidXX.X.

Você pode confirmar que um pacote é compatível com o .NET 8 examinando a guia Estruturas no NuGet para o pacote que você está usando e verificando 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 .NET Standard que não têm dependências nas estruturas incompatíveis listadas acima ainda são compatíveis com o .NET 8.

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

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

  • Recompile o pacote com os TFMs do .NET, se você for o proprietário do código.
  • Procure uma prévia da versão .NET 8 do pacote.
  • Substitua a dependência por uma alternativa compatível com .NET 8.

Compilar e solucionar problemas

Depois que suas dependências forem resolvidas, você deverá criar seu projeto. Todos os erros o orientarão para as próximas etapas.

Dica

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

A tabela a seguir fornece diretrizes para superar problemas comuns de build ou runtime:

Questão Dica
Xamarin.* o namespace não existe. Atualize o namespace para seu equivalente .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 de MAUI do .NET. Para obter mais informações, consulte as alterações de API.
O aplicativo não será implantado. Verifique se o projeto de plataforma necessário está definido para ser implantado no Configuration Manager do Visual Studio.
O aplicativo não está iniciando. Atualize a classe de ponto de entrada de cada projeto de plataforma e o ponto de entrada do aplicativo. Para obter mais informações, consulte Configure seu aplicativo migrado.
CollectionView não rola. Verifique o layout do contêiner e o tamanho medido do CollectionView. Por padrão, o controle ocupará o máximo de espaço que o contêiner permitir. Um Grid limita as crianças dentro de seu próprio tamanho. No entanto, um StackLayout permite que as crianças ocupem espaço além de seus limites.
O pop-up é exibido embaixo da página no iOS. Em Xamarin.Forms, todos os pop-ups no iOS são instâncias de UIWindow, mas no .NET MAUI, os pop-ups são exibidos ao localizar o elemento ViewController atual e exibir o pop-up com PresentViewControllerAsync. Em plug-ins como o Mopups, para garantir que seus pop-ups sejam exibidos corretamente, você deve chamar DisplayAlert (ou DisplayAlertAsync no .NET 10+), DisplayActionSheet (ou DisplayActionSheetAsync no .NET 10+), ou DisplayPromptAsync do ContentPage que é usado dentro do pop-up Mopup.
BoxView não está aparecendo. O tamanho padrão de uma BoxView entrada Xamarin.Forms é 40 x 40. O tamanho padrão de um BoxView em .NET MAUI é 0x0. Defina WidthRequest e HeightRequest seja 40.
O layout carece de padding, margem ou espaçamento. Adicione valores padrão ao seu projeto com base no recurso de estilo .NET MAUI. Para mais informações, veja Mudanças nos valores padrão de Xamarin.Forms.
O layout personalizado não funciona. O código de layout personalizado precisa ser atualizado para funcionar no MAUI do .NET. Para obter mais informações, consulte Alterações de layout personalizadas.
O renderizador personalizado não funciona. O código do renderizador precisa ser atualizado para funcionar no MAUI do .NET. Para obter mais informações, consulte Usar renderizadores personalizados no .NET MAUI.
O efeito não funciona. O código de efeito precisa ser atualizado para funcionar no MAUI do .NET. Para obter mais informações, consulte Efeitos de uso no MAUI do .NET.
SkiaSharp O código não funciona. SkiaSharp O código precisa de pequenas atualizações para funcionar no MAUI do .NET. Para obter mais informações, veja Reutilizar SkiaSharp código no .NET MAUI.
Não é possível acessar dados de propriedades de aplicativo criados anteriormente. Migre os dados das propriedades do aplicativo para as preferências do .NET MAUI. Para obter mais informações, consulte Xamarin.Forms.
Não é possível acessar dados de armazenamento seguro criados anteriormente. Migre os dados de armazenamento seguros para o MAUI do .NET. Para obter mais informações, consulte Migrar do Xamarin.Essentials armazenamento seguro 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 MAUI do .NET. Para obter mais informações, consulte Migrar dados de controle de versão de um Xamarin.Forms aplicativo para um aplicativo MAUI do .NET.