تطوير ASP.NET Framework 4.x على macOS باستخدام ServBay

يتيح ServBay، من خلال بيئة Mono القوية والمدمجة، تطوير واختبار تطبيقات ASP.NET Framework 1.1/2.0/3.x/4.x (حتى الإصدار 4.7.x) بسهولة وفاعلية على نظام macOS.

بدءًا من إصدار ServBay v1.12.0، قمنا بدمج Mono 6.14.0، مع توفير خادم التطوير XSP وأداة fastcgi-mono-server، مما يوفر طريقتين رئيسيتين لتشغيل تطبيقات ASP.NET Framework 4.x:

1. التطوير والاختبار السريع باستخدام XSP: XSP هو خادم ويب خفيف الوزن صُمم خصيصًا لـ Mono، ويعد خيارًا مثاليًا لمراحل التطوير والاختبار السريع.
2. النشر باستخدام Nginx + FastCGI: يقدم هذا النهج استقرارًا وأداءً أعلى، ويُحاكي بيئة الإنتاج عبر استخدام Nginx المُدار من ServBay لتحويل الطلبات إلى عملية Mono الخلفية.

ستساعدك هذه الوثيقة في إعداد وتشغيل مشروع ASP.NET Framework 4.x الخاص بك ضمن بيئة ServBay على macOS.

حول .NET Framework و.NET

يرجى ملاحظة أن هذه الوثيقة تركز على تطوير ASP.NET Framework 4.x باستخدام Mono، وهو جزء من تقنيات .NET الأقدم.

يدعم ServBay أيضًا أحدث إصدارات .NET (بما في ذلك .NET Core و .NET 5/6/7/8+). إذا كنت تبدأ مشروعًا جديدًا أو ترغب بالترقية إلى إصدارات .NET الأكثر حداثة، نوصي باستخدام حزمة Microsoft .NET الرسمية المتوفرة في ServBay بدلًا من طريقة ASP.NET Framework القائمة على Mono.

المتطلبات الأساسية

1. تثبيت ServBay: تأكد من تثبيت ServBay بإصدار v1.12.0 أو أحدث على macOS.
2. تثبيت Mono:
   • افتح تطبيق ServBay.
   • من الشريط الجانبي الأيسر، اختر "الحزم".
   • في قائمة الحزم، اعثر على فئة ".NET" ثم وسّعها.
   • ابحث عن "Mono 6" (يجب أن يكون الإصدار 6.14.0 أو أعلى)، ثم اضغط زر "تثبيت" وانتظر حتى انتهاء التثبيت.

تجهيز مشروع ASP.NET الخاص بك

1. ملفات المشروع: تأكد من وجود مشروع Web Application أو Web Site يعتمد على ASP.NET Framework 4.x ويحتوي على ملف web.config.
2. الموقع المقترح للتخزين: ننصح بشدة بوضع مشروع موقعك ضمن مجلد www الذي يديره ServBay مركزيًا والمسار هو: /Applications/ServBay/www/. أنشئ مجلدًا فرعيًا لكل مشروع.
   • مثال: إذا كان اسم مشروعك MyWebApp، فإن المسار الجذري المقترح هو: /Applications/ServBay/www/MyWebApp.
   • سنستخدم /Applications/ServBay/www/MyWebApp كمثال في الخطوات القادمة. يرجى استبداله بمسار مشروعك الفعلي في تطبيقك.

الطريقة الأولى: استخدام XSP (خادم التطوير المدمج)

XSP هو خادم ويب خفيف يأتي مع مشروع Mono ومناسب جدًا للتطوير المحلي والاختبار السريع لتطبيقات ASP.NET Framework. تتضمن حزمة Mono 6 التي يوفرها ServBay النسخة XSP4 (لـ ASP.NET 4.x).

تنبيه

• إذا كنت تشغّل مشروع ASP.NET 1.1، استخدم أمر xsp.
• إذا كنت تشغّل مشروع ASP.NET 2.0/3.x، استخدم أمر xsp2.
• إذا كنت تشغّل مشروع ASP.NET 4.x، استخدم أمر xsp4.

الخطوات:

1. افتح الطرفية: شغّل تطبيق "Terminal" في macOS.

2. انتقل إلى مجلد المشروع: استخدم أمر cd لدخول المسار الجذري لمشروعك ASP.NET (حيث يوجد ملف web.config).

   # مثال: دخول مجلد مشروع اسمه MyWebApp
   cd /Applications/ServBay/www/MyWebApp

3. تشغيل خادم XSP: من المسار الجذري للمشروع، شغّل الخادم باستخدام الأمر التالي. يمكنك تحديد أي منفذ غير مستخدم (مثال 8080 أو 9000) لتفادي التعارض مع خدمات أخرى في ServBay.

   # تشغيل المشروع على المنفذ 9000
   xsp4 --port 9000

   • xsp4: تشغيل خادم XSP المناسب لـ .NET Framework 4.x.
   • --port 9000: تحديد رقم المنفذ الذي سيعمل عليه الخادم.

4. الوصول إلى التطبيق: افتح متصفح الإنترنت وانتقل إلى http://localhost:9000 أو http://127.0.0.1:9000. يجب أن يظهر لك تطبيق ASP.NET قيد التشغيل.

5. إيقاف الخادم: بعد الانتهاء من التطوير أو الاختبار، عد إلى نافذة الطرفية التي يعمل عليها XSP واضغط Ctrl + C أو "Enter" لإيقاف الخادم.

المزايا:

• إعداد سريع وسهل.
• مثالي للتطوير المحلي وتصحيح الأخطاء.

العيوب:

• الأداء أقل من خوادم الإنتاج (مثل Nginx).
• إمكانياته أساسية ولا يُحاكي بيئة الإنتاج بالكامل.
• ضرورة إبقاء نافذة الطرفية مفتوحة.

الطريقة الثانية: استخدام Nginx + FastCGI

في هذه الطريقة، يتم استخدام Nginx الذي يديره ServBay كخادم ويب أمامي يعالج الطلبات من العملاء والملفات الثابتة، بينما يتم تحويل الطلبات الديناميكية (مثل .aspx, .ashx، إلخ) إلى عملية Mono الخلفية (fastcgi-mono-server4) عبر بروتوكول FastCGI. وهذا الحل يقترب كثيرًا من بيئة الإنتاج ويوفر أداءً أفضل مع الاستفادة من ميزات Nginx المتقدمة (مثل SSL، التخزين المؤقت، الضغط، إلخ).

تنبيه

• إذا كنت تشغّل مشروع ASP.NET 1.1، استخدم أمر fastcgi-mono-server.
• إذا كنت تشغّل مشروع ASP.NET 2.0/3.x، استخدم أمر fastcgi-mono-server2.
• إذا كنت تشغّل مشروع ASP.NET 4.x، استخدم أمر fastcgi-mono-server4.

الخطوات:

1. تأكد من تثبيت Mono وNginx وتشغيلهما:

   • قم بتثبيت Mono 6 وNginx عبر "الحزم" في ServBay.
   • في قسم "الخدمات"، تأكد أن خدمة Nginx مفعلة وتعمل.

2. تجهيز مشروع ASP.NET: تأكد أن مشروعك موضوع في المسار المقترح، مثل /Applications/ServBay/www/MyWebApp.

3. تشغيل FastCGI Mono Server:

   • افتح نافذة طرفية جديدة.
   • قم بتشغيل عملية fastcgi-mono-server4 التي تتولى الاستماع لطلبات FastCGI القادمة من Nginx وتشغيل صفحات وخدمات ASP.NET.

     # مثال: تشغيل خدمة FastCGI لمشروع MyWebApp
     fastcgi-mono-server4 --applications=/:/Applications/ServBay/www/MyWebApp \
                          --socket=tcp:127.0.0.1:9001 \
                          --loglevels=Standard \
                          --printlog

     • fastcgi-mono-server4: لتشغيل خادم FastCGI المناسب لـ .NET Framework 4.x.
     • --applications=/:/Applications/ServBay/www/MyWebApp: هذا الخيار يحدد مطابقة المسار على الويب مع المسار الفعلي. /: تعني الجذر (/) و/Applications/ServBay/www/MyWebApp هو المسار الفعلي للمشروع. عندما يُرسل الطلب لـ /some/page.aspx، سيبحث Mono في /Applications/ServBay/www/MyWebApp/some/page.aspx. تأكد من استبدال المسار بمسار مشروعك الفعلي.
     • --socket=tcp:127.0.0.1:9001: تخصيص عنوان المنفذ والـ TCP الذي يسمع عليه خادم FastCGI. تأكد أن المنفذ (مثل 9001) غير مستخدم من خدمات أخرى وأنه متطابق مع المنفذ في إعدادات Nginx أدناه.
     • --loglevels=Standard --printlog: (اختياري) طباعة سجلّ التشغيل القياسي في الطرفية لتسهيل تصحيح المشاكل.
   • تنويه: يجب إبقاء نافذة الطرفية التي تشغل فيها fastcgi-mono-server4 مفتوحة ليعمل التطبيق. للتشغيل طويل الأجل، يمكن استخدام أدوات مثل nohup أو screen أو tmux لجعلها تعمل في الخلفية.

4. إعداد موقع Nginx:

   • في ServBay، انتقل إلى قسم "المواقع".

   • اضغط "إضافة موقع" أو عدّل موقعًا موجودًا.

   • تحديد اسم النطاق: مثل نطاق خاص بك mywebapp.servbay.demo. سيقوم ServBay بإضافته تلقائيًا إلى ملف Hosts في macOS ليرتبط بـ 127.0.0.1.

   • تحديد المسار الجذري للموقع: مهم جدًا! يجب أن يكون مسار مشروعك ASP.NET، مثل /Applications/ServBay/www/MyWebApp ستستخدم هذه القيمة لتعليمات root في إعداد Nginx.

   • تفعيل وتعديل إعدادات مخصصة: فعل خيار "إعدادات مخصصة" في الزاوية العليا للواجهة. سيولّد ServBay ملف إعدادات Nginx أساسي بناءً على النطاق والمسار الجذري. تحتاج لتعديل أو إضافة بعض الخيارات ليدعم تحويل الطلبات الديناميكية إلى FastCGI Mono Server.

     مثال لإعداد قد تحتاج لمراجعته أو تعديله (حسب الإعداد الأساسي في ServBay):

     server {
         listen 80; # الاستماع للطلبات عبر HTTP
         listen 443 ssl http2; # الاستماع للطلبات عبر HTTPS مع تفعيل SSL وHTTP/2
     
         # إعدادات شهادات SSL المدارة أوتوماتيكيًا من ServBay
         ssl_protocols TLSv1.2 TLSv1.3;
         ssl_ciphers 'TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384';
         ssl_prefer_server_ciphers on;
         ssl_session_timeout 1d;
         ssl_session_cache shared:ServBay:10m;
         ssl_session_tickets off;
     
         # مسارات ملفات الشهادة، ستُولد وتُدار تلقائيًا من ServBay
         ssl_certificate /Applications/ServBay/ssl/private/tls-certs/mywebapp.servbay.demo/mywebapp.servbay.demo.crt; # تأكد من تطابق المسار مع اسم النطاق
         ssl_certificate_key /Applications/ServBay/ssl/private/tls-certs/mywebapp.servbay.demo/mywebapp.servbay.demo.key; # تأكد من تطابق المسار مع اسم النطاق
     
         server_name mywebapp.servbay.demo; # يجب أن يتطابق مع اسم النطاق الذي حددته
         root /Applications/ServBay/www/MyWebApp; # **تأكد** من تطابقه مع مسار الموقع
     
         # إضافة وثائق افتراضية لـ ASP.NET. سيحاول Nginx فتحها إذا لم يجد index.html/htm
         index index.html index.htm default.aspx Default.aspx;
     
         # منطق المعالجة الرئيسية للطلبات
         location / {
             # يحاول العثور على ملف أو مجلد مباشرة، وإن لم يجد يحوّل الطلب إلى @mono
             try_files $uri $uri/ @mono;
         }
     
         # (اختياري ولكن موصى به) معالجة ملفات الساكنة بكفاءة وتفعيل التخزين المؤقت
         location ~* \.(ico|css|js|gif|jpe?g|png|svg|woff|woff2|ttf|eot)$ {
             expires max; # زمن التخزين المؤقت الأقصى للمتصفحات
             log_not_found off; # عدم تسجيل أخطاء عدم وجود الملف
             access_log off; # لا تسجل زيارات هذه الملفات لخفض حجم السجلّات
         }
     
         # تعريف منطقة @mono لمعالجة الطلبات الديناميكية
         location @mono {
             # تحويل الطلب إلى خادم Mono عبر FastCGI
             # **يجب أن يكون المنفذ هو نفسه المحدد في أمر fastcgi-mono-server4**
             fastcgi_pass 127.0.0.1:9001;
     
             # تضمين معلمات FastCGI الافتراضية
             include fastcgi_params;
             # أهم معلمة: تعيين مسار ملف السكربت لكي يتمكن Mono Server من تنفيذه
             fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
             # عادة لا حاجة لـ PATH_INFO هنا، لذلك قيمتها فارغة
             fastcgi_param PATH_INFO "";
     
             # (اختياري) يمكن إضافة معلمات FastCGI أخرى مثل HOST عند الحاجة
             # fastcgi_param HOST $host;
         }
     
         # سيضيف ServBay تلقائيًا إعدادات افتراضية مثل مسارات السجلّات
         # access_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.access.log;
         # error_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.error.log;
     }

   • حفظ الإعدادات وإعادة تحميل Nginx: بعد حفظ إعدادات الموقع في ServBay، سيُعاد تحميل إعدادات Nginx أوتوماتيكيًا. إذا حدث خطأ في الإعدادات، سيعرض ServBay رسالة تنبيه. يمكنك أيضًا إعادة تشغيل خدمة Nginx يدويًا من واجهة "الخدمات" إن لزم الأمر.

5. الوصول إلى التطبيق: افتح متصفح الإنترنت وانتقل إلى النطاق الذي حددته في إعدادات Nginx (مثال: https://mywebapp.servbay.demo). بما أن Nginx معد ليدعم SSL على المنفذ 443، يُوصى باستخدام https. سيخدم Nginx الملفات الثابتة مباشرة ويحول الطلبات الديناميكية إلى fastcgi-mono-server4 الذي ينفذ كودك في .NET عبر Mono.

المزايا:

• يوفر أداءً أعلى وثبات أكبر، ويقترب من بيئة الإنتاج الحقيقية.
• يمكن الاستفادة من ميزات Nginx المتقدمة (خدمات الملفات الثابتة، SSL، توازن التحميل، إلخ).
• تكامل أفضل مع إدارة المواقع والأسماء وملف Hosts في ServBay.

العيوب:

• الإعداد أعقد من XSP نسبياً.
• تحتاج لإدارة عملية fastcgi-mono-server4 يدويًا (إلا إذا استخدمت أدوات الخدمات الخلفية).

كيف تختار الطريقة المناسبة؟

• للتطوير السريع، التصحيح، والاختبارات البسيطة، XSP هو الأسهل والأسرع، ويعمل بأمر واحد فقط.
• عند الحاجة لأداء أعلى، أو لاختبار واقعي قريب من الإنتاج أو الاستفادة من خصائص متقدمة (مثل HTTPS، أسماء النطاقات المخصصة، وتحسين الملفات الثابتة) مع إدارة المواقع في ServBay، يكون Nginx + FastCGI الخيار الأفضل.

ملاحظات وحلول المشاكل

• صلاحيات الملفات: تأكد أن مستخدم macOS المشغل لـ Nginx (يديره ServBay غالبًا) وكذلك من يشغل fastcgi-mono-server4 يمتلكان صلاحيات كافية (قراءة/كتابة) لملفات مشروعك (/Applications/ServBay/www/YourProjectName). قد تحتاج لتعديل الصلاحيات باستخدام أوامر chmod أو chown.
• تطابق المسارات: تحقق بدقة من تطابق مسار مشروعك في إعدادات Nginx (root) وأمر تشغيل fastcgi-mono-server4 (--applications) وأنهما يشيران للجذر الصحيح حيث يوجد ملف web.config.
• مشكلة احتلال المنافذ: تأكد أن المنافذ المختارة لـ XSP أو fastcgi-mono-server4 (مثل 9000 أو 9001) ليست مشغولة من خدمات أو برامج أخرى في النظام.
• فحص السجلات:
  • راجع سجلات تشغيل fastcgi-mono-server4 من الطرفية أو من خيار --printlog لمعرفة تفاصيل الخطأ والتشغيل.
  • راجع سجلات Nginx للأخطاء. يمكنك بسهولة معرفة المسار من إعدادات الموقع في ServBay، غالبًا في: /Applications/ServBay/logs/nginx/your-domain.error.log. هذه السجلات بالغة الأهمية لتشخيص مشاكل إعداد Nginx أو الاتصال بخادم Mono بسرعة.
• توافق إصدار Mono: إصدار Mono 6.14.0 المدمج في ServBay متوافق تقريبًا مع خصائص .NET Framework من 1.1 إلى 4.7.2. إذا استخدمت ميزات من إصدارات أحدث أو واجهت مشاكل توافق، جرب تشغيل مشروعك على إصدارات أقدم، أو فضلًا استخدم حزمة .NET الرسمية من Microsoft عبر ServBay لحلول .NET الحديثة.
• إدارة عملية FastCGI: إذا استخدمت طريقة Nginx + FastCGI، تذكر أن عملية fastcgi-mono-server4 يجب أن تبقى شغالة دومًا. في التطوير يمكنك إبقاء طرفية مفتوحة، وفي البيئات الأكثر اعتمادية، يجدر بك استخدام مشغلات عمليات في الخلفية أو أدوات إدارة العمليات لتشغيلها تلقائيًا.

---

من خلال بيئة Mono 6 المدمجة في ServBay وهيكلية المشاريع الموصى بها، أصبحت عملية تطوير وتشغيل تطبيقات ASP.NET Framework 4.x التقليدية على macOS أكثر سلاسة وتنظيمًا من أي وقت مضى. نتمنى أن يساعدك هذا الدليل في الانطلاق بسلاسة في مسيرة تطويرك!