.NET迁移Cosmos DB SDK v3时自动生成$type属性问题咨询

这个$type字段不是Cosmos DB服务端自动生成的，是客户端JSON序列化层写入的类型元数据，属于Newtonsoft.Json（Json.NET）的内置特性：
当序列化配置开启了TypeNameHandling选项，且序列化的字段声明类型为object、接口、父类，实际运行时值是具体的子类/集合类型时，序列化器会自动写入$type字段，存储对应值的CLR类型全限定名，方便反序列化时自动还原为原始具体类型，不需要手动指定反序列化类型。
你看到的字典类型的$type值，就是对应Dictionary<string, int>类型在.NET运行时的全限定名。

v2版本的Cosmos DB .NET SDK内置序列化器默认将TypeNameHandling设为None，全局关闭了类型元数据输出，所以写入的文档不会带这个字段。
你当前迁移过程中出现这个问题，核心原因是你还在使用v2 SDK的Document基类，新旧SDK的序列化默认配置不兼容：v3 SDK默认的序列化配置如果没有显式覆盖，或者你混用了v2 SDK的序列化方法（比如你代码里BaseCosmosDBDocument调用的SaveTo方法就是v2 Document类的内置方法），就会触发类型元数据写入。

• 优先移除对v2 SDK基类的依赖：v3 SDK不要求实体类继承任何特定基类，直接将BaseCosmosDBDocument改为普通POCO类，删除对v2 Microsoft.Azure.Documents.Document的继承，从根源上避免新旧SDK的序列化逻辑冲突，这也是官方推荐的v3迁移最佳实践。
• 显式配置v3客户端的序列化规则：创建CosmosClient实例时传入自定义序列化配置，明确关闭类型元数据输出，参考代码如下：

var jsonSettings = new JsonSerializerSettings
{
    TypeNameHandling = TypeNameHandling.None, // 核心配置，禁止写入$type
    ContractResolver = new CamelCasePropertyNamesContractResolver(), // 可选，按业务命名规则配置
    NullValueHandling = NullValueHandling.Ignore // 其他自定义配置按需添加
};
var clientOptions = new CosmosClientOptions
{
    Serializer = new NewtonsoftJsonCosmosSerializer(jsonSettings)
};
var cosmosClient = new CosmosClient(连接字符串, clientOptions);

• 检查自定义序列化逻辑：你代码中ReadAsDocumentSubclass方法里手动调用了JsonConvert.DeserializeObject，如果后续有手动序列化/反序列化Cosmos文档的逻辑，也需要统一使用相同的序列化配置，不要使用默认开启TypeNameHandling的设置，避免局部逻辑写入多余字段。

注意：如果你的业务存在多态反序列化需求（比如同一字段可能存储不同子类实例），不需要全局关闭TypeNameHandling，可以给不需要类型元数据的属性（比如示例中的DataSample1字典属性）标注[JsonProperty(TypeNameHandling = TypeNameHandling.None)]，单独关闭该字段的类型元数据输出，不影响其他多态逻辑。

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