‫مدیریت و قالب‌بندی DateTimeOffset در دات‌نت

چکیده: مدیریت زمان و تاریخ در سامانه‌های نرم‌افزاریِ توزیع‌شده، به‌محض عبور داده‌ها از مرزهای برنامه‌ی مبدأ، به یکی از چالش‌های اصلی توسعه‌دهندگان تبدیل می‌شود. تغییرات منطقه زمانی (Time Zone)، نادیده‌گرفتن اختلاف از ساعت هماهنگ جهانی (UTC Offset) و قالب‌بندی‌های نادرست، از عوامل رایج بروز اختلالات خاموش در ارتباطات API، پایگاه‌های داده و لایه‌های Frontend هستند. در این مقاله، به بررسی دقیق رفتار ساختار DateTimeOffset در زبان #C# و اکوسیستم .NET می‌پردازیم. چگونگی تبدیل این ساختار به قالب‌های استاندارد نظیر ISO 8601، RFC 3339، Unix Time و JSON، و همچنین سازوکار بازخوانی (Parse) و میزان بقای اطلاعات (Round-trip) در هر سناریو، ارزیابی خواهد شد.

var timestamp = new DateTimeOffset(
    year: 2026, month: 7, day: 14,
    hour: 9, minute: 11, second: 30, millisecond: 123,
    offset: TimeSpan.FromHours(2));

using System.Globalization;

// قالب همراه با Offset صریح
const string offsetFormat = "yyyy-MM-dd'T'HH:mm:ss.fffK";
// قالب استاندارد UTC با علامت Z
const string utcFormat = "yyyy-MM-dd'T'HH:mm:ss.fff'Z'";

string withOffset = timestamp.ToString(offsetFormat, CultureInfo.InvariantCulture);
// خروجی: 2026-07-14T09:11:30.123+02:00

string inUtc = timestamp.ToUniversalTime().ToString(utcFormat, CultureInfo.InvariantCulture);
// خروجی: 2026-07-14T07:11:30.123Z

نکته مهم (Trap): توکن fff دقیقاً ۳ رقم اعشار (میلی‌ثانیه) تولید می‌کند. اگر می‌خواهید اعشارهای صفرِ انتهایی حذف شوند، از FFFFFF استفاده کنید. همچنین هرگز حرف 'Z' را بدون تبدیل زمان به UTC (روش .ToUniversalTime()) به رشته اضافه نکنید؛ چرا که این کار زمان محلی را بدون تغییر ساعت، به عنوان UTC معرفی کرده و اختلال زمانی ایجاد می‌کند.

var utcStyles = DateTimeStyles.AssumeUniversal | DateTimeStyles.AdjustToUniversal;

// پردازش قالب همراه با Offset
DateTimeOffset parsedOffset = DateTimeOffset.ParseExact(
    withOffset, offsetFormat, CultureInfo.InvariantCulture, DateTimeStyles.None);

// پردازش قالب UTC
DateTimeOffset parsedUtc = DateTimeOffset.ParseExact(
    inUtc, utcFormat, CultureInfo.InvariantCulture, utcStyles);

const string fileFormat = "yyyyMMdd'T'HHmmss.fff'Z'";

string fileTimestamp = timestamp
    .ToUniversalTime()
    .ToString(fileFormat, CultureInfo.InvariantCulture);
// خروجی: 20260714T071130.123Z

// برای Parse کردن این قالب، حتماً باید از ParseExact استفاده شود:
DateTimeOffset parsedFileTime = DateTimeOffset.ParseExact(
    fileTimestamp, fileFormat, CultureInfo.InvariantCulture, utcStyles);

string json = JsonSerializer.Serialize(timestamp);
// خروجی: "2026-07-14T09:11:30.123+02:00"

DateTimeOffset deserialized = JsonSerializer.Deserialize<DateTimeOffset>(json);

using System.Text.Json;
using System.Text.Json.Serialization;

public sealed class UtcDateTimeOffsetJsonConverter : JsonConverter<DateTimeOffset>
{
    private const string Format = "yyyy-MM-dd'T'HH:mm:ss.fff'Z'";

    public override DateTimeOffset Read(
        ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        return DateTimeOffset.ParseExact(
            reader.GetString()!,
            Format,
            CultureInfo.InvariantCulture,
            DateTimeStyles.AssumeUniversal | DateTimeStyles.AdjustToUniversal);
    }

    public override void Write(
        Utf8JsonWriter writer, DateTimeOffset value, JsonSerializerOptions options)
    {
        writer.WriteStringValue(
            value.ToUniversalTime().ToString(Format, CultureInfo.InvariantCulture));
    }
}

const fromText = new Date("2026-07-14T09:11:30.123+02:00");
const fromUnix = new Date(1784013090123);

console.log(fromText.toISOString()); // 2026-07-14T07:11:30.123Z
console.log(fromText.getTime() === fromUnix.getTime()); // true

تله‌های رایج سمت Client:

• رشته‌های بدون Offset (مانند قالب s در دات‌نت) توسط مرورگر بر اساس ساعت محلی کاربر Parse می‌شوند.
• رشته‌های فقط تاریخ (مانند "2026-07-14") بر خلاف مورد قبل، توسط مرورگر بر اساس ساعت UTC (00:00:00Z) Parse می‌شوند که می‌تواند باعث نمایش تاریخ روز قبل برای کاربران غرب UTC شود.
• مشخصه O در دات‌نت ۷ رقم اعشار تولید می‌کند، در حالی که استاندارد ECMAScript ۳ رقم اعشار را تضمین می‌کند. بهتر است از O فقط برای ارتباط بین سرویس‌های دات‌نت استفاده شود.

long seconds = timestamp.ToUnixTimeSeconds();       // 1784013090
long milliseconds = timestamp.ToUnixTimeMilliseconds(); // 1784013090123

// بازگرداندن به DateTimeOffset (همواره با Offset +00:00)
DateTimeOffset fromSec = DateTimeOffset.FromUnixTimeSeconds(seconds);
DateTimeOffset fromMSec = DateTimeOffset.FromUnixTimeMilliseconds(milliseconds);

DateOnly dateOnly = DateOnly.FromDateTime(timestamp.DateTime); // 2026-07-14
TimeOnly timeOnly = TimeOnly.FromDateTime(timestamp.DateTime); // 09:11:30.123

var culture = CultureInfo.GetCultureInfo("fa-IR");
// یا فرهنگ‌های دیگر جهت قالب‌بندی بومی

string[] acceptedFormats =
{
    "O",
    "yyyy-MM-dd'T'HH:mm:ss.fffK",
    "yyyy-MM-dd'T'HH:mm:ss.FFFFFFFK"
};

if (DateTimeOffset.TryParseExact(
    input, acceptedFormats, CultureInfo.InvariantCulture, DateTimeStyles.None, out var parsed))
{
    // پردازش ورودی معتبر
}

• لایه‌های داخلی و پایگاه داده: تمام Timestampها را داخل برنامه و در پایگاه داده (مثلاً نوع داده datetimeoffset در SQL Server) به‌صورت تایپ‌شده با DateTimeOffset نگهداری کنید.
• ارتباطات متنی (JSON / REST API): از پیکربندی پیش‌فرض System.Text.Json یا استاندارد صریح RFC 3339 استفاده کنید. فرمت .NET Round-trip (O) را فقط برای سرویس‌های .NET-to-.NET حفظ کنید.
• پروتکل‌های عددی: در صورت استفاده از Unix Time، unit (ثانیه یا میلی‌ثانیه) را مشخص کنید.
• دقت در Parsing: برای جلوگیری از رفتارهای غیرمنتظره به دلیل اختلاف منطقه زمانی سرورها، از TryParseExact همراه با DateTimeStyles صریح استفاده کنید.