Pembangunan ASP.NET Framework 4.x di macOS dengan ServBay

ServBay memudahkan pembangunan dan ujian ASP.NET Framework 1.1/2.0/3.x/4.x (sehingga 4.7.x) di macOS melalui integrasi persekitaran Mono yang mantap.

Bermula dari ServBay v1.12.0, kami telah menggabungkan Mono 6.14.0 bersama XSP sebagai server pembangunan serta alat fastcgi-mono-server, membolehkan anda menjalankan aplikasi ASP.NET Framework 4.x melalui dua kaedah utama:

1. Pembangunan & Pengujian Pantas dengan XSP: XSP ialah web server ringan khusus untuk Mono, sangat sesuai untuk fasa pembangunan dan pengujian pantas.
2. Deployment dengan Nginx + FastCGI: Kaedah ini lebih stabil, berprestasi tinggi, dan hampir dengan persekitaran produksi—Nginx mengendalikan permintaan dan meneruskannya ke proses Mono di belakang.

Dokumentasi ini akan memandu anda mengkonfigurasi dan menjalankan projek ASP.NET Framework 4.x dalam persekitaran ServBay.

Tentang .NET Framework dan .NET

Sila ambil maklum: dokumen ini mengulas pembangunan ASP.NET Framework 4.x berasaskan Mono, iaitu tumpukan teknologi .NET yang lebih lama.

ServBay turut menyokong sepenuhnya pembangunan dan deployment .NET terkini (termasuk .NET Core, .NET 5/6/7/8+). Jika anda membangunkan projek .NET baharu, atau ingin berhijrah ke versi .NET moden, kami mencadangkan menggunakan SDK/Rumah Jalan .NET rasmi Microsoft yang disediakan oleh ServBay — bukannya kaedah berasaskan Mono di sini.

Pra-syarat

1. Pasang ServBay: Pastikan anda telah memasang ServBay v1.12.0 atau yang lebih baru pada macOS.
2. Pasang Mono:
   • Buka aplikasi ServBay.
   • Di bar navigasi kiri, pilih “Pakej”.
   • Dalam senarai pakej, cari kategori “.NET” dan kembangkan.
   • Cari “Mono 6” (versi 6.14.0 atau lebih baru), klik butang “Pasang”, dan tunggu sehingga selesai.

Sediakan Projek ASP.NET Anda

1. Fail Projek: Pastikan anda mempunyai projek Web Application atau Web Site ASP.NET Framework 4.x yang mengandungi fail web.config.
2. Lokasi Projek yang Disarankan: Sangat digalakkan anda meletakkan projek laman web di dalam direktori www yang dikendalikan secara piawai oleh ServBay, iaitu /Applications/ServBay/www/. Cipta subdirektori berasingan untuk setiap projek.
   • Contoh: Jika projek anda bernama MyWebApp, laluan akar projek disarankan ialah /Applications/ServBay/www/MyWebApp.
   • Dalam panduan berikut, kami akan gunakan /Applications/ServBay/www/MyWebApp sebagai contoh. Pastikan anda ganti dengan laluan sebenar projek anda.

Kaedah 1: Menggunakan XSP (Server Pembangunan Bawaan)

XSP ialah web server ringan dari projek Mono — sangat ideal untuk pembangunan tempatan dan ujian pantas aplikasi ASP.NET Framework. Pakej Mono 6 yang dipasang via ServBay sudah termasuk XSP4 (untuk ASP.NET 4.x).

Petua

• Untuk menjalankan projek ASP.NET 1.1, gunakan arahan xsp.
• Untuk projek ASP.NET 2.0/3.x, gunakan arahan xsp2.
• Untuk projek ASP.NET 4.x, gunakan arahan xsp4.

Langkah-langkah:

1. Buka Terminal: Lancarkan aplikasi Terminal di macOS.

2. Navigasi ke Direktori Projek: Guna arahan cd ke direktori akar projek ASP.NET anda (direktori yang mengandungi web.config).

   # Contoh: Masuk ke direktori projek MyWebApp
   cd /Applications/ServBay/www/MyWebApp

3. Mulakan Server XSP: Dari akar projek, jalankan arahan berikut untuk memulakan XSP4. Pilih port yang tidak digunakan (contoh 8080 atau 9000) untuk elak konflik dengan servis lain.

   # Mulakan projek pada port 9000
   xsp4 --port 9000

   • xsp4: Panggil XSP untuk .NET Framework 4.x.
   • --port 9000: Tetapkan nombor port TCP.

4. Akses Aplikasi Anda: Buka pelayar web dan lawati http://localhost:9000 atau http://127.0.0.1:9000. Anda kini sepatutnya dapat melihat aplikasi ASP.NET anda berjalan.

5. Hentikan Server: Selesai pembangunan/ujian, kembali ke tetingkap terminal XSP dan tekan Ctrl + C atau Enter untuk menghentikan server.

Kelebihan:

• Mudah dikonfigurasi dan cepat dilancarkan.
• Sangat sesuai untuk pembangunan tempatan dan penyahpepijatan.

Kekurangan:

• Prestasi tidak setanding Nginx mahupun server web produksi.
• Fungsi asas sahaja — tidak 100% menyamai suasana produksi.
• Tetingkap terminal perlu sentiasa dibuka.

Kaedah 2: Menggunakan Nginx + FastCGI

Kaedah ini menggunakan Nginx (dikendalikan ServBay) sebagai web server hadapan untuk menerima permintaan klien dan mengurus fail statik, sambil menggunakan protokol FastCGI untuk meneruskan permintaan dinamik (seperti .aspx, .ashx dll) ke proses Mono (fastcgi-mono-server4). Kaedah ini lebih mirip suasana produksi, menawarkan prestasi dan sokongan ciri lanjutan (SSL, cache, compressi, dll) melalui Nginx.

Petua

• Untuk projek ASP.NET 1.1, gunakan arahan fastcgi-mono-server.
• Untuk projek ASP.NET 2.0/3.x, gunakan arahan fastcgi-mono-server2.
• Untuk projek ASP.NET 4.x, gunakan arahan fastcgi-mono-server4.

Langkah-langkah:

1. Pastikan Mono dan Nginx telah dipasang & berjalan:

   • Guna seksyen “Pakej” di ServBay untuk instalasi Mono 6 dan Nginx.
   • Di seksyen “Perkhidmatan” ServBay, pastikan servis Nginx telah dimulakan.

2. Sediakan Projek ASP.NET: Pastikan projek berada di laluan disarankan, contoh /Applications/ServBay/www/MyWebApp.

3. Mulakan FastCGI Mono Server:

   • Buka tetingkap terminal baharu.
   • Jalankan proses fastcgi-mono-server4, bertanggungjawab menerima permintaan FastCGI dari Nginx serta mengendalikan halaman ASP.NET dan logik aplikasi.

     # Contoh: Mulakan servis FastCGI untuk projek MyWebApp
     fastcgi-mono-server4 --applications=/:/Applications/ServBay/www/MyWebApp \
                          --socket=tcp:127.0.0.1:9001 \
                          --loglevels=Standard \
                          --printlog

     • fastcgi-mono-server4: Mulakan server FastCGI untuk .NET Framework 4.x.
     • --applications=/:/Applications/ServBay/www/MyWebApp: Membina pemetaan URL ke laluan sebenar fail. /: mewakili akar URL, /Applications/ServBay/www/MyWebApp adalah laluan sebenar projek. Pastikan ganti dengan laluan projek anda.
     • --socket=tcp:127.0.0.1:9001: Tetapkan alamat dan port TCP untuk FastCGI. Port ini (contoh 9001) mesti tidak digunakan servis lain dan digunakan secara konsisten dalam konfigurasi Nginx (fastcgi_pass).
     • --loglevels=Standard --printlog: (Pilihan) Paparkan log operasi untuk debugging.
   • Perhatian: Tetingkap terminal ini perlu dibiarkan terbuka jika anda belum mengurus proses secara latar (gunakan tools seperti nohup, screen atau tmux untuk perkhidmatan latar).

4. Konfigurasikan Tapak Nginx:

   • Dalam ServBay, pergi ke bahagian “Tapak”.

   • Klik “Tambah Tapak” atau pilih tapak sedia ada untuk pengeditan.

   • Setkan domain: Cth., gunakan domain berkaitan projek seperti mywebapp.servbay.demo. ServBay akan uruskan fail Hosts macOS supaya ia menunjuk ke 127.0.0.1.

   • Setkan akar dokumen: Penting! Tetapkan ke laluan sebenar projek ASP.NET, seperti /Applications/ServBay/www/MyWebApp, supaya Nginx berfungsi dengan betul.

   • Aktifkan & Edit Konfigurasi Tersuai: Tandakan pilihan “Konfigurasi tersuai”. ServBay akan menjana fail konfigurasi Nginx asas. Anda perlu tambah/ubah konfigurasi untuk melaraskan forwarding permintaan kepada FastCGI Mono Server.

     Contoh asas konfigurasi Nginx hasil dari ServBay—pastikan bahagian berikut diperiksa/dipersuaikan:

     server {
         listen 80; # Dengar pada port HTTP
         listen 443 ssl http2; # Dengar pada port HTTPS, aktifkan SSL & HTTP/2
     
         # Konfigurasi SSL automatik (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;
     
         # Laluan fail sijil SSL (diuruskan 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; # Padankan dengan domain ditetapkan
         root /Applications/ServBay/www/MyWebApp; # Pastikan laluan betul
     
         # Senarai default dokumen ASP.NET
         index index.html index.htm default.aspx Default.aspx;
     
         # Logik utama pemprosesan permintaan
         location / {
             # Cuba cari fail ($uri) atau direktori ($uri/)
             # Jika tiada, serahkan pada @mono
             try_files $uri $uri/ @mono;
         }
     
         # (Pilihan, tapi disyorkan) Nginx uruskan fail statik dengan cekap
         location ~* \.(ico|css|js|gif|jpe?g|png|svg|woff|woff2|ttf|eot)$ {
             expires max;
             log_not_found off;
             access_log off;
         }
     
         # Blok @mono untuk permintaan dinamik
         location @mono {
             fastcgi_pass 127.0.0.1:9001; # Padankan port FastCGI
     
             include fastcgi_params;
             fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
             fastcgi_param PATH_INFO "";
     
             # Tambahan parameter FastCGI jika perlu
             # fastcgi_param HOST $host;
         }
     
         # Konfigurasi lalai lain, cth. laluan log
         # access_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.access.log;
         # error_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.error.log;
     }

   • Simpan & Muat Semula/Restart Nginx: Simpan konfigurasi melalui ServBay. ServBay akan cuba reload konfigurasi secara automatik dan memaklumkan jika terdapat ralat sintaks. Jika perlu, anda boleh restart servis Nginx secara manual dari seksyen “Perkhidmatan”.

5. Akses Aplikasi Anda: Buka pelayar web dan lawati domain yang dikonfigurasikan pada Nginx (contohnya https://mywebapp.servbay.demo). Dengan SSL disokong pada port 443, gunakan HTTPS. Nginx akan terus hantar fail statik dan serahkan permintaan dinamik kepada fastcgi-mono-server4, di mana Mono akan jalankan kod ASP.NET anda.

Kelebihan:

• Lebih stabil dan berprestasi tinggi—sesuai untuk ujian hampir produksi.
• Manfaatkan ciri-ciri premium Nginx (servis statik, SSL, load balancing, dsb.).
• Integrasi lebih baik dengan pengurusan tapak, domain dan fail Hosts melalui ServBay.

Kekurangan:

• Konfigurasi lebih kompleks berbanding XSP.
• Proses fastcgi-mono-server4 perlu dikawal secara manual (kecuali gunakan alat pengurusan proses).

Memilih Kaedah yang Sesuai

• Untuk pembangunan pantas, debugging, dan ujian ciri asas, XSP ialah pilihan terpantas & termudah—hanya satu arahan untuk mula.
• Untuk keperluan prestasi lebih tinggi, ujian pra-produksi, atau ingin gunakan ciri lanjutan Nginx (seperti HTTPS, domain khusus, pengoptimuman statik) serta integrasi tapak ServBay, pilih mod Nginx + FastCGI.

Perkara Penting & Penyelesaian Masalah

• Akses Fail: Pastikan proses pengguna Nginx (biasanya diuruskan ServBay) dan pengguna macOS yang menjalankan fastcgi-mono-server4 mempunyai akses baca ke fail projek (dalam /Applications/ServBay/www/NamaProjekAnda). Anda mungkin perlu guna chmod atau chown untuk betulkan kebenaran.
• Konsistensi Laluan: Semak dengan teliti bahawa laluan projek dalam konfigurasi Nginx (root) dan arahan fastcgi-mono-server4 (--applications) adalah betul dan menunjuk ke direktori akar projek dengan web.config.
• Konflik Port: Pastikan port digunakan oleh XSP atau fastcgi-mono-server4 (cth 9000 atau 9001) tidak digunakan oleh servis lain pada ServBay atau aplikasi lain.
• Semak Log:
  • Semak log output di terminal ketika memulakan fastcgi-mono-server4. Argumen --printlog membantu anda pantau log runtime Mono.
  • Semak log ralat Nginx—laluan log tapak biasanya dipaparkan pada tetapan tapak dan boleh ditemui di /Applications/ServBay/logs/nginx/your-domain.error.log. Log ini penting untuk penyahpepijatan konfigurasi atau komunikasi FastCGI.
• Keserasian Versi Mono: Mono 6.14.0 yang dibawakan oleh ServBay secara umumnya serasi dengan ciri-ciri .NET Framework 1.1 hingga 4.7.2. Jika anda menggunakan ciri .NET Framework lebih baharu atau menghadapi isunya, pertimbangkan pemasangan SDK/Rumah Jalan .NET rasmi Microsoft melalui ServBay atau downgrade projek anda ke versi yang disokong Mono.
• Pengurusan Proses FastCGI: Untuk Nginx + FastCGI, ingat bahawa proses fastcgi-mono-server4 perlu sentiasa berjalan. Sepanjang pembangunan, memadai biarkan terminal terbuka; untuk operasi lebih formal, gunakan alat pengurusan proses/daemon untuk latar belakang.

---

Dengan persekitaran Mono 6 dalaman ServBay dan struktur projek yang teratur, pembangunan & pelaksanaan aplikasi ASP.NET Framework 4.x tradisional di macOS menjadi lebih mudah, terurus, dan bersistematik. Semoga dokumen ini membantu anda memulakan pembangunan dengan lancar!