如何在 macOS 下进行 ASP.NET Framework 4.x 的开发

ServBay 通过内置强大的 Mono 环境，使得在 macOS 上进行 ASP.NET Framework 1.1/2.0/3.x/4.x (最高支持到 4.7.x) 的开发和测试变得简单可行。

自 ServBay v1.12.0 版本起，我们集成了 Mono 6.14.0，并自带了 XSP 开发服务器，为您提供两种主要的运行 ASP.NET Framework 4.x 应用程序的方式：

使用 XSP 进行快速开发和测试
以及使用 Nginx + FastCGI 部署更稳定、更接近生产环境的应用。

本文档将指导您如何在 ServBay 环境下配置和运行您的 ASP.NET Framework 4.x 项目。

前提条件

安装 ServBay: 确保您已在 macOS 上安装了 ServBay v1.12.0 或更高版本。
安装 Mono:
- 打开 ServBay 应用程序。
- 在左侧导航栏中，选择「软件包」。
- 在软件包列表中，找到「.NET」分类，点击展开。
- 找到「Mono 6」 (版本应为 6.14.0 或更高)，点击右侧的「安装」按钮，并等待安装完成。

准备您的 ASP.NET 项目

项目文件: 确保您有一个 ASP.NET Framework 4.x 的 Web Application 或 Web Site 项目。
推荐存放位置: 我们强烈建议将您的网站项目放置在 ServBay 统一管理的 www 目录下，即 /Applications/ServBay/www/。为每个项目创建一个单独的子目录。
- 示例: 如果您的项目名为 MyWebApp，则推荐的路径为 /Applications/ServBay/www/MyWebApp。
- 在后续的步骤中，我们将使用 /Applications/ServBay/www/MyWebApp 作为示例路径。请务必将其替换为您项目的实际路径。

方法一：使用 XSP (内置开发服务器)

XSP 是一个轻量级的、专为 Mono 设计的 ASP.NET Web 服务器，非常适合开发和快速测试阶段。ServBay 安装的 Mono 6 包已内置 XSP4 (对应 ASP.NET 4.x)。

提示

如果你要运行ASP.NET 1.1的项目，请使用xsp命令。
如果你要运行ASP.NET 2.0的项目，请使用xsp2命令。

步骤：

打开终端: 打开 macOS 的终端应用程序 (Terminal)。
导航到项目目录: 使用 cd 命令进入到您 ASP.NET 项目的根目录（包含 web.config 文件的目录）。
bash
```
# 示例：进入名为 MyWebApp 的项目目录
cd /Applications/ServBay/www/MyWebApp
```
1
2
启动 XSP 服务器: 在项目根目录下，运行以下命令来启动 XSP4 服务器。您可以指定一个端口号（例如 8080 或 9000），避免与 ServBay 中其他服务冲突。
bash
```
# 在 9000 端口启动当前目录下的项目
xsp4 --port 9000
```
1
2
- xsp4: 调用适用于 .NET 4.x 的 XSP 服务器。
- --port 9000: 指定服务器监听的端口号。
访问应用程序: 打开您的 Web 浏览器，访问 http://localhost:9000 或 http://127.0.0.1:9000。您应该能看到您的 ASP.NET 应用程序正在运行。
停止服务器: 当您完成开发或测试后，返回到终端窗口，按下 Ctrl + C 或者 回车键 来停止 XSP 服务器。

优点:

配置简单，快速启动。
非常适合本地开发和调试。

缺点:

性能不如 Nginx 等生产级服务器。
功能相对基础，不完全模拟生产环境。

方法二：使用 Nginx + FastCGI

这种方式使用 ServBay 管理的 Nginx 作为前端 Web 服务器，通过 FastCGI 协议将动态请求转发给 Mono 后端进程 (fastcgi-mono-server4) 处理。这种方式更接近生产环境部署，性能也更好。

提示

如果你要运行ASP.NET 1.1的项目，请使用fastcgi-mono-server命令。
如果你要运行ASP.NET 2.0的项目，请使用fastcgi-mono-server2命令。

步骤：

确保 Mono 和 Nginx 已安装并运行:
- 通过 ServBay 的「软件包」安装 Mono 6 和 Nginx。
- 在 ServBay 的「服务」部分，确保 Nginx 服务已启动。
准备 ASP.NET 项目: 确保您的项目位于推荐路径下，例如 /Applications/ServBay/www/MyWebApp。
启动 FastCGI Mono Server:
- 打开一个新的终端窗口。
- 运行 fastcgi-mono-server4 进程。这个进程负责监听来自 Nginx 的 FastCGI 请求并执行您的 ASP.NET 代码。
  bash
```
# 示例：为 MyWebApp 项目启动 FastCGI 服务
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: 将网站的根路径 (/) 映射到您项目的物理路径。请务必将 /Applications/ServBay/www/MyWebApp 替换为您项目的实际路径。
  - --socket=tcp:127.0.0.1:9001: 指定 FastCGI 服务器监听的 TCP 地址和端口。请确保此端口（例如 9001）未被占用，并且与下面 Nginx 配置中的 fastcgi_pass 指令匹配。
  - --loglevels=Standard --printlog: （可选）在终端打印标准级别的日志，方便调试。
- 注意: 这个终端窗口需要保持打开状态以运行 FastCGI 服务。对于长期运行，您可能需要使用 nohup 或 screen/tmux 等工具让它在后台运行。

配置 Nginx 站点:

在 ServBay 中，转到「站点」部分。
点击「添加站点」或选择一个现有站点进行编辑。
设置域名: 例如 mywebapp.test。ServBay 会自动为您添加到 Hosts 文件。
设置网站根目录: 非常重要！ 将此设置为您 ASP.NET 项目的实际路径，例如 /Applications/ServBay/www/MyWebApp。这会正确设置 Nginx 配置中的 root 指令。

关键：检查/编辑 Nginx 配置文件: 点击站点设置右上角的「自定义配置」选择框。ServBay 会根据您设置的网站根目录生成基础配置。您需要确保 location / 和 @mono (或其他类似命名的 location 块) 配置正确，以将请求代理到 FastCGI Mono Server。

一个基于 ServBay 自动生成的配置，需要检查或添加的部分示例如下：

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; # 确保证书与实际路径一致
    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 Server
        # **端口必须**与 fastcgi-mono-server4 启动时 --socket 参数指定的端口一致
        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 会提示错误。必要时，可在 ServBay 的「服务」页面手动重启 Nginx。

访问应用程序: 打开浏览器，访问您在 Nginx 中配置的域名（例如 https://mywebapp.test，注意此处使用了 HTTPS 协议）。Nginx 会将请求转发给 fastcgi-mono-server4，由 Mono 执行您的 ASP.NET 代码。

优点:

性能更好，更稳定。
更接近生产环境的部署方式。
可以利用 Nginx 处理静态文件、负载均衡、SSL 等高级功能。
与 ServBay 的站点管理、域名和 Hosts 管理集成度更高。

缺点:

配置相对 XSP 复杂一些。
需要手动管理 fastcgi-mono-server4 进程。

如何选择

对于快速开发、调试和简单测试，使用 XSP 是最便捷的方式。
对于需要更高性能、更接近生产环境的测试或内部部署，或者希望利用 Nginx 的高级特性和 ServBay 的站点管理功能时，选择 Nginx + FastCGI 模式是更好的选择。

注意事项与故障排查

文件权限: 确保 Nginx 进程（通常由 ServBay 管理）和运行 fastcgi-mono-server4 的 macOS 用户对您的项目文件（位于 /Applications/ServBay/www/YourProjectName）有读取权限。有时可能需要调整目录权限 (chmod 或 chown)。
路径: 仔细检查 Nginx 配置 (root 指令) 和 fastcgi-mono-server4 命令 (--applications 参数) 中的项目路径是否完全正确，并指向包含 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 大致兼容到 .NET Framework 4.7.2。如果您使用了更高版本 .NET Framework 的特性，请使用 ServBay 安装微软官方的.NET Core 或者 .NET。

通过 ServBay 内置的 Mono 6 环境和推荐的项目结构，在 macOS 上开发和运行 ASP.NET Framework 4.x 应用变得更加规范和便捷。希望本文档能帮助您顺利地开始您的开发工作！

如何在 macOS 下进行 ASP.NET Framework 4.x 的开发 ​

前提条件 ​

准备您的 ASP.NET 项目 ​

方法一：使用 XSP (内置开发服务器) ​

方法二：使用 Nginx + FastCGI ​

如何选择 ​

注意事项与故障排查 ​