docs: breaking change - DateOnly/TimeOnly TryParse throws ArgumentException for invalid DateTimeStyles (.NET 11)

[Copilot]

In .NET 11 Preview 2, DateOnly.TryParse, DateOnly.TryParseExact, TimeOnly.TryParse, and TimeOnly.TryParseExact changed from silently returning false to throwing ArgumentException when passed invalid DateTimeStyles values or format specifiers.

Changes

• New article docs/core/compatibility/core-libraries/11/dateonly-timeonly-tryparse-argumentexception.md — covers previous/new behavior, reason (consistency with other TryParse APIs), recommended try/catch migration pattern, and all 8 affected API xrefs
• docs/core/compatibility/11.md — added entry to Core .NET libraries breaking changes table
• docs/core/compatibility/toc.yml — added TOC entry under .NET 11 > Core .NET libraries

Behavior delta

// Before (.NET 10 and earlier)
bool result = DateOnly.TryParseExact("2023-10-15", "yyyy-MM-dd",
    CultureInfo.InvariantCulture, (DateTimeStyles)999, out DateOnly date);
Console.WriteLine(result); // False — silent failure

// After (.NET 11+)
// Throws ArgumentException: "The value '999' is not valid for DateTimeStyles. (Parameter 'style')"

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Breaking change]: Fix DateOnly/TimeOnly TryParse to throw on invalid DateTimeStyles and format specifiers</issue_title>
<issue_description>## [Breaking change]: DateOnly.TryParse and TimeOnly.TryParse now throw exceptions for invalid DateTimeStyles and format specifiers

Description

Starting in .NET 11 Preview 2, the DateOnly.TryParse, DateOnly.TryParseExact, TimeOnly.TryParse, and TimeOnly.TryParseExact methods have been updated to throw an ArgumentException when invalid DateTimeStyles values or format specifiers are provided. Previously, these methods returned false in such cases, which was inconsistent with the behavior of other TryParse APIs in .NET.

This change was introduced to improve API consistency and ensure that invalid arguments are explicitly flagged as errors, rather than being silently ignored.

This change was implemented in dotnet/runtime#123805.

Version

.NET 11 Preview 2

Previous behavior

When invalid DateTimeStyles values or format specifiers were passed to DateOnly.TryParse, DateOnly.TryParseExact, TimeOnly.TryParse, or TimeOnly.TryParseExact, the methods returned false without throwing an exception.

Example

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

When invalid DateTimeStyles values or format specifiers are passed to these methods, an ArgumentException is thrown. The exception includes details about the invalid argument, such as the parameter name.

Example

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

• Behavioral change: Existing binaries might behave differently at runtime.

Reason for change

This change was introduced to align the behavior of DateOnly and TimeOnly parsing methods with other TryParse APIs in .NET, which throw exceptions for invalid arguments. The previous behavior of returning false for invalid arguments could lead to silent failures and make debugging more difficult.

Recommended action

Developers should review their usage of DateOnly.TryParse, DateOnly.TryParseExact, TimeOnly.TryParse, and TimeOnly.TryParseExact to ensure that valid DateTimeStyles values and format specifiers are being passed. If invalid arguments are possible, consider wrapping the calls in a try-catch block to handle ArgumentException.

Example of handling exceptions

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

• DateOnly.TryParse(string, out DateOnly)
• DateOnly.TryParse(string, IFormatProvider, DateTimeStyles, out DateOnly)
• DateOnly.TryParseExact(string, string, IFormatProvider, DateTimeStyles, out DateOnly)
• DateOnly.TryParseExact(string, string[], IFormatProvider, DateTimeStyles, out DateOnly)
• TimeOnly.TryParse(string, out TimeOnly)
• TimeOnly.TryParse(string, IFormatProvider, DateTimeStyles, out TimeOnly)
• TimeOnly.TryParseExact(string, string, IFormatProvider, DateTimeStyles, out TimeOnly)
• TimeOnly.TryParseExact(string, string[], IFormatProvider, DateTimeStyles, out TimeOnly)</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Breaking change]: Fix DateOnly/TimeOnly TryParse to throw on invalid DateTimeStyles and format specifiers #51438

---

📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.

---

Internal previews

📄 File	🔗 Preview link
docs/core/compatibility/11.md	Breaking changes in .NET 11
docs/core/compatibility/core-libraries/11/dateonly-timeonly-tryparse-argumentexception.md	DateOnly and TimeOnly TryParse methods throw for invalid input
docs/core/compatibility/toc.yml	docs/core/compatibility/toc

[Copilot]

Pull request overview

Adds a new .NET 11 breaking change compatibility article documenting that DateOnly/TimeOnly TryParse and TryParseExact APIs throw ArgumentException for invalid DateTimeStyles values (and invalid format specifiers), and wires the article into the .NET 11 compatibility index and TOC.

Changes:

• Added a new breaking change article for DateOnly/TimeOnly parsing behavior in .NET 11 Preview 2.
• Linked the new article from the .NET 11 “Core .NET libraries” breaking changes table.
• Added the new article to the compatibility TOC under .NET 11 > Core .NET libraries.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
docs/core/compatibility/core-libraries/11/dateonly-timeonly-tryparse-argumentexception.md	New breaking change article describing the behavior change, rationale, mitigation, and affected APIs.
docs/core/compatibility/11.md	Adds the new breaking change entry to the .NET 11 index table.
docs/core/compatibility/toc.yml	Adds the new article to the .NET 11 TOC under Core .NET libraries.

---

You can also share your feedback on Copilot code review. Take the survey.

[tarekgh]

LGTM, Thanks!