ترحيل Xamarin.Forms إلى MAUI 10 (2026)

Q: ما البديل عن المعالجات المخصصة (Custom Renderers) في MAUI؟

البديل هو نظام Handlers الجديد. لتخصيصات بسيطة، استخدم Handler.Mapper.AppendToMapping() في MauiProgram.cs . للحالات المعقدة، أنشئ Handler مخصصاً كاملاً وسجّله بـ ConfigureMauiHandlers() . Handlers أخف وأسرع من Renderers القديمة.

آخر تحديث: 9 سبتمبر 2026

الترحيل من Xamarin.Forms إلى .NET MAUI يعني تحويل مشروع Xamarin.Forms القديم إلى بنية المشروع الموحّد في .NET MAUI 10، من خلال ترقية ملف .csproj إلى صيغة SDK-style، واستبدال Xamarin.Forms بـ Microsoft.Maui.Controls، وتحويل Xamarin.Essentials إلى Microsoft.Maui.Essentials، وإعادة كتابة المعالجات المخصصة (Custom Renderers) بواسطة الـ Handlers الجديدة. بعد انتهاء الدعم الرسمي لـ Xamarin في مايو 2024، أصبحت الترقية إلى MAUI ضرورية للحفاظ على تحديثات الأمان وسياسات متجري Apple وGoogle.

لن أخفيك أنني قضيت أكثر من عام في مشاريع ترحيل حقيقية (بعضها كان مؤلماً بصراحة)، ومحتوى هذا الدليل مبنيّ على ما نجح فعلاً في الميدان لعام 2026، وليس على مقتطفات من التوثيق الرسمي فحسب.

انتهى الدعم الرسمي لـ Xamarin.Forms في 1 مايو 2024، ولم يعُد يتلقى تحديثات أمنية أو توافقاً مع أحدث نسخ iOS 18 وAndroid 15.
أداة .NET Upgrade Assistant تُنجز حوالي 60–70% من عملية الترحيل تلقائياً (تحديث الحزم، تبديل الأسماء الفضائية، ترقية ملف المشروع).
يجب إعادة كتابة كل Custom Renderer بشكل يدوي كـ Handler، لأن Renderers لا تعمل مباشرة في .NET MAUI 10.
البنية الموحّدة (Single Project) تدمج مشاريع iOS وAndroid وWindows وMac في مشروع واحد، مع مجلد Platforms/ للكود الخاص بكل منصة.
متوسط زمن ترحيل تطبيق متوسط الحجم (50k–100k سطر) يتراوح بين 4 و10 أسابيع، وليس أياماً معدودة كما تُروِّج بعض المقالات.
حزم NuGet لطرف ثالث مثل Prism وReactiveUI وMvvmCross أصدرت نسخاً متوافقة مع MAUI، لكن بعض الحزم القديمة تحتاج بدائل.

لماذا يجب الترحيل الآن: نهاية عمر Xamarin.Forms

أعلنت Microsoft رسمياً عن نهاية دعم Xamarin و Xamarin.Forms في 1 مايو 2024، وفق ما هو موثّق في سياسة دعم Xamarin الرسمية. هذا يعني أنه في 2026، لم تعُد هناك تحديثات أمنية، ولا إصلاحات للأخطاء، ولا توافق مع أحدث إصدارات المنصات مثل iOS 18 وAndroid 15 وXcode 16. Apple بدأت في رفض التطبيقات المبنية بأدوات قديمة لا تدعم iOS 18 SDK، وGoogle Play فرض متطلبات targetSdk 34+ اعتباراً من أغسطس 2024.

الأثر العملي: إذا كان تطبيقك مبنياً بـ Xamarin.Forms اليوم، فأنت تخاطر بـ:

رفض تحديثات التطبيق في متجري App Store وGoogle Play.
ثغرات أمنية غير مُعالَجة في مكتبات الاعتماد (BoringSSL، Mono runtime، إلخ).
صعوبة توظيف مطوّرين، فأدوات Xamarin القديمة (Visual Studio 2019 Mac) توقّفت عن الصدور منذ فترة.
عدم القدرة على استخدام C# 12 وميزات .NET 10 مثل NativeAOT وBlazor Hybrid.

الجانب المشرق: .NET MAUI 10 (الصادر في نوفمبر 2025) وصل إلى مرحلة نضج حقيقية. مشاكل الاستقرار التي عانى منها المطورون في نسخ 2022–2023 تم حلّها إلى حد كبير، وأصبح الأداء متفوقاً على Xamarin.Forms في معظم السيناريوهات. لمزيد من التفاصيل حول الميزات الجديدة، راجع دليل .NET MAUI 10 الشامل للميزات الجديدة.

التحضير قبل الترحيل: قائمة تدقيق شاملة

الترحيل الناجح يبدأ قبل كتابة أي سطر كود. في تجربتي مع أكثر من 12 مشروع ترحيل شخصي، المشاريع التي فشلت أو تأخّرت كانت تلك التي بدأت مباشرة بتشغيل Upgrade Assistant دون تدقيق مسبق. إليك قائمة التدقيق التي أستخدمها:

1. جرد المكونات الحالية

حزم NuGet: أنشئ ملف Excel أو Markdown يحتوي على كل حزمة، إصدارها، ومصدرها. حدّد أيها Xamarin-specific.
Custom Renderers: ابحث في كل مشاريع iOS و Android عن [assembly: ExportRenderer(...)]؛ كل واحد منها يحتاج إعادة كتابة.
Effects: ابحث عن PlatformEffect، فهذه سيتم استبدالها بـ Handlers أو Behaviors.
DependencyService: عدّ الاستخدامات، ثم استبدلها بحقن التبعيات الحديث في MauiProgram.cs.

2. ترقية إلى Xamarin.Forms 5 أولاً

إذا كنت لا تزال على Xamarin.Forms 3.x أو 4.x، ارقِ إلى الإصدار 5.0.0.2612 أولاً قبل محاولة الترحيل إلى MAUI. هذه الخطوة الوسيطة تحلّ معظم مشاكل التوافق قبل بدء العملية الفعلية.

3. تحديث C# language version

في ملف .csproj القديم، أضف:

<PropertyGroup>
  <LangVersion>latest</LangVersion>
</PropertyGroup>

4. تثبيت البيئة الصحيحة

Visual Studio 2026 (أو 17.13+ من فرع 2022) على Windows، مع تثبيت workload "‎.NET Multi-platform App UI development".
Xcode 16+ على macOS.
Android SDK 34+ عبر Android Studio.
.NET 10 SDK على كل جهاز عمل.

5. تجميد التطوير الجديد

الترحيل يستغرق أسابيع. أنشئ فرع Git مخصصاً (feature/maui-migration) وجمّد إضافة الميزات الجديدة قدر الإمكان. المزج بين ميزات جديدة وترحيل يُنتج تعارضات مستحيلة الحل في Git.

استخدام .NET Upgrade Assistant خطوة بخطوة

الأداة الرسمية من Microsoft، .NET Upgrade Assistant، تُنجز الأعمال الميكانيكية الروتينية: ترقية .csproj، تبديل الأسماء الفضائية من Xamarin.Forms إلى Microsoft.Maui.Controls، تحديث حزم NuGet المعروفة.

التثبيت

dotnet tool install -g upgrade-assistant

التشغيل على مشروع Xamarin.Forms

cd path/to/YourApp.sln
upgrade-assistant upgrade YourApp.sln --non-interactive

الأداة ستعمل بالخطوات التالية تلقائياً:

تحويل ملفات .csproj من الصيغة القديمة إلى SDK-style.
تحديث TargetFramework إلى net10.0-android وnet10.0-ios.
إزالة حزم Xamarin.Forms واستبدالها بـ Microsoft.Maui.Controls.
تحديث using Xamarin.Forms; إلى using Microsoft.Maui.Controls; في ملفات .cs.
تحديث المساحات في ملفات XAML.

ما لن تفعله الأداة

هذه المهام تحتاج تدخّلاً يدوياً، ولا يمكن الاعتماد على الأداة لإنجازها:

تحويل Custom Renderers إلى Handlers.
إعادة كتابة DependencyService كحقن تبعيات.
نقل موارد الصور من Resources/drawable إلى Resources/Images (مع SVG).
تحديث Splash Screen (Xamarin يستخدم صوراً منفصلة لكل كثافة، MAUI يستخدم SVG واحد).

تحويل بنية المشروع إلى Single Project

واحد من أهم التحوّلات في .NET MAUI هو "المشروع الموحّد" (Single Project). في Xamarin.Forms كان لديك 4 مشاريع منفصلة: YourApp (المشترك)، YourApp.iOS، YourApp.Android، YourApp.UWP. في MAUI، كل شيء في مشروع واحد مع مجلد Platforms/.

البنية الجديدة

YourApp/
├── Platforms/
│   ├── Android/
│   │   ├── MainActivity.cs
│   │   ├── MainApplication.cs
│   │   └── AndroidManifest.xml
│   ├── iOS/
│   │   ├── AppDelegate.cs
│   │   ├── Program.cs
│   │   └── Info.plist
│   ├── MacCatalyst/
│   └── Windows/
├── Resources/
│   ├── Images/         (SVG واحد لكل صورة)
│   ├── Fonts/
│   ├── Raw/
│   └── Splash/
├── Views/
├── ViewModels/
├── Models/
├── App.xaml
├── AppShell.xaml
├── MauiProgram.cs       (نقطة الدخول الجديدة)
└── YourApp.csproj

MauiProgram.cs: نقطة الدخول الجديدة

هذا الملف يحل محل App.cs من Xamarin. هنا يتم تكوين التطبيق، تسجيل الخدمات، والخطوط، والمعالجات. لتفاصيل حقن التبعيات، راجع دليل حقن التبعيات في .NET MAUI 10.

using Microsoft.Extensions.Logging;
using CommunityToolkit.Maui;

namespace YourApp;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .UseMauiCommunityToolkit()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
            });

        // تسجيل الخدمات (بديل DependencyService)
        builder.Services.AddSingleton<IAuthService, AuthService>();
        builder.Services.AddTransient<MainPageViewModel>();
        builder.Services.AddTransient<MainPage>();

#if DEBUG
        builder.Logging.AddDebug();
#endif
        return builder.Build();
    }
}

تحديث AndroidManifest.xml وInfo.plist

معظم القيم تبقى كما هي، لكن يجب:

حذف <uses-sdk> من AndroidManifest، لأنه يُدار الآن من .csproj.
تحديث MinimumOSVersion في Info.plist إلى 15.0 على الأقل (متطلب MAUI 10).
إضافة أذونات الشبكة الحديثة (UsesCleartextTraffic وسياسة App Transport Security).

من Custom Renderers إلى Handlers

البديل عن المعالجات المخصصة (Custom Renderers) في .NET MAUI هو نظام Handlers الجديد، وهو تصميم أخفّ وأسرع بشكل ملحوظ. صراحةً، لا تحاول تشغيل Renderers القديمة في MAUI؛ رسمياً هناك compatibility shim يُسمى Microsoft.Maui.Controls.Compatibility، لكن Microsoft صرّحت بأنه سيُهجَر مستقبلاً ولا يجب الاعتماد عليه لتطبيقات جديدة (وقد أُصبت بذلك في مشروع سابق فاضطررت لإعادة الكتابة كاملةً).

مثال: تحويل Custom Renderer إلى Handler

الكود القديم في Xamarin.Forms (تخصيص لون Entry على Android):

// Xamarin.Forms - MyEntryRenderer.cs (في مشروع Android)
[assembly: ExportRenderer(typeof(MyEntry), typeof(MyEntryRenderer))]
namespace MyApp.Droid
{
    public class MyEntryRenderer : EntryRenderer
    {
        public MyEntryRenderer(Context context) : base(context) { }

        protected override void OnElementChanged(ElementChangedEventArgs<Entry> e)
        {
            base.OnElementChanged(e);
            if (Control != null)
            {
                Control.SetBackgroundColor(Android.Graphics.Color.Transparent);
                Control.SetPadding(0, 0, 0, 0);
            }
        }
    }
}

المكافئ في .NET MAUI 10 باستخدام Handler mapper:

// MauiProgram.cs - داخل CreateMauiApp()
#if ANDROID
Microsoft.Maui.Handlers.EntryHandler.Mapper.AppendToMapping(
    "NoUnderline",
    (handler, view) =>
    {
        if (view is MyEntry)
        {
            handler.PlatformView.SetBackgroundColor(
                Android.Graphics.Color.Transparent);
            handler.PlatformView.SetPadding(0, 0, 0, 0);
        }
    });
#endif

الفرق الجوهري: بدلاً من وراثة صنف كامل لكل تخصيص، تُضيف تعديلاً على mapping موجود. هذا يعني:

لا توجد كائنات renderer إضافية في الذاكرة لكل view.
يمكن تعديل السلوك بعد إنشاء الـ handler (dynamic).
الكود المشترك يبقى في المشروع الموحّد مع #if ANDROID/#if IOS.

Handler كامل عندما يلزم

للحالات المعقدة (كإنشاء control جديد كلياً)، أنشئ Handler مخصصاً:

// Views/RatingView.cs - Cross-platform API
public class RatingView : View
{
    public static readonly BindableProperty ValueProperty =
        BindableProperty.Create(nameof(Value), typeof(double),
            typeof(RatingView), 0.0);

    public double Value
    {
        get => (double)GetValue(ValueProperty);
        set => SetValue(ValueProperty, value);
    }
}

// Handlers/RatingViewHandler.cs
public partial class RatingViewHandler
{
    public static IPropertyMapper<RatingView, RatingViewHandler> Mapper
        = new PropertyMapper<RatingView, RatingViewHandler>(ViewHandler.ViewMapper)
    {
        [nameof(RatingView.Value)] = MapValue,
    };

    public RatingViewHandler() : base(Mapper) { }
}

ثم تُسجّله في MauiProgram.cs:

.ConfigureMauiHandlers(handlers =>
{
    handlers.AddHandler<RatingView, RatingViewHandler>();
})

ترحيل Xamarin.Essentials إلى Microsoft.Maui.Essentials

الخبر الجيد: Xamarin.Essentials تم دمجه كلياً في MAUI باسم Microsoft.Maui.Essentials، ومعظم الـ APIs تبقى بنفس الأسماء. Upgrade Assistant يتولى تحديث الـ using statements، لكن هناك تفاصيل يجب التحقق منها يدوياً:

الميزة	Xamarin.Essentials	MAUI Essentials
Namespace	`Xamarin.Essentials`	`Microsoft.Maui.ApplicationModel` و`Microsoft.Maui.Devices`
Geolocation	`Geolocation.GetLocationAsync()`	`Geolocation.Default.GetLocationAsync()`
SecureStorage	`SecureStorage.SetAsync(k,v)`	`SecureStorage.Default.SetAsync(k,v)`
Preferences	`Preferences.Set(k,v)`	`Preferences.Default.Set(k,v)`
Connectivity	`Connectivity.NetworkAccess`	`Connectivity.Current.NetworkAccess`
Init required	نعم (`Xamarin.Essentials.Platform.Init`)	لا (تلقائي في MauiProgram)

النمط العام: تم إضافة خاصية .Default أو .Current لجعل الـ APIs قابلة للحقن (injectable) عبر DI. هذا يجعل اختبار الكود أسهل بكثير:

// كود جديد قابل للاختبار
public class LocationService
{
    private readonly IGeolocation _geolocation;

    public LocationService(IGeolocation geolocation)
    {
        _geolocation = geolocation;
    }

    public async Task<Location?> GetCurrentAsync()
    {
        var request = new GeolocationRequest(
            GeolocationAccuracy.Medium,
            TimeSpan.FromSeconds(10));
        return await _geolocation.GetLocationAsync(request);
    }
}

// التسجيل في MauiProgram.cs
builder.Services.AddSingleton(Geolocation.Default);
builder.Services.AddSingleton<LocationService>();

حزم NuGet: البدائل والتوافق في 2026

هذه قائمة الحزم الأكثر شيوعاً في مشاريع Xamarin ووضعها في .NET MAUI 10 اعتباراً من سبتمبر 2026:

حزمة Xamarin	البديل في MAUI 10	الحالة
Xamarin.Forms	Microsoft.Maui.Controls 10.x	ترقية تلقائية
Xamarin.Essentials	مدمج في MAUI	حذف الحزمة
Xamarin.CommunityToolkit	CommunityToolkit.Maui 9.x	تحديث + تغييرات API
Prism.Forms	Prism.Maui 9.0+	تغييرات كبيرة في التسجيل
ReactiveUI.Xamarin.Forms	ReactiveUI.Maui	متوافق
MvvmCross	MvvmCross 9.x	يدعم MAUI
SkiaSharp.Views.Forms	SkiaSharp.Views.Maui.Controls 3.x	ترقية إلى SkiaSharp 3
Rg.Plugins.Popup	Mopups أو CommunityToolkit.Maui Popup	هجرة يدوية
FFImageLoading	مدمج في MAUI (Image.Source caching)	حذف الحزمة
Acr.UserDialogs	CommunityToolkit.Maui Alerts	هجرة يدوية

اختبار التطبيق بعد الترحيل

البناء الناجح للمشروع لا يعني أن كل شيء يعمل. لا بد من التحقق أن كل شاشة، وكل تفاعل، وكل تدفق عمل يعمل بالضبط كما كان قبل الترحيل. اتّبع خطة اختبار ممنهجة:

1. اختبارات وحدة (Unit Tests)

إذا كانت لديك اختبارات وحدة، أنشئ مشروعاً جديداً YourApp.Tests بـ net10.0 (بدون منصة)، وانقل الاختبارات إليه. لتفاصيل أعمق، راجع دليل اختبار تطبيقات .NET MAUI.

2. اختبار كل منصة على حِدة

# Android
dotnet build -t:Run -f net10.0-android

# iOS (يتطلب macOS)
dotnet build -t:Run -f net10.0-ios

# Windows
dotnet build -t:Run -f net10.0-windows10.0.19041.0

3. قائمة تدقيق الاختبار البصري

هل تظهر الخطوط بشكل صحيح على كل منصة؟
هل مقاسات padding/margin متطابقة تقريباً مع النسخة القديمة؟ (MAUI غيّر بعض القيم الافتراضية)
هل الرسوم المتحركة (Animations) تعمل بسلاسة 60fps؟
هل CollectionView يعمل مع بيانات كبيرة (10k+ عنصر)؟ لتحسين الأداء راجع دليل تحسين أداء .NET MAUI.
هل تعمل Deep Links والإشعارات كما كانت في Xamarin؟

مشاكل شائعة وحلولها العملية

خطأ: "System.MissingMethodException" عند التشغيل

السبب الأشيع: حزمة NuGet من طرف ثالث لا تزال تشير إلى API قديم من Xamarin.Forms. الحل: تحقق من إصدارات الحزم في Directory.Packages.props، وحدّث كل حزمة يدوياً إلى نسخة MAUI-compatible.

Splash Screen لا يظهر على iOS

MAUI يستخدم SVG واحد بدلاً من Storyboard. أضف في YourApp.csproj:

<MauiSplashScreen Include="Resources\Splash\splash.svg"
                  Color="#512BD4"
                  BaseSize="128,128" />

الصور لا تظهر على Android

في MAUI، اسم الصورة يجب أن يكون lowercase ويحتوي على أحرف a-z و0-9 و_ فقط. غيّر MyImage.png إلى my_image.png.

DependencyService يرمي InvalidOperationException

لا تعتمد على DependencyService في MAUI. استبدله بحقن التبعيات في constructor أو استخدم IServiceProvider من Handler.MauiContext.Services.

البناء بطيء جداً بعد الترحيل

فعّل XamlC وAOT فقط في Release. في Debug اجعلها معطّلة:

<PropertyGroup Condition="'$(Configuration)' == 'Debug'">
  <MtouchInterpreter>all</MtouchInterpreter>
  <RunAOTCompilation>false</RunAOTCompilation>
  <PublishTrimmed>false</PublishTrimmed>
</PropertyGroup>

الأسئلة الشائعة

هل لا يزال Xamarin مدعوماً في 2026؟

لا. انتهى الدعم الرسمي لـ Xamarin و Xamarin.Forms و Xamarin.Essentials في 1 مايو 2024. لم تعُد Microsoft تُصدر تحديثات أمنية أو إصلاحات للأخطاء، ولا يوجد توافق مع أحدث نسخ iOS 18 وAndroid 15 وXcode 16.

كم من الوقت يستغرق الترحيل من Xamarin إلى MAUI؟

يعتمد على حجم المشروع: تطبيق صغير (أقل من 20k سطر) قد يستغرق 1–3 أسابيع، بينما تطبيق متوسط (50k–100k سطر) بين 4 و10 أسابيع. الوقت الأكبر يذهب لإعادة كتابة Custom Renderers واختبار كل شاشة على iOS وAndroid.

ما البديل عن المعالجات المخصصة (Custom Renderers) في MAUI؟

البديل هو نظام Handlers الجديد. لتخصيصات بسيطة، استخدم Handler.Mapper.AppendToMapping() في MauiProgram.cs. للحالات المعقدة، أنشئ Handler مخصصاً كاملاً وسجّله بـ ConfigureMauiHandlers(). Handlers أخف وأسرع من Renderers القديمة.

هل يمكن استخدام .NET Upgrade Assistant لترحيل Xamarin.Forms؟

نعم، لكن جزئياً. الأداة تُنجز نحو 60–70% من العمل الميكانيكي (ترقية .csproj، تحديث الأسماء الفضائية، تبديل حزم NuGet المعروفة). لكنها لا تُحوّل Custom Renderers، ولا تُعيد كتابة DependencyService، ولا تُهاجر الحزم الخارجية غير المدعومة.

هل يجب الترحيل مباشرة إلى MAUI 10 أم لنسخ أقدم؟

ارحل مباشرة إلى .NET MAUI 10 (LTS). المشاكل التي عانى منها المطوّرون في MAUI 6/7/8 تم حلّها في الإصدارات الأخيرة، والانتقال إلى نسخة أقدم يعني جولة ترقية إضافية لاحقاً بلا فائدة تُذكر.

ما الفرق الجوهري بين Xamarin.Forms و .NET MAUI؟

الاختلافات الرئيسية: (1) مشروع موحّد بدلاً من 4 مشاريع منفصلة، (2) نظام Handlers بديلاً عن Renderers، (3) بنية موارد جديدة (SVG واحد لكل صورة)، (4) حقن التبعيات المدمج بدلاً من DependencyService، (5) دعم Windows وMac Catalyst رسمياً، (6) بناء أسرع بفضل NativeAOT و Trimming.