diff --git a/docs/core/compatibility/11.md b/docs/core/compatibility/11.md index 25638945abfa1..8654a6a8b2d52 100644 --- a/docs/core/compatibility/11.md +++ b/docs/core/compatibility/11.md @@ -24,6 +24,7 @@ See [Breaking changes in ASP.NET Core 10](/aspnet/core/breaking-changes/10/overv | Title | Type of change | |-------------------------------------------------------------------|-------------------| +| [DateOnly and TimeOnly TryParse methods throw for invalid input](core-libraries/11/dateonly-timeonly-tryparse-argumentexception.md) | Behavioral change | | [DeflateStream and GZipStream write headers and footers for empty payload](core-libraries/11/deflatestream-gzipstream-empty-payload.md) | Behavioral change | | [Environment.TickCount made consistent with Windows timeout behavior](core-libraries/11/environment-tickcount-windows-behavior.md) | Behavioral change | | [MemoryStream maximum capacity updated and exception behavior changed](core-libraries/11/memorystream-max-capacity.md) | Behavioral change | diff --git a/docs/core/compatibility/core-libraries/11/dateonly-timeonly-tryparse-argumentexception.md b/docs/core/compatibility/core-libraries/11/dateonly-timeonly-tryparse-argumentexception.md new file mode 100644 index 0000000000000..ef831303a8b26 --- /dev/null +++ b/docs/core/compatibility/core-libraries/11/dateonly-timeonly-tryparse-argumentexception.md @@ -0,0 +1,99 @@ +--- +title: "Breaking change: DateOnly and TimeOnly TryParse methods throw for invalid input" +description: "Learn about the breaking change in .NET 11 where DateOnly and TimeOnly TryParse methods throw ArgumentException for invalid DateTimeStyles values or format specifiers." +ms.date: 03/19/2026 +ai-usage: ai-assisted +--- + +# DateOnly and TimeOnly TryParse methods throw for invalid input + +The and `TryParse` and `TryParseExact` methods now throw an when invalid values or format specifiers are provided. This aligns their behavior with other `TryParse` APIs in .NET. + +## Version introduced + +.NET 11 Preview 2 + +## Previous behavior + +Previously, passing invalid values or format specifiers to `DateOnly.TryParse`, `DateOnly.TryParseExact`, `TimeOnly.TryParse`, or `TimeOnly.TryParseExact` caused the methods to return `false` without throwing an exception. + +```csharp +using System; +using System.Globalization; + +bool result = DateOnly.TryParseExact( + "2023-10-15", + "yyyy-MM-dd", + CultureInfo.InvariantCulture, + (DateTimeStyles)999, // Invalid DateTimeStyles value + out DateOnly date); + +Console.WriteLine(result); // Output: False +``` + +## New behavior + +Starting in .NET 11, passing invalid values or format specifiers to these methods throws an . The exception includes details about the invalid argument, such as the parameter name. + +```csharp +using System; +using System.Globalization; + +try +{ + bool result = DateOnly.TryParseExact( + "2023-10-15", + "yyyy-MM-dd", + CultureInfo.InvariantCulture, + (DateTimeStyles)999, // Invalid DateTimeStyles value + out DateOnly date); +} +catch (ArgumentException ex) +{ + Console.WriteLine(ex.Message); + // Output: "The value '999' is not valid for DateTimeStyles. (Parameter 'style')" +} +``` + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +This change aligns the behavior of `DateOnly` and `TimeOnly` parsing methods with other `TryParse` APIs in .NET, which throw exceptions for invalid arguments. The previous behavior of silently returning `false` for invalid arguments could mask programming errors and make debugging more difficult. + +## Recommended action + +Review your usage of `DateOnly.TryParse`, `DateOnly.TryParseExact`, `TimeOnly.TryParse`, and `TimeOnly.TryParseExact` to ensure that valid values and format specifiers are being passed. If invalid arguments are possible in your code paths, wrap the calls in a `try`-`catch` block to handle . + +```csharp +using System; +using System.Globalization; + +try +{ + bool result = DateOnly.TryParseExact( + "2023-10-15", + "yyyy-MM-dd", + CultureInfo.InvariantCulture, + (DateTimeStyles)999, // Invalid DateTimeStyles value + out DateOnly date); +} +catch (ArgumentException ex) +{ + Console.WriteLine($"Error: {ex.Message}"); + // Handle the exception as needed +} +``` + +## Affected APIs + +- +- +- +- +- +- +- +- diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 748675af35f84..e696ac000dbb9 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -10,6 +10,8 @@ items: href: 11.md - name: Core .NET libraries items: + - name: DateOnly and TimeOnly TryParse methods throw for invalid input + href: core-libraries/11/dateonly-timeonly-tryparse-argumentexception.md - name: DeflateStream and GZipStream write headers and footers for empty payload href: core-libraries/11/deflatestream-gzipstream-empty-payload.md - name: Environment.TickCount made consistent with Windows timeout behavior