Button

Mac 中使用 VSCode 开发 Framework 项目指南

前置要求

对于 .NET Framework 4.5.2 项目，在 macOS 上需要使用 Mono 来运行。

第一步：安装必需工具

1. 安装 Mono

brew install mono

验证安装：

mono --version

2. 安装 NuGet

brew install nuget

3. 安装 MSBuild (包含在 Mono 中)

验证安装：

msbuild -version

4. 安装 XSP (Mono 的 Web 服务器)

brew install xsp

第二步：安装 VSCode 扩展

在 VSCode 中安装以下扩展（已在 <code>.vscode/extensions.json</code> 中推荐）：

  1. C# Dev Kit – 微软官方 C# 支持
  2. C# – OmniSharp 语言服务
  3. .NET Test Explorer – 测试资源管理器

重启 VSCode 以激活扩展。

第三步：构建项目

方法 1：使用 VSCode 任务（推荐）

  1. 按 <code>Cmd+Shift+P</code> 打开命令面板
  2. 选择 <code>Tasks: Run Task</code>
  3. 选择 <code>构建解决方案 (Debug)</code>

方法 2：使用终端命令

# 恢复 NuGet 包
nuget restore <Solution-Name>.sln

# 构建项目
msbuild <Solution-Name>.sln /p:Configuration=Debug

第四步：运行和调试

运行 WebAPI 项目

方法 1：使用 XSP（Mono Web 服务器）

# 在终端中运行
xsp4 --port=<PORT> --path=<ProjectName>

然后访问：http://localhost:23985/api/message

方法 2：使用 VSCode 任务

  1. 按 <code>Cmd+Shift+P</code>
  2. 选择 <code>Tasks: Run Task</code>
  3. 选择 <code>运行 WebAPI (XSP)</code>

调试代码

  1. 在代码中设置断点（点击行号左侧）
  2. 按 <code>F5</code> 或点击调试面板的"开始调试"
  3. 选择配置：<code>调试 WebAPI (Mono)</code>

运行单元测试

使用 VSCode 任务：

  1. 按 <code>Cmd+Shift+P</code>
  2. 选择 <code>Tasks: Run Task</code>
  3. 选择 <code>运行单元测试</code>

使用命令行：

# 首先需要安装 NUnit Console Runner（如果还没有）
nuget install NUnit.ConsoleRunner -Version 3.15.0 -OutputDirectory packages

# 运行测试
mono packages/NUnit.ConsoleRunner.3.15.0/tools/nunit3-console.exe \
  <TestProjectName>/bin/Debug/<TestProjectName>.dll

常用 VSCode 快捷键

  • <code>Cmd+Shift+B</code> – 运行默认构建任务
  • <code>F5</code> – 开始调试
  • <code>Shift+F5</code> – 停止调试
  • <code>F9</code> – 切换断点
  • <code>F10</code> – 单步跳过
  • <code>F11</code> – 单步进入
  • <code>Cmd+K Cmd+D</code> – 格式化文档

常见问题

1. Mono 找不到程序集

确保已运行 <code>nuget restore</code> 来恢复所有依赖包。

2. MSBuild 失败

检查 Mono 版本是否支持 .NET Framework 4.5.2：

mono --version

需要 Mono 5.0 或更高版本。

3. XSP 无法启动

确保端口 23985 未被占用：

lsof -i :23985

4. OmniSharp 无法加载项目

在 VSCode 设置中确保：

  • <code>omnisharp.useModernNet</code> 设置为 <code>false</code>
  • <code>omnisharp.monoPath</code> 指向正确的 Mono 安装路径

已知限制

  1. 调试功能受限：Mono 的调试体验不如 Windows 上的 Visual Studio
  2. 性能差异：Mono 运行性能可能低于 Windows .NET Framework
  3. 某些 API 不可用：部分 Windows 特定的 API 在 Mono 上不支持

建议

对于生产环境部署，建议：

  1. 在 Windows Server 上使用 IIS 托管
  2. 或考虑将项目迁移到 .NET 6/8 以获得跨平台支持

迁移到现代 .NET 的好处

如果你计划长期维护此项目，可以考虑迁移到 .NET 8：

  • 原生跨平台支持（无需 Mono）
  • 更好的性能
  • 现代化的工具链
  • 长期支持（LTS）

迁移步骤请参考：https://docs.microsoft.com/zh-cn/aspnet/core/migration/

Related Posts