C# Web API接收DocuSign Connect XML Webhook模型映射及SQL存储问题咨询

我来帮你梳理下解决这个问题的完整步骤，毕竟DocuSign Connect的XML结构确实复杂，手动写Model太容易出错了：

这是最关键的一步，不用自己硬写所有嵌套节点的类：

• 打开Visual Studio，新建一个.cs文件（比如命名为DocuSignWebhookModels.cs）
• 复制你拿到的DocuSign XML示例内容
• 点击菜单栏的编辑 > 选择性粘贴 > 将XML粘贴为类
• 工具会自动生成所有嵌套的类，并且带上对应的[XmlElement]、[XmlRoot]等特性，完美匹配XML结构
• 注意：如果你的XML带有命名空间（比如开头的xmlns="http://www.docusign.net/API/3.0"），要确保生成的根类上的[XmlRoot]特性包含正确的Namespace属性，不然反序列化会失败

默认Web API更偏向JSON，所以需要手动开启XML媒体格式化器：

• 如果是.NET 6+/Minimal API，在Program.cs里配置：

  builder.Services.AddControllers()
      .AddXmlSerializerFormatters(); // 用XmlSerializer，和第一步生成的类兼容更好
  

• 如果是老版本的.NET Framework/Web API，在WebApiConfig.cs里添加：

  config.Formatters.XmlFormatter.UseXmlSerializer = true;
  config.Formatters.Add(new XmlMediaTypeFormatter());
  

现在可以直接在Post方法里接收强类型的Model了：

• 新建一个Webhook控制器，比如DocuSignWebhookController.cs，写Post方法：

  [ApiController]
  [Route("api/docusign/webhook")]
  public class DocuSignWebhookController : ControllerBase
  {
      [HttpPost]
      public async Task<IActionResult> ReceiveWebhook([FromBody] EnvelopeStatus envelopeStatus)
      {
          // 这里envelopeStatus就是反序列化后的完整对象，包含所有子节点数据
          if (envelopeStatus == null)
          {
              return BadRequest("Invalid XML payload");
          }
  
          // 后续处理：存入数据库
          await SaveToDatabase(envelopeStatus);
  
          // DocuSign需要200响应确认接收
          return Ok();
      }
  
      // 数据库存储方法，后面会讲
      private async Task SaveToDatabase(EnvelopeStatus envelopeStatus)
      {
          // 实现逻辑
      }
  }
  

• 如果自动反序列化有问题（比如命名空间冲突），可以手动读取请求内容并反序列化：

  [HttpPost]
  public async Task<IActionResult> ReceiveWebhook()
  {
      using var reader = new StreamReader(Request.Body);
      var xmlContent = await reader.ReadToEndAsync();
  
      var serializer = new XmlSerializer(typeof(EnvelopeStatus), "http://www.docusign.net/API/3.0"); // 替换成你的XML命名空间
      using var stringReader = new StringReader(xmlContent);
      var envelopeStatus = (EnvelopeStatus)serializer.Deserialize(stringReader);
  
      await SaveToDatabase(envelopeStatus);
      return Ok();
  }
  

这里推荐用Entity Framework Core来简化操作：

• 首先创建对应数据库表的实体类（如果表已经存在，确保实体类和表结构匹配），比如EnvelopeEntity.cs
• 可以用AutoMapper来自动映射Model到实体类，避免手动赋值：

  // 配置AutoMapper映射规则
  var config = new MapperConfiguration(cfg =>
  {
      cfg.CreateMap<EnvelopeStatus, EnvelopeEntity>();
      // 如果有嵌套对象，比如Recipients，也要配置对应的映射
      cfg.CreateMap<Recipient, RecipientEntity>();
  });
  var mapper = config.CreateMapper();
  

• 然后在SaveToDatabase方法里写入：

  private async Task SaveToDatabase(EnvelopeStatus envelopeStatus)
  {
      using var dbContext = new YourDbContext(); // 替换成你的DbContext
  
      var envelopeEntity = mapper.Map<EnvelopeEntity>(envelopeStatus);
      dbContext.Envelopes.Add(envelopeEntity);
      await dbContext.SaveChangesAsync();
  }
  

• 如果不用AutoMapper，就手动把Model的属性赋值给实体类，比如：

  var envelopeEntity = new EnvelopeEntity
  {
      EnvelopeId = envelopeStatus.EnvelopeID,
      Status = envelopeStatus.Status,
      CreatedDate = envelopeStatus.Created,
      // 其他属性一一对应
  };
  

• 反序列化失败：检查XML命名空间是否和Model里的[XmlRoot]/[XmlElement]特性一致，XML节点名称和类属性的[XmlElement]名称是否完全匹配（XML大小写敏感）
• 接收不到请求：确保DocuSign的Webhook URL能被公网访问（可以用ngrok做内网穿透测试），请求的Content-Type是application/xml
• 数据库写入失败：检查实体类和数据库表的字段名、数据类型是否匹配，主键、外键约束是否正确，必填字段是否都赋值了

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