C# .NET应用中Firestore反序列化报错：无法创建UserCustomData类型转换器

在C# .NET应用中使用Firestore，尝试将Firestore文档转换为自定义类UserCustomData的实例时触发反序列化错误，报错信息如下：

未处理的异常已在应用中发生。
Unable to create converter for type RepoGen.Classes.UserCustomData.

自定义类代码：

public class UserCustomData
{
    public UserCustomData() { } 

    public string Username { get; set; }
    public string Email { get; set; }    
}

获取并转换文档的代码：

public static async Task<UserCustomData> GetUserAsync(string uid)
{
    DocumentReference docRef = Database.Collection("users").Document(uid);
    DocumentSnapshot snapshot = await docRef.GetSnapshotAsync();
    if (snapshot.Exists)
    {
        UserCustomData userCustomData = snapshot.ConvertTo<UserCustomData>();
        return userCustomData;
    }
    else
    {
        return null;
    }
}

已完成的排查：

• Firestore文档字段与类属性名（含大小写）完全匹配
• 文档结构简单，无嵌套对象
• 已安装并更新至最新版Google.Cloud.Firestore NuGet包

1. 添加Firestore特性标记 #

Firestore的序列化器需要明确的映射标记，即使字段名完全匹配，也需为类添加[FirestoreData]特性，为属性添加[FirestoreProperty]特性：

[FirestoreData]
public class UserCustomData
{
    public UserCustomData() { } 

    [FirestoreProperty]
    public string Username { get; set; }
    [FirestoreProperty]
    public string Email { get; set; }    
}

2. 手动注册类型转换器 #

如果自定义类位于独立类库中，Firestore序列化器可能无法自动识别该类型，可在应用启动时手动注册转换器：

FirestoreDb db = FirestoreDb.Create("你的项目ID");
db.Settings.Converters.Add(new ValueConverter<UserCustomData>(
    // 序列化逻辑（可选，仅当需要将类写入Firestore时用）
    user => new Dictionary<string, object>
    {
        ["Username"] = user.Username,
        ["Email"] = user.Email
    },
    // 反序列化逻辑
    snapshot => new UserCustomData
    {
        Username = snapshot.GetValue<string>("Username"),
        Email = snapshot.GetValue<string>("Email")
    }));

3. 检查NuGet包版本兼容性 #

卸载当前Google.Cloud.Firestore包，重新安装稳定版本（如3.x及以上），同时确保Google.Cloud.Core等依赖包版本与Firestore包保持一致，避免版本冲突。

4. 确认类的访问权限 #

确保UserCustomData类的访问修饰符为public，且所在类库已被主应用项目正确引用，避免序列化器无法访问该类型。

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