Document MDS breaking changes from efcore#36229. (#5056)

Author: cincuranet

entity-framework/core/what-is-new/ef-core-10.0/breaking-changes.md

@@ -17,6 +17,9 @@ This page documents API and behavior changes that have the potential to break ex
 
 ## Summary
 
+> [!NOTE]
+> If you are using Microsoft.Data.Sqlite, please see the [separate section below on Microsoft.Data.Sqlite breaking changes](#MDS-breaking-changes).
+
 | **Breaking change**                                                                                       | **Impact** |
 |:----------------------------------------------------------------------------------------------------------|------------|
 | [ExecuteUpdateAsync now accepts a regular, non-expression lambda](#ExecuteUpdateAsync-lambda)             | Low        |
@@ -83,3 +86,101 @@ await context.Blogs.ExecuteUpdateAsync(s =>
     }
 });
 ```
+
+<a name="MDS-breaking-changes"></a>
+
+## Microsoft.Data.Sqlite breaking changes
+
+### Summary
+
+| **Breaking change**                                                                                       | **Impact** |
+|:----------------------------------------------------------------------------------------------------------|------------|
+| [Using GetDateTimeOffset without an offset now assumes UTC](#DateTimeOffset-read)                          | High       |
+| [Writing DateTimeOffset into REAL column now writes in UTC](#DateTimeOffset-write)                        | High       |
+| [Using GetDateTime with an offset now returns value in UTC](#DateTime-read)                                | High       |
+
+### High-impact changes
+
+<a name="DateTimeOffset-read"></a>
+
+#### Using GetDateTimeOffset without an offset now assumes UTC
+
+[Tracking Issue #36195](https://github.com/dotnet/efcore/issues/36195)
+
+##### Old behavior
+
+Previously, when using `GetDateTimeOffset` on a textual timestamp that did not have an offset (e.g., `2014-04-15 10:47:16`), Microsoft.Data.Sqlite would assume the value was in the local time zone. I.e. the value was parsed as `2014-04-15 10:47:16+02:00` (assuming local time zone was UTC+2).
+
+##### New behavior
+
+Starting with Microsoft.Data.Sqlite 10.0, when using `GetDateTimeOffset` on a textual timestamp that does not have an offset, Microsoft.Data.Sqlite will assume the value is in UTC.
+
+##### Why
+
+Is is to align with SQLite's behavior where timestamps without an offset are treated as UTC.
+
+##### Mitigations
+
+Code should be adjusted accordingly.
+
+As a last/temporary resort, you can revert to previous behavior by setting `Microsoft.Data.Sqlite.Pre10TimeZoneHandling` AppContext switch to `true`, see [AppContext for library consumers](/dotnet/api/system.appcontext#ForConsumers) for more details.
+
+```C#
+AppContext.SetSwitch("Microsoft.Data.Sqlite.Pre10TimeZoneHandling", isEnabled: true);
+```
+
+<a name="DateTimeOffset-write"></a>
+
+#### Writing DateTimeOffset into REAL column now writes in UTC
+
+[Tracking Issue #36195](https://github.com/dotnet/efcore/issues/36195)
+
+##### Old behavior
+
+Previously, when writing a `DateTimeOffset` value into a REAL column, Microsoft.Data.Sqlite would write the value without taking the offset into account.
+
+##### New behavior
+
+Starting with Microsoft.Data.Sqlite 10.0, when writing a `DateTimeOffset` value into a REAL column, Microsoft.Data.Sqlite will convert the value to UTC before doing the conversions and writing it.
+
+##### Why
+
+The value written was incorrect, not aligning with SQLite's behavior where REAL timestamps are asummed to be UTC.
+
+##### Mitigations
+
+Code should be adjusted accordingly.
+
+As a last/temporary resort, you can revert to previous behavior by setting `Microsoft.Data.Sqlite.Pre10TimeZoneHandling` AppContext switch to `true`, see [AppContext for library consumers](/dotnet/api/system.appcontext#ForConsumers) for more details.
+
+```C#
+AppContext.SetSwitch("Microsoft.Data.Sqlite.Pre10TimeZoneHandling", isEnabled: true);
+```
+
+<a name="DateTime-read"></a>
+
+#### Using GetDateTime with an offset now returns value in UTC
+
+[Tracking Issue #36195](https://github.com/dotnet/efcore/issues/36195)
+
+##### Old behavior
+
+Previously, when using `GetDateTime` on a textual timestamp that had an offset (e.g., `2014-04-15 10:47:16+02:00`), Microsoft.Data.Sqlite would return the value with `DateTimeKind.Local` (even if the offset was not local). The time was parsed correctly taking the offset into account.
+
+##### New behavior
+
+Starting with Microsoft.Data.Sqlite 10.0, when using `GetDateTime` on a textual timestamp that has an offset, Microsoft.Data.Sqlite will convert the value to UTC and return it with `DateTimeKind.Utc`.
+
+##### Why
+
+Even though the time was parsed correctly it was dependent on the machine-configured local time zone, which could lead to unexpected results.
+
+##### Mitigations
+
+Code should be adjusted accordingly.
+
+As a last/temporary resort, you can revert to previous behavior by setting `Microsoft.Data.Sqlite.Pre10TimeZoneHandling` AppContext switch to `true`, see [AppContext for library consumers](/dotnet/api/system.appcontext#ForConsumers) for more details.
+
+```C#
+AppContext.SetSwitch("Microsoft.Data.Sqlite.Pre10TimeZoneHandling", isEnabled: true);
+```