System.Globalization.CompareOptions update

[daverayment]

Summary

• New remarks section describing the change in .NET 5 to use the ICU library, which changes the default sort order and affects the behaviour of comparing against ligature characters.
• Rewrote descriptions for each of the options, simplifying language and improving consistency.
• New code example which details how each of the CompareOptions enum values affect string comparisons, for all four supported languages.
• Updated StringSort code example, which now uses more modern and consistent .NET conventions, and includes a note about changes brought about in .NET 5 (where StringSort and None are now equivalent by default).
• Added StringSort F# example.

Additional Globalization documentation update in main dotnet/docs repo PR: 41661

Fixes #41052

[daverayment]

@dotnet-policy-service agree

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-globalization

[tarekgh]

@daverayment Thanks for submitting the PR! Would you be able to fix the errors here: https://github.com/dotnet/dotnet-api-docs/actions/runs/9810025035/job/27168649470?pr=10087? I don't believe your changes caused them, but since we're already modifying the code, it would be great to address them.

Also, did you run the updated samples to ensure everything works correctly?

[tarekgh]

Modulo the minor comment and fixing the CI failures, LGTM!

[tarekgh]

@daverayment would you have a chance to address the minor remaining feedback so we can proceed merging this one?

[daverayment]

@tarekgh Thank you for the review.

I'm sorry, I don't have time to revisit this at the moment. I don't know how to add the parent project, so perhaps you could help?

[tarekgh]

@gewarren do you know who can help guide how we can fix the issues with this PR?

• System.Globalization.CompareOptions update #10087 (comment)
• https://github.com/dotnet/dotnet-api-docs/actions/runs/14208294553/job/39810584209?pr=10087

[tarekgh]

CC @BillWagner if can help too.

[learn-build-service-prod]

Learn Build status updates of commit 448db5d:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
xml/System.Globalization/CompareOptions.xml	⚠️Warning	View	Details
snippets/cpp/VS_Snippets_CLR_System/system.Globalization.CompareOptions.StringSort/CPP/compareoptions_stringsort.cpp	✅Succeeded	n/a (file deleted or renamed)
snippets/csharp/System.Globalization/CompareOptions/Overview/compareoptions_stringsort.cs	✅Succeeded	View
snippets/csharp/System.Globalization/CompareOptions/Overview/compareoptions_values.cs	✅Succeeded	View
snippets/csharp/System.Globalization/CompareOptions/Overview/Program.cs	✅Succeeded
snippets/csharp/System.Globalization/CompareOptions/Overview/Project.csproj	✅Succeeded
snippets/fsharp/System.Globalization/compareoptions_stringsort.fs	✅Succeeded	View
snippets/fsharp/System.Globalization/compareoptions_values.fs	✅Succeeded	View
snippets/fsharp/System.Globalization/Project.fsproj	✅Succeeded
snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CompareOptions.StringSort/VB/compareoptions_stringsort.vb	✅Succeeded	View
snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CompareOptions.StringSort/VB/Project.vbproj	✅Succeeded
snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CompareOptions.Values/VB/compareoptions_values.vb	✅Succeeded	View
snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CompareOptions.Values/VB/Project.vbproj	✅Succeeded

xml/System.Globalization/CompareOptions.xml

• Line 0, Column 0: [Warning: invalid-code] It looks like your code snippet was not rendered. Try range instead.
• Line 0, Column 0: [Warning: invalid-code] It looks like your code snippet was not rendered. Try range instead.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

For any questions, please:

• Try searching the learn.microsoft.com contributor guides
• Post your question in the Learn support channel