Generate AsyncEnumerableDeprecated facade in runtime assembly (#2293)

Author: idg10

Ix.NET/Documentation/adr/0002-System-Linq-Async-In-Net10.md

@@ -36,20 +36,23 @@ A further complication is that some methods in `System.Interactive.Async` clash
 
 One more important point to consider is that although LINQ to `IAsyncEnumerable<T>` _mostly_ consists of extension methods, there are a few static methods. (E.g., `AsyncEnumerable.Range`, which the .NET library implements, and `AsyncEnumerable.Create`, which it does not.) With extension methods, the compiler does not have a problem with multiple identically-named types in different assemblies all defining extension methods as long as the individual methods do not conflict. However, non-extension methods are a problem. If `System.Linq.Async` were to continue to define a public `AsyncEnumerable` type, then calls to `AsyncEnumerable.Range` would fail to compile: even though there would only be a single `Range` method (supplied by the new `System.Linq.AsyncEnumerable`) this would fail to compile because `AsyncEnumerable` itself is an ambiguous class name. So it will be necessary for the public API of `System.Linq.Async` v7 not to define an `AsyncEnumerable` type. This places some limits on how far we can go with source-level compatibility. (Binary compatibility is not a problem because the runtime assemblies can continue to define this type.)
 
+Since that constraint requires us to define a new type to hold all the obsolete extension methods (which we'll be calling `AsyncEnumerableDeprecated`) this creates a new problem: the runtime API needs to continue to provide all these methods as members of `AsyncEnumerable` (to provide binary compatibility) but any code newly compiled against Ix.NET v7 that is continuing to use these deprecated method (and which is therefore tolerating or suppressing the deprecation warning) will now end up building code that expects these methods to be in the `AsyncEnumerableDeprecated` class. We therefore need to provide all these methods in the runtime assemblies _twice_: once for binary compatibility as members of `AsyncEnumerable` (a class we completely hide at build time) and again as members of `AsyncEnumerableDeprecated` (the class we add to provide source-level backwards compatibility for code using the deprecated methods, in a way that doesn't cause ambiguous type name errors).
+
 
 ## Decision
 
 The next Ix.NET release will:
 
 1. add a reference to `System.Linq.AsyncEnumerable` and `System.Interactive.Async` in `System.Linq.Async`
 2. remove from `System.Linq.Async`'s and `System.Interactive.Async`'s publicly visible API (ref assemblies) all `IAsyncEnumerable<T>` extension methods for which direct replacements exist (adding `MinByWithTiesAsync` and `MaxByWithTiesAsync` for the case where the new .NET runtime library methods actually have slightly different functionality)
-4. Rename `AsyncEnumerable` to `AsyncEnumerableDeprecated` in the public API (reference assemblies; the old name will be retained in runtime assemblies for binary compatibility) to avoid errors arising from there being two definitions of `AsyncEnumerable` in the same namespace
-5. add [Obsolete] attribute for members of `AsyncEnumerableDeprecated` for which `System.Linq.AsyncEnumerable` offers replacements that require code changes to use (e.g., `WhereAwait`, which is replaced by an overload of `Where`)
-6. the `AsyncEnumerable.ToEnumerable` method that was a bad idea and that should probably have never existed has been marked as `Obsolete` and will not be replaced; note that although `ToObservable` has issues that meant the .NET team decided not to replicate it, the main issue is that it embeds opinions, and not that there's anything fundamentally broken about it, so we do not include `ToObservable` in this category
-7. remaining methods of `AsyncEnumerable` (where `System.Linq.AsyncEnumerable` offers no equivalent) are removed from the publicly visible API of `System.Linq.Async`, with identical replacements being defined by `AsyncEnumerableEx` in `System.Interactive.Async`
-8. mark `IAsyncGrouping` as obsolete
-9. mark the public `IAsyncIListProvider` as obsolete, and define a non-public version for continued internal use in `System.Interactive.Linq`
-10. continue to provide the full `System.Linq.Async` API in the `lib` assemblies to provide binary compatibility
+3. Rename `AsyncEnumerable` to `AsyncEnumerableDeprecated` in the public API (reference assemblies; the old name will be retained in runtime assemblies for binary compatibility) to avoid errors arising from there being two definitions of `AsyncEnumerable` in the same namespace
+4. add [Obsolete] attribute for members of `AsyncEnumerableDeprecated` for which `System.Linq.AsyncEnumerable` offers replacements that require code changes to use (e.g., `WhereAwait`, which is replaced by an overload of `Where`)
+5. the `AsyncEnumerable.ToEnumerable` method that was a bad idea and that should probably have never existed has been marked as `Obsolete` and will not be replaced; note that although `ToObservable` has issues that meant the .NET team decided not to replicate it, the main issue is that it embeds opinions, and not that there's anything fundamentally broken about it, so we do not include `ToObservable` in this category
+6. remaining methods of `AsyncEnumerable` (where `System.Linq.AsyncEnumerable` offers no equivalent) are removed from the publicly visible API of `System.Linq.Async`, with identical replacements being defined by `AsyncEnumerableEx` in `System.Interactive.Async`
+7. mark `IAsyncGrouping` as obsolete
+8. mark the public `IAsyncIListProvider` as obsolete, and define a non-public version for continued internal use in `System.Interactive.Linq`
+9. continue to provide the full `System.Linq.Async` API in the `lib` assemblies to provide binary compatibility
+10. in the runtime `System.Linq.Async` assembly provide a facade that duplicates the legacy `AsyncEnumerable` methods on an `AsyncEnumerableDeprecated` type so that code that builds against `System.Linq.Async` v7, and which chooses to continue to use methods marked as `[Obsolete]`, will find those methods at runtime
 11. mark the `System.Linq.Async` NuGet package as obsolete, and recommend the use of `System.Linq.AsyncEnumerable` and/or `System.Interactive.Async` instead
 
 The main effect of this is that code that had been using the `System.Linq.Async` implementation of LINQ for `IAsyncEnumerable<T>` will, in most cases, now be using the .NET runtime library implementation if it is rebuilt against this new version of `System.Linq.Async`.

Ix.NET/Source/Playground/Program.cs

@@ -3,6 +3,7 @@
 // See the LICENSE file in the project root for more information. 
 
 #pragma warning disable IDE0051 // Remove unused private members - all used via reflection
+#pragma warning disable CS0618 // Type or member is obsolete - this has not been updated since the deprecation of System.Linq.Async due to .NET 10's System.Linq.AsyncEnumerable
 
 using System;
 using System.Collections.Generic;

Ix.NET/Source/System.Linq.Async.SourceGenerator/AsyncOverloadsGenerator.cs

@@ -1,4 +1,8 @@
-using System.Collections.Generic;
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT License.
+// See the LICENSE file in the project root for more information. 
+
+using System.Collections.Generic;
 using System.IO;
 using System.Text;
 using Microsoft.CodeAnalysis;
@@ -12,7 +16,7 @@ namespace System.Linq.Async.SourceGenerator
     [Generator]
     public sealed class AsyncOverloadsGenerator : ISourceGenerator
     {
-        private const string AttributeSource =
+        private const string GenerateAsyncOverloadAttributeSource =
             "using System;\n" +
             "using System.Diagnostics;\n" +
             "namespace System.Linq\n" +
@@ -21,25 +25,47 @@ public sealed class AsyncOverloadsGenerator : ISourceGenerator
             "    [Conditional(\"COMPILE_TIME_ONLY\")]\n" +
             "    internal sealed class GenerateAsyncOverloadAttribute : Attribute { }\n" +
             "}\n";
+        private const string DuplicateAsyncEnumerableAsAsyncEnumerableDeprecatedAttributeSource =
+            "using System;\n" +
+            "using System.Diagnostics;\n" +
+            "namespace System.Linq\n" +
+            "{\n" +
+            "    [AttributeUsage(AttributeTargets.Assembly)]\n" +
+            "    [Conditional(\"COMPILE_TIME_ONLY\")]\n" +
+            "    internal sealed class DuplicateAsyncEnumerableAsAsyncEnumerableDeprecatedAttribute : Attribute { }\n" +
+            "}\n";
 
         public void Initialize(GeneratorInitializationContext context)
         {
             context.RegisterForSyntaxNotifications(() => new SyntaxReceiver());
-            context.RegisterForPostInitialization(c => c.AddSource("GenerateAsyncOverloadAttribute", AttributeSource));
+            context.RegisterForPostInitialization(c =>
+            {
+                c.AddSource("GenerateAsyncOverloadAttribute", GenerateAsyncOverloadAttributeSource);
+                c.AddSource("DuplicateAsyncEnumerableAsAsyncEnumerableDeprecatedAttribute", DuplicateAsyncEnumerableAsAsyncEnumerableDeprecatedAttributeSource);
+            });
         }
 
         public void Execute(GeneratorExecutionContext context)
         {
             if (context.SyntaxReceiver is not SyntaxReceiver syntaxReceiver) return;
 
             var options = GetGenerationOptions(context);
-            var attributeSymbol = GetAsyncOverloadAttributeSymbol(context);
+            var asyncOverloadAttributeSymbol = GetAsyncOverloadAttributeSymbol(context);
             var methodsBySyntaxTree = GetMethodsGroupedBySyntaxTree(context, syntaxReceiver);
 
             foreach (var grouping in methodsBySyntaxTree.Where(g => g.Methods.Any()))
                 context.AddSource(
                     $"{Path.GetFileNameWithoutExtension(grouping.SyntaxTree.FilePath)}.AsyncOverloads",
-                    GenerateOverloads(grouping, options, context, attributeSymbol));
+                    GenerateOverloads(grouping, options, context, asyncOverloadAttributeSymbol));
+
+            var duplicateAsyncEnumerableAsAsyncEnumerableDeprecatedAttributeSymbol = GetDuplicateAsyncEnumerableAsAsyncEnumerableDeprecatedAttributeSymbol(context);
+            var dupBuilder = new DeprecatedDuplicateBuilder(
+                context,
+                options,
+                asyncOverloadAttributeSymbol,
+                duplicateAsyncEnumerableAsAsyncEnumerableDeprecatedAttributeSymbol,
+                syntaxReceiver);
+            dupBuilder.BuildDuplicatesIfRequired();
         }
 
         private static GenerationOptions GetGenerationOptions(GeneratorExecutionContext context)
@@ -95,7 +121,7 @@ private static string GenerateOverload(AsyncMethod method, GenerationOptions opt
                          select a))))
                 .Where(list => list.Attributes.Count > 0));
 
-            return MethodDeclaration(method.Syntax.ReturnType, GetMethodName(method.Symbol, options))
+            return MethodDeclaration(method.Syntax.ReturnType, GetMethodNameForGeneratedAsyncMethod(method.Symbol, options))
                 .WithAttributeLists(attributeListsWithGenerateAsyncOverloadRemoved)
                 .WithModifiers(TokenList(Token(SyntaxKind.PublicKeyword), Token(SyntaxKind.StaticKeyword)))
                 .WithTypeParameterList(method.Syntax.TypeParameterList)
@@ -117,8 +143,11 @@ private static string GenerateOverload(AsyncMethod method, GenerationOptions opt
         private static INamedTypeSymbol GetAsyncOverloadAttributeSymbol(GeneratorExecutionContext context)
             => context.Compilation.GetTypeByMetadataName("System.Linq.GenerateAsyncOverloadAttribute") ?? throw new InvalidOperationException();
 
+        private static INamedTypeSymbol GetDuplicateAsyncEnumerableAsAsyncEnumerableDeprecatedAttributeSymbol(GeneratorExecutionContext context)
+            => context.Compilation.GetTypeByMetadataName("System.Linq.DuplicateAsyncEnumerableAsAsyncEnumerableDeprecatedAttribute") ?? throw new InvalidOperationException();
+
         private static IEnumerable<AsyncMethodGrouping> GetMethodsGroupedBySyntaxTree(GeneratorExecutionContext context, SyntaxReceiver syntaxReceiver, INamedTypeSymbol attributeSymbol)
-            => from candidate in syntaxReceiver.Candidates
+            => from candidate in syntaxReceiver.CandidateMethods
                group candidate by candidate.SyntaxTree into grouping
                let model = context.Compilation.GetSemanticModel(grouping.Key)
                select new AsyncMethodGrouping(
@@ -128,7 +157,7 @@ from methodSyntax in grouping
                   where methodSymbol.GetAttributes().Any(a => SymbolEqualityComparer.Default.Equals(a.AttributeClass!, attributeSymbol))
                   select new AsyncMethod(methodSymbol, methodSyntax));
 
-        private static string GetMethodName(IMethodSymbol methodSymbol, GenerationOptions options)
+        internal static string GetMethodNameForGeneratedAsyncMethod(IMethodSymbol methodSymbol, GenerationOptions options)
         {
             var methodName = methodSymbol.Name.Replace("Core", "");
             return options.SupportFlatAsyncApi