EF Core Cosmos DB DateTime存为本地时间而非UTC问题排查

1. 明确EF Core Cosmos的DateTime序列化规则 #

EF Core Cosmos对DateTime的默认序列化行为在不同环境可能存在差异，建议在DbContext配置里强制指定UTC处理逻辑，避免环境差异导致的问题：

protected override void ConfigureConventions(ModelConfigurationBuilder configurationBuilder)
{
    configurationBuilder.Properties<DateTime>()
        .HaveConversion<DateTimeOffsetConverter>()
        .HavePrecision(7);
}

或者针对TimeSlot.Start单独配置转换器，确保序列化时保留UTC标识：

builder.Entity<MyMainAggregate>()
    .Property(e => e.TimeSlot.Start)
    .HasConversion(
        v => v.ToString("o"),
        v => DateTime.Parse(v, null, DateTimeStyles.RoundtripKind));

注："o"格式会完整保留DateTime的Kind信息，避免序列化时丢失UTC标记。

2. 排查部署环境的序列化库配置 #

dev环境的服务器时区或序列化库配置可能和本地不一致，即使代码里设置了UTC，序列化时仍可能被错误转换：

• 若使用Newtonsoft.Json，确保全局配置强制UTC序列化：

services.AddControllers()
    .AddNewtonsoftJson(options =>
    {
        options.SerializerSettings.DateTimeZoneHandling = DateTimeZoneHandling.Utc;
        options.SerializerSettings.DateFormatHandling = DateFormatHandling.IsoDateFormat;
    });

• 若使用System.Text.Json，添加自定义转换器强制UTC输出：

services.AddControllers()
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.Converters.Add(new UtcDateTimeConverter());
    });

// 自定义转换器实现
public class UtcDateTimeConverter : JsonConverter<DateTime>
{
    public override DateTime Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        return DateTimeOffset.Parse(reader.GetString()!).UtcDateTime;
    }

    public override void Write(Utf8JsonWriter writer, DateTime value, JsonSerializerOptions options)
    {
        var utcValue = value.Kind != DateTimeKind.Utc ? value.ToUniversalTime() : value;
        writer.WriteStringValue(utcValue.ToString("o"));
    }
}

3. 验证数据写入前的最终状态 #

在数据存入Cosmos DB前，加入轻量校验逻辑，确认TimeSlot.Start的Kind和值是否符合预期，同时避免冗余拦截器：

public override int SaveChanges()
{
    var targetEntities = ChangeTracker.Entries<MyMainAggregate>()
        .Where(e => e.State is EntityState.Added or EntityState.Modified)
        .Select(e => e.Entity);

    foreach (var entity in targetEntities)
    {
        var startDate = entity.TimeSlot.Start;
        if (startDate.Kind != DateTimeKind.Utc)
        {
            // 打日志记录异常情况，或直接修正为UTC
            Logger.LogWarning("发现非UTC时间：{Start}，Kind为{Kind}", startDate, startDate.Kind);
            entity.TimeSlot.Start = DateTime.SpecifyKind(startDate, DateTimeKind.Utc);
        }
    }

    return base.SaveChanges();
}

4. 检查Cosmos DB容器的时区配置 #

登录Azure门户查看dev环境的Cosmos DB容器配置，确认TimeZone设置为UTC——虽然默认是UTC，但不排除人为修改导致的异常。

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