从Microsoft.Azure.Cosmos.Table迁移到Azure.Data.Tables后UpsertEntityAsync报错

一、400 InvalidInput错误排查 #

从Microsoft.Azure.Cosmos.Table迁移到Azure.Data.Tables后，替换InsertOrMergeAsync为UpsertEntityAsync出现400错误，结合场景可从以下方向排查：

1. 核心属性合法性检查 #

确保自定义实体OfficeSupplyEntity的PartitionKey和RowKey符合Azure Tables规则：

• 不能包含\/#?等特殊字符
• 单个属性长度不超过1024个字符
• 不能为空字符串

2. DateTime属性处理差异 #

新SDKAzure.Data.Tables对DateTime类型属性序列化要求更严格：

• 必须使用UTC时间（建议用DateTime.UtcNow赋值，避免本地时间）
• 禁止使用DateTime.MinValue这类超出服务允许范围的时间值

3. Azurite版本兼容性 #

你当前使用的Azurite 3.33.0可能与Azure.Data.Tables新API存在兼容问题，建议升级到最新版Azurite后重试。

4. Upsert模式调整 #

默认UpsertEntityAsync使用Merge模式，若原逻辑存在兼容问题，可尝试指定Replace模式测试：

private async Task InsertOrMergeAsync(TableClient table, OfficeSupplyEntity record)
{
    await table.UpsertEntityAsync(record, TableUpdateMode.Replace);
}

5. 自定义属性序列化问题 #

新旧SDK对自定义属性的序列化逻辑有差异：

• 检查实体中是否包含新SDK不支持的类型（如旧SDK允许的复杂类型，新SDK需手动处理序列化）
• 确保属性名称无特殊字符，避免序列化解析错误

二、tableEntity与entity的区别 #

迁移指南里的tableEntity和旧代码中的entity本质是同一概念，只是命名更精准：

• 旧SDK的entity泛指符合Table服务要求的实体对象（可能是继承TableEntity类或实现ITableEntity的自定义类）
• 新SDK的tableEntity是对这类实体的明确称呼，特指实现ITableEntity接口、符合Azure Tables规范的实体类，两者无本质区别，仅术语表述更清晰。

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