Cách phát triển ASP.NET Framework 4.x trên macOS

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

Kể từ phiên bản ServBay v1.12.0, chúng tôi đã tích hợp Mono 6.14.0 cùng với máy chủ phát triển XSP, cung cấp cho bạn hai phương pháp chính để chạy các ứng dụng ASP.NET Framework 4.x:

Sử dụng XSP để phát triển và thử nghiệm nhanh
Và sử dụng Nginx + FastCGI để triển khai các ứng dụng ổn định hơn, gần hơn với môi trường sản xuất.

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

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

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

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

Tập tin dự án: Đảm bảo bạn có một ứng dụng Web hoặc dự án Web ASP.NET Framework 4.x.
Vị trí đề xuất: Chúng tôi rất khuyến khích bạn đặt dự án web của mình trong thư mục www do ServBay quản lý, tức là /Applications/ServBay/www/. Tạo một thư mục con riêng cho mỗi dự án.
- Ví dụ: Nếu tên dự án của bạn là MyWebApp, đường dẫn đề xuất sẽ là /Applications/ServBay/www/MyWebApp.
- Trong các bước tiếp theo, chúng tôi sẽ sử dụng /Applications/ServBay/www/MyWebApp làm đường dẫn ví dụ. Hãy chắc chắn thay thế nó bằng đường dẫn thực tế của dự án bạn.

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

XSP là một máy chủ web ASP.NET nhẹ, được thiết kế đặc biệt cho Mono, rất thích hợp cho các giai đoạn phát triển và thử nghiệm nhanh. Gói Mono 6 cài đặt với ServBay đã tích hợp sẵn XSP4 (tương ứng với ASP.NET 4.x).

Mẹo

Nếu bạn muốn chạy dự án ASP.NET 1.1, hãy sử dụng lệnh xsp.
Nếu bạn muốn chạy dự án ASP.NET 2.0, hãy sử dụng lệnh xsp2.

Bước:

Mở Terminal: Mở ứng dụng Terminal trên macOS.
Chuyển đến thư mục dự án: Sử dụng lệnh cd để vào thư mục gốc của dự án ASP.NET của bạn (thư mục chứa tệp web.config).
bash
```
# Ví dụ: vào thư mục dự án có tên MyWebApp
cd /Applications/ServBay/www/MyWebApp
```
1
2
Khởi động máy chủ XSP: Tại thư mục gốc của dự án, chạy lệnh sau để khởi động máy chủ XSP4. Bạn có thể chỉ định một số cổng (ví dụ 8080 hoặc 9000) để tránh xung đột với các dịch vụ khác trong ServBay.
bash
```
# Khởi động dự án trong thư mục hiện tại trên cổng 9000
xsp4 --port 9000
```
1
2
- xsp4: Gọi máy chủ XSP phù hợp với .NET 4.x.
- --port 9000: Chỉ định cổng mà máy chủ lắng nghe.
Truy cập ứng dụng: Mở trình duyệt web của bạn, 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 bạn đang chạy.
Dừng máy chủ: Khi bạn hoàn thành phát triển hoặc thử nghiệm, trở lại cửa sổ terminal và nhấn Ctrl + C hoặc phím Enter để dừng máy chủ XSP.

Ưu điểm:

Cấu hình đơn giản, khởi động nhanh.
Rất phù hợp cho phát triển và gỡ lỗi cục bộ.

Nhược điểm:

Hiệu suất không bằng các máy chủ sản xuất như Nginx.
Tính năng cơ bản, không hoàn toàn mô phỏng môi trường sản xuất.

Phương pháp 2: Sử dụng Nginx + FastCGI

Phương pháp này sử dụng Nginx quản lý bởi ServBay làm máy chủ web phía trước, chuyển tiếp các yêu cầu động qua giao thức FastCGI đến tiến trình backend Mono (fastcgi-mono-server4). Phương pháp này gần giống với triển khai môi trường sản xuất và có hiệu suất tốt hơn.

Mẹo

Nếu bạn muốn chạy dự án ASP.NET 1.1, hãy sử dụng lệnh fastcgi-mono-server.
Nếu bạn muốn chạy dự án ASP.NET 2.0, hãy sử dụng lệnh fastcgi-mono-server2.

Bước:

Đảm bảo Mono và Nginx đã được cài đặt và đang chạy:
- Cài đặt Mono 6 và Nginx thông qua gói của ServBay.
- Trong phần "Dịch vụ" của ServBay, đảm bảo dịch vụ Nginx đã khởi động.
Chuẩn bị dự án ASP.NET: Đảm bảo dự án của bạn nằm trong đường dẫn đề xuất, 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 có trách nhiệm lắng nghe các yêu cầu FastCGI từ Nginx và thực thi mã ASP.NET của bạn.
  bash
```
# Ví dụ: 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
  - --applications=/:/Applications/ServBay/www/MyWebApp: ánh xạ đường dẫn gốc của trang web (/) đến đường dẫn vật lý của dự án của bạn. Hãy chắc chắn thay thế /Applications/ServBay/www/MyWebApp bằng đường dẫn thực tế của dự án bạn.
  - --socket=tcp:127.0.0.1:9001: chỉ định địa chỉ và cổng TCP mà máy chủ FastCGI nghe. Hãy chắc chắn rằng cổng này (ví dụ 9001) không bị chiếm dụng và khớp với chỉ thị fastcgi_pass trong cấu hình Nginx bên dưới.
  - --loglevels=Standard --printlog: (tùy chọn) in nhật ký mức chuẩn trên terminal để dễ dàng gỡ lỗi.
- Lưu ý: Cửa sổ terminal này cần phải mở để máy chủ FastCGI chạy. Đối với hoạt động lâu dài, bạn có thể cần sử dụng nohup hoặc các công cụ như screen/tmux để chạy nó ở chế độ nền.

Cấu hình trang web Nginx:

Trong ServBay, đi đến phần "Trang web".
Nhấn "Thêm trang web" hoặc chọn một trang web hiện có để chỉnh sửa.
Đặt tên miền: Ví dụ mywebapp.test. ServBay sẽ tự động thêm vào tệp Hosts.
Đặt thư mục gốc của trang web: Rất quan trọng! Đặt cài đặt này là đường dẫn thực tế của dự án ASP.NET của bạn, ví dụ /Applications/ServBay/www/MyWebApp. Điều này sẽ thiết lập chính xác chỉ thị root trong cấu hình Nginx.

Chú ý quan trọng: Kiểm tra/chỉnh sửa tệp cấu hình Nginx: Nhấn vào hộp chọn "Cấu hình tùy chỉnh" ở góc bên phải của cài đặt trang web. ServBay sẽ tạo cấu hình cơ bản dựa trên thư mục gốc của bạn. Bạn cần đảm bảo rằng cấu hình cho location / và @mono (hoặc các khối location tương tự khác) đúng để chuyển tiếp yêu cầu đến FastCGI Mono Server.

Một phần mẫu của cấu hình tự động sinh ra bởi ServBay mà cần kiểm tra hoặc thêm như sau:

nginx

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; # Đảm bảo chứng chỉ khớp với đường dẫn thực tế
    ssl_certificate_key /Applications/ServBay/ssl/private/tls-certs/mywebapp.test/mywebapp.test.key; # Đảm bảo chứng chỉ khớp với đường dẫn thực tế

    server_name mywebapp.test; # Phải khớp với tên miền bạn đã thiết lập trong ServBay
    root /Applications/ServBay/www/MyWebApp; # **Đảm bảo** điều này khớp với thư mục gốc bạn đã đặt
    index index.html index.htm default.aspx Default.aspx; # Thêm tài liệu mặc định của ASP.NET

    location / {
        try_files $uri $uri/ @mono; # Cố gắng truy cập tệp tĩnh, nếu không chuyển tới @mono xử lý
    }

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

    location @mono {
        # Chuyển tiếp yêu cầu đến FastCGI Mono Server
        # **Cổng phải** khớp với cổng được chỉ định trong tham số --socket khi khởi động fastcgi-mono-server4
        fastcgi_pass 127.0.0.1:9001;

        # Các tham số FastCGI cần thiết
        include fastcgi_params;
        # SCRIPT_FILENAME sẽ được thiết lập dựa trên chỉ thị root và $fastcgi_script_name
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO "";
    }

    # ServBay có thể bao gồm các cấu hình mặc định khác như nhật ký, kiểm soát truy cập, v.v.
    # access_log /Applications/ServBay/logs/nginx/mywebapp.test.access.log;
    # error_log /Applications/ServBay/logs/nginx/mywebapp.test.error.log;
}

Lưu cấu hình và khởi động lại Nginx: Lưu tệp cấu hình Nginx. ServBay sẽ tự động tải lại cấu hình Nginx sau khi lưu. Nếu cấu hình sai, ServBay sẽ thông báo lỗi. Nếu cần, bạn có thể khởi động lại Nginx thủ công từ trang "Dịch vụ" của ServBay.

Truy cập ứng dụng: Mở trình duyệt, truy cập tên miền bạn đã cấu hình trong Nginx (ví dụ https://mywebapp.test, lưu ý rằng đây là giao thức HTTPS). Nginx sẽ chuyển tiếp yêu cầu đến fastcgi-mono-server4, và Mono sẽ thực thi mã ASP.NET của bạn.

Ưu điểm:

Hiệu suất tốt hơn và ổn định hơn.
Cách triển khai gần nhất so với môi trường sản xuất.
Có thể tận dụng Nginx để xử lý tệp tĩnh, cân bằng tải, SSL và các tính năng nâng cao khác.
Tích hợp cao hơn với quản lý trang web, tên miền và quản lý Hosts của ServBay.

Nhược điểm:

Cấu hình phức tạp hơn một chút so với XSP.
Cần quản lý thủ công tiến trình fastcgi-mono-server4.

Cách chọn

Đối với phát triển nhanh, gỡ lỗi và thử nghiệm đơn giản, sử dụng XSP là cách thuận tiện nhất.
Đối với thử nghiệm hoặc triển khai nội bộ cần hiệu suất cao hơn, gần giống môi trường sản xuất, hoặc muốn tận dụng các tính năng nâng cao của Nginx và chức năng quản lý trang web của ServBay, lựa chọn Nginx + FastCGI là lựa chọn tốt hơn.

Lưu ý và khắc phục sự cố

Quyền tệp: Đảm bảo rằng tiến trình Nginx (thường được quản lý bởi ServBay) và người dùng macOS chạy fastcgi-mono-server4 có quyền đọc tệp dự án của bạn (nằm ở /Applications/ServBay/www/YourProjectName). Đôi khi bạn cần điều chỉnh quyền thư mục (chmod hoặc chown).
Đường dẫn: Kiểm tra kỹ cấu hình Nginx (chỉ thị root) và lệnh fastcgi-mono-server4 (tham số --applications) để đảm bảo đường dẫn dự án hoàn toàn chính xác và trỏ đến thư mục chứa web.config.
Xung đột cổng: Đảm bảo rằng cổng sử dụng bởi XSP hoặc fastcgi-mono-server4 (ví dụ 9000 hoặc 9001 trong ví dụ) không bị các ứng dụng khác chiếm dụng.
Nhật ký:
- Kiểm tra nhật ký đầu ra trên terminal khi khởi động fastcgi-mono-server4.
- Kiểm tra nhật ký lỗi của Nginx. Bạn có thể tìm thấy đường dẫn nhật ký lỗi tương ứng của trang web trong cài đặt trang web của ServBay (thường là /Applications/ServBay/logs/nginx/mywebapp.test.error.log).
Tương thích phiên bản Mono: Mono 6.14.0 tương thích từ .NET Framework 1.1 đến khoảng .NET Framework 4.7.2. Nếu bạn sử dụng các tính năng của phiên bản .NET Framework cao hơn, hãy sử dụng ServBay để cài đặt .NET Core hoặc .NET chính thức của Microsoft.

Với môi trường Mono 6 tích hợp sẵn của ServBay và cấu trúc dự án đề xuất, việc phát triển và chạy ứng dụng ASP.NET Framework 4.x trên macOS trở nên chuẩn hóa và thuận tiện hơn. Hy vọng tài liệu này sẽ giúp bạn thuận lợi bắt đầu công việc phát triển của mình!

Cách phát triển ASP.NET Framework 4.x trên macOS ​

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

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

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

Phương pháp 2: Sử dụng Nginx + FastCGI ​

Cách chọn ​

Lưu ý và khắc phục sự cố ​