كيفية تطوير ASP.NET Framework 4.x على macOS

توفر 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، مما يوفر لك طريقتين رئيسيتين لتشغيل تطبيقات ASP.NET Framework 4.x:

• استخدام XSP للتطوير السريع والاختبار
• أو استخدام Nginx + FastCGI لنشر تطبيقات أكثر استقرارًا تقترب من بيئة الإنتاج.

ستوجهك هذه الوثيقة حول كيفية تكوين وتشغيل مشروع ASP.NET Framework 4.x في بيئة ServBay.

الشروط المسبقة

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

إعداد مشروع ASP.NET الخاص بك

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

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

XSP هو خادم ويب ASP.NET خفيف الوزن مصمم خصيصًا لـ Mono، وهو مناسب تمامًا لمرحلة التطوير والاختبار السريع. يحتوي Mono 6 المثبت عبر ServBay على XSP4 (المخصص لـ ASP.NET 4.x).

نصيحة

• إذا كنت ترغب في تشغيل مشروع ASP.NET 1.1، يرجى استخدام أمر xsp.
• إذا كنت ترغب في تشغيل مشروع ASP.NET 2.0، يرجى استخدام أمر xsp2.

الخطوات:

1. فتح الطرفية: افتح تطبيق الطرفية (Terminal) في macOS.

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

   # مثال: الانتقال إلى الدليل الخاص بمشروع MyWebApp
   cd /Applications/ServBay/www/MyWebApp

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

   # بدء المشروع الموجود حاليًا على المنفذ 9000
   xsp4 --port 9000

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

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

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

الميزات:

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

العيوب:

• الأداء أدنى مقارنة بخوادم الإنتاج مثل Nginx.
• الوظائف أساسية نسبيًا ولا تحاكي بيئة الإنتاج بالكامل.

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

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

نصيحة

• إذا كنت ترغب في تشغيل مشروع ASP.NET 1.1، يرجى استخدام أمر fastcgi-mono-server.
• إذا كنت ترغب في تشغيل مشروع ASP.NET 2.0، يرجى استخدام أمر fastcgi-mono-server2.

الخطوات:

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

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

2. إعداد مشروع ASP.NET: تأكد من وجود مشروعك في المسار الموصى به، مثل /Applications/ServBay/www/MyWebApp.

3. بدء خادم FastCGI Mono:

   • افتح نافذة طرفية جديدة.
   • قم بتشغيل عملية 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

     • --applications=/:/Applications/ServBay/www/MyWebApp: لخريطة المسار الجذري للموقع (/) إلى المسار الفيزيائي لمشروعك. تأكد من استبدال /Applications/ServBay/www/MyWebApp بالمسار الفعلي لمشروعك.
     • --socket=tcp:127.0.0.1:9001: لتحديد عنوان TCP ورقم المنفذ الذي يستمع إليه خادم FastCGI. تأكد من أن هذا المنفذ (مثل 9001) غير مستخدم، ويتطابق مع امتداد fastcgi_pass في تكوين Nginx أدناه.
     • --loglevels=Standard --printlog: (اختياري) لطباعة سجلات بالمستوى القياسي في الطرفية، تسهل عملية استكشاف الأخطاء.
   • ملاحظة: تحتاج هذه نافذة الطرفية للبقاء مفتوحة لتشغيل خدمة FastCGI. للتشغيل لفترات طويلة، قد تحتاج إلى استخدام أدوات مثل nohup أو screen/tmux لتشغيلها في الخلفية.

4. تكوين موقع Nginx:

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

   • اضغط على "إضافة موقع" أو اختر موقعًا موجودًا للتعديل.

   • إعداد اسم النطاق: مثل mywebapp.test. ستقوم ServBay تلقائيًا بإضافته إلى ملف Hosts.

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

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

     جزء من ملف التكوين الذي تم إنشاؤه تلقائيًا من ServBay ويحتاج إلى التحقق أو الإضافة هو كالتالي:

     server {
         listen 443;
         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;
     
         ssl_certificate /Applications/ServBay/ssl/private/tls-certs/mywebapp.test/mywebapp.test.crt; # تأكد من مطابقة الشهادة للمسار الفعلي
         ssl_certificate_key /Applications/ServBay/ssl/private/tls-certs/mywebapp.test/mywebapp.test.key; # تأكد من مطابقة الشهادة للمسار الفعلي
     
         server_name mywebapp.test; # يجب أن يتطابق مع اسم النطاق الذي قمت بتعيينه في ServBay
         root /Applications/ServBay/www/MyWebApp; # **تأكد من تطابقه** مع الدليل الجذري الذي تم ضبطه
         index index.html index.htm default.aspx Default.aspx; # إضافة مستندات ASP.NET الافتراضية
     
         location / {
             try_files $uri $uri/ @mono; # حاول استخدام الملفات الثابتة، وإلا قم بإدارة الطلب من قبل @mono
         }
     
         # (اختياري ولكن موصى به) تتعامل Nginx مباشرةً مع الملفات الثابتة الشائعة
         # location ~* \.(ico|css|js|gif|jpe?g|png|svg|woff|woff2|ttf|eot)$ {
         #     expires max;
         #     log_not_found off;
         #     access_log off;
         # }
     
         location @mono {
             # تمرير الطلبات إلى خادم FastCGI Mono
             # يجب أن يتطابق المنفذ مع البراميتر/socket المخصص عند بدء fastcgi-mono-server4
             fastcgi_pass 127.0.0.1:9001;
     
             # البراميتر اللازمة لـ FastCGI
             include fastcgi_params;
             # سيتم ضبط SCRIPT_FILENAME بناءً على ارشاد root و $fastcgi_script_name بشكل صحيح
             fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
             fastcgi_param PATH_INFO "";
         }
     
         # قد تتضمن ServBay تكوينات افتراضية أخرى، مثل السجلات، والتحكم في الوصول، إلخ.
         # access_log /Applications/ServBay/logs/nginx/mywebapp.test.access.log;
         # error_log /Applications/ServBay/logs/nginx/mywebapp.test.error.log;
     }

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

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

الميزات:

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

العيوب:

• إعدادات أكثر تعقيدًا مقارنةً بـ XSP.
• يتطلب إدارة يديوية لعملية fastcgi-mono-server4.

كيفية اختيار

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

الملاحظات واستكشاف الأخطاء

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

---

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