Phát triển ASP.NET Framework 4.x trên macOS với ServBay

ServBay mang đến môi trường Mono tích hợp mạnh mẽ, giúp phát triển và kiểm thử ASP.NET Framework 1.1/2.0/3.x/4.x (hỗ trợ tối đa tới 4.7.x) trên macOS trở nên đơn giản và khả thi.

Từ phiên bản ServBay v1.12.0, chúng tôi đã tích hợp Mono 6.14.0 kèm theo máy chủ phát triển XSP và công cụ fastcgi-mono-server, cung cấp hai phương pháp chính để chạy ứng dụng ASP.NET Framework 4.x:

Phát triển và kiểm thử nhanh với XSP: XSP là một máy chủ web ASP.NET nhẹ, thiết kế riêng cho Mono, rất phù hợp cho giai đoạn phát triển và kiểm thử nhanh.
Triển khai với Nginx + FastCGI: Cách này ổn định hơn, hiệu suất vượt trội và gần giống với môi trường sản xuất, chuyển tiếp yêu cầu từ Nginx do ServBay quản lý về tiến trình Mono để xử lý.

Tài liệu này sẽ hướng dẫn bạn cấu hình và vận hành dự án ASP.NET Framework 4.x trong môi trường ServBay.

Về .NET Framework và .NET

Lưu ý, tài liệu này đề cập đến phát triển ASP.NET Framework 4.x dựa trên Mono – một hệ sinh thái .NET truyền thống.

ServBay cũng hỗ trợ đầy đủ phát triển và triển khai .NET mới nhất (bao gồm .NET Core, .NET 5/6/7/8+). Nếu bạn tạo dự án .NET hiện đại hoặc muốn chuyển đổi, hãy ưu tiên chọn các SDK và runtime .NET chính thức do Microsoft cung cấp mà ServBay hỗ trợ, thay vì phương pháp dựa trên Mono được đề cập ở đây.

Điều kiện tiên quyết

Cài đặt ServBay: Đảm bảo bạn đã cài đặt ServBay phiên bản v1.12.0 hoặc mới hơn trên macOS.
Cài đặt Mono:
- Mở ứng dụng ServBay.
- Trong thanh điều hướng bên trái, chọn "Gói phần mềm".
- Tìm mục ".NET", nhấp để mở rộng.
- Tìm "Mono 6" (cần tối thiểu bản 6.14.0), nhấn nút "Cài đặt" bên phải và chờ hoàn thành.

Chuẩn bị dự án ASP.NET của bạn

Tập tin dự án: Đảm bảo bạn đã có một dự án Web Application hoặc Web Site dựa trên ASP.NET Framework 4.x, có chứa tập tin web.config.
Vị trí lưu trữ đề xuất: Rất nên đặt dự án website của bạn trong thư mục www được quản lý tập trung bởi ServBay, tại /Applications/ServBay/www/, mỗi dự án ở một thư mục con riêng biệt.
- Ví dụ: Nếu dự án của bạn tên là MyWebApp, đường dẫn gốc website nên là /Applications/ServBay/www/MyWebApp.
- Ở các bước tiếp theo, sẽ dùng /Applications/ServBay/www/MyWebApp làm đường dẫn mẫu. Hãy thay thế bằng đường dẫn thực tế tới dự án của bạn.

Cách 1: Sử dụng XSP (máy chủ phát triển tích hợp)

XSP là một máy chủ web nhẹ cho ASP.NET do Mono cung cấp, lý tưởng cho phát triển và kiểm thử nhanh các ứng dụng ASP.NET Framework. Gói Mono 6 trên ServBay đã bao gồm XSP4 (tương ứng ASP.NET 4.x).

Mẹo

Nếu đang chạy dự án ASP.NET 1.1, hãy dùng lệnh xsp.
Nếu chạy ASP.NET 2.0/3.x, hãy dùng lệnh xsp2.
Nếu chạy ASP.NET 4.x, hãy dùng lệnh xsp4.

Các bước thực hiện:

Mở Terminal: Khởi chạy ứng dụng Terminal trên macOS.
Chuyển tới thư mục dự án: Dùng lệnh cd để đến thư mục gốc của dự án ASP.NET (chứa tập tin web.config).
bash
```
# Ví dụ: Di chuyển vào thư mục dự án MyWebApp
cd /Applications/ServBay/www/MyWebApp
```
1
2
Khởi động máy chủ XSP: Tại thư mục gốc dự án, chạy lệnh sau để khởi động XSP4 trên một cổng chưa sử dụng (ví dụ 8080 hoặc 9000) để tránh xung đột với các dịch vụ khác trên ServBay.
bash
```
# Khởi chạy dự án trên cổng 9000
xsp4 --port 9000
```
1
2
- xsp4: Chạy máy chủ XSP tương thích .NET Framework 4.x.
- --port 9000: Chỉ định cổng TCP mà máy chủ lắng nghe.
Truy cập ứng dụng: Mở trình duyệt và truy cập http://localhost:9000 hoặc http://127.0.0.1:9000. Bạn sẽ thấy ứng dụng ASP.NET của mình đang chạy.
Dừng máy chủ: Khi hoàn thành kiểm thử, quay lại cửa sổ Terminal vừa chạy XSP, nhấn Ctrl + C hoặc Enter để dừng máy chủ XSP.

Ưu điểm:

Cấu hình nhanh, dễ sử dụng.
Phù hợp phát triển và debug cục bộ.

Nhược điểm:

Hiệu suất không bằng các máy chủ web sản xuất như Nginx.
Tính năng cơ bản, không thể mô phỏng đầy đủ môi trường production.
Cần giữ Terminal luôn mở khi chạy.

Cách 2: Sử dụng Nginx + FastCGI

Với phương pháp này, Nginx do ServBay quản lý đóng vai trò làm máy chủ web phía trước, tiếp nhận yêu cầu từ client và xử lý tệp tĩnh, đồng thời chuyển tiếp các yêu cầu động (như .aspx, .ashx...) qua FastCGI tới tiến trình Mono (fastcgi-mono-server4) để xử lý. Đây là lựa chọn gần giống production hơn, hiệu năng tốt hơn và tận dụng các tính năng nâng cao của Nginx (như SSL, cache, nén, v.v.).

Mẹo

Để chạy dự án ASP.NET 1.1, sử dụng lệnh fastcgi-mono-server.
Với ASP.NET 2.0/3.x, sử dụng fastcgi-mono-server2.
Với ASP.NET 4.x, dùng fastcgi-mono-server4.

Các bước thực hiện:

Đảm bảo Mono và Nginx đã được cài và chạy:
- Cài đặt Mono 6 và Nginx từ phần "Gói phần mềm" của ServBay.
- Trong phần "Dịch vụ" của ServBay, kiểm tra Nginx đã khởi động.
Chuẩn bị dự án ASP.NET: Đặt dự án tại vị trí khuyến nghị, ví dụ /Applications/ServBay/www/MyWebApp.
Khởi động FastCGI Mono Server:
- Mở một cửa sổ Terminal mới.
- Chạy tiến trình fastcgi-mono-server4. Tiến trình này lắng nghe các yêu cầu FastCGI từ Nginx, phân tích các trang ASP.NET và xử lý nghiệp vụ.
  bash
```
# Khởi động dịch vụ FastCGI cho dự án 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: Khởi tạo server FastCGI tương thích .NET Framework 4.x.
  - --applications=/:/Applications/ServBay/www/MyWebApp: Xác định ánh xạ đường dẫn URL đến đường dẫn vật lý của website. /: là URL gốc (/), /Applications/ServBay/www/MyWebApp là đường dẫn thực tế của bạn. Khi Nginx chuyển tiếp một request như /some/page.aspx, Mono sẽ tìm và thực thi tại /Applications/ServBay/www/MyWebApp/some/page.aspx. Hãy thay bằng đường dẫn dự án của bạn.
  - --socket=tcp:127.0.0.1:9001: Chỉ định địa chỉ và cổng TCP FastCGI sẽ lắng nghe. 127.0.0.1 nghĩa là chỉ accept kết nối nội bộ, 9001 là cổng. Đảm bảo cổng này chưa bị dịch vụ nào khác dùng, đồng thời cổng này phải thống nhất với tham số cấu hình fastcgi_pass trên Nginx.
  - --loglevels=Standard --printlog: (Tùy chọn) In log chuẩn ra Terminal để tiện debug.
- Lưu ý: Cửa sổ Terminal chạy fastcgi-mono-server4 cần luôn mở. Để dùng lâu dài, nên chạy tiến trình dưới nền với nohup, screen hoặc tmux.

Cấu hình website trên Nginx:

Truy cập phần "Website" trong ServBay.
Nhấn "Thêm site" hoặc chỉnh sửa một site hiện có.
Cấu hình tên miền: Chọn tên miền ví dụ mywebapp.servbay.demo. ServBay sẽ tự động thêm tên miền này vào file Hosts của macOS, trỏ về 127.0.0.1.
Cấu hình thư mục gốc: Cực kỳ quan trọng! Cần trỏ đến đường dẫn thực tế dự án ASP.NET, ví dụ /Applications/ServBay/www/MyWebApp. Lệnh này sẽ xác lập tham số root trên Nginx cho xử lý file tĩnh.

Bật và sửa cấu hình tùy chỉnh: Đánh dấu "Cấu hình tùy chỉnh" ở góc trên phải của phần cấu hình site. ServBay sẽ sinh sẵn file cấu hình Nginx cơ bản. Bạn cần bổ sung/sửa cấu hình để chuyển tiếp request động sang FastCGI Mono Server.

Ví dụ phần cấu hình cần kiểm tra hoặc hiệu chỉnh như sau:

nginx

server {
    listen 80; # Lắng nghe cổng HTTP
    listen 443 ssl http2; # Lắng nghe HTTPS, bật SSL & HTTP/2

    # Cấu hình chứng chỉ SSL do ServBay quản lý
    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;

    # Đường dẫn file chứng chỉ – ServBay sẽ tự động quản lý
    ssl_certificate /Applications/ServBay/ssl/private/tls-certs/mywebapp.servbay.demo/mywebapp.servbay.demo.crt; # Đảm bảo đúng domain
    ssl_certificate_key /Applications/ServBay/ssl/private/tls-certs/mywebapp.servbay.demo/mywebapp.servbay.demo.key;

    server_name mywebapp.servbay.demo; # Phải khớp với tên domain trên ServBay
    root /Applications/ServBay/www/MyWebApp; # **Đảm bảo** khớp thư mục gốc

    # Bổ sung default page cho ASP.NET khi Nginx không tìm thấy index.html/htm
    index index.html index.htm default.aspx Default.aspx;

    # Logic chính cho xử lý yêu cầu
    location / {
        # Tìm file hoặc thư mục tĩnh, nếu không thấy thì chuyển tới @mono
        try_files $uri $uri/ @mono;
    }

    # (Tùy chọn, khuyến nghị) Nginx xử lý trực tiếp file tĩnh, tận dụng cache
    location ~* \.(ico|css|js|gif|jpe?g|png|svg|woff|woff2|ttf|eot)$ {
        expires max;
        log_not_found off;
        access_log off;
    }

    # Khối location @mono để chuyển tiếp request động
    location @mono {
        # Chuyển tới Mono qua FastCGI
        # **Cổng phải khớp với --socket đã cấu hình**
        fastcgi_pass 127.0.0.1:9001;

        # Thêm bộ tham số chuẩn FastCGI
        include fastcgi_params;
        # Tham số quan trọng: xác định script file cho Mono Server
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO "";

        # (Tùy chọn) Có thể bổ sung các tham số FastCGI khác nếu cần
        # fastcgi_param HOST $host;
    }

    # Có thể bổ sung các cấu hình mặc định khác như đường dẫn log v.v.
    # access_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.access.log;
    # error_log /Applications/ServBay/logs/nginx/mywebapp.servbay.demo.error.log;
}

Lưu lại và tải lại/khởi động lại Nginx: Lưu file cấu hình trên ServBay. ServBay sẽ tự động reload Nginx nếu cấu hình hợp lệ, hoặc báo lỗi nếu có vấn đề cú pháp. Nếu cần, vào mục "Dịch vụ" để khởi động lại Nginx thủ công.

Truy cập ứng dụng: Mở trình duyệt và truy cập domain đã config trên Nginx (ví dụ https://mywebapp.servbay.demo). Vì đã bật SSL trên cổng 443, khuyến nghị sử dụng HTTPS. Nginx sẽ trả về file tĩnh trực tiếp hoặc chuyển yêu cầu động qua fastcgi-mono-server4 để Mono chạy mã lệnh ASP.NET của bạn.

Ưu điểm:

Hiệu suất cao, ổn định, gần giống môi trường production.
Tận dụng sức mạnh của Nginx (phục vụ file tĩnh, SSL, balancing...).
Tích hợp tốt với quản lý website, domain và Hosts của ServBay.

Nhược điểm:

Cấu hình phức tạp hơn XSP.
Cần quản lý tiến trình fastcgi-mono-server4 thủ công (nếu không chạy dưới nền).

Chọn phương pháp phù hợp

Nếu cần phát triển nhanh, debug hoặc kiểm thử chức năng đơn giản, hãy chọn XSP để khởi chạy tức thì.
Nếu cần hiệu năng cao, kiểm thử sát thực tế hoặc tích hợp domain/HTTPS, hãy chọn Nginx + FastCGI để tận dụng các tính năng nâng cao của Nginx và hệ thống quản lý site của ServBay.

Lưu ý & Xử lý sự cố

Quyền truy cập tập tin: Đảm bảo cả tiến trình Nginx (do ServBay quản lý) và tiến trình fastcgi-mono-server4 (do user macOS của bạn chạy) đều có quyền đọc đủ các file dự án (/Applications/ServBay/www/YourProjectName). Có thể cần dùng lệnh chmod hoặc chown để thiết lập quyền truy cập.
Đồng nhất đường dẫn: Kiểm tra kỹ thư mục project trên cả cấu hình Nginx (root) và lệnh fastcgi-mono-server4 (--applications) đều đúng và trỏ về thư mục gốc chứa web.config.
Xung đột cổng: Đảm bảo các cổng sử dụng cho XSP hay fastcgi-mono-server4 (ví dụ 9000, 9001) không bị chiếm bởi dịch vụ hoặc ứng dụng nào khác trong hệ thống hoặc trên ServBay.
Kiểm tra log:
- Kiểm tra log xuất ra Terminal khi khởi động fastcgi-mono-server4 (sử dụng --printlog).
- Kiểm tra log lỗi của Nginx, thường được hiển thị trong phần cài đặt site của ServBay, mặc định tại /Applications/ServBay/logs/nginx/your-domain.error.log. Log lỗi giúp xác định sự cố cấu hình Nginx hoặc vấn đề kết nối FastCGI.
Tương thích phiên bản Mono: Mono 6.14.0 tích hợp trên ServBay tương đối tương thích các đặc tả .NET Framework 1.1 tới 4.7.2. Nếu sử dụng tính năng mới hơn, hoặc gặp trục trặc tương thích, hãy cân nhắc chuyển sang sử dụng .NET SDK/runtime chính thức của Microsoft trên ServBay, hoặc hạ cấp project về mức được Mono hỗ trợ.
Quản lý tiến trình FastCGI: Nếu chọn cách Nginx + FastCGI, đảm bảo tiến trình fastcgi-mono-server4 luôn chạy. Trong khi phát triển chỉ cần Terminal luôn mở, nhưng ở môi trường chính thức, hãy thiết lập dịch vụ nền hoặc dùng tiến trình manager cho tiện quản lý.

Nhờ môi trường Mono 6 tích hợp sẵn của ServBay và cấu trúc dự án thống nhất được khuyến nghị, việc phát triển và chạy ứng dụng ASP.NET Framework 4.x truyền thống trên macOS giờ đây trở nên chuyên nghiệp và tiện lợi hơn bao giờ hết. Chúc bạn triển khai dự án thành công!

Phát triển ASP.NET Framework 4.x trên macOS với ServBay ​

Điều kiện tiên quyết ​

Chuẩn bị dự án ASP.NET của bạn ​

Cách 1: Sử dụng XSP (máy chủ phát triển tích hợp) ​

Cách 2: Sử dụng Nginx + FastCGI ​

Chọn phương pháp phù hợp ​

Lưu ý & Xử lý sự cố ​