React JSX中使用VSS SDK调用ADO扩展存储遇本地调试问题

核心问题根源 #

本地直接运行React项目无法调用ExtensionData服务，因为该服务依赖Azure DevOps的宿主环境，需要完整加载VSS SDK并通过ADO的权限校验，纯本地环境不具备这些条件。

具体解决方案 #

1. 配置完整的VSS SDK调试环境 #

• 安装依赖工具：

  npm install vss-web-extension-sdk
  npm install -g tfx-cli
  

• 在React入口文件（如index.jsx）中初始化SDK，必须在组件渲染前执行：

  import * as VSS from "vss-web-extension-sdk";
  import React from "react";
  import ReactDOM from "react-dom/client";
  import App from "./App";
  
  // 初始化VSS SDK
  VSS.init({
    explicitNotifyLoaded: true,
    usePlatformScripts: true,
    usePlatformStyles: true
  });
  
  VSS.ready().then(() => {
    const root = ReactDOM.createRoot(document.getElementById("root"));
    root.render(<App />);
    // 通知ADO扩展加载完成
    VSS.notifyLoadSucceeded();
  });
  

2. 完善扩展清单权限 #

在vss-extension.json中声明ExtensionData服务权限：

{
  "manifestVersion": 1,
  "id": "your-custom-extension-id",
  "name": "Your Extension",
  "scopes": ["vso.extension.data"],
  "contributions": [
    {
      "id": "react-tab",
      "type": "ms.vss-web.tab",
      "targets": ["ms.vss-work-web.work-item-form"],
      "properties": {
        "name": "Custom Data Tab",
        "uri": "index.html"
      }
    }
  ]
}

3. 正确的本地调试流程 #

1. 构建React项目：npm run build
2. 登录ADO组织：tfx login --service-url https://dev.azure.com/你的组织名
3. 侧加载扩展到ADO：tfx extension publish --manifest-globs vss-extension.json --share-with 你的组织名
4. 在ADO中安装侧加载的扩展，打开对应页面（如工作项表单），用浏览器开发者工具断点调试代码。

4. 代码错误修正 #

• 集合式读取代码中，console.log(doc.Name)改为console.log(doc.value)（你的文档对象定义的是value字段）
• 设置式写入代码中，若需用户范围存储，将scopeType: "Default"改为scopeType: "User"，Default对应项目范围，需额外权限。

5. 本地模拟存储（可选） #

开发阶段可封装适配层，用localStorage模拟ExtensionData，避免依赖ADO环境：

const useDataStorage = () => {
  const isLocalDev = process.env.NODE_ENV === "development";

  const setValue = async (key, value) => {
    if (isLocalDev) {
      localStorage.setItem(key, JSON.stringify(value));
      return value;
    }
    const dataService = await VSS.getService(VSS.ServiceIds.ExtensionData);
    return dataService.setValue(key, value, { scopeType: "User" });
  };

  const getValue = async (key) => {
    if (isLocalDev) {
      return JSON.parse(localStorage.getItem(key) || "null");
    }
    const dataService = await VSS.getService(VSS.ServiceIds.ExtensionData);
    return dataService.getValue(key);
  };

  return { setValue, getValue };
};

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