调试 vvvv gamma C# 项目

关于 CLI 参数和会话文件，请参阅 vvvv-startup 技能。

上下文感知的配置工作流

当用户要求设置调试环境时，请遵循以下工作流。必须在生成任何文件之前，一次性提出所有配置问题（使用 AskUserQuestion）。切勿假设默认值——所有选项均需明确向用户确认。

1. 检测 vvvv 安装路径

通过扫描 C:\Program Files\vvvv 目录下匹配 vvvv_gamma_* 的子目录，自动定位 vvvv.exe：

ls -d "/c/Program Files/vvvv/vvvv_gamma_"* 2>/dev/null | sort -r

目录命名格式为：vvvv_gamma_MAJOR.MINOR[-BUILD-gHASH-PLATFORM]。按版本号降序排列。默认过滤掉含 -beta、-alpha、-rc、-test、-dev 后缀的预发布版本，除非工作区中不存在稳定版。

2. 扫描工作区

检测工作区中已存在的内容：

• .csproj / .sln 文件（可能需要或不需要构建任务 —— 见第 3 步）
• .vl 文件（可作为 --open 参数的目标）
• help/ 目录（常见测试补丁存放位置）
• 已存在的 .vscode/launch.json（应扩展而非覆盖）
• Git 子模块（尤其是 VL.StandardLibs —— 见下方关于包仓库的警告）
• 从仓库文件夹名、主 *.vl 文件或 .csproj 中的 元素提取包名称（用于 --editable-packages）

3. 向用户提问 —— 在生成前确认全部问题

关键：必须在生成任何配置前，使用 AskUserQuestion 提出以下全部问题。 可将相关问题合并为多选题形式以提升效率。在收集完全部答案前，禁止生成 launch.json。

问题组 1：vvvv 版本与补丁文件

• 使用哪个 vvvv 版本？ —— 列出已检测到的版本，推荐最新稳定版；允许用户从中选择，或指定自定义路径。
• 打开哪个 .vl 补丁？ —— 列出所有发现的 .vl 文件供选择；若存在 help/ 目录，则优先建议其中的文件。

问题组 2：启动参数

• 是否启用 --debug 标志？ —— 启用后支持断点调试，但会降低补丁加载速度。提问：“是否启用 --debug 以支持断点？（启动变慢）”。默认：快速迭代时为否；用户明确需要断点时为是。
• 是否启用 --allowmultiple？ —— 允许同时运行多个 vvvv 实例。提问：“是否允许多个 vvvv 实例？若选否，当已有 vvvv 运行时启动将失败（有助于发现残留进程）。” 默认：否。
• 是否启用 --package-repositories？ —— 指定 vvvv 扫描包的文件夹路径。警告：若工作区包含 VL.StandardLibs/ 等 Git 子模块，使用 --package-repositories ${workspaceFolder} 将导致 vvvv 重新编译全部核心库源码，耗时数分钟。 提问：“是否添加 --package-repositories？仅当 vvvv 无法自动发现你的包时才需启用。警告：若你的仓库包含 VL.StandardLibs 或其他库子模块，此选项将触发完整重编译。” 默认：否。
• 是否启用 --editable-packages？ —— 从源码加载指定包。仅在启用 --package-repositories 时有意义。仅当用户已启用 --package-repositories 后再询问此项。

问题组 3：构建模式

• 引用源码还是 DLL？ —— 提问：“你的 .vl 文档是直接引用 .csproj（源码引用，最常见），还是引用预编译的 DLL？” 源码引用 = 不需要构建任务；DLL 引用 = 需添加 preLaunchTask: "build"。

4. 生成配置文件

仅当所有问题均已回答完毕后，方可生成 .vscode/launch.json，并视情况生成 .vscode/tasks.json。

必须始终生成以下配置：

1. 一个使用用户所选参数的启动配置
2. 一个“附加到 vvvv”的配置，用于连接已运行的 vvvv 实例

可选生成：

• 若首个启动配置未启用 --debug，则额外生成一个启用该参数的配置（反之亦然）
• 若选择的是 DLL/二进制引用模式，则生成 tasks.json

VS Code launch.json

最小化配置（源码引用，无额外参数）

最简配置 —— 仅打开补丁：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "vvvv — MyPatch",
      "type": "coreclr",
      "request": "launch",
      "program": "C:\Program Files\vvvv\vvvv_gamma_7.1-win-x64\vvvv.exe",
      "args": [
        "-o",
        "${workspaceFolder}/help/HowTo Use MyFeature.vl"
      ],
      "cwd": "${workspaceFolder}",
      "stopAtEntry": false,
      "console": "internalConsole"
    },
    {
      "name": "Attach to vvvv",
      "type": "coreclr",
      "request": "attach",
      "processName": "vvvv.exe"
    }
  ]
}

完整配置（启用全部可选参数）

当用户启用所有参数时：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug with vvvv",
      "type": "coreclr",
      "request": "launch",
      "program": "C:\Program Files\vvvv\vvvv_gamma_7.0-win-x64\vvvv.exe",
      "args": [
        "--package-repositories",
        "${workspaceFolder}",
        "--editable-packages",
        "VL.MyPackage*",
        "-o",
        "${workspaceFolder}/help/HowTo Use MyFeature.vl",
        "--debug",
        "--allowmultiple"
      ],
      "cwd": "${workspaceFolder}",
      "stopAtEntry": false,
      "console": "internalConsole"
    },
    {
      "name": "Attach to vvvv",
      "type": "coreclr",
      "request": "attach",
      "processName": "vvvv.exe"
    }
  ]
}

DLL/二进制引用（需外部构建）

在启动 vvvv 前添加 preLaunchTask 构建 C# 项目：

{
  "name": "Debug with vvvv (pre-build)",
  "type": "coreclr",
  "request": "launch",
  "preLaunchTask": "build",
  "program": "C:\Program Files\vvvv\vvvv_gamma_7.0-win-x64\vvvv.exe",
  "args": [
    "-o",
    "${workspaceFolder}/help/HowTo Use MyFeature.vl",
    "--debug"
  ],
  "cwd": "${workspaceFolder}",
  "stopAtEntry": false,
  "console": "internalConsole"
}

关键要点：

• 源码引用时请省略 preLaunchTask —— vvvv 通过 Roslyn 在运行时处理 C# 编译
• 仅对 DLL/二进制引用或复杂构建场景添加 preLaunchTask: "build"
• --debug 启用调试符号（断点必需，但会降低补丁加载速度）
• --package-repositories 告知 vvvv 包的查找路径 —— 警告：将重新编译扫描目录树中发现的所有 VL 库子模块
• --editable-packages 从源码加载指定包（支持通配符模式）
• -o 在启动时打开指定的 .vl 补丁
• --allowmultiple 允许启动第二个 vvvv 实例 —— 省略该参数可用于检测残留实例
• 参数应以数组项形式列出（而非单个字符串），以提高可读性

附加到正在运行的 vvvv

当 vvvv 已运行且你希望在不重启的情况下调试时使用：

{
  "name": "Attach to vvvv",
  "type": "coreclr",
  "request": "attach",
  "processName": "vvvv.exe"
}

VS Code tasks.json（仅适用于 DLL/二进制引用配置）

仅当项目需要外部构建（如 DLL 引用、原生依赖、Release 构建）时才生成 tasks.json。对于 vvvv 在运行时编译 C# 的源码项目引用，完全跳过此步骤。

使用 dotnet 构建

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build",
      "command": "dotnet",
      "type": "process",
      "args": ["build", "${workspaceFolder}/src/MyProject.csproj", "-c", "Debug"],
      "problemMatcher": "$msCompile",
      "group": { "kind": "build", "isDefault": true }
    },
    {
      "label": "build-release",
      "command": "dotnet",
      "type": "process",
      "args": ["build", "${workspaceFolder}/src/MyProject.csproj", "-c", "Release"],
      "problemMatcher": "$msCompile"
    }
  ]
}

使用 MSBuild 构建（适用于 .sln 或需 Visual Studio 工具链的项目）

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build",
      "type": "shell",
      "command": "& 'C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe' '${workspaceFolder}/src/MyProject.sln' -p:Configuration=Debug -p:Platform=x64 -t:Rebuild -v:minimal",
      "options": {
        "shell": { "executable": "powershell.exe", "args": ["-Command"] }
      },
      "problemMatcher": "$msCompile",
      "group": { "kind": "build", "isDefault": true }
    }
  ]
}

除非项目依赖 MSBuild 特有功能或需针对平台目标构建的 .sln，否则优先使用 dotnet build。

Visual Studio 配置

通过外部程序调试

1. 在 Visual Studio 中打开 .csproj
2. 调试 > 调试属性（或 项目属性 > 调试 > 常规）
3. 新建启动配置文件：
   • 命令：指向 vvvv.exe 的路径
   • 命令行参数：-o YourPatch.vl（如需断点，请添加 --debug）
   • 工作目录：项目所在文件夹
4. 按 F5 启动并自动附加调试器

附加到进程

1. 正常启动 vvvv（如需断点，请添加 --debug）
2. 调试 > 附加到进程（Ctrl+Alt+P）
3. 在进程列表中找到 vvvv.exe
4. 选择代码类型为 托管（.NET Core、.NET 5+）
5. 点击“附加”

launchSettings.json（dotnet 工具链）

{
  "profiles": {
    "Debug vvvv": {
      "commandName": "Executable",
      "executablePath": "C:\Program Files\vvvv\vvvv_gamma_6.8-win-x64\vvvv.exe",
      "commandLineArgs": "-o YourPatch.vl",
      "workingDirectory": "$(ProjectDir)"
    }
  }
}

调试技巧

• --debug —— 强制生成调试符号以确保断点可靠生效，但会带来性能开销。建议仅在 Debug 配置中启用；性能测试或部署验证时请禁用。
• --stoppedonstartup —— 启动时暂停执行，便于在首次调用 Update() 前设置断点
• --nocache —— 若断点无法绑定，可强制从源码重新编译
• Debugger.Break() —— 在 C# 代码中插入该调用，可编程触发断点
• Update() 中的条件断点 —— Update() 每帧执行一次，建议使用命中次数或条件表达式控制断点触发
• 构造函数断点 —— 在每次热重载周期中也会触发（先调用 Dispose，再执行新构造函数）
• console: "internalConsole" —— 将 Console.WriteLine 输出捕获至 VS Code 调试控制台
• 调试器附加行为 —— 当 .NET 调试器附加后，vvvv 初始化将同步执行（不捕获异步异常），因此启动断点可稳定生效

常见陷阱

• --package-repositories + VL.StandardLibs 子模块 —— 若工作区包含 VL.StandardLibs/ Git 子模块（vvvv 贡献仓库中常见），--package-repositories ${workspaceFolder} 将导致 vvvv 发现并从源码重编译全部标准库，耗时数分钟，且几乎从非所需行为。建议：省略 --package-repositories，或将其指向不含库子模块的特定子目录。
• --allowmultiple 掩盖残留实例 —— 若未启用该标志，vvvv 在检测到其他实例运行时将拒绝启动。这是有益的设计：可及时发现残留进程。启用 --allowmultiple 后，可能意外运行两个实例并占用双倍资源。
• --debug 显著拖慢整体性能 —— 调试符号生成会显著降低 vvvv 的实时编译速度。仅在真正需要断点时启用；对于 UI 快速验证或行为检查等场景，请禁用以提升迭代效率。