‫بررسی رفتار نگاشت زمانی در SQLite و ارتقاء به دات‌نت ۱۰: تغییرات ساختاری در DateTimeOffset و راه‌کارهای مهاجرت داده

چکیده: در فرآیند انتشار فریم‌ورک‌های مدرن دات‌نت، تغییرات ساختاری ناسازگار (Breaking Changes) معمولاً با خطاهای زمان کامپایل (Compile-time) یا تغییر در ساختار SQLهای تولیدی توسط ORM مشخص می‌شوند. با این حال، در NET 10. و در کتابخانه Microsoft.Data.Sqlite 10 (و لایه دیتابیس EF Core 10)، یک تغییر با درجه اهمیت بالا (High Impact) اعمال شده است که رفتاری کاملاً خاموش (Silent) دارد. این تغییر نحوه تفسیر و پارس رشته‌های زمانی فاقد آفست (Offset-less Timestamps) را بازتعریف می‌کند؛ رکوردهایی که پیش از این در دات‌نت ۹ به افست محلی ماشین (TimeZoneInfo.Local) نگاشت می‌شدند، در دات‌نت ۱۰ به صورت پیش‌فرض و غیرمشروط به عنوان زمان جهانی هماهنگ (UTC / +00:00) تفسیر می‌شوند. این مقاله به بررسی دقیق فنی، بازتولید سناریوی تغییر، تبعات داده‌ای پنهان، تغییرات تکمیلی روی REAL و DateTime.Kind و ارائه راهکارهای عملی جهت ممیزی و مهاجرت ایمن داده‌ها می‌پردازد.

• در دات‌نت ۹: تابع پارسر مقدار محلی سرور را الصاق می‌کرد. برای مثال، در منطقه‌ای با تفاضل زمانی 01:00+ (مانند ساعت تابستانی بریتانیا/ایرلند IST)، خروجی نهایی به شکل 2026-08-14T20:00:00+01:00 حاصل می‌شد (معادل ساعت ۱۹:۰۰ زمان UTC).
• در دات‌نت ۱۰: مقدار رشته بدون توجه به سرور یا کلاینت، به شکل 2026-08-14T20:00:00+00:00 پردازش می‌شود (دقیقاً ساعت ۲۰:۰۰ زمان UTC).

چالش اصلی: این تغییر سبب جابه‌جایی زمانی داده‌های تاریخی (Historical Data) می‌شود، بدون آنکه استثنایی (Exception) پرتاب گردد یا فرآیند اجرای برنامه متوقف شود.

• پیش از دات‌نت ۱۰: مقدار اعشاری روزهای جولیان بر اساس زمان محلی تولید و نوشته می‌شد.
• در دات‌نت ۱۰: پرووایدر پیش از تبدیل به REAL و ذخیره‌سازی، داده را به صورت خودکار به معادل UTC تبدیل می‌کند.

• در دات‌نت ۹: مقدار برگشتی به صورت DateTimeKind.Local علامت‌گذاری می‌شد.
• در دات‌نت ۱۰: پرووایدر مقدار را با فلگ DateTimeKind.Utc برمی‌گرداند.

public class Event
{
    public int Id { get; set; }
    public string Description { get; set; } = string.Empty;
    public DateTimeOffset OccurredAt { get; set; }
}

sqlite3 migrationchecklist.db "INSERT INTO \"Events\" (\"Description\",\"OccurredAt\") VALUES ('OffsetlessTest','2026-08-14 20:00:00');"

• پاسخ در .NET 9 (با فرض منطقه زمانی سرور روی UTC+1):

{
  "id": 1,
  "description": "OffsetlessTest",
  "occurredAt": "2026-08-14T20:00:00+01:00"
}

• پاسخ در .NET 10 (روی همان فایل دیتابیس و بدون تغییر سیستم):

{
  "id": 1,
  "description": "OffsetlessTest",
  "occurredAt": "2026-08-14T20:00:00+00:00"
}

AppContext.SetSwitch("Microsoft.Data.Sqlite.Pre10TimeZoneHandling", isEnabled: true);

<ItemGroup>
  <RuntimeHostConfigurationOption Include="Microsoft.Data.Sqlite.Pre10TimeZoneHandling" Value="true" />
</ItemGroup>

هشدار: این کلید سازگاری صرفاً یک مسکّن موقت برای پیشبرد برنامه‌ریزی مهاجرت است و نباید به عنوان راه‌حل دائمی سیستم تلقی شود.

SELECT Id, Description, OccurredAt 
FROM "Events"
WHERE OccurredAt NOT LIKE '%Z' 
  AND OccurredAt NOT LIKE '%+%' 
  AND OccurredAt NOT LIKE '%-%' 
  AND OccurredAt GLOB '[0-9][0-9][0-9][0-9]*';

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    // تضمین ثبت مقادیر با فرمت کامل استاندارد ISO-8601 شامل آفست زمانی
    modelBuilder.Entity<Event>()
        .Property(e => e.OccurredAt)
        .HasConversion(
            v => v.ToString("O"), // مثال: 2026-08-14T20:00:00.0000000+00:00
            v => DateTimeOffset.Parse(v, CultureInfo.InvariantCulture)
        );
}

• داده‌های خام فیلدهای زمانی در جداول SQLite را بازبینی و ممیزی کنند.
• در صورت لزوم، مقادیر فاقد آفست را اصلاح کرده و فرمت ذخیره‌سازی را با استفاده از استاندارد Round-trip ("O") تثبیت نمایند.
• در صورت نیاز به زمان بیشتر، از سوئیچ Pre10TimeZoneHandling صرفاً در طول دوره گذار بهره بگیرند.