ترحيل مشروع من .NET Framework إلى .NET 10: دليل عملي خطوة بخطوة

هل لديك تطبيق يعمل على .NET Framework 4.8 أو ASP.NET MVC 5، وتريد نقله إلى .NET الحديثة دون تعطيل العمل أو إعادة كتابة آلاف الأسطر دفعة واحدة؟ التحدي الحقيقي ليس تغيير TargetFramework فحسب؛ بل تحديد أجزاء النظام التي يمكن نقلها، والتعامل مع System.Web، والمكتبات القديمة، والمصادقة، وقاعدة البيانات، ثم إصدار النسخة الجديدة تدريجيا مع إمكانية الرجوع الآمن.

هذا دليل عملي لمطور أو قائد فريق يتعامل مع نظام قائم في الإنتاج. سنبني خطة انتقال من .NET Framework إلى .NET 10 LTS، مع مثال صغير لنقل Controller من ASP.NET MVC 5 إلى ASP.NET Core، وقائمة مراجعة لاختبار النظام، وسيناريو واضح للـRollback. لا نفترض أن ترحيل النظام بالكامل يتم بأمر واحد، ولا أن إعادة كتابة كل شيء هي أفضل قرار.

إذا كنت تريد معرفة الفرق الأساسي بين .NET و.NET Framework قبل بدء المشروع، فاقرأ أولا دليل مشاكس عن .NET الحديثة و.NET Framework. هنا سنركز على قرار الترحيل وتنفيذه بأقل مخاطرة، وليس على تعلم C# من البداية.

هل يمكنك نقل مشروع .NET Framework مباشرة إلى .NET 10؟

الجواب: أحيانا لبعض المكتبات والتطبيقات الصغيرة، لكن ليس عادة لتطبيق ASP.NET MVC 5 إنتاجي كبير دون تغييرات. فكود MVC 5 يعتمد على System.Web.Mvc ودورة معالجة الطلبات في ASP.NET Framework. أما ASP.NET Core فهو إطار ويب مختلف له بنية Middleware وDependency Injection وConfiguration وHosting جديدة.

بحسب دليل Microsoft الرسمي للهجرة إلى ASP.NET Core، يصبح الترحيل التدريجي أنسب لمعظم التطبيقات الإنتاجية الكبيرة، في حين يمكن اختيار النقل المباشر لمشروع صغير يعتمد على عدد محدود من المكونات المتوافقة.

نقطة مهمة في أكتوبر 2026: .NET 10 إصدار LTS مدعوم حتى نوفمبر 2028، بينما ينتهي دعم .NET 8 و.NET 9 خلال نوفمبر 2026 بحسب سياسة دعم .NET. لذلك إذا كنت تبدأ مشروع ترحيل جديد الآن ولا توجد قيود توافق تمنع ذلك، فالاستهداف الأولي المنطقي هو .NET 10 بعد التحقق من توافق الأدوات والمكتبات. أما .NET Framework نفسه فله دورة دعم مختلفة مرتبطة بإصدارات Windows المدعومة.

المرحلة الأولى: اعرف ما لديك قبل كتابة أي كود

أسوأ بداية هي إنشاء مشروع ASP.NET Core جديد ثم نسخ كل الملفات إليه على أمل إصلاح أخطاء البناء لاحقا. ابدأ بـMigration Inventory يسجل كل مشروع وتبعياته ومسؤول تشغيله ومدى خطورته.

1. أنشئ قائمة بجميع المشروعات

احصر Web App وClass Libraries وBackground Jobs وWindows Services وأي مشاريع اختبارات. سجل هل ما زالت تستخدم packages.config أو تنسيق مشاريع قديم، وأي منها مرتبط بإصدارات Windows أو IIS.

يمكن أن تبدأ بجدول بسيط مثل هذا، وقيمه مجرد مثال توضيحي وليست بيانات مشروع حقيقي:

Project,Type,Target,Dependencies,Framework-only APIs,Owner,Tests,Risk
Legacy.Web,ASP.NET MVC 5,net48,EF6;OWIN,System.Web,Web Team,Smoke,High
Legacy.Domain,Class Library,net48,None,None,Backend,Unit,Low
Legacy.Reports,Class Library,net48,Vendor DLL,GDI+/COM,Backend,Integration,High

2. حدد نقاط الارتباط الخطرة

• System.Web: مثل HttpContext.Current وHttpModule وHttpHandler، والجلسات القديمة.
• Authentication: Forms Authentication وOWIN Cookies وWindows Authentication وأنظمة Identity المخصصة.
• Database: Entity Framework 6 أو ADO.NET أو Stored Procedures، وطرق إدارة Schema وTransactions.
• ملفات خارجية: مكتبات DLL لا تدعم .NET الحديثة، وCOM وGDI+ ومكونات تقارير قديمة.
• مشغلات الخلفية: Scheduled Tasks أو Jobs مرتبطة بتطبيق الويب ودورة حياة IIS.
• الواجهة: Razor Views القديمة وBundling وStatic Files والمسارات المستخدمة في روابط Google أو تكاملات API.

توصي Microsoft بتحليل التبعيات ومراجعة Target Framework Monikers قبل الانتقال. وجود مكتبة تستهدف net48 لا يعني أنها ستعمل في net10.0 تلقائيا؛ وقد يظهر تحذير توافق دون أن يضمن نجاح التشغيل.

3. اجمع خط أساس (Baseline) قبل التحويل

احفظ نتائج البناء والاختبارات الحالية، وخذ نسخة احتياطية قابلة للاستعادة من قاعدة البيانات وإعدادات الإنتاج، وسجل أهم المسارات ومقاييس أدائها. الاختبارات المطلوبة تشمل تسجيل الدخول والخروج والبحث وإنشاء البيانات وتعديلها ورفع الملفات وإرسال الرسائل والتكامل مع الخدمات الخارجية.

من دون هذا الخط الأساس لن تستطيع التفرقة بين مشكلة موجودة قبل الترحيل ومشكلة أحدثها الترحيل.

المرحلة الثانية: اختر استراتيجية الترحيل

الاختيار الأول: Big Bang Migration

توقف التطوير مؤقتا، وانقل المشروع بالكامل إلى إطار جديد، ثم استبدل الإصدار القديم دفعة واحدة. قد يكون مقبولا في أداة داخلية صغيرة قليلة المستخدمين، لكنه خطر إذا كان لديك نظام إنتاجي واسع يعتمد عليه العملاء يوميا.

الاختيار الثاني: Incremental Migration بنمط Strangler Fig

هذا هو الخيار الذي نرشحه لمعظم تطبيقات ASP.NET MVC 5 الكبيرة: شغّل تطبيق ASP.NET Core بجانب التطبيق القديم، ثم وجّه بعض الطلبات إلى الجديد واترك المسارات غير المنقولة تعمل على القديم. تقدم Microsoft مسارا رسميا يستخدم YARP Reverse Proxy مع System.Web Adapters لتسهيل بعض سيناريوهات الانتقال.

مخطط حركة الطلبات:

المستخدم
   |
   v
المدخل العام / Reverse Proxy
   |-- /products/...  ---> ASP.NET Core (المسار الجديد)
   |-- /orders/...    ---> ASP.NET MVC 5 (المسار القديم)
   '-- /account/...   ---> حسب استراتيجية المصادقة المشتركة

أنت لا تنقل طلبا واحدا بين Framework وCore داخل نفس عملية التشغيل. الفكرة هي وجود تطبيقين منفصلين وربطهما على مستوى HTTP مع الحفاظ على تجربة المستخدم.

يمكنك اتباع خطوات Microsoft في Getting started with incremental migration. مثالنا هنا يوضح القرار والبنية فقط؛ إعداد الـProxy والإعدادات الأمنية بين التطبيقين يجب تطبيقه وفقا للدليل الرسمي، وليس باستخدام قواعد تحويل عشوائية قد تمرر طلبات غير مقصودة.

المرحلة الثالثة: انقل أول مسار صغير من MVC 5 إلى ASP.NET Core

افترض أن لدينا تطبيق MVC 5 فيه Controller يعيد حالة الخدمة. في المشروع القديم قد يكون كالتالي:

using System.Web.Mvc;

public class StatusController : Controller
{
    public ActionResult Index()
    {
        return Json(
            new { service = "legacy", status = "ok" },
            JsonRequestBehavior.AllowGet);
    }
}

الاعتماد هنا على System.Web.Mvc وطريقة JsonRequestBehavior.AllowGet الخاصة بـMVC القديم. هدفنا أن ننقل هذا المسار المحدود ونختبره من دون نقل تسجيل الدخول وقاعدة البيانات والواجهة كلها دفعة واحدة.

1. أنشئ مشروع ASP.NET Core جديد

على جهاز مثبت عليه .NET 10 SDK:

dotnet new mvc -n ModernWeb -f net10.0
cd ModernWeb
dotnet build

هذا الأمر ينشئ مشروع MVC جديدا. ليس ترحيلا آليا لمشروع MVC 5، لكنه يوفر هدفا نظيفا ننقل إليه المسارات والخدمات خطوة خطوة.

2. انقل الـController مع تغيير الواجهة البرمجية

في ASP.NET Core يصبح المثال:

using Microsoft.AspNetCore.Mvc;

public class StatusController : Controller
{
    [HttpGet]
    public IActionResult Index()
    {
        return Json(new { service = "core", status = "ok" });
    }
}

ويمكن تبسيط ملف Program.cs في مشروع تجريبي لا يحتوي على نظام مصادقة كالتالي:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();

var app = builder.Build();

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.Run();

بعد التشغيل، اختبر /Status/Index وتأكد من صيغة الـJSON ورمز الحالة. ثم انتقل إلى Controllers تقرأ البيانات من خدمات منفصلة بدل وضع منطق الأعمال داخل Controller نفسه.

ملاحظة عملية: عند نقل Controllers الفعلية ستحتاج إلى مراجعة Attributes وFilters وModel Binding وRazor Views وAnti-forgery وRouting وResponse Serialization، وليس استبدال using فقط. توضح وثائق ترحيل MVC وWeb API هذه الفروق بالمثال.

كيف تتعامل مع System.Web وGlobal.asax؟

قد تجد في التطبيق القديم شيفرة تعتمد على HttpContext.Current أو Server.MapPath أو Application_Start. هذه ليست مجرد أسماء مختلفة؛ دورة حياة طلب HTTP وإعداد التطبيق تغيرت.

في المكتبات المشتركة، قد تفيدك System.Web Adapters في بعض السيناريوهات لتقليل التعديل أثناء الانتقال. لكنها ليست إعادة تنفيذ كاملة لكل System.Web ولا تغني عن إعادة تصميم التبعيات على المدى الطويل.

نقل الإعدادات من web.config إلى appsettings.json دون تسريب الأسرار

في التطبيق القديم قد تجد إعدادات appSettings وconnectionStrings داخل web.config. في ASP.NET Core أصبحت الإعدادات جزءا من نظام IConfiguration الذي يقرأ عدة مصادر، منها ملفات JSON ومتغيرات البيئة.

مثال على ملف appsettings.json يحتوي على أسماء المفاتيح دون وضع أي سر حقيقي داخل المستودع:

{
  "ConnectionStrings": {
    "DefaultConnection": ""
  },
  "Features": {
    "NewOrdersPage": false
  }
}

ثم تقرأها في Program.cs أو داخل خدمة مُحقنة:

var connectionString =
    builder.Configuration.GetConnectionString("DefaultConnection");

var newOrdersPageEnabled =
    builder.Configuration.GetValue("Features:NewOrdersPage");

يمكن حقن القيمة الفعلية للاتصال من متغير البيئة ConnectionStrings__DefaultConnection أو Secret Store حسب بيئة النشر. لا تنسخ كلمات المرور من web.config القديم إلى ملف JSON متتبع بـGit.

تنبيه مهم: إذا كنت تستضيف ASP.NET Core خلف IIS فقد يظل هناك ملف web.config لأغراض تكامل الاستضافة، لكن هذا لا يعني العودة إلى نموذج إعدادات ASP.NET Framework القديم. راجع توثيق Microsoft لترحيل الإعدادات.

هل يجب نقل Entity Framework 6 إلى EF Core في المرحلة نفسها؟

ليس بالضرورة، وفي حالات كثيرة من الأفضل فصل القرارين. نقل Runtime وتغيير ORM في إصدار واحد يزيد مساحة الأخطاء المحتملة. تشرح Microsoft في دليل EF6 إلى EF Core أن EF Core إعادة كتابة أساسية وليست Upgrade مباشرًا لـEF6، وأن EF6 يمكنه العمل على .NET الحديثة في سيناريوهات مدعومة.

الخطة الأكثر تحفظا عادة:

1. تحقق من دعم نسخة EF6 ومزوّد قاعدة البيانات للهدف الجديد.
2. احتفظ بـEF6 مبدئيا إذا كان ذلك يخفض مخاطرة ترحيل التطبيق، ثم أعد اختبار الاستعلامات والمعاملات.
3. بعد استقرار التشغيل، انقل جزءا من طبقة البيانات إلى EF Core إذا كانت هناك فائدة واضحة.
4. راجع الاختلافات في Tracking وLoading والعلاقات والتحويلات والاستعلامات، ولا تفترض أن السلوك متطابق حتى لو نجح Compile.

أخطر تفصيلة: سجل EF6 Migrations ليس متوافقا مباشرة مع سجل EF Core Migrations. لا تشغّل عملية ترحيل تلقائية للـSchema على قاعدة بيانات الإنتاج قبل فهم نقطة البداية والتغييرات الممكنة وخطة الرجوع. في فترة تشغيل التطبيقين معًا، ضع خطة Schema متوافقة مع الإصدارين.

تسجيل الدخول وSession: الجزء الذي لا يصح تركه للنهاية

هذا من أكثر الأسباب التي قد تجعل مشروعًا «يعمل على جهاز المطور» لكنه يفشل للمستخدمين عند الانتقال بين صفحة قديمة وأخرى جديدة.

ASP.NET Framework يدعم Forms Authentication وOWIN وWindows Authentication وأنماطا مخصصة، بينما ASP.NET Core يستخدم Authentication Middleware وإعدادات مختلفة. ملف Cookie في النظام القديم ليس بالضرورة صالحا في الجديد دون تنسيق المفاتيح والإعدادات.

تصف Microsoft ثلاث استراتيجيات:

• تطبيق مصادقة جديد: مناسب عندما تستطيع نقل تسجيل الدخول بالكامل وإلغاء اعتماد المستخدمين على النظام القديم.
• Remote Authentication: يمكن لبعض السيناريوهات أن تستعلم من التطبيق القديم عن هوية المستخدم خلال الترحيل التدريجي باستخدام Adapters؛ لها تكلفة اتصال وحدود، ولا تدعم كل سيناريوهات Windows Authentication بنفس الطريقة.
• Shared Cookie: متاحة بشروط لتطبيقات تستخدم OWIN Cookies وتتطلب توافق إعدادات مفاتيح التشفير وData Protection؛ ليست حلا جاهزا لكل Forms Authentication قديم.

أما Session، فتختلف في ASP.NET Core أساليب التسلسل والتزامن وقفل الجلسة عن ASP.NET Framework. إذا كانت جلسات المستخدمين مشتركة بين التطبيقين فراجع خيارات System.Web Adapters والـRemote Session في دليل ترحيل Session الرسمي.

اختبار إلزامي: سجل دخولك في المسار القديم، ثم افتح مسارا نُقل إلى الجديد، ثم عد إلى مسار قديم، ثم اختبر تسجيل الخروج. إذا فقد المستخدم الجلسة أو احتاج لتسجيل الدخول مرتين، فلا تنتقل إلى الإنتاج.

خطة اختبار عملية قبل نقل أول Route إلى الإنتاج

نجاح dotnet build ليس معيار نجاح الترحيل. استخدم قائمة تحقق تبدأ من السيناريوهات التي يتعامل معها المستخدم فعلا:

ابدأ بمسار قراءة GET بسيط، مثل صفحة تفاصيل أو استعلام غير مؤثر، ثم انتقل إلى مسار فيه قاعدة بيانات، ثم مسار يحتاج مصادقة، وأخيرا الوظائف التي تُحدث تغييرات مالية أو تشغيلية. لا تكرر تلقائيا طلبات POST في تطبيقين لإجراء مقارنة صامتة؛ فقد تؤدي إلى تكرار عمليات دفع أو تحديثات.

خطة Rollout وRollback: كيف ترجع دون إفساد البيانات؟

لنفرض أننا نقلنا مسار /products إلى تطبيق ASP.NET Core. الأفضل أن يكون تحويل المسار قابلا للعكس عبر طبقة التوجيه دون الحاجة لإعادة نشر النظام القديم في كل مرة.

1. قبل الإطلاق: خذ Backup وتأكد أن عملية الاستعادة اختُبرت، وثبت إعدادات النسختين وتوثيق النسخة المنشورة.
2. إطلاق محدود: فعّل المسار الجديد لمجموعة داخلية أو شريحة محدودة مع مراقبة الأخطاء والـlatency، مع مراعاة ثبات الجلسات.
3. مراقبة واضحة: قارن عدد الطلبات والأخطاء ونتائج الأعمال، لا استجابة HTTP فقط.
4. إذا ظهرت مشكلة: أعد توجيه المسار إلى التطبيق القديم عبر الـProxy، مع إبقاء سجلات التطبيق الجديد للتحقيق.
5. قبل الرجوع: تأكد أن تغييرات قاعدة البيانات ما زالت متوافقة مع القديم، وأن أي Jobs أو Messages لم تُعالج مرتين.

قاعدة مهمة: الرجوع بالتوجيه ليس ضمانا إذا كان الترحيل قد حذف أعمدة أو عدل بيانات بصورة غير قابلة للرجوع. اعتمد على تغييرات Schema تدريجية ومتوافقة للأمام والخلف قدر الإمكان، وافصل توقيت حذف الحقول القديمة عن إطلاق الكود الجديد.

هل توجد أداة تساعد على ترحيل المشروع تلقائيا في 2026؟

نعم، لكن يجب تحديث أي دليل قديم يقول إن .NET Upgrade Assistant ما زالت الأداة الأساسية الجديدة. توضح وثائق Microsoft الحالية أن Upgrade Assistant أصبحت Deprecated، وتوجه أعمال التحديث الجديدة إلى GitHub Copilot app modernization agent داخل إصدارات Visual Studio المدعومة.

تساعد الأداة الحديثة في تحليل المشاريع والتبعيات وتقديم خطة ترحيل وتعديلات برمجية شائعة، لكنها لا تلغي مسؤولية الفريق عن المصادقة وبيانات العملاء والاختبارات والتوافق ومراقبة الإنتاج. إن لم تكن الأداة متاحة في بيئتك، تستطيع تنفيذ خطوات التحليل والنقل اليدوي وفق أدلة Microsoft الرسمية.

خطة تنفيذ واقعية على أربع مراحل

لا تعطِ الفريق موعدا نهائيا بناء على عدد Controllers فقط. الصعوبة الفعلية غالبا في القواعد التجارية غير المختبرة والتبعيات الخارجية والحالة المشتركة وقاعدة البيانات. اجعل التقدير بعد الـAssessment وأول Pilot، لا قبلهما.

أخطاء شائعة تفسد مشروع الترحيل

• اعتبار تغيير TargetFramework كافيا: ASP.NET MVC 5 وASP.NET Core ليسا التطبيق نفسه بإصدار مختلف.
• نقل EF6 إلى EF Core مع باقي التغييرات دفعة واحدة: يزيد عدد المتغيرات ويصعب تحديد سبب العطل.
• نسيان Session والمصادقة حتى نهاية المشروع: يؤدي إلى خروج المستخدم أو فقد حالته عند التنقل بين التطبيقين.
• إهمال الروابط العامة: قد تفقد صفحات مفهرسة أو تتعطل تكاملات أنظمة أخرى.
• نشر تغيير Schema مدمر دون توافق: يجعل Rollback للكود بلا جدوى.
• الاعتماد على نجاح الـBuild فقط: لا يكشف أخطاء الاستخدام الفعلي أو الأداء أو التزامن.
• افتراض أن GitHub Copilot سيصلح كل شيء آليا: الأداة تساعد، لكن القرارات الحرجة تحتاج مراجعة بشرية واختبارات.

أسئلة شائعة

هل يمكن تشغيل ASP.NET MVC 5 على .NET 10 مباشرة؟

لا بالطريقة المعتادة التي يُنقل بها ملف مشروع فقط. MVC 5 مبني على ASP.NET Framework وSystem.Web، بينما .NET 10 يستخدم ASP.NET Core للويب الحديث؛ عليك نقل التطبيق أو فصل المسارات والخدمات تدريجيا.

هل الأفضل إعادة كتابة التطبيق بالكامل؟

ليس دائما. يعتمد القرار على حجم المشروع وتبعياته واختباراته ومدة التوقف المقبولة. توصي Microsoft بالترحيل التدريجي كمسار مناسب لمعظم تطبيقات الإنتاج الكبيرة.

هل يجب الانتقال إلى EF Core فور نقل التطبيق؟

لا. يمكن في سيناريوهات مدعومة استخدام EF6 مع .NET الحديثة أولا، ثم نقل طبقة البيانات لاحقا بعد التحقق من التوافق. لا تتعامل مع EF6 Migrations وEF Core Migrations باعتبارهما سجل تغييرات واحدا.

هل يستطيع YARP الحفاظ على كل جلسات المستخدمين تلقائيا؟

لا. الـProxy يحل جزء توجيه الطلبات فقط؛ مشاركة حالة المصادقة والجلسات تحتاج استراتيجية وتكوينا واختبارات إضافية.

هل .NET 10 مناسبة لمشروع ترحيل جديد في 2026؟

غالبا نعم إذا دعمتها المكتبات والأدوات والبنية التحتية لديك؛ فهي إصدار LTS، لكن القرار يجب أن يأتي بعد فحص القيود ومتطلبات المنتج، لا اختيار الإصدار وحده.

الخلاصة

أفضل مشروع ترحيل ليس الأسرع في تغيير أسماء المكتبات، بل الذي ينقل المخاطر إلى مناطق صغيرة قابلة للفحص والرجوع. ابدأ بجرد التبعيات، وحدد المسارات الحساسة، واختر النقل المباشر للمشروعات الصغيرة أو الترحيل التدريجي للتطبيقات الكبيرة، وافصل قدر الإمكان بين ترحيل ASP.NET وترحيل EF، ثم اختبر تسجيل الدخول والبيانات والروابط قبل كل خطوة إنتاجية.

إذا أردت تعميق فهم ما يجري أثناء تنفيذ برنامج .NET بعد نقله، راجع أيضا شرح Compiler وInterpreter وJIT لفهم مراحل ترجمة الكود وتشغيله داخل الـRuntime.

المراجع الرسمية

• Microsoft: Migrate from ASP.NET Framework to ASP.NET Core.
• Microsoft: Incremental ASP.NET migration with YARP and System.Web Adapters.
• Microsoft: Migrating ASP.NET MVC and Web API.
• Microsoft: Authentication migration.
• Microsoft: Session migration.
• Microsoft: Port EF6 to EF Core.
• Microsoft: Analyze third-party dependencies.
• Microsoft: .NET Upgrade Assistant deprecation and modernization alternative.
• Microsoft: .NET releases and support.

آخر مراجعة: 13 أكتوبر 2026. أمثلة الأكواد مبسطة لغرض التعليم وليست قالب Migration جاهزا للإنتاج؛ تحقق من الإصدارات والتبعيات والتكوين الأمني قبل التطبيق.