Uygulamayı Xamarin.Forms el ile çok projeli bir .NET MAUI uygulamasına yükseltme

Çok projeli bir uygulamayı çok projeli Xamarin.Forms bir .NET Çok Platformlu Uygulama Kullanıcı Arabirimi (.NET MAUI) uygulamasına yükseltmek, Xamarin.Android ve Xamarin.iOS projesiyle aynı adımları izler ve .NET MAUI'deki değişikliklerden yararlanmaya yönelik ek adımlar içerir.

Bu makalede, bir Xamarin.Forms kitaplık projesini .NET MAUI kitaplık projesine el ile geçirme açıklanmaktadır. Bunu gerçekleştirmeden önce platform projelerinizi SDK stili projeler olacak şekilde güncelleştirmeniz Xamarin.Forms gerekir. SDK stilindeki projeler tüm .NET iş yükleri tarafından kullanılan proje biçimiyle aynıdır ve birçok Xamarin projesiyle karşılaştırıldığında çok daha az ayrıntılıdır. Uygulama projelerinizi güncelleştirme hakkında bilgi için bkz . Xamarin.Android, Xamarin.iOS ve Xamarin.Mac projelerini .NET'e yükseltme, Xamarin.Android proje geçişi, Xamarin Apple proje geçişi ve Xamarin.Forms UWP proje geçişi.

Bir Xamarin.Forms kitaplık projesini .NET MAUI kitaplık projesine geçirmek için:

Yükseltme işlemini basitleştirmek için, kitaplık projenizle Xamarin.Forms aynı ada sahip yeni bir .NET MAUI kitaplık projesi oluşturmanız ve ardından kodunuzu, yapılandırmanızı ve kaynaklarınızı kopyalamanız gerekir. Aşağıda özetlenen yaklaşım budur.

Uygulamanızı Xamarin.Forms güncelleştirme

Uygulamanızı Xamarin.Forms .NET MAUI'ye yükseltmeden önce uygulamanızı 5 kullanacak Xamarin.Forms şekilde güncelleştirmeli Xamarin.Forms ve hala düzgün çalıştığından emin olmalısınız. Ayrıca, uygulamanızın kullandığı bağımlılıkları en son sürümlere güncelleştirmeniz gerekir.

Bu, ve .NET MAUI arasındaki Xamarin.Forms API farklarını en aza indirgeyeceği için geçiş işleminin geri kalanını basitleştirmeye yardımcı olur ve varsa bağımlılıklarınızın .NET uyumlu sürümlerini kullandığınızdan emin olur.

Yeni proje oluşturma

Visual Studio'da, kitaplık projenizle Xamarin.Forms aynı ada sahip yeni bir .NET MAUI sınıf kitaplığı projesi oluşturun. Bu proje, kitaplık projenizdeki Xamarin.Forms kodu barındıracak. Proje dosyasını açtığınızda .NET SDK stilinde bir projeniz olduğunu onaylar:

<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>

Platform projelerinizde bu yeni kitaplık projesine bir başvuru ekleyin. Ardından kitaplık dosyalarınızı .NET MAUI kitaplık projesine kopyalayın Xamarin.Forms .

Ad alanı değişiklikleri

.NET MAUI'den Xamarin.Forms .NET MAUI'ye geçişte ad alanları değişti ve Xamarin.Essentials özellikler artık .NET MAUI'nin bir parçasıdır. Ad alanı güncelleştirmeleri yapmak için aşağıdaki ad alanları için bir bulma ve değiştirme gerçekleştirin:

.NET MAUI projeleri örtük global using yönergeleri kullanır. Bu özellik, ad alanı yönergelerini Xamarin.Essentials eşdeğer .NET MAUI ad alanlarıyla değiştirmek zorunda kalmadan kaldırmanıza using olanak tanır.

Ayrıca, .NET MAUI'de Xamarin.Forms http://schemas.microsoft.com/dotnet/2021/maui varsayılan XAML ad alanı olarak değiştirildihttp://xamarin.com/schemas/2014/forms. Bu nedenle, öğesinin xmlns="http://xamarin.com/schemas/2014/forms" tüm oluşumlarını ile xmlns="http://schemas.microsoft.com/dotnet/2021/maui"değiştirmelisiniz.

API değişiklikleri

Bazı API'ler .NET MAUI'den Xamarin.Forms geçişte değişti. Bu, .NET MAUI'nin parçası olmanın neden olduğu Xamarin.Essentials yinelenen işlevleri kaldırma ve API'lerin .NET adlandırma yönergelerini izlemesini sağlama gibi birden çok nedendir. Aşağıdaki bölümlerde bu değişiklikler açıklanmıştır.

Renk değişiklikleri

içinde Xamarin.FormsXamarin.Forms.Color yapısı, değerleri kullanarak double nesneler oluşturmanıza Color olanak tanır ve gibi Xamarin.Forms.Color.AliceBlueadlandırılmış renkler sağlar. .NET MAUI'de bu işlev sınıfına ve sınıfına ayrılmıştır Microsoft.Maui.Graphics.Color Microsoft.Maui.Graphics.Colors .

Microsoft.Maui.Graphics.Color sınıfı, ad alanında Microsoft.Maui.Graphics değerleri, byte değerleri ve int değerleri kullanarak float nesneler oluşturmanıza Color olanak tanır. Microsoft.Maui.Graphics.Colors Ad alanında Microsoft.Maui.Graphics da bulunan sınıfı büyük ölçüde aynı adlandırılmış renkleri sağlar. Örneğin, rengi belirtmek AliceBlue için kullanınColors.AliceBlue.

Aşağıdaki tabloda yapı ile sınıf arasındaki Xamarin.Forms.Color API değişiklikleri gösterilmektedir Microsoft.Maui.Graphics.Color :

Buna ek olarak, içinde kullanılan sayısal değerlerin Microsoft.Maui.Graphics.Color tümü yerine şeklindedirfloatdouble.Xamarin.Forms.Color

Düzen değişiklikleri

Aşağıdaki tabloda ,NET MAUI'den Xamarin.Forms .NET MAUI'ye geçişte kaldırılan düzen API'leri listelenmiştir:

Buna ek olarak, içindeki koddaki Xamarin.Forms bir düzene alt öğeler eklemek, alt öğeleri düzenin Children koleksiyonuna ekleyerek gerçekleştirilir:

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

.NET MAUI'de, Children koleksiyon .NET MAUI tarafından dahili kullanıma yöneliktir ve doğrudan işlenmemelidir. Bu nedenle kodda alt öğeler doğrudan düzene eklenmelidir:

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

Yükseltilmiş .NET MAUI uygulamanızı çalıştırırken düzen davranışının farklı olduğunu fark edebilirsiniz. Daha fazla bilgi için bkz. düzen davranışı değişiklikleri.Xamarin.Forms

Özel düzen değişiklikleri

içinde Xamarin.Forms özel düzen oluşturma işlemi, öğesinden Layout<View>türetilen bir sınıf oluşturmayı ve ve Layout.LayoutChildren yöntemlerini geçersiz kılmayı VisualElement.OnMeasure içerir. Daha fazla bilgi için bkz . içinde Xamarin.Formsözel düzen oluşturma.

.NET MAUI'de düzen sınıfları soyut Layout sınıftan türetilir. Bu sınıf, platformlar arası düzeni ve ölçümü düzen yöneticisi sınıfına devreder. Her düzen yöneticisi sınıfı, ve ArrangeChildren uygulamalarının ILayoutManager sağlanması gerektiğini belirten Measure arabirimini uygular:

• Uygulama Measure , düzendeki her görünümü çağırır IView.Measure ve kısıtlamalara göre düzenin toplam boyutunu döndürür.
• Uygulama, ArrangeChildren her görünümün düzenin sınırları içinde nereye yerleştirileceğini belirler ve her görünüme uygun sınırlarıyla çağrılar Arrange . Dönüş değeri, düzenin gerçek boyutudur.

Daha fazla bilgi için bkz . Özel düzenler.

Cihaz değişiklikleri

Xamarin.Forms , uygulamanın üzerinde çalıştığı cihaz ve platformla etkileşim kurmanıza yardımcı olan bir Xamarin.Forms.Device sınıfa sahiptir. .NET MAUI, Microsoft.Maui.Controls.Deviceiçindeki eşdeğer sınıf kullanım dışıdır ve işlevselliği birden çok türle değiştirilir.

Aşağıdaki tabloda, sınıfındaki işlevselliğin .NET MAUI değişimleri gösterilmektedir Xamarin.Forms.Device :

Eşleme değişiklikleri

Map içindeXamarin.Forms, denetim ve ilişkili türler ad alanındadırXamarin.Forms.Maps. .NET MAUI'de bu işlev ve Microsoft.Maui.Maps ad alanlarına taşınmıştırMicrosoft.Maui.Controls.Maps. Bazı özellikler yeniden adlandırıldı ve bazı türler den Xamarin.Essentialseşdeğer türlerle değiştirildi.

Aşağıdaki tabloda, ad alanında Xamarin.Forms.Maps işlevselliğin .NET MAUI değişimleri gösterilmektedir:

.NET MAUI'nin iki Map türü vardır: Microsoft.Maui.Controls.Maps.Map ve Microsoft.Maui.ApplicationModel.Map. Microsoft.Maui.ApplicationModel Ad alanı .NET MAUI'nin global using yönergelerinden biri olduğundan, koddaki Microsoft.Maui.Controls.Maps.Map denetimi kullanırken kullanımınızı tam olarak nitelemeniz Map veya bir diğer ad kullanmanız gerekir.

XAML'de, denetim için Map bir xmlns ad alanı tanımı eklenmelidir. Bu gerekli olmasa da, hem hem de Microsoft.Maui.Controls.Shapes Microsoft.Maui.Controls.Maps ad alanında bulunan ve Polyline türleri arasında Polygon çakışmayı önler. Daha fazla bilgi için bkz . Harita görüntüleme.

Diğer değişiklikler

.NET MAUI'den Xamarin.Forms .NET MAUI'ye geçişte az sayıda başka API birleştirilmiştir. Aşağıdaki tabloda bu değişiklikler gösterilmektedir:

Buna ek olarak, içindeXamarin.FormsPage.OnAppearing, bir uygulama arka planlandığında ve ardından ön plana getirildiğinde, geçersiz kılma Android'de çağrılır. Ancak, bu geçersiz kılma aynı senaryoda iOS ve Windows'ta çağrılmaz. .NET MAUI'de, OnAppearing() bir uygulama arka planlandığında ve ardından ön plana getirildiğinde geçersiz kılma hiçbir platformda çağrılmaz. Bunun yerine, bir uygulama ön plana döndüğünde bildirim almak için yaşam döngüsü olaylarını Window dinlemeniz gerekir. Daha fazla bilgi için bkz . .NET MAUI pencereleri.

Yerel form değişiklikleri

içindeki Xamarin.Forms yerel formlar .NET MAUI'de yerel eklemeye dönüştü ve platformlar arası denetimleri yerel türlerine dönüştürmek için farklı bir başlatma yaklaşımı ve farklı uzantı yöntemleri kullanıyor. Daha fazla bilgi için bkz . Yerel ekleme.

Geçirilen uygulamanızı önyükleme

Bir Xamarin.Forms uygulamayı .NET MAUI'ye el ile güncelleştirirken her platform projesinde .NET MAUI desteğini etkinleştirmeniz, her platform projesinin giriş noktası sınıfını güncelleştirmeniz ve ardından .NET MAUI uygulamanızın önyüklemesini yapılandırmanız gerekir.

Platform projelerinde .NET MAUI'yi etkinleştirme

Her platform projesinin giriş noktası sınıfını güncelleştirmeden önce .NET MAUI desteğini etkinleştirmeniz gerekir. Bu, her platform projesinde $(UseMaui) derleme özelliği true olarak ayarlanarak elde edilebilir:

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

Paket başvuruları ekleme

.NET 8'de .NET MAUI bir .NET iş yükü ve birden çok NuGet paketi olarak sunulur. Bu yaklaşımın avantajı, projelerinizi belirli sürümlere kolayca sabitlemenize ve ayrıca yayınlanmamış veya deneysel derlemeleri kolayca önizlemenize olanak sağlamasıdır.

Her proje dosyasına aşağıdaki açık paket başvurularını <ItemGroup> eklemelisiniz:

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

$(MauiVersion) Değişkenine yüklediğiniz .NET MAUI sürümünden başvurulur. Derleme özelliğini her proje dosyasına ekleyerek $(MauiVersion) bunu geçersiz kılabilirsiniz:

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

Android proje yapılandırması

.NET MAUI Android projenizde sınıfı aşağıdaki MainApplication kodla eşleşecek şekilde güncelleştirin:

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();
    }
}

Ayrıca sınıfını MainActivity öğesinden MauiAppCompatActivitydevralacak şekilde güncelleştirin:

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);
        }
    }
}

Ardından bildirim dosyanızı güncelleştirerek .NET MAUI için gereken en düşük Android SDK sürümünün 21 olduğunu belirtin minSdKVersion . Bu, düğümün <uses-sdk /> alt <manifest> öğesi olan düğümü değiştirerek elde edilebilir:

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

iOS proje yapılandırması

.NET MAUI iOS projenizde sınıfını öğesinden MauiUIApplicationDelegatedevralacak şekilde güncelleştirinAppDelegate:

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();
    }
}

Ardından Info.plist dosyasını 11.0 olacak şekilde MinimumOSVersion güncelleştirin. Bu, .NET MAUI için gereken en düşük iOS sürümüdür.

UWP proje yapılandırması

.NET MAUI WinUI 3 projenizde App.xaml dosyasını aşağıdaki kodla eşleşecek şekilde güncelleştirin:

<?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>

Ayrıca, App.xaml.cs aşağıdaki kodla eşleşecek şekilde güncelleştirin:

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();
}

Ardından projenin Özellikler klasörüne bir launchSettings.json dosyası ekleyin ve dosyaya aşağıdaki JSON dosyasını ekleyin:

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

Uygulama giriş noktası

.NET MAUI uygulamalarının tek bir platformlar arası uygulama giriş noktası vardır. Her platform giriş noktası statik sınıfta bir CreateMauiApp yöntem çağırır ve döndürürMauiApp.MauiProgram

Bu nedenle, aşağıdaki kodu içeren adlı MauiProgram yeni bir sınıf ekleyin:

namespace YOUR_NAMESPACE_HERE;

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

        return builder.Build();
    }
}

.NET MAUI'ye geçirilmesi gereken platforma özgü hizmetler varsa, belirtilen türdeki geçici bir hizmeti belirtilen IServiceCollectionöğesine eklemek için yöntemini kullanınAddTransient(IServiceCollection, Type).

AssemblyInfo değişiklikleri

Genellikle bir AssemblyInfo.cs dosyasında ayarlanan özellikler artık SDK stili projenizde kullanılabilir. Bunları her projedeki AssemblyInfo.cs proje dosyanıza geçirmenizi ve AssemblyInfo.cs dosyasını kaldırmanızı öneririz.

İsteğe bağlı olarak, AssemblyInfo.cs dosyasını tutabilir ve proje dosyanızdaki özelliğini olarak falseayarlayabilirsinizGenerateAssemblyInfo:

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

özelliği hakkında GenerateAssemblyInfo daha fazla bilgi için bkz . GenerateAssemblyInfo.

Uygulama bağımlılıklarını güncelleştirme

Genellikle, Xamarin.Forms NuGet paketleri .NET hedef çerçeve takma adları (TFM) kullanılarak yeniden derlenmedikleri sürece .NET 8 ile uyumlu değildir. Ancak Android uygulamaları ve monoandroidXX.X çerçevelerini hedefleyen monoandroid NuGet paketlerini kullanabilir.

Kullandığınız paketin NuGet'teki Çerçeveler sekmesine bakarak ve aşağıdaki tabloda gösterilen uyumlu çerçevelerden birini listeleyip listelediğini denetleyerek paketin .NET 8 uyumlu olduğunu onaylayabilirsiniz:

NuGet üzerindeki bir paket, uyumlu olmayan çerçeveler de dahil olmak üzere yukarıdaki uyumlu çerçevelerden herhangi biriyle uyumluluğu gösteriyorsa, paket uyumludur. Uyumlu NuGet paketleri Visual Studio'daki NuGet paket yöneticisi kullanılarak .NET MAUI kitaplık projenize eklenebilir.

NuGet paketinin .NET 8 uyumlu sürümünü bulamıyorsanız:

• Kodun sahibiyseniz paketi .NET TFM'leri ile yeniden derleyebilirsiniz.
• Paketin .NET 8 sürümünün önizleme sürümünü arayın.
• Bağımlılığı .NET 8 uyumlu bir alternatifle değiştirin.

Derleme ve sorun giderme

Bağımlılıklarınız çözümlendikten sonra projenizi oluşturmanız gerekir. Hatalar sonraki adımlarda size yol gösterir.

Aşağıdaki tablo, yaygın derleme veya çalışma zamanı sorunlarının üstesinden gelmek için rehberlik sağlar:

Ayrıca bkz.

• .NET Framework'ten .NET'e taşıma
• .NET Yükseltme Yardımcısı