DocuSign Connect：从XML（旧版）迁移至JSON的技术问询

我们有一套运行超2年的生产系统，使用C#和.NET Framework处理DocuSign Connect通知，当前采用**XML（Legacy）**负载。已通过官方Schema生成对应XML结构的C#类层级。

系统分为两个核心模块：

• Listener（Webhook）：执行安全检查和负载初步解析（用于验证），之后将通知加入队列等待处理；
• Processor：取出队列中的通知，反序列化XML至DocuSign类以完成处理。

已知2023年5月起将无法获取XML格式的Connect通知，必须切换为JSON负载。查看Connect配置中的JSON负载示例后，发现其结构与XML完全不同，无法沿用当前XML反序列化逻辑：

var serializer = new XmlSerializer(typeof(DocuSignEnvelopeInformation));
var buffer = Encoding.UTF8.GetBytes(request.Content.ReadAsStringAsync().Result);
using (var stream = new MemoryStream(buffer))
{
    var envelopeInfo = (DocuSignEnvelopeInformation)serializer.Deserialize(stream);
    return envelopeInfo;
}

核心问题 #

是否存在可用于生成C#类的JSON负载权威Schema（类似XML的WSDL）？希望能借助它估算迁移工作量，同时欢迎提供相关迁移建议。

2023年1月5日更新 #

为查看DocuSign发送的JSON内容，我配置了一个简单的Connect配置并启用JSON格式，发起DocuSign请求后未运行Listener，预期会看到连接失败。完成签署后查看Connect日志，发现两条通知：(1) "recipient-sent"事件的JSON通知；(2) 信封完成状态的XML通知（与当前使用的XML类型一致）。曾疑惑为何会同时收到JSON和XML混合通知，后更正：创建了一个仅执行安全检查、保存负载至磁盘并返回成功的简化Listener，已收到"envelope-completed"事件的JSON负载，之前的XML通知是发送至DocuSign内部Listener。

2023年1月5日更新2 #

我了解到Visual Studio的便捷功能：将JSON复制到剪贴板后，使用Edit -> Paste Special -> Paste JSON as Classes生成类。但这些类不完整，仅反映所用数据的结构，比如仅生成了Sign Here、Date Signed、Text和Checkbox等少数Tab类，部分属性因JSON无值被定义为object。因此我希望获取DocuSign Connect通知JSON的权威Schema。

1. 权威JSON Schema获取 #

DocuSign官方提供了Connect JSON负载的完整Schema，包含所有事件类型、字段定义及嵌套结构，可直接用于生成覆盖全场景的C#类，避免手动生成类的不完整性问题。

2. 迁移工作量估算 #

基于现有系统架构，迁移主要涉及以下环节：

• 类结构重构：借助官方Schema生成完整的C#类层级，替换原XML序列化类。通过工具（如结合Schema的代码生成工具）完成的话，工作量约1-2人天，主要是调整类命名、字段映射及处理可选字段。
• Listener适配：修改负载解析逻辑，从XML验证切换为JSON验证（签名验证逻辑与XML一致，仅需调整负载读取方式），工作量约0.5-1人天。
• Processor逻辑改造：将XmlSerializer替换为JSON序列化器（如Newtonsoft.Json或.NET内置System.Text.Json），调整业务逻辑中对类属性的访问（JSON与XML结构差异较大，部分字段路径、命名会变化），工作量取决于业务复杂度，一般为2-3人天。
• 测试与验证：覆盖核心事件类型（信封完成、收件人发送、签署完成等）的测试，确保处理逻辑与原XML版本一致，工作量约1-2人天。

3. 迁移注意事项 #

• 序列化工具选择：.NET Framework环境优先用Newtonsoft.Json，它对复杂类型支持更成熟；新版本.NET可使用System.Text.Json，但需配置忽略未知字段、处理可选属性等。
• 字段兼容性：JSON结构的字段命名、嵌套层级与XML不同，需对照官方文档核对字段映射，避免遗漏核心业务数据。
• 增量迁移测试：可先搭建并行处理逻辑，同时接收XML和JSON通知，验证JSON逻辑正确性，稳定后再完全切换，降低生产风险。

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