为 Selenium .NET 绑定新增与移除 Chromium DevTools Protocol 版本DevTools 版本化维护操作指南【免费下载链接】seleniumA browser automation framework and ecosystem.项目地址: https://gitcode.com/GitHub_Trending/se/selenium本文以仓库内 dotnet/src/webdriver/DevTools/README.md 为核心系统讲解如何为 Selenium 的 .NET 语言绑定Selenium.WebDriver增加或移除某一个 Chromium DevTools ProtocolCDP主版本的支持。CDP 随 Chrome/Edge 等 Chromium 系浏览器按主版本演进Selenium .NET 绑定以“一版本一目录 强类型生成代码”的方式跟进读完本文你将掌握完整的版本登记、代码生成、域工厂注册、构建钩子配置与测试用例同步流程并能独立把某个vN接入或移出当前的 DevTools 版本矩阵。为什么 .NET 绑定需要对 CDP 做“按版本维护”Chromium DevTools Protocol 由浏览器主版本驱动不同大版本之间的接口、命令与事件类型并不完全兼容。为了让用户在 .NET 中拿到强类型的 DevTools 调用体验例如network.EnableNetwork()、domains.Target等Selenium 为每个受支持的 CDP 版本维护一套独立代码而非运行时反射式的弱类型转发。这也是本仓库同时存在v150、v151、v152三个版本目录的原因。从源码结构看这套机制由两类代码拼合而成提交在仓库中的手写门面facade类每个版本目录下都有VNDomains、VNNetwork、VNJavaScript、VNTarget、VNLog五个文件封装稳定的高层 API构建期自动生成的协议类型代码针对该版本的完整命令/事件/类型实现由 Bazel 规则按协议定义实时生成到bazel-bin输出目录不直接提交。下文提到的“新增/移除版本支持”本质上就是让新版本进入这份版本矩阵并补齐两类代码的过程。当前仓库的版本化代码布局以仓库当前状态为例DevTools 相关核心位置如下版本目录dotnet/src/webdriver/DevTools/ 下有v150、v151、v152三个子目录例如 v150、v151、v152每个版本目录中的手写文件均以版本号大写开头以 v152 为例V152Domains.cs、V152Network.cs、V152JavaScript.cs、V152Target.cs、V152Log.cs版本白名单dotnet/version.bzl 中的SUPPORTED_DEVTOOLS_VERSIONS列表域工厂与版本匹配DevToolsDomains.csBazel 生成规则DevTools/BUILD.bazel版本相关测试dotnet/test/webdriver/DevTools/。其中 V152Domains.cs 的构造逻辑反映了每个版本门面的标准骨架它通过new DevToolsSessionDomains(session)创建该版本的强类型域对象并分别用LazyT包装Network对接协议层Network与Fetch、JavaScript对接Runtime与Page、Target、Log同时对外暴露static int DevToolsVersion 152;用于版本自检。新增一个 CDP 版本9 步完整操作指南以下N均指要新增的 CDP 主版本号如 152。该流程记录于 dotnet/src/webdriver/DevTools/README.md 的 “Adding support…” 一节本文在保留原始步骤的同时补充对应的源码依据。第 1 步把新版本号登记进version.bzl在 dotnet/version.bzl 的SUPPORTED_DEVTOOLS_VERSIONS列表中追加vN例如当前文件为SUPPORTED_DEVTOOLS_VERSIONS [ v152, v150, v151, ]这份列表的作用远不止“登记”DevTools/BUILD.bazel 通过load(//dotnet:version.bzl, SUPPORTED_DEVTOOLS_VERSIONS) ... for devtools_version in SUPPORTED_DEVTOOLS_VERSIONS为列表中的每个版本自动实例化一个名为generate-版本号的代码生成 Bazel 目标如//dotnet/src/webdriver/DevTools:generate-v152。该目标以//common/devtools/chromium/vN下的browser_protocol与js_protocol即该版本的.pdl协议定义为输入配合//third_party/dotnet/devtools/src/generator生成器与Templates模板目录中command.hbs、event.hbs、domain.hbs、DevToolsSessionDomains.hbs等模板产出该版本整套类型化代码。换句话说只要这里加了版本号Bazel 层面就已具备生成该版本代码的目标。第 2 步复制上一个版本的目录作为新版本起点创建新目录dotnet/src/webdriver/DevTools/vN并把上一版本目录dotnet/src/webdriver/DevTools/vN-1的全部内容复制进去。例如新增 v152 时把 v151 里的文件整体复制为v152的初始内容。由于 CDP 相邻主版本的手写门面结构高度相似从上一版复制可以显著降低改动量。第 3 步重命名.cs文件使文件名以VN开头把vN目录中所有*.cs文件从VN-1*前缀重命名为VN*前缀。例如 v151 的V151Domains.cs在 v152 目录中应变为V152Domains.csV151Network.cs变为V152Network.cs其余文件同理。可对照当前 v152 目录中实际存在的五个文件名来核对命名规则。第 4 步替换文件内部的版本号字样注意大小写在vN目录下每个*.cs文件中把出现的所有VN-1替换为VN。这些位置通常包括namespace OpenQA.Selenium.DevTools.VN;类型声明如public class VNDomains : DevToolsDomains内部引用如new VNNetwork(...)、new DevToolsSessionDomains(session)等。IMPORTANT原文强调替换时不要改动VN的大小写。因为协议类型与方法参数大量以“v 小写 数字”的形式出现例如模板生成代码中的版本参数而类型名、命名空间使用大写VN二者必须严格区分盲目做大小写不敏感替换会造成大面积编译错误。第 5 步在DevToolsDomains.cs中注册新版本在 DevToolsDomains.cs 中为新版本补上登记项。README 将其表述为 “向SupportedDevToolsVersions字典初始化中添加版本N的条目”对照当前源码这一步实际包含两处修改版本号数组SupportedDevToolsVersions第 34-39 行例如当前为[151, 150, 152]需要追加153工厂方法CreateDevToolsDomain第 41-47 行的switch表达式为其增加分支153 new V153.V153Domains(session)。private static DevToolsDomains? CreateDevToolsDomain(int protocolVersion, DevToolsSession session) protocolVersion switch { 151 new V151.V151Domains(session), 150 new V150.V150Domains(session), 152 new V152.V152Domains(session), _ null };补充说明DevToolsDomains是版本无关的抽象门面对外暴露四个高层域对象属性Network、JavaScript、Target、Log第 56-72 行它们在不同版本间保持方法签名稳定而底层强类型实现由各自的VNDomains提供。因此漏注册任何一处都会导致新版本无法被InitializeDomains命中。第 6 步配置 Windows 预构建钩子WebDriver.csproj.prebuild.cmd在 Windows 侧构建WebDriver当前检出目录中对应的工程文件为 dotnet/src/webdriver/Selenium.WebDriver.csproj时需要让预构建步骤在“该版本生成产物缺失”时自动触发 Bazel 代码生成。在 README 所述路径//dotnet/src/webdriver:WebDriver.csproj.prebuild.cmd追加以下块N换成真实版本号if not exist %1..\..\..\bazel-bin\dotnet\src\webdriver\DevTools\vN\DevToolsSessionDomains.cs ( echo Generating CDP code for version N pushd %1..\..\.. bazel build //dotnet/src/webdriver/DevTools:generate-vN popd )这段脚本的逻辑是先判断bazel-bin/dotnet/src/webdriver/DevTools/vN/DevToolsSessionDomains.cs是否已存在——该文件是生成代码的核心产物对应 DevToolsSessionDomains.cs 抽象基类的各版本具体子类包含该版本全部命令/事件/类型的响应映射若不存在则调用bazel build //dotnet/src/webdriver/DevTools:generate-vN现场生成。采用“缺失才生成”的判断可避免在未安装 Bazel 或网络受限的纯 .NET 构建场景中无条件触发重型构建。第 7 步配置 macOS/Linux 预构建钩子WebDriver.csproj.prebuild.sh与第 6 步等价但面向类 Unix 环境追加以下块if [[ ! -f $1../../../bazel-bin/dotnet/src/webdriver/DevTools/vN/DevToolsSessionDomains.cs ]] then echo Generating CDP code for version N bazel build //dotnet/src/webdriver/DevTools:generate-vN fi两个钩子脚本检查的产物路径与触发的 Bazel 目标完全一致仅 shell 语法不同从而保证三平台构建行为统一。无论通过哪个平台构建最终生成的DevToolsSessionDomains.cs每个版本的强类型协议实现都会落在 Bazel 输出目录再与第 2-4 步创建的手写门面一同参与编译。第 8 步同步更新 DevTools 测试用例的版本别名在dotnet/test/下的 DevTools 测试文件中把出现的VN-2全部替换为VN-1。README 特别说明出于 CI 工具链更新时效性的考虑目前测试代码始终保持比最新支持版本落后一个版本即测试始终针对次新版本运行。以当前检出仓库为例测试实际位于 dotnet/test/webdriver/DevTools/其中 DevToolsNetworkTests.cs、DevToolsConsoleTests.cs、DevToolsLogTests.cs 等文件的顶部均通过别名机制指向某一具体版本using CurrentCdpVersion OpenQA.Selenium.DevTools.V152;随后测试体统一以CurrentCdpVersion这个别名引用版本域例如new CurrentCdpVersion.DevToolsDomains(...)这样 CI 中测试覆盖的 CDP 版本只需改一处别名即可整体迁移。该目录还包含 DevToolsTestFixture.cs 作为共享夹具以及DevToolsDomainsTests.cs、DevToolsTargetTests.cs、DevToolsProfilerTests.cs、DevToolsSecurityTests.cs、DevToolsTabsTests.cs等覆盖不同协议域的测试类可作为新增版本后回归验证的测试集。第 9 步提交变更将以上涉及的文件变更一并提交一个 CDP 版本的接入即告完成。移除不再支持的 CDP 版本4 步操作对应 README 的 “Removing support…” 一节当某个主版本停止支持时执行以下步骤删除dotnet/src/webdriver/DevTools/vN目录的全部内容在 DevToolsDomains.cs 中从SupportedDevToolsVersions列表移除版本N的登记项同样别忘了同步移除CreateDevToolsDomainswitch 中对应分支否则会出现“列表未登记但工厂仍能实例化”或“版本未登记但被枚举”的不一致状态在 dotnet/version.bzl 的SUPPORTED_DEVTOOLS_VERSIONS中移除vN字符串——这一步会使 DevTools/BUILD.bazel 中的for循环不再为该版本生成generate-vN目标提交变更。从工程完整性角度可以推断移除时还建议同步清理第 6/7 步中该版本对应的prebuild脚本块并把测试文件中的CurrentCdpVersion别名回退到仍受支持的目标版本避免构建钩子与测试继续引用已删除目录这一步 README 虽未逐条展开但却是保持仓库自洽的必然收尾。底层版本匹配逻辑不是“严格等于”而是“区间回退”新增版本之所以只需登记数组与工厂分支是因为运行时版本解析并非要求精确匹配。DevToolsDomains.cs 的实现揭示了两个关键策略默认容忍范围DefaultVersionRange 5第 29 行浏览器报告的实际 CDP 版本可能略高于绑定已生成的版本只要差距在 5 个大版本以内Selenium 仍会尝试用已有实现承载。“The Price Is Right”式回退匹配CreateFallbackDomain第 113-131 行当CreateDevToolsDomain(protocolVersion)精确匹配返回null后代码把支持版本列表降序排序然后挑选“不大于目标版本、且与目标版本差值小于versionRange”的最高支持版本来兜底即“最接近且不超过”if (desiredVersion supportedVersion desiredVersion - supportedVersion versionRange) { return CreateDevToolsDomain(supportedVersion, session)!; }若遍历结束仍无命中则抛出WebDriverException并附上期望版本、range 与全部受支持版本的提示信息。两个重载的InitializeDomains第 82-111 行分别使用默认 5 与调用方指定versionRange当versionRange为负数时直接抛ArgumentException。最终开发者通过 DevToolsSession.cs 中GetVersionSpecificDomainsT()该方法要求T : DevToolsSessionDomains取出对应版本的具体域对象完成强类型调用。理解了这段匹配逻辑就能明白新增版本本质上是在给“回退候选池”增加一个更高位的新选项这也解释了为什么第 5 步的登记如此重要——漏登记等于把新版本从候选池中移除旧版浏览器请求该版本时将无法被正确回退。如何验证一次版本接入是否成功接入完成后可用以下方式做端到端验证以N代指新版本直接构建生成目标确认协议定义可以被生成器消费bazel build //dotnet/src/webdriver/DevTools:generate-vN成功后检查bazel-bin/dotnet/src/webdriver/DevTools/vN/DevToolsSessionDomains.cs是否产出该产物文件正是第 6/7 步预构建钩子的判断依据。确认手写门面可编译vN目录下的五个VN*.cs文件名与命名空间均已正确改写第 3/4 步的完成度且VNDomains.DevToolsVersion静态属性返回正确的N。确认测试别名指向目标版本在 dotnet/test/webdriver/DevTools/ 下核对using CurrentCdpVersion OpenQA.Selenium.DevTools.VN;然后按 README 的测试节奏运行该目录下网络、控制台、日志、Target、Profiler、Security 等 DevTools 测试用例做回归。此类测试依赖真实 Chromium 系浏览器及对应版本的 driver需要本地具备可用的浏览器与 .NET/Bazel 测试环境。小结Selenium .NET 绑定对 Chromium DevTools Protocol 的版本支持是一套“版本白名单 版本目录门面 Bazel 模板生成 预构建钩子 测试别名”的完整流水线SUPPORTED_DEVTOOLS_VERSIONSdotnet/version.bzl是唯一事实来源同时驱动 Bazel 生成目标与文档所述步骤每个版本的手写门面v 目录承担稳定 API 层生成的强类型协议代码承担版本差异层DevToolsDomains.cs 的登记与匹配逻辑决定了“哪个浏览器版本回退到哪套实现”新增版本 复制目录 → 重命名 → 替换版本号 → 登记 → 配置预构建 → 更新测试别名 → 提交移除版本则为上述过程的逆操作。掌握这套流程后你不仅能按本文 9 步把任意新 CDP 大版本接入 Selenium .NET还能在浏览器快速迭代时安全地淘汰旧版本让绑定始终覆盖“最新 可控回退范围”的协议区间。【免费下载链接】seleniumA browser automation framework and ecosystem.项目地址: https://gitcode.com/GitHub_Trending/se/selenium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考