Azure DevOps Server 2022本地版扩展onLoaded事件无响应排查

一、先查vss-extension.json的核心配置 #

你的扩展没被加载，大概率是配置没声明正确的贡献点或环境匹配项：

• 缺失工作项表单贡献点：必须声明ms.vss-work-web.work-item-form类型的贡献，告诉系统要在工作项表单注入你的代码。正确配置示例：

  "contributions": [
    {
      "id": "work-item-custom-field",
      "type": "ms.vss-work-web.work-item-form",
      "targets": [
        "ms.vss-work-web.work-item-form-page"
      ],
      "properties": {
        "uri": "dist/index.htm"
      }
    }
  ]
  

• 目标平台版本不匹配：本地ADO Server 2022对应版本号是19.x，必须在targets里明确指定，否则扩展会被系统判定为不兼容：

  "targets": [
    {
      "id": "Microsoft.VisualStudio.Services",
      "version": "[19.0, 20.0)"
    }
  ]
  

• 权限作用域缺失：工作项操作需要至少vso.work_read权限，添加到scopes字段：

  "scopes": [
    "vso.work_write"
  ]
  

• 文件路径错误：确认properties.uri里的路径和打包后的文件结构一致，打包时要确保dist文件夹被包含在扩展包内（tfx打包时会自动包含vss-extension.json里声明的文件，也可以手动指定files字段）。

二、修正dist/index.htm的代码逻辑 #

本地ADO的扩展必须通过VSS SDK初始化，直接写原生JS不会执行：

• 强制引入VSS SDK并完成初始化：你的页面必须加载服务器对应的VSS SDK，通过VSS.init和VSS.ready触发代码执行。示例代码：

  <!DOCTYPE html>
  <html>
  <head>
      <script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js"></script>
      <script>
          // 替换成你的本地ADO服务器SDK路径，可从页面源码中提取
          window.requirejs.config({
              paths: {
                  'VSS': 'http://<你的ADO服务器地址>:8080/tfs/_static/tfs/Dev19.M170/_scripts/VSS.SDK'
              }
          });
  
          require(['VSS'], function(VSS) {
              VSS.init({
                  explicitNotifyLoaded: true,
                  usePlatformScripts: true
              });
  
              VSS.ready(function() {
                  // 测试alert
                  alert("工作项表单已加载！");
                  // 必须通知SDK加载完成，否则扩展会被判定为加载失败
                  VSS.notifyLoadSucceeded();
              });
          });
      </script>
  </head>
  <body></body>
  </html>
  

  注意：本地服务器的VSS SDK路径要和实际环境一致，打开工作项页面后，查看源码找VSS.SDK的真实路径。

三、部署环节的关键检查点 #

• 打包与上传：用tfx extension create打包时，确保所有必要文件都被包含，生成的.vsix文件上传到服务器的「服务器设置->扩展->上传扩展」页面。
• 启用扩展：上传后必须在组织级别启用该扩展，否则不会生效。
• 清除缓存：即使递增版本号，浏览器可能缓存旧资源，按Ctrl+F5强制刷新，或直接清除浏览器缓存后测试。
• 查看控制台日志：打开DevTools的Console面板，搜索VSS相关错误，比如SDK加载失败、权限不足等，这些日志会直接指出问题所在。

四、字段自定义选择列表的优化实现 #

等alert测试通过后，建议用官方API而非直接操作DOM，稳定性更高：

VSS.ready(function() {
    VSS.getService(VSS.ServiceIds.WorkItemForm).then(function(formService) {
        // 给Effort字段设置自定义选项
        formService.getFieldControl("Microsoft.VSTS.Scheduling.Effort").then(function(control) {
            control.setAllowedValues([1, 2, 3, 5, 8, 13]);
        });
        // 给Business Value字段设置自定义选项
        formService.getFieldControl("Microsoft.VSTS.Common.BusinessValue").then(function(control) {
            control.setAllowedValues([0, 5, 10, 15, 20]);
        });
    });
    VSS.notifyLoadSucceeded();
});

注：字段的引用名可以在工作项设置的「字段」详情中查看，确保拼写正确。

内容的提问来源于stack exchange，提问作者InteXX