使用KingswaySoft对Dynamics实体执行Upsert时报400 Bad Request错误

{"error":{"code":"0x80040265","message":"Unhandled Plugin Exception Object reference not set to an instance of an object."}}

上述报错为Dynamics 365服务端自定义插件执行时抛出的空引用异常，与你配置的Record Matching Criteria匹配规则无关，可按以下步骤排查解决：

• 临时禁用目标实体的所有自定义插件、同步工作流，重新执行Upsert测试。如果测试执行成功，即可确定是插件逻辑问题，后续定向排查对应插件即可。
• 若禁用插件后仍存在报错，检查KingswaySoft的字段映射配置：
  • 确认所有查找类型字段的映射值是否合法，禁止传入不存在的关联实体GUID、仅传显示名无有效值的错误数据
  • 确认实体必填字段在更新场景下也有映射值，部分插件逻辑会直接读取请求内的字段值，若Upsert更新时未传入该字段，插件直接取值就会触发空引用报错
  • 确认你作为匹配依据的暂存表主键，在Dynamics目标实体中已配置为备用键（Alternate Key）。未配置备用键时，KingswaySoft的Upsert逻辑会先执行查询再触发更新/创建操作，部分插件未兼容该操作路径会抛出异常
• 若确认是插件逻辑问题，按以下要求调整插件代码：
  • 所有从请求参数、Target实体中读取字段的逻辑，必须先判断字段是否存在、是否为Null再进行后续操作
  • 兼容Upsert操作场景：Upsert请求的上下文MessageName为Upsert，而非传统的Create/Update，部分插件仅适配了后两种请求，碰到Upsert请求会出现变量未初始化的问题
  • 插件内所有查询操作的返回结果，必须先判断是否为空再使用
• KingswaySoft侧可做兼容配置优化：
  • 直接打开Dynamics Destination组件的Bypass Custom Business Logic选项，跳过自定义插件执行，若你无需在同步时触发插件逻辑，该配置可直接规避该报错
  • 若需要保留插件执行，将组件批次大小调整为1，开启错误输出捕获具体失败行数据，匹配Dynamics侧的插件跟踪日志，可精准定位触发异常的具体字段和数据

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