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

ServBay menyediakan lingkungan Mono yang kuat secara bawaan, sehingga Anda dapat dengan mudah melakukan pengembangan dan pengujian ASP.NET Framework 1.1/2.0/3.x/4.x (hingga versi 4.7.x) langsung di macOS.

Sejak ServBay v1.12.0, kami telah mengintegrasikan Mono 6.14.0 lengkap dengan server pengembangan XSP dan alat fastcgi-mono-server, sehingga Anda memiliki dua cara utama untuk menjalankan aplikasi ASP.NET Framework 4.x Anda:

Pengembangan cepat & uji coba menggunakan XSP: XSP adalah server web ringan yang dirancang khusus untuk Mono—ideal untuk proses pengembangan dan pengujian cepat.
Deploy menggunakan Nginx + FastCGI: Pilihan ini menawarkan performa yang lebih tinggi, lebih stabil, serta mendekati standar lingkungan produksi; Nginx (dikelola ServBay) meneruskan permintaan ke proses backend Mono.

Dokumentasi ini membimbing Anda dalam mengonfigurasi dan menjalankan proyek ASP.NET Framework 4.x dalam lingkungan ServBay.

Tentang .NET Framework & .NET

Perhatikan bahwa dokumen ini membahas pengembangan ASP.NET Framework 4.x berbasis Mono—teknologi .NET generasi lama.

ServBay juga sepenuhnya mendukung pengembangan & deployment .NET modern (termasuk .NET Core, .NET 5/6/7/8+). Jika Anda memulai proyek .NET baru atau ingin migrasi ke versi .NET yang lebih modern, kami sarankan untuk memakai SDK/runtime Microsoft .NET resmi dari ServBay, bukan metode berbasis Mono yang dijelaskan di sini.

Syarat Awal

Install ServBay: Pastikan ServBay v1.12.0 atau yang lebih baru sudah terpasang di macOS Anda.
Install Mono:
- Buka aplikasi ServBay.
- Dari sidebar kiri, pilih "Paket".
- Temukan kategori ".NET" pada daftar paket, lalu klik.
- Cari "Mono 6" (harus versi 6.14.0 ke atas), klik tombol "Install" di sebelah kanan dan tunggu proses selesai.

Menyiapkan Proyek ASP.NET Anda

File Proyek: Pastikan Anda memiliki proyek Web Application atau Web Site ASP.NET Framework 4.x beserta file web.config.
Direktori Penyimpanan yang Disarankan: Sangat dianjurkan untuk meletakkan proyek website di direktori www milik ServBay: /Applications/ServBay/www/. Buat subdirektori tersendiri untuk setiap proyek.
- Contoh: Jika nama proyek Anda MyWebApp, direktori root website yang dianjurkan adalah /Applications/ServBay/www/MyWebApp.
- Pada langkah-langkah berikut, /Applications/ServBay/www/MyWebApp akan digunakan sebagai contoh. Jangan lupa ganti dengan path proyek Anda sendiri.

Metode 1: Menggunakan XSP (Server Pengembangan Bawaan)

XSP adalah web server lightweight milik proyek Mono yang sangat cocok untuk pengembangan lokal dan pengujian kilat aplikasi ASP.NET Framework. Mono 6 bawaan ServBay sudah dilengkapi XSP4 (untuk ASP.NET 4.x).

Tips

Untuk menjalankan proyek ASP.NET 1.1, gunakan perintah xsp.
Untuk proyek ASP.NET 2.0/3.x, gunakan xsp2.
Untuk proyek ASP.NET 4.x, gunakan xsp4.

Langkah-langkah:

Buka Terminal: Jalankan aplikasi Terminal pada macOS.
Masuk ke direktori proyek: Gunakan perintah cd menuju root proyek ASP.NET Anda (direktori tempat file web.config berada).
bash
```
# Contoh: Masuk ke direktori proyek bernama MyWebApp
cd /Applications/ServBay/www/MyWebApp
```
1
2
Menyalakan XSP Server: Dari root proyek, jalankan perintah berikut untuk memulai server XSP4. Pilih port yang tidak bentrok dengan layanan lain di ServBay (misal 8080 atau 9000).
bash
```
# Menyalakan proyek pada port 9000
xsp4 --port 9000
```
1
2
- xsp4: Memulai server XSP untuk .NET Framework 4.x.
- --port 9000: Menentukan port TCP tempat server akan mendengarkan.
Akses aplikasi: Buka browser Anda dan kunjungi http://localhost:9000 atau http://127.0.0.1:9000. Anda seharusnya sudah dapat melihat aplikasi ASP.NET Anda berjalan.
Mematikan server: Setelah selesai, kembali ke jendela terminal tadi dan tekan Ctrl + C atau tombol Enter untuk menghentikan server XSP.

Kelebihan:

Sangat mudah dikonfigurasi dan cepat dijalankan.
Cocok untuk pengembangan lokal dan debugging.

Kekurangan:

Performa di bawah web server tingkat produksi seperti Nginx.
Fitur terbatas; tidak sepenuhnya menyerupai lingkungan produksi.
Terminal harus tetap terbuka.

Metode 2: Menggunakan Nginx + FastCGI

Metode ini menggunakan Nginx (dikelola ServBay) sebagai front-end web server. Nginx menangani permintaan klien & file statis, lalu meneruskan permintaan dinamis (seperti .aspx, .ashx, dll.) ke proses Mono backend (fastcgi-mono-server4) lewat protokol FastCGI. Cara ini lebih mendekati deployment produksi dan menawarkan performa lebih baik, serta mendukung fitur-fitur andalan Nginx (SSL, cache, kompresi, dsb).

Tips

Untuk aplikasi ASP.NET 1.1, gunakan perintah fastcgi-mono-server.
Untuk ASP.NET 2.0/3.x, gunakan fastcgi-mono-server2.
Untuk ASP.NET 4.x, gunakan fastcgi-mono-server4.

Langkah-langkah:

Pastikan Mono & Nginx Terpasang dan Berjalan:
- Install Mono 6 dan Nginx lewat menu "Paket" di ServBay.
- Di menu "Layanan" ServBay, pastikan Nginx sudah menyala.
Siapkan Proyek ASP.NET: Pastikan proyek Anda berada pada path yang direkomendasikan (misal /Applications/ServBay/www/MyWebApp).
Menyalakan FastCGI Mono Server:
- Buka terminal baru.
- Jalankan fastcgi-mono-server4. Proses ini akan langsung menangani permintaan FastCGI dari Nginx dan memproses halaman ASP.NET serta logika bisnis Anda.
  bash
```
# Contoh: Menyalakan layanan FastCGI untuk proyek MyWebApp
fastcgi-mono-server4 --applications=/:/Applications/ServBay/www/MyWebApp \
                     --socket=tcp:127.0.0.1:9001 \
                     --loglevels=Standard \
                     --printlog
```
  1
  2
  3
  4
  5
  - fastcgi-mono-server4: Memulai FastCGI server untuk .NET Framework 4.x.
  - --applications=/:/Applications/ServBay/www/MyWebApp: Mendefinisikan pemetaan URL ke path fisik, /: adalah root URL (/), /Applications/ServBay/www/MyWebApp adalah path fisik proyek Anda pada disk. Ketika Nginx meneruskan permintaan ke /some/page.aspx, Mono mencari dan mengeksekusi file di /Applications/ServBay/www/MyWebApp/some/page.aspx. Pastikan untuk mengganti /Applications/ServBay/www/MyWebApp sesuai dengan path proyek Anda.
  - --socket=tcp:127.0.0.1:9001: Menentukan alamat & port TCP yang akan didengarkan FastCGI server. 127.0.0.1 artinya hanya menerima koneksi lokal, 9001 adalah nomor portnya. Pastikan port ini tidak digunakan layanan lain dan konsisten dengan fastcgi_pass di konfigurasi Nginx nantinya.
  - --loglevels=Standard --printlog: (Opsional) Menampilkan log standar di terminal—sangat berguna untuk debugging.
- Catatan: Terminal tempat Anda menjalankan fastcgi-mono-server4 harus tetap aktif agar layanannya berjalan. Untuk penggunaan jangka panjang, gunakan tools seperti nohup, screen, atau tmux bila ingin menjalankan di latar belakang.

Mengonfigurasi Situs Nginx:

Pada ServBay, buka bagian "Situs".
Klik "Tambah Situs" atau edit situs yang sudah ada.
Atur nama domain: Misal, gunakan domain internal seperti mywebapp.servbay.demo. ServBay secara otomatis memasukkan domain ini ke file Hosts di macOS, mengarah ke 127.0.0.1.
Setel root direktori situs: WAJIB! Pastikan mengarah ke folder proyek ASP.NET (misal /Applications/ServBay/www/MyWebApp). Ini akan mengisi direktif root pada konfigurasi Nginx—penting untuk menangani file statis.

Aktifkan & edit konfigurasi kustom: Centang opsi "Konfigurasi Kustom" di kanan atas pengaturan situs. ServBay akan menghasilkan konfigurasi dasar Nginx, dan Anda dapat menambah/mengubah bagian tertentu agar permintaan dinamis diteruskan ke FastCGI Mono Server.

Contoh konfigurasi hasil modifikasi (berdasarkan auto-generate ServBay):

nginx

server {
    listen 80; # Listen HTTP
    listen 443 ssl http2; # Listen HTTPS, aktifkan SSL dan HTTP/2

    # Konfigurasi sertifikat SSL—diatur otomatis 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;

    # Path file sertifikat, diatur otomatis sesuai domain
    ssl_certificate /Applications/ServBay/ssl/private/tls-certs/mywebapp.servbay.demo/mywebapp.servbay.demo.crt; # Pastikan path sesuai domain
    ssl_certificate_key /Applications/ServBay/ssl/private/tls-certs/mywebapp.servbay.demo/mywebapp.servbay.demo.key; # Pastikan path sesuai domain

    server_name mywebapp.servbay.demo; # Sesuaikan dengan domain pada pengaturan ServBay
    root /Applications/ServBay/www/MyWebApp; # **Konsisten** dengan root website Anda

    # Default document ASP.NET, fallback bila index.html/htm tidak ditemukan
    index index.html index.htm default.aspx Default.aspx;

    # Logika utama routing permintaan
    location / {
        # Cari file ($uri) atau direktori ($uri/), jika gagal, teruskan ke @mono
        try_files $uri $uri/ @mono;
    }

    # (Opsional tapi disarankan) Nginx melayani file statis dengan efisien
    # Manfaatkan expires agar cache browser maksimal
    location ~* \.(ico|css|js|gif|jpe?g|png|svg|woff|woff2|ttf|eot)$ {
        expires max; # Cache browser maksimal
        log_not_found off; # Jangan log error jika file statis tak ditemukan
        access_log off; # Nonaktifkan pencatatan akses file statis
    }

    # Lokasi @mono untuk handling permintaan dinamis
    location @mono {
        # Teruskan lewat protokol FastCGI ke Mono Server
        # **Port harus** sama persis dengan --socket pada fastcgi-mono-server4
        fastcgi_pass 127.0.0.1:9001;

        # Parameter FastCGI standar
        include fastcgi_params;
        # Kunci: atur nama file skrip yang akan dieksekusi Mono
        # $document_root dari directive root, $fastcgi_script_name biasanya path request relatif terhadap root
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        # PATH_INFO biasanya tidak dibutuhkan, set ke kosong
        fastcgi_param PATH_INFO "";

        # (Opsional) Parameter FastCGI lain seperti HOST bisa ditambah sesuai kebutuhan
        # fastcgi_param HOST $host;
    }

    # Pengaturan lain dari ServBay: path log, dsb.
    # access_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.access.log;
    # error_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.error.log;
}

Simpan & reload/restart Nginx: Simpan konfigurasi Nginx di ServBay. ServBay akan mencoba reload otomatis. Jika konfigurasi salah, akan muncul notifikasi error. Jika perlu, restart Nginx manual dari menu "Layanan" ServBay.

Akses aplikasi: Buka browser dan kunjungi domain yang Anda atur di Nginx (misal https://mywebapp.servbay.demo). Karena SSL aktif di port 443, disarankan mengakses via HTTPS. Nginx akan mengembalikan file statis secara langsung; permintaan dinamis diteruskan ke fastcgi-mono-server4 agar Mono mengeksekusi kode ASP.NET Anda.

Kelebihan:

Performa lebih baik, stabil, dan menyerupai production.
Mendukung fitur andalan Nginx (servis file statis, SSL, load balancing, dsb.).
Terintegrasi penuh dengan site management ServBay dan pengelolaan domain serta Hosts.

Kekurangan:

Lebih kompleks dibanding XSP.
Proses fastcgi-mono-server4 harus dijaga tetap berjalan (kecuali memakai tool background).

Cara Memilih Metode yang Tepat

Untuk pengembangan & debugging cepat atau pengujian fungsi sederhana, XSP adalah opsi paling praktis dan instan.
Untuk pengujian performa, staging, atau deployment internal—terutama jika ingin menggunakan fitur canggih Nginx (HTTPS, domain kustom, optimasi file statis) serta pengelolaan situs ServBay—Nginx + FastCGI adalah pilihan yang lebih kuat.

Catatan Penting & Troubleshooting

Hak akses file: Pastikan user proses Nginx (dikelola ServBay) dan user macOS yang menjalankan fastcgi-mono-server4 sama-sama memiliki izin baca yang cukup pada file proyek Anda di /Applications/ServBay/www/YourProjectName. Terkadang perlu memakai chmod atau chown untuk mengatur permission folder/file.
Konsistensi path: Selalu cek path pada konfigurasi Nginx (root) dan fastcgi-mono-server4 (--applications) benar-benar konsisten, dan menunjuk ke folder root proyek (tempat web.config).
Konflik port: Pastikan port yang digunakan XSP maupun fastcgi-mono-server4 (misal 9000 atau 9001) tidak bentrok dengan layanan lain di ServBay maupun aplikasi lain di sistem.
Cek log:
- Pantau log terminal saat menjalankan fastcgi-mono-server4 (parameter --printlog sangat membantu).
- Lihat error log Nginx; ServBay menunjukkan path log tiap situs di panel setting, biasanya di /Applications/ServBay/logs/nginx/your-domain.error.log. Penting untuk debugging masalah konfigurasi Nginx atau komunikasi ke FastCGI Mono Server.
Kompatibilitas versi Mono: Mono 6.14.0 bawaan ServBay umumnya kompatibel dengan fitur .NET Framework 1.1–4.7.2. Jika fitur dari .NET Framework yang lebih tinggi tidak berjalan, atau ada masalah kompatibilitas, pertimbangkan install SDK/runtime .NET official Microsoft via ServBay, atau turunkan versi proyek agar sesuai dengan kompatibilitas Mono.
Manajemen proses FastCGI: Jika memakai model Nginx + FastCGI, pastikan proses fastcgi-mono-server4 selalu aktif. Untuk pengembangan, cukup jalankan di terminal; untuk produksi/internal, pertimbangkan setup sebagai layanan background atau gunakan process manager.

Dengan lingkungan Mono 6 bawaan ServBay dan struktur proyek yang terorganisis, pengembangan serta deployment aplikasi ASP.NET Framework 4.x klasik di macOS kini lebih nyaman dan terstandarisasi. Semoga panduan ini membantu Anda memulai proyek dengan lancar!

Pengembangan ASP.NET Framework 4.x di macOS dengan ServBay ​

Syarat Awal ​

Menyiapkan Proyek ASP.NET Anda ​

Metode 1: Menggunakan XSP (Server Pengembangan Bawaan) ​

Metode 2: Menggunakan Nginx + FastCGI ​

Cara Memilih Metode yang Tepat ​

Catatan Penting & Troubleshooting ​