diff --git a/docs/core/compatibility/core-libraries/10.0/obsolete-apis.md b/docs/core/compatibility/core-libraries/10.0/obsolete-apis.md index 391fcf47ee01c..797c61c39f824 100644 --- a/docs/core/compatibility/core-libraries/10.0/obsolete-apis.md +++ b/docs/core/compatibility/core-libraries/10.0/obsolete-apis.md @@ -2,7 +2,7 @@ title: "Breaking change: .NET 10 obsoletions with custom IDs" titleSuffix: "" description: Learn about the APIs that have been marked as obsolete in .NET 10 with a custom diagnostic ID. -ms.date: 01/14/2025 +ms.date: 03/28/2025 ai-usage: ai-assisted --- # API obsoletions with non-default diagnostic IDs (.NET 10) @@ -20,6 +20,7 @@ The following table lists the custom diagnostic IDs and their corresponding warn | [SYSLIB0058](../../../../fundamentals/syslib-diagnostics/syslib0058.md) | The `KeyExchangeAlgorithm`, `KeyExchangeStrength`, `CipherAlgorithm`, `CipherAlgorithmStrength`, `HashAlgorithm`, and `HashStrength` properties of are obsolete. Use instead. | Warning | | [SYSLIB0059](../../../../fundamentals/syslib-diagnostics/syslib0059.md) | callbacks aren't run before the process exits. Use instead. | Warning | | [SYSLIB0060](../../../../fundamentals/syslib-diagnostics/syslib0060.md) | constructors are obsolete. Use instead. | Warning | +| [SYSLIB0061](../../../../fundamentals/syslib-diagnostics/syslib0061.md) | and taking an `IComparer` are obsolete. Use the new ones that take an `IComparer`. | Warning | ## Version introduced @@ -58,6 +59,11 @@ These obsoletions can affect [source compatibility](../../categories.md#source-c - - +### SYSLIB0061 + +- +- + ## See also - [API obsoletions with non-default diagnostic IDs (.NET 9)](../9.0/obsolete-apis-with-custom-diagnostics.md) diff --git a/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md b/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md index fac18796d6033..43e95dab5bb67 100644 --- a/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md +++ b/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md @@ -20,7 +20,7 @@ If you encounter build warnings or errors due to usage of an obsolete API, follo The following table provides an index to the `SYSLIB0XXX` obsoletions in .NET 5+. | Diagnostic ID | Warning or error | Description | -| - | - | +|---------------|------------------|-------------| | [SYSLIB0001](syslib0001.md) | Warning | The UTF-7 encoding is insecure and should not be used. Consider using UTF-8 instead. | | [SYSLIB0002](syslib0002.md) | Error | is not honored by the runtime and must not be used. | | [SYSLIB0003](syslib0003.md) | Warning | Code access security (CAS) is not supported or honored by the runtime. | @@ -78,9 +78,10 @@ The following table provides an index to the `SYSLIB0XXX` obsoletions in .NET 5+ | [SYSLIB0055](syslib0055.md) | Warning | `AdvSimd.ShiftRightLogicalRoundedNarrowingSaturate*` methods with signed parameters are obsolete. Use the unsigned overloads instead. | | [SYSLIB0056](syslib0056.md) | Warning | `Assembly.LoadFrom` with a custom `AssemblyHashAlgorithm` is obsolete. Use overloads without an `AssemblyHashAlgorithm`. | | [SYSLIB0057](syslib0057.md) | Warning | `X509Certificate2` and `X509Certificate` constructors for binary and file content are obsolete. | -| SYSLIB0058 | Warning | The `KeyExchangeAlgorithm`, `KeyExchangeStrength`, `CipherAlgorithm`, `CipherAlgorithmStrength`, `HashAlgorithm`, and `HashStrength` properties of are obsolete. Use instead. | +| [SYSLIB0058](syslib0058.md) | Warning | The `KeyExchangeAlgorithm`, `KeyExchangeStrength`, `CipherAlgorithm`, `CipherAlgorithmStrength`, `HashAlgorithm`, and `HashStrength` properties of are obsolete. Use instead. | | [SYSLIB0059](syslib0059.md) | Warning | callbacks aren't run before the process exits. Use instead. | | [SYSLIB0060](syslib0060.md) | Warning | Constructors on are obsolete. Use instead. | +| [SYSLIB0061](syslib0061.md) | Warning | The `Queryable` and taking an `IComparer` are obsolete. Use the new ones that take an `IComparer`. | ## Suppress warnings diff --git a/docs/fundamentals/syslib-diagnostics/syslib0061.md b/docs/fundamentals/syslib-diagnostics/syslib0061.md new file mode 100644 index 0000000000000..6d35bf5e93396 --- /dev/null +++ b/docs/fundamentals/syslib-diagnostics/syslib0061.md @@ -0,0 +1,77 @@ +--- +title: SYSLIB0061 warning - System.Linq.Queryable.MaxBy and System.Linq.Queryable.MinBy accepting an IComparer\ are obsolete. +description: Learn about the obsoletion of some MaxBy and MinBy extension methods. Use of these extension methods generates compile-time warning SYSLIB0061. +ms.date: 03/31/2025 +f1_keywords: + - SYSLIB0061 +--- +# SYSLIB0061: System.Linq.Queryable.MaxBy and System.Linq.Queryable.MinBy taking an IComparer\ are obsolete. + +Starting in .NET 10, the two extension methods and that accept an `IComparer` are obsolete. Please use the newly added overloads that accept an `IComparer` instead. + +Calling these old extension methods in code generates warning `SYSLIB0061` at compile time and typically generates a at runtime. + +## Reason for obsoletion + +The original `MaxBy` and `MinBy` accepting an `IComparer? comparer` expression parameter were incorrectly implemented using the generic type `TSource` for the `IComparer? comparer` type parameter. This is incorrect because the values passed to the method are selected by the `Expression> keySelector` expression parameter, thus the extracted value is of generic type `TKey`. + +### Note + +This would previously work only if `TSource` and `TKey` were actually the same constructed type. If the types were distinct then a runtime _: Index was outside the bounds of the array._ would be thrown because the needed extension method for `IQueryable source` could not be found (for example in ). + +## Workaround + +Use the newly added `MaxBy` or `MinBy` method that accepts an `IComparer? comparer` parameter. These will not throw an exception. + +For example: + +```csharp +// This worked correctly since TKey and TSource are both int. +Enumerable.Range(1, 10) + .AsQueryable() + .MaxBy(key => (0 - key), Comparer.Default); + +// This would throw since TKey is string but TSource is int +// and will trigger the obsoletion warning now and would +// throw an exeception at runtime. +Enumerable.Range(1, 10) + .AsQueryable() + .MaxBy(key => key.ToString(), Comparer.Default); + +// This previously would not compile before to the addition of +// the new methods since TKey is string and TSource is int. +// It will now compile and execute correctly. +Enumerable.Range(1, 10) + .AsQueryable() + .MaxBy(key => key.ToString(), Comparer.Default); +``` + +## Suppress a warning + +If you must use the obsolete API, you can suppress the warning in code or in your project file. + +To suppress only a single violation, add preprocessor directives to your source file to disable and then re-enable the warning. + +```csharp +// Disable the warning. +#pragma warning disable SYSLIB0061 + +// Code that uses obsolete API. +// ... + +// Re-enable the warning. +#pragma warning restore SYSLIB0061 +``` + +To suppress all the `SYSLIB0061` warnings in your project, add a `` property to your project file. + +```xml + + + ... + $(NoWarn);SYSLIB0061 + + +``` + +For more information, see [Suppress warnings](obsoletions-overview.md#suppress-warnings). diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index 1733d82b6267b..3a5d71dff6e37 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -1837,6 +1837,8 @@ items: href: ../../fundamentals/syslib-diagnostics/syslib0059.md - name: SYSLIB0060 href: ../../fundamentals/syslib-diagnostics/syslib0060.md + - name: SYSLIB0061 + href: ../../fundamentals/syslib-diagnostics/syslib0061.md - name: Experimental features items: - name: Overview