Azure Cosmos DB .NET SDK V3参数化查询报JSON格式错误如何解决？

你写的参数化查询语法本身是符合V3 SDK规范的，触发Invalid query. Specified parameterized query JSON is malformed异常可按以下优先级排查：

• 参数名匹配错误：确认WithParameter传入的参数名和查询语句中的占位符完全一致，包括大小写、@前缀都不能有差异。例如查询中使用@Token，参数传递必须写"@Token"，不能省略@、也不能写成"@token"。
• 查询语句携带不可见特殊字符：如果查询SQL是从其他文档、网页复制粘贴得到的，大概率携带了零宽空格、非法换行等不可见特殊字符，导致SQL解析失败。可以手动重新逐字输入一遍查询语句验证。
• SDK版本存在已知bug：3.23.0之前的Azure Cosmos DB .NET V3 SDK存在参数序列化的已知问题，会将合法参数序列化为畸形JSON结构。可以先将SDK升级到最新稳定版验证问题是否解决。
• 自定义序列化器不兼容：如果你配置了自定义序列化器（比如用System.Text.Json替换了默认的Newtonsoft.Json序列化器），需要确认序列化器同时适配了查询参数的序列化场景，部分自定义实现只会处理文档读写的序列化，忽略查询参数的序列化逻辑，导致参数输出格式错误。

你可以先写最小测试用例验证，以下是经过验证的标准写法：

// 手动输入查询语句，避免复制粘贴的特殊字符
var query = new QueryDefinition("SELECT * FROM products p WHERE p.label = @Token")
    .WithParameter("@Token", "a_string");

var queryOptions = new QueryRequestOptions
{
    // 如果需要传分区键按实际字段值填写即可，不影响查询格式
    // PartitionKey = new PartitionKey("your_partition_key_value")
};

var results = new List<ProductDocument>();
using var iterator = Container.GetItemQueryIterator<ProductDocument>(query, requestOptions: queryOptions);
while (iterator.HasMoreResults)
{
    var response = await iterator.ReadNextAsync();
    results.AddRange(response);
}

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