Clarify XmlConvert.ToDateTimeOffset format handling

[steveisok]

Summary

• document that the custom-format XmlConvert.ToDateTimeOffset overloads call DateTimeOffset.ParseExact with invariant formatting and leading/trailing whitespace enabled
• describe format and formats as .NET standard or custom date and time format strings rather than XML Schema patterns
• clarify that z, zz, and zzz require signed numeric UTC offsets, while K supports the XML UTC designator Z
• align FormatException documentation with exact format matching

Validation

• xmllint --noout xml/System.Xml/XmlConvert.xml
• git diff --check
• code-review pass (no findings)

Fixes dotnet/runtime#125579

---

Internal previews

File	Preview link
xml/Microsoft.Extensions.DependencyInjection/ValidationLocalizationServiceCollectionExtensions.xml	Preview published page
xml/Microsoft.Extensions.Validation.Localization/ValidationLocalizationOptions.xml	Preview published page
xml/System.Xml/XmlConvert.xml	Preview published page

[Copilot]

Pull request overview

This PR updates the ECMAXML documentation for System.Xml.XmlConvert.ToDateTimeOffset to more precisely describe how the custom-format overloads interpret format/formats, including exact-match parsing behavior, invariant formatting, and timezone designator handling.

Changes:

• Reframed format/formats as .NET standard/custom date and time format strings (not XML Schema dateTime patterns).
• Documented that the overloads behave like DateTimeOffset.ParseExact using invariant formatting and allowing leading/trailing whitespace.
• Clarified that z/zz/zzz require signed numeric offsets and that K supports the XML Z UTC designator.

Show a summary per file

File	Description
xml/System.Xml/XmlConvert.xml	Clarifies ToDateTimeOffset overload docs for ParseExact equivalence, accepted format strings, UTC offset specifiers, and FormatException conditions.

Review details

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Suppressed comments (3)

xml/System.Xml/XmlConvert.xml:1168

• Use “whitespace” consistently (one word) in exception text, to match other parts of this file.

          <paramref name="format" /> is invalid, or <paramref name="s" /> doesn't exactly match <paramref name="format" /> under the invariant culture rules, except for leading or trailing white space.</exception>

xml/System.Xml/XmlConvert.xml:1220

• Use “whitespace” consistently (one word) to match other wording in this file.

 This overload is equivalent to calling <xref:System.DateTimeOffset.ParseExact(System.String,System.String%5B%5D,System.IFormatProvider,System.Globalization.DateTimeStyles)?displayProperty=nameWithType> with <xref:System.Globalization.DateTimeFormatInfo.InvariantInfo?displayProperty=nameWithType> and the <xref:System.Globalization.DateTimeStyles.AllowLeadingWhite> and <xref:System.Globalization.DateTimeStyles.AllowTrailingWhite> flags. Leading and trailing white space is ignored, but `s` must otherwise exactly match one of the strings in `formats`. The `formats` parameter uses .NET [standard date and time format strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) or [custom date and time format strings](/dotnet/standard/base-types/custom-date-and-time-format-strings), not XML Schema dateTime patterns.

xml/System.Xml/XmlConvert.xml:1252

• Use “whitespace” consistently (one word) in exception text, to match other parts of this file.

        <exception cref="T:System.FormatException">An element of <paramref name="formats" /> is invalid, or <paramref name="s" /> doesn't exactly match any element of <paramref name="formats" /> under the invariant culture rules, except for leading or trailing white space.</exception>

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Lite