Support the "datetimeoffset" type.

Author: RyanLamansky

SqlServerSimulator.Tests.EFCore/EFCoreDateTime.cs

@@ -1,15 +1,17 @@
 namespace SqlServerSimulator;
 
 /// <summary>
-/// Exercises the simulator's <c>datetime2(N)</c> column support through EF
-/// Core's idiomatic surface. Confirms the full-precision (precision 7) round
-/// trip and the lower-precision (precision 3) rounding-on-store behavior land
-/// correctly through EF's parameter binding and reader hydration.
+/// Exercises the simulator's <c>datetime2(N)</c> and <c>datetimeoffset(N)</c>
+/// column support through EF Core's idiomatic surface. Confirms full-precision
+/// (precision 7) round trips and lower-precision (precision 3 / 0) rounding-
+/// on-store behavior land correctly through EF's parameter binding and reader
+/// hydration. Datetimeoffset additionally pins offset preservation across the
+/// round trip and equality-by-UTC-instant in <c>WHERE</c>.
 /// </summary>
 /// <remarks>
-/// Only <see cref="DateTime"/> properties are covered today — see
-/// <see cref="SimulatedDbParameter"/> for the per-mapping compatibility table
-/// explaining why the other date/time configurations
+/// Only <see cref="DateTime"/> and <see cref="DateTimeOffset"/> properties are
+/// covered — see <see cref="SimulatedDbParameter"/> for the per-mapping
+/// compatibility table explaining why the other date/time configurations
 /// (<c>DateOnly → date</c>, <c>TimeOnly → time</c>, <c>TimeSpan → time</c>,
 /// <c>DateTime → date</c>) are unreachable through EF Core until a bridge
 /// adapter ships.
@@ -111,4 +113,63 @@ public void MultipleRows_RoundTripBothColumns()
         Assert.AreEqual(b, rows[1].CreatedAt);
         Assert.IsNull(rows[1].Updated);
     }
+
+    [TestMethod]
+    public void Insert_DateTimeOffset_FullPrecisionAndOffsetRoundTrip()
+    {
+        using var context = new TestDbContext(TestDbContext.CreateEventsSimulation());
+
+        var dto = new DateTimeOffset(2026, 5, 4, 13, 45, 30, TimeSpan.FromHours(-7)).AddTicks(1234567);
+        _ = context.Events.Add(new Event { Id = 1, CreatedAt = new DateTime(2026, 5, 4), OccurredAt = dto });
+        _ = context.SaveChanges();
+
+        var read = context.Events.Select(e => e.OccurredAt).First();
+        Assert.AreEqual(dto, read);
+        Assert.AreEqual(TimeSpan.FromHours(-7), read.Offset);
+    }
+
+    [TestMethod]
+    public void Insert_NullableDateTimeOffset_AcceptsNullAndValue()
+    {
+        using var context = new TestDbContext(TestDbContext.CreateEventsSimulation());
+        var cancelled = new DateTimeOffset(2026, 5, 4, 14, 0, 0, TimeSpan.FromHours(2));
+        context.Events.AddRange(
+            new Event { Id = 1, CreatedAt = new DateTime(2026, 5, 4), OccurredAt = DateTimeOffset.UnixEpoch },
+            new Event { Id = 2, CreatedAt = new DateTime(2026, 5, 4), OccurredAt = DateTimeOffset.UnixEpoch, Cancelled = cancelled });
+        _ = context.SaveChanges();
+
+        var rows = context.Events.OrderBy(e => e.Id).Select(e => e.Cancelled).ToArray();
+        Assert.IsNull(rows[0]);
+        Assert.AreEqual(cancelled, rows[1]);
+    }
+
+    [TestMethod]
+    public void Insert_DateTimeOffset_LowerPrecisionColumn_RoundsHalfUp()
+    {
+        // Cancelled is datetimeoffset(3); 0.5ms above a millisecond boundary rounds to next ms.
+        using var context = new TestDbContext(TestDbContext.CreateEventsSimulation());
+        var cancelled = new DateTimeOffset(2026, 5, 4, 13, 45, 30, 100, TimeSpan.FromHours(-7)).AddTicks(5_000);
+        _ = context.Events.Add(new Event { Id = 1, CreatedAt = new DateTime(2026, 5, 4), OccurredAt = DateTimeOffset.UnixEpoch, Cancelled = cancelled });
+        _ = context.SaveChanges();
+
+        var expected = new DateTimeOffset(2026, 5, 4, 13, 45, 30, 101, TimeSpan.FromHours(-7));
+        Assert.AreEqual(expected, context.Events.Select(e => e.Cancelled).First());
+    }
+
+    [TestMethod]
+    public void Where_FiltersByDateTimeOffsetEquality_CrossOffset()
+    {
+        // The stored value and the parameter share a UTC instant but carry
+        // different offsets; equality should still match.
+        using var context = new TestDbContext(TestDbContext.CreateEventsSimulation());
+        var east = new DateTimeOffset(2026, 5, 4, 20, 45, 30, TimeSpan.FromHours(7));
+        context.Events.AddRange(
+            new Event { Id = 1, CreatedAt = new DateTime(2026, 5, 4), OccurredAt = east },
+            new Event { Id = 2, CreatedAt = new DateTime(2026, 5, 4), OccurredAt = new DateTimeOffset(2026, 5, 5, 0, 0, 0, TimeSpan.Zero) });
+        _ = context.SaveChanges();
+
+        var west = new DateTimeOffset(2026, 5, 4, 6, 45, 30, TimeSpan.FromHours(-7));
+        var match = context.Events.Where(e => e.OccurredAt == west).Select(e => e.Id).Single();
+        Assert.AreEqual(1, match);
+    }
 }

SqlServerSimulator.Tests.EFCore/TestDbContext.cs

@@ -29,14 +29,16 @@ internal class Person
 }
 
 /// <summary>
-/// Exercises the simulator's <c>datetime2</c> column support through EF Core.
-/// Properties are <see cref="DateTime"/> rather than <see cref="DateOnly"/> /
-/// <see cref="TimeOnly"/> / <see cref="TimeSpan"/> because EF Core's SqlServer
-/// provider downcasts <see cref="System.Data.Common.DbParameter"/> to
-/// <c>SqlParameter</c> in those mappings; <c>DateTime → datetime2</c> is the
-/// only date/time configuration whose mapping leaves the default
-/// <c>SqlDbType</c> in place and so doesn't trigger the downcast.
-/// See <see cref="SimulatedDbParameter"/> for the full compatibility matrix.
+/// Exercises the simulator's <c>datetime2</c> and <c>datetimeoffset</c>
+/// column support through EF Core. The CLR-side properties stay narrow:
+/// <see cref="DateTime"/> for datetime2 and <see cref="DateTimeOffset"/>
+/// for datetimeoffset, because EF Core's SqlServer provider downcasts
+/// <see cref="System.Data.Common.DbParameter"/> to <c>SqlParameter</c> in
+/// the mappings for <see cref="DateOnly"/>, <see cref="TimeOnly"/>,
+/// <see cref="TimeSpan"/>, and <c>DateTime → date</c>. The two configurations
+/// covered here are the ones that leave the default <c>SqlDbType</c> in
+/// place and so don't trigger the downcast. See
+/// <see cref="SimulatedDbParameter"/> for the full compatibility matrix.
 /// </summary>
 internal class Event
 {
@@ -47,6 +49,12 @@ internal class Event
 
     [Column(TypeName = "datetime2(3)")]
     public DateTime? Updated { get; set; }
+
+    [Column(TypeName = "datetimeoffset(7)")]
+    public DateTimeOffset OccurredAt { get; set; }
+
+    [Column(TypeName = "datetimeoffset(3)")]
+    public DateTimeOffset? Cancelled { get; set; }
 }
 
 internal class TestDbContext(Simulation simulation) : DbContext
@@ -106,7 +114,7 @@ public static Simulation CreateEventsSimulation()
         var simulation = new Simulation();
         _ = simulation
             .CreateOpenConnection()
-            .CreateCommand("create table Events ( Id int, CreatedAt datetime2(7) not null, Updated datetime2(3) null )")
+            .CreateCommand("create table Events ( Id int, CreatedAt datetime2(7) not null, Updated datetime2(3) null, OccurredAt datetimeoffset(7) not null, Cancelled datetimeoffset(3) null )")
             .ExecuteNonQuery();
         return simulation;
     }

SqlServerSimulator.Tests.Internal/Storage/RowRoundTripTests.cs

@@ -204,4 +204,25 @@ public void EncodedDateRow_StoresDayCountLittleEndian()
         AreEqual(7, BitConverter.ToUInt16(bytes, 2));                   // fixed-length end offset (4 + 3)
         CollectionAssert.AreEqual(new byte[] { 0x9B, 0x49, 0x0B }, bytes[4..7]);
     }
+
+    [TestMethod]
+    public void EncodedSingleColumnDateTimeOffsetRow_PrecisionZero_HasLength15()
+    {
+        // 4 (header) + 8 (datetimeoffset(0): 3 time + 3 date + 2 offset) + 2 (column count) + 1 (NULL bitmap byte) = 15.
+        var type = SqlType.GetDateTimeOffset(0);
+        var value = SqlValue.FromDateTimeOffset(type, new DateTimeOffset(2026, 5, 4, 13, 45, 30, TimeSpan.FromHours(-7)));
+        AreEqual(15, RowEncoder.EncodeRow([type], [value]).Length);
+    }
+
+    [TestMethod]
+    public void EncodedDateTimeOffsetRow_StoresOffsetAsSignedLittleEndianMinutes()
+    {
+        // Layout at precision 0: 3-byte UTC time-of-day, 3-byte UTC day count, 2-byte signed offset minutes.
+        var type = SqlType.GetDateTimeOffset(0);
+        var value = SqlValue.FromDateTimeOffset(type, new DateTimeOffset(2026, 5, 4, 13, 45, 30, TimeSpan.FromHours(-7)));
+        var bytes = RowEncoder.EncodeRow([type], [value]);
+
+        AreEqual(12, BitConverter.ToUInt16(bytes, 2));                  // fixed-length end offset (4 + 8)
+        AreEqual(-420, BitConverter.ToInt16(bytes, 10));                // -07:00 in minutes
+    }
 }

SqlServerSimulator.Tests.Internal/Storage/SqlValueTests.cs

@@ -209,4 +209,31 @@ public void Time_DifferentPrecisions_AreDistinctTypes()
         AreNotSame(v3.Type, v7.Type);
         AreNotEqual(v3, v7);
     }
+
+    [TestMethod]
+    public void FromDateTimeOffset_RejectsNonDateTimeOffsetType() =>
+        Throws<ArgumentException>(() => SqlValue.FromDateTimeOffset(SqlType.Int32, DateTimeOffset.UtcNow));
+
+    [TestMethod]
+    public void DateTimeOffset_DifferentPrecisions_AreDistinctTypes()
+    {
+        var v3 = SqlValue.FromDateTimeOffset(SqlType.GetDateTimeOffset(3), new DateTimeOffset(2026, 5, 4, 13, 45, 30, TimeSpan.Zero));
+        var v7 = SqlValue.FromDateTimeOffset(SqlType.GetDateTimeOffset(7), new DateTimeOffset(2026, 5, 4, 13, 45, 30, TimeSpan.Zero));
+        AreNotSame(v3.Type, v7.Type);
+        AreNotEqual(v3, v7);
+    }
+
+    [TestMethod]
+    public void DateTimeOffset_EqualByUtc_DifferentOffsets_HaveEqualHashCodes()
+    {
+        // The Equals side of the by-UTC-instant contract is covered publicly
+        // by FromTableWhere_FiltersByDateTimeOffsetEquality_AcrossOffsets.
+        // GetHashCode has no public SQL trigger today (no DISTINCT/GROUP BY/
+        // JOIN), so we pin the equal-objects-have-equal-hashes invariant
+        // here directly until those features land.
+        var type = SqlType.GetDateTimeOffset(7);
+        var east = SqlValue.FromDateTimeOffset(type, new DateTimeOffset(2026, 5, 4, 20, 45, 30, TimeSpan.FromHours(7)));
+        var west = SqlValue.FromDateTimeOffset(type, new DateTimeOffset(2026, 5, 4, 6, 45, 30, TimeSpan.FromHours(-7)));
+        AreEqual(east.GetHashCode(), west.GetHashCode());
+    }
 }

SqlServerSimulator.Tests/CastTests.cs

@@ -167,4 +167,98 @@ public void Cast_TimeToDateTime2_FillsLegacyDate()
     [TestMethod]
     public void Cast_TimeNullPassesThrough() =>
         IsInstanceOfType<DBNull>(ExecuteScalar("select cast(cast(null as time(7)) as varchar(20))"));
+
+    [TestMethod]
+    [DataRow("cast('2026-05-04 13:45:30 -07:00' as datetimeoffset(0))", "2026-05-04T13:45:30-07:00")]
+    [DataRow("cast('2026-05-04 13:45:30.123 +03:00' as datetimeoffset(3))", "2026-05-04T13:45:30.123+03:00")]
+    [DataRow("cast('2026-05-04 13:45:30.1234567 +00:00' as datetimeoffset(7))", "2026-05-04T13:45:30.1234567+00:00")]
+    public void Cast_StringToDateTimeOffset(string expression, string expectedIso)
+    {
+        var value = ExecuteScalar($"select {expression}");
+        var dto = IsInstanceOfType<DateTimeOffset>(value);
+        AreEqual(DateTimeOffset.Parse(expectedIso, System.Globalization.CultureInfo.InvariantCulture), dto);
+    }
+
+    [TestMethod]
+    public void Cast_StringWithoutOffsetToDateTimeOffset_AssumesUtc()
+    {
+        // SQL Server treats an offsetless string as +00:00 when casting to datetimeoffset.
+        var value = ExecuteScalar("select cast('2026-05-04 13:45:30' as datetimeoffset(0))");
+        var dto = IsInstanceOfType<DateTimeOffset>(value);
+        AreEqual(new DateTimeOffset(2026, 5, 4, 13, 45, 30, TimeSpan.Zero), dto);
+        AreEqual(TimeSpan.Zero, dto.Offset);
+    }
+
+    [TestMethod]
+    [DataRow("not a datetimeoffset")]
+    [DataRow("2026-13-01 13:45:30 +00:00")]
+    public void Cast_BadStringToDateTimeOffset_RaisesConversionFailed(string text)
+    {
+        var ex = Throws<DbException>(() => ExecuteScalar($"select cast('{text}' as datetimeoffset(7))"));
+        AreEqual("Conversion failed when converting date and/or time from character string.", ex.Message);
+    }
+
+    [TestMethod]
+    [DataRow("cast(cast('2026-05-04 13:45:30 -07:00' as datetimeoffset(0)) as varchar(40))", "2026-05-04 13:45:30 -07:00")]
+    [DataRow("cast(cast('2026-05-04 13:45:30.123 +03:00' as datetimeoffset(3)) as varchar(40))", "2026-05-04 13:45:30.123 +03:00")]
+    public void Cast_DateTimeOffsetToString(string expression, string expected) =>
+        AreEqual(expected, ExecuteScalar($"select {expression}"));
+
+    [TestMethod]
+    public void Cast_DateTimeOffset_NarrowingPrecisionRoundsHalfUp()
+    {
+        var result = ExecuteScalar("select cast(cast('2026-05-04 13:45:30.5 -07:00' as datetimeoffset(7)) as datetimeoffset(0))");
+        var dto = IsInstanceOfType<DateTimeOffset>(result);
+        AreEqual(new DateTimeOffset(2026, 5, 4, 13, 45, 31, TimeSpan.FromHours(-7)), dto);
+    }
+
+    [TestMethod]
+    public void Cast_DateTime2ToDateTimeOffset_AssumesZeroOffset()
+    {
+        var result = ExecuteScalar("select cast(cast('2026-05-04 13:45:30' as datetime2(7)) as datetimeoffset(7))");
+        var dto = IsInstanceOfType<DateTimeOffset>(result);
+        AreEqual(new DateTimeOffset(2026, 5, 4, 13, 45, 30, TimeSpan.Zero), dto);
+    }
+
+    [TestMethod]
+    public void Cast_DateTimeOffsetToDateTime2_DropsOffset()
+    {
+        // SQL Server: casting datetimeoffset → datetime2 returns the LOCAL
+        // (offset-bearing) wall-clock and discards the offset.
+        var result = ExecuteScalar("select cast(cast('2026-05-04 13:45:30 -07:00' as datetimeoffset(7)) as datetime2(7))");
+        AreEqual(new DateTime(2026, 5, 4, 13, 45, 30), IsInstanceOfType<DateTime>(result));
+    }
+
+    [TestMethod]
+    public void Cast_DateToDateTimeOffset_AppliesMidnightAndZeroOffset()
+    {
+        var result = ExecuteScalar("select cast(cast('2026-05-04' as date) as datetimeoffset(7))");
+        AreEqual(new DateTimeOffset(2026, 5, 4, 0, 0, 0, TimeSpan.Zero), IsInstanceOfType<DateTimeOffset>(result));
+    }
+
+    [TestMethod]
+    public void Cast_DateTimeOffsetToDate_DropsTimeAndOffset()
+    {
+        var result = ExecuteScalar("select cast(cast('2026-05-04 23:45:30 -07:00' as datetimeoffset(7)) as date)");
+        // Local date, not the UTC-shifted one.
+        AreEqual(new DateTime(2026, 5, 4), IsInstanceOfType<DateTime>(result));
+    }
+
+    [TestMethod]
+    public void Cast_TimeToDateTimeOffset_FillsLegacyDateAndZeroOffset()
+    {
+        var result = ExecuteScalar("select cast(cast('13:45:30' as time(7)) as datetimeoffset(7))");
+        AreEqual(new DateTimeOffset(1900, 1, 1, 13, 45, 30, TimeSpan.Zero), IsInstanceOfType<DateTimeOffset>(result));
+    }
+
+    [TestMethod]
+    public void Cast_DateTimeOffsetToTime_DropsDateAndOffset()
+    {
+        var result = ExecuteScalar("select cast(cast('2026-05-04 13:45:30 -07:00' as datetimeoffset(7)) as time(7))");
+        AreEqual(new TimeSpan(13, 45, 30), IsInstanceOfType<TimeSpan>(result));
+    }
+
+    [TestMethod]
+    public void Cast_DateTimeOffsetNullPassesThrough() =>
+        IsInstanceOfType<DBNull>(ExecuteScalar("select cast(cast(null as datetimeoffset(7)) as varchar(40))"));
 }

SqlServerSimulator.Tests/CreateTableTests.cs

@@ -320,4 +320,36 @@ public void CreateTableTime_PrecisionOutOfRange(int precision)
         var x = Assert.Throws<DbException>(() => command.ExecuteNonQuery());
         Assert.AreEqual($"Specified scale {precision} is invalid.", x.Message);
     }
+
+    [TestMethod]
+    [DataRow("datetimeoffset")]         // default precision = 7
+    [DataRow("DATETIMEOFFSET")]
+    [DataRow("datetimeoffset(0)")]
+    [DataRow("datetimeoffset(3)")]
+    [DataRow("datetimeoffset(7)")]
+    public void CreateTableDateTimeOffset(string typeSpec)
+    {
+        var simulation = new Simulation();
+
+        using var connection = simulation.CreateDbConnection();
+        using var command = connection.CreateCommand($"create table t ( v {typeSpec} )");
+
+        connection.Open();
+        Assert.AreEqual(-1, command.ExecuteNonQuery());
+    }
+
+    [TestMethod]
+    [DataRow(8)]
+    [DataRow(99)]
+    public void CreateTableDateTimeOffset_PrecisionOutOfRange(int precision)
+    {
+        var simulation = new Simulation();
+
+        using var connection = simulation.CreateDbConnection();
+        using var command = connection.CreateCommand($"create table t ( v datetimeoffset({precision}) )");
+
+        connection.Open();
+        var x = Assert.Throws<DbException>(() => command.ExecuteNonQuery());
+        Assert.AreEqual($"Specified scale {precision} is invalid.", x.Message);
+    }
 }