C#のDateTimeOffset.AddMilliseconds()メソッドの使い方を徹底解説

C#のDateTimeOffset.AddMilliseconds()メソッドは、現在のDateTimeOffsetインスタンスの値に指定したミリ秒数を加算し、その結果を表す新しいDateTimeOffsetオブジェクトを返します。

重要なポイントとして、このメソッドは元のインスタンスの値を変更しません。DateTimeOffset構造体は不変（イミュータブル）であるため、計算結果は常に新しいオブジェクトとして返されます。

構文

AddMilliseconds()メソッドの構文は以下のとおりです。

public DateTimeOffset AddMilliseconds (double val);

パラメータ

• val：加算するミリ秒数（double型）。負の値を指定すると、日時からミリ秒が減算されます。

戻り値

指定したミリ秒数を加算（または減算）した結果を表す、新しいDateTimeOffsetオブジェクトを返します。

使用例1：ミリ秒を加算する場合

まず、AddMilliseconds()メソッドを使ってミリ秒を加算する例を見てみましょう。

using System;
public class Demo {
   public static void Main() {
      DateTimeOffset dateTimeOffset = new DateTimeOffset(2019, 08, 10, 4, 20, 10, new TimeSpan(-5, 0, 0));
      Console.WriteLine("DateTimeOffset (before adding milliseconds) = {0}", dateTimeOffset);
      DateTimeOffset res = dateTimeOffset.AddMilliseconds(3000);
      Console.WriteLine("DateTimeOffset (after adding milliseconds) = {0}", res);
   }
}

出力結果

このプログラムを実行すると、以下の出力が得られます。

DateTimeOffset (before adding milliseconds) = 8/10/2019 4:20:10 AM -05:00
DateTimeOffset (after adding milliseconds) = 8/10/2019 4:20:13 AM -05:00

3000ミリ秒（3秒）が加算され、時刻が「4:20:10」から「4:20:13」に更新されていることがわかります。

使用例2：ミリ秒を減算する場合

次に、負の値を指定してミリ秒を減算する例を確認しましょう。

using System;
public class Demo {
   public static void Main() {
      DateTimeOffset dateTimeOffset = new DateTimeOffset(2019, 08, 10, 4, 20, 10, new TimeSpan(-5, 0, 0));
      Console.WriteLine("DateTimeOffset (before subtracting milliseconds) = {0}", dateTimeOffset);
      DateTimeOffset res = dateTimeOffset.AddMilliseconds(-2000);
      Console.WriteLine("DateTimeOffset (after subtracting milliseconds) = {0}", res);
   }
}

出力結果

このプログラムを実行すると、以下の出力が得られます。

DateTimeOffset (before subtracting milliseconds) = 8/10/2019 4:20:10 AM -05:00
DateTimeOffset (after subtracting milliseconds) = 8/10/2019 4:20:08 AM -05:00

-2000ミリ秒（-2秒）が指定されたため、時刻が「4:20:10」から「4:20:08」に減算されています。

まとめ

DateTimeOffset.AddMilliseconds()メソッドを使用すると、UTCオフセット情報を保持したまま、日時にミリ秒単位の加算・減算を簡単に行うことができます。タイムゾーンを考慮した日時処理が必要なアプリケーションで特に有用なメソッドです。