Add CA1876 analyzer to detect misuse of AsParallel() in foreach loops (#51287)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: stephentoub <[email protected]>

Author: Copilot

src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers.md

@@ -1908,6 +1908,18 @@ In many situations, logging is disabled or set to a log level that results in an
 |CodeFix|True|
 ---
 
+## [CA1876](https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/ca1876): Do not use 'AsParallel' in 'foreach'
+
+Using 'AsParallel()' directly in a 'foreach' loop has no effect. The 'foreach' statement iterates serially through the collection regardless. To parallelize LINQ operations, call 'AsParallel()' earlier in the query chain before other LINQ operators. To parallelize the loop itself, use 'Parallel.ForEach' instead.
+
+|Item|Value|
+|-|-|
+|Category|Performance|
+|Enabled|True|
+|Severity|Info|
+|CodeFix|False|
+---
+
 ## [CA2000](https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/ca2000): Dispose objects before losing scope
 
 If a disposable object is not explicitly disposed before all references to it are out of scope, the object will be disposed at some indeterminate time when the garbage collector runs the finalizer of the object. Because an exceptional event might occur that will prevent the finalizer of the object from running, the object should be explicitly disposed instead.

src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers.sarif

@@ -3507,6 +3507,26 @@
             ]
           }
         },
+        "CA1876": {
+          "id": "CA1876",
+          "shortDescription": "Do not use 'AsParallel' in 'foreach'",
+          "fullDescription": "Using 'AsParallel()' directly in a 'foreach' loop has no effect. The 'foreach' statement iterates serially through the collection regardless. To parallelize LINQ operations, call 'AsParallel()' earlier in the query chain before other LINQ operators. To parallelize the loop itself, use 'Parallel.ForEach' instead.",
+          "defaultLevel": "note",
+          "helpUri": "https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/ca1876",
+          "properties": {
+            "category": "Performance",
+            "isEnabledByDefault": true,
+            "typeName": "DoNotUseAsParallelInForEachLoopAnalyzer",
+            "languages": [
+              "C#",
+              "Visual Basic"
+            ],
+            "tags": [
+              "Telemetry",
+              "EnabledRuleInAggressiveMode"
+            ]
+          }
+        },
         "CA2000": {
           "id": "CA2000",
           "shortDescription": "Dispose objects before losing scope",

src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/AnalyzerReleases.Unshipped.md

@@ -7,6 +7,7 @@ Rule ID | Category | Severity | Notes
 CA1873 | Performance | Info | AvoidPotentiallyExpensiveCallWhenLoggingAnalyzer, [Documentation](https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/ca1873)
 CA1874 | Performance | Info | UseRegexMembers, [Documentation](https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/ca1874)
 CA1875 | Performance | Info | UseRegexMembers, [Documentation](https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/ca1875)
+CA1876 | Performance | Info | DoNotUseAsParallelInForEachLoopAnalyzer, [Documentation](https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/ca1876)
 CA2023 | Reliability | Warning | LoggerMessageDefineAnalyzer, [Documentation](https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/ca2023)
 CA2024 | Reliability | Warning | DoNotUseEndOfStreamInAsyncMethods, [Documentation](https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/ca2024)
 CA2025 | Reliability | Disabled | DoNotPassDisposablesIntoUnawaitedTasksAnalyzer, [Documentation](https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/ca2025)

src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/MicrosoftNetCoreAnalyzersResources.resx

@@ -195,6 +195,15 @@
   <data name="DoNotUseCountWhenAnyCanBeUsedTitle" xml:space="preserve">
     <value>Do not use Count() or LongCount() when Any() can be used</value>
   </data>
+  <data name="DoNotUseAsParallelInForEachLoopTitle" xml:space="preserve">
+    <value>Do not use 'AsParallel' in 'foreach'</value>
+  </data>
+  <data name="DoNotUseAsParallelInForEachLoopMessage" xml:space="preserve">
+    <value>Using 'AsParallel()' directly in a 'foreach' loop has no effect and the loop is not parallelized</value>
+  </data>
+  <data name="DoNotUseAsParallelInForEachLoopDescription" xml:space="preserve">
+    <value>Using 'AsParallel()' directly in a 'foreach' loop has no effect. The 'foreach' statement iterates serially through the collection regardless. To parallelize LINQ operations, call 'AsParallel()' earlier in the query chain before other LINQ operators. To parallelize the loop itself, use 'Parallel.ForEach' instead.</value>
+  </data>
   <data name="PreferConvertToHexStringOverBitConverterTitle" xml:space="preserve">
     <value>Prefer 'Convert.ToHexString' and 'Convert.ToHexStringLower' over call chains based on 'BitConverter.ToString'</value>
   </data>

src/Microsoft.CodeAnalysis.NetAnalyzers/src/Microsoft.CodeAnalysis.NetAnalyzers/Microsoft.NetCore.Analyzers/Performance/DoNotUseAsParallelInForEachLoop.cs

@@ -0,0 +1,100 @@
+// Copyright (c) Microsoft.  All Rights Reserved.  Licensed under the MIT license.  See License.txt in the project root for license information.
+
+using System.Collections.Immutable;
+using System.Linq;
+using Analyzer.Utilities;
+using Analyzer.Utilities.Extensions;
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.Diagnostics;
+using Microsoft.CodeAnalysis.Operations;
+
+namespace Microsoft.NetCore.Analyzers.Performance
+{
+    using static MicrosoftNetCoreAnalyzersResources;
+
+    /// <summary>
+    /// CA1876: <inheritdoc cref="DoNotUseAsParallelInForEachLoopTitle"/>
+    /// Analyzer to detect misuse of AsParallel() when used directly in a foreach loop.
+    /// </summary>
+    [DiagnosticAnalyzer(LanguageNames.CSharp, LanguageNames.VisualBasic)]
+    public sealed class DoNotUseAsParallelInForEachLoopAnalyzer : DiagnosticAnalyzer
+    {
+        internal const string RuleId = "CA1876";
+
+        internal static readonly DiagnosticDescriptor Rule = DiagnosticDescriptorHelper.Create(
+            RuleId,
+            CreateLocalizableResourceString(nameof(DoNotUseAsParallelInForEachLoopTitle)),
+            CreateLocalizableResourceString(nameof(DoNotUseAsParallelInForEachLoopMessage)),
+            DiagnosticCategory.Performance,
+            RuleLevel.IdeSuggestion,
+            description: CreateLocalizableResourceString(nameof(DoNotUseAsParallelInForEachLoopDescription)),
+            isPortedFxCopRule: false,
+            isDataflowRule: false);
+
+        public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics { get; } = ImmutableArray.Create(Rule);
+
+        public override void Initialize(AnalysisContext context)
+        {
+            context.EnableConcurrentExecution();
+            context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None);
+            context.RegisterCompilationStartAction(OnCompilationStart);
+        }
+
+        private static void OnCompilationStart(CompilationStartAnalysisContext context)
+        {
+            var typeProvider = WellKnownTypeProvider.GetOrCreate(context.Compilation);
+
+            // Get the ParallelEnumerable type
+            var parallelEnumerableType = typeProvider.GetOrCreateTypeByMetadataName(WellKnownTypeNames.SystemLinqParallelEnumerable);
+
+            if (parallelEnumerableType == null)
+            {
+                return;
+            }
+
+            // Get all AsParallel methods - use SymbolEqualityComparer for proper comparison
+            var asParallelMethods = ImmutableHashSet.CreateRange<IMethodSymbol>(
+                SymbolEqualityComparer.Default,
+                parallelEnumerableType.GetMembers("AsParallel").OfType<IMethodSymbol>());
+
+            if (asParallelMethods.IsEmpty)
+            {
+                return;
+            }
+
+            context.RegisterOperationAction(ctx => AnalyzeForEachLoop(ctx, asParallelMethods), OperationKind.Loop);
+        }
+
+        private static void AnalyzeForEachLoop(OperationAnalysisContext context, ImmutableHashSet<IMethodSymbol> asParallelMethods)
+        {
+            if (context.Operation is not IForEachLoopOperation forEachLoop)
+            {
+                return;
+            }
+
+            // Check if the collection is a direct result of AsParallel()
+            var collection = forEachLoop.Collection;
+
+            // Walk up conversions to find the actual operation
+            while (collection is IConversionOperation conversion)
+            {
+                collection = conversion.Operand;
+            }
+
+            // Check if this is an invocation of AsParallel
+            if (collection is IInvocationOperation invocation)
+            {
+                var targetMethod = invocation.TargetMethod;
+
+                // For extension methods, we need to check the ReducedFrom or the original method
+                var methodToCheck = targetMethod.ReducedFrom ?? targetMethod;
+
+                if (asParallelMethods.Contains(methodToCheck.OriginalDefinition))
+                {
+                    // Report diagnostic on the AsParallel call
+                    context.ReportDiagnostic(invocation.CreateDiagnostic(Rule));
+                }
+            }
+        }
+    }
+}