issue 43952

Author: Cam Soper

docs/core/compatibility/10.0.md

@@ -21,6 +21,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 |----------------------------------------------------------------------------------------------------------------------------|---------------------|--------------------|
 | [API obsoletions with non-default diagnostic IDs](core-libraries/10.0/obsolete-apis.md)                                    | Source incompatible | Preview 1          |
 | [ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change](core-libraries/10.0/activity-sampling.md) | Behavioral change   | Preview 1          |
+| [C# 14 overload resolution with span parameters](csharp-overload-resolution.md)                                            | Behavioral change   | Preview 1          |
 
 ## Windows Forms
 

docs/core/compatibility/core-libraries/10.0/csharp-overload-resolution.md

@@ -0,0 +1,50 @@
+---
+title: "Breaking change: C# 14 overload resolution with span parameters"
+description: Learn about the .NET 10 breaking change in core .NET libraries where overloads with span parameters are applicable in more scenarios.
+ms.date: 01/30/2025
+---
+# C# 14 overload resolution with span parameters
+
+C# 14 introduces new [built-in span conversions and type inference rules](https://github.com/dotnet/csharplang/issues/7905) making overloads with span parameters applicable in more scenarios.
+
+## Previous behavior
+
+In C# 13 and earlier, an extension method taking a `ReadOnlySpan<T>` or `Span<T>` receiver is not applicable to a value of type `T[]`. Therefore, only non-span extension methods like the ones from the `System.Linq.Enumerable` class are usually bound inside Expression lambdas.
+
+## New behavior
+
+In C# 14 and later, methods with `ReadOnlySpan<T>` or `Span<T>` parameters can participate in type inference or be used as extension methods in more scenarios. This makes span-based methods like the ones from the `System.MemoryExtensions` class bind in more scenarios, including inside Expression lambdas where they will cause runtime exceptions when compiled with interpretation.
+
+## Version introduced
+
+.NET 10 Preview 1
+
+## Type of breaking change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+The C# language feature allows simplified API design and usage (e.g., one ReadOnlySpan extension method can apply to both spans and arrays).
+
+## Recommended action
+
+If you need to continue using Expression interpretation, you should make sure the non-span overloads are bound, e.g., by casting arguments to the exact types the method signature takes or calling the extension methods as explicit static invocations:
+
+```cs
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Linq.Expressions;
+
+M((array, num) => array.Contains(num)); // fails, binds to MemoryExtensions.Contains
+M((array, num) => ((IEnumerable<int>)array).Contains(num)); // ok, binds to Enumerable.Contains
+M((array, num) => array.AsEnumerable().Contains(num)); // ok, binds to Enumerable.Contains
+M((array, num) => Enumerable.Contains(array, num)); // ok, binds to Enumerable.Contains
+
+void M(Expression<Func<int[], int, bool>> e) => e.Compile(preferInterpretation: true);
+```
+
+## Affected APIs
+
+- <xref:System.Linq.Expressions.Expression`1.Compile*?displayProperty=fullName>

docs/core/compatibility/toc.yml

@@ -14,6 +14,8 @@ items:
                 href: core-libraries/10.0/obsolete-apis.md
               - name: ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change
                 href: core-libraries/10.0/activity-sampling.md
+              - name: C# 14 overload resolution with span parameters
+                href: csharp-overload-resolution.md
           - name: Windows Forms
             items:
               - name: TreeView checkbox image truncation
@@ -1320,6 +1322,8 @@ items:
                 href: core-libraries/10.0/obsolete-apis.md
               - name: ActivitySource.CreateActivity and ActivitySource.StartActivity behavior change
                 href: core-libraries/10.0/activity-sampling.md
+              - name: C# 14 overload resolution with span parameters
+                href: csharp-overload-resolution.md
           - name: .NET 9
             items:
               - name: Adding a ZipArchiveEntry sets header general-purpose bit flags