C#のDateTimeOffset.ToUnixTimeMilliseconds()メソッドの使い方をわかりやすく解説

C#のDateTimeOffset.ToUnixTimeMilliseconds()メソッドは、UNIXエポックと呼ばれる「1970年1月1日 00:00:00.000Z（UTC）」からの経過時間をミリ秒単位で返すメソッドです。タイムスタンプの生成やAPIとのデータ連携など、日時を数値として扱いたい場面でよく利用されます。

構文

このメソッドの構文は以下の通りです。

public long ToUnixTimeMilliseconds ();

戻り値はlong型で、エポックからの経過ミリ秒数が返されます。なお、1970年より前の日時を指定した場合は、負の値が返される点に注意してください。

使用例1：基本的な使い方

まずは基本的な実装例を見てみましょう。2019年9月10日の日時に対してToUnixTimeMilliseconds()メソッドを呼び出し、さらにToOffset()メソッドでオフセットを変更した場合の挙動も確認します。

using System;
public class Demo {
    public static void Main() {
        DateTimeOffset dateTimeOffset = new DateTimeOffset(2019, 9, 10, 4, 20, 10, new TimeSpan(5, 0, 0));
        Console.WriteLine("DateTimeOffset = {0}", dateTimeOffset);
        Console.WriteLine("ミリ秒数: " + dateTimeOffset.ToUnixTimeMilliseconds());
        DateTimeOffset res = dateTimeOffset.ToOffset(new TimeSpan(-5, 0, 0));
        Console.WriteLine("\nDateTimeOffset (更新後) = {0}", res);
        Console.WriteLine("ミリ秒数: " + res.ToUnixTimeMilliseconds());
    }
}

出力結果

DateTimeOffset = 9/10/2019 4:20:10 AM +05:00
Number of milliseconds: 1568071210000
DateTimeOffset (updated) = 9/9/2019 6:20:10 PM -05:00
Number of milliseconds: 1568071210000

この例から分かるように、ToOffset()メソッドでタイムゾーンのオフセットを+05:00から-05:00に変更しても、表現される瞬間（時刻の実体）は同じであるため、取得できるミリ秒数はどちらも同じ値になります。これはDateTimeOffsetが絶対的な時点を基準としているためです。

使用例2：1970年以前の日時の場合

次に、UNIXエポック（1970年1月1日）より前の日時を指定した場合の例を見てみましょう。

using System;
public class Demo {
    public static void Main() {
        DateTimeOffset dateTimeOffset = new DateTimeOffset(1967, 11, 11, 6, 15, 45, new TimeSpan(3, 0, 0));
        Console.WriteLine("DateTimeOffset = {0}", dateTimeOffset);
        Console.WriteLine("ミリ秒数: " + dateTimeOffset.ToUnixTimeMilliseconds());
        DateTimeOffset res = dateTimeOffset.ToOffset(new TimeSpan(-5, 0, 0));
        Console.WriteLine("\nDateTimeOffset (更新後) = {0}", res);
        Console.WriteLine("ミリ秒数: " + res.ToUnixTimeMilliseconds());
    }
}

出力結果

DateTimeOffset = 11/11/1967 6:15:45 AM +03:00
Number of milliseconds: -67553055000
DateTimeOffset (updated) = 11/10/1967 10:15:45 PM -05:00
Number of milliseconds: -67553055000

1970年より前の日時を指定すると、上記のように負のミリ秒数が返されます。こちらの例でも、オフセットを変更しても同じ瞬間を指しているため、結果は同一の値となっています。

まとめ

• ToUnixTimeMilliseconds()は、1970年1月1日00:00:00.000Z（UTC）からの経過ミリ秒をlong型で返す
• 1970年以前の日時を指定した場合は負の値が返る
• タイムゾーンのオフセットが異なるDateTimeOffsetでも、同じ瞬間を表していれば同じ値が返る