Add analyzer and code fix to recommend against IHeaderDictionary.Add

src/Analyzers/Analyzers/test/Microsoft.AspNetCore.Analyzers.Test.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <TargetFramework>$(DefaultNetCoreTargetFramework)</TargetFramework>
@@ -8,7 +8,7 @@
 
   <ItemGroup>
     <ProjectReference Include="$(RepoRoot)src\Analyzers\Analyzers\src\Microsoft.AspNetCore.Analyzers.csproj" />
-
+    
     <Reference Include="Microsoft.CodeAnalysis.CSharp.Analyzer.Testing.XUnit" />
     <Reference Include="Microsoft.CodeAnalysis.CSharp.Workspaces" />
     <Reference Include="Microsoft.Extensions.DependencyModel" />

src/Framework/AspNetCoreAnalyzers/src/Analyzers/DiagnosticDescriptors.cs

@@ -151,4 +151,13 @@ internal static class DiagnosticDescriptors
         DiagnosticSeverity.Info,
         isEnabledByDefault: true,
         helpLinkUri: "https://aka.ms/aspnet/analyzers");
+
+    internal static readonly DiagnosticDescriptor DoNotUseIHeaderDictionaryAdd = new(
+        "ASP0019",
+        new LocalizableResourceString(nameof(Resources.Analyzer_HeaderDictionaryAdd_Title), Resources.ResourceManager, typeof(Resources)),
+        new LocalizableResourceString(nameof(Resources.Analyzer_HeaderDictionaryAdd_Message), Resources.ResourceManager, typeof(Resources)),
+        "Usage",
+        DiagnosticSeverity.Warning,
+        isEnabledByDefault: true,
+        helpLinkUri: "https://aka.ms/aspnet/analyzers");
 }

src/Framework/AspNetCoreAnalyzers/src/Analyzers/Http/HeaderDictionaryAddAnalyzer.cs

@@ -0,0 +1,96 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Collections.Immutable;
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.Diagnostics;
+using Microsoft.CodeAnalysis.Operations;
+
+namespace Microsoft.AspNetCore.Analyzers.Http;
+
+[DiagnosticAnalyzer(LanguageNames.CSharp)]
+public partial class HeaderDictionaryAddAnalyzer : DiagnosticAnalyzer
+{
+    public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics => ImmutableArray.Create(DiagnosticDescriptors.DoNotUseIHeaderDictionaryAdd);
+
+    public override void Initialize(AnalysisContext context)
+    {
+        context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None);
+        context.EnableConcurrentExecution();
+        context.RegisterOperationAction(context =>
+        {
+            var invocation = (IInvocationOperation)context.Operation;
+
+            if (invocation.Instance?.Type is INamedTypeSymbol type &&
+                IsIHeadersDictionaryType(type))
+            {
+                if (invocation.TargetMethod.Parameters.Length == 2 &&
+                    IsAddMethod(invocation.TargetMethod))
+                {
+                    AddDiagnosticWarning(context, invocation.Syntax.GetLocation());
+                }
+            }
+        }, OperationKind.Invocation);
+    }
+
+    private static bool IsIHeadersDictionaryType(INamedTypeSymbol type)
+    {
+        // Only IHeaderDictionary is valid. Types like HeaderDictionary, which implement IHeaderDictionary,
+        // can't access header properties unless cast as IHeaderDictionary.
+        return type is
+        {
+            Name: "IHeaderDictionary",
+            ContainingNamespace:
+            {
+                Name: "Http",
+                ContainingNamespace:
+                {
+                    Name: "AspNetCore",
+                    ContainingNamespace:
+                    {
+                        Name: "Microsoft",
+                        ContainingNamespace:
+                        {
+                            IsGlobalNamespace: true
+                        }
+                    }
+                }
+            }
+        };
+    }
+
+    private static bool IsAddMethod(IMethodSymbol method)
+    {
+        return method is
+        {
+            Name: "Add",
+            ContainingType:
+            {
+                Name: "IDictionary",
+                ContainingNamespace:
+                {
+                    Name: "Generic",
+                    ContainingNamespace:
+                    {
+                        Name: "Collections",
+                        ContainingNamespace:
+                        {
+                            Name: "System",
+                            ContainingNamespace:
+                            {
+                                IsGlobalNamespace: true
+                            }
+                        }
+                    }
+                }
+            }
+        };
+    }
+
+    private static void AddDiagnosticWarning(OperationAnalysisContext context, Location location)
+    {
+        context.ReportDiagnostic(Diagnostic.Create(
+            DiagnosticDescriptors.DoNotUseIHeaderDictionaryAdd,
+            location));
+    }
+}

src/Framework/AspNetCoreAnalyzers/src/Analyzers/Resources.resx

@@ -201,4 +201,10 @@
   <data name="Analyzer_UnusedParameter_Title" xml:space="preserve">
     <value>Unused route parameter</value>
   </data>
+  <data name="Analyzer_HeaderDictionaryAdd_Message" xml:space="preserve">
+    <value>Suggest using IHeaderDictionary.Append or the indexer instead of Add</value>
+  </data>
+  <data name="Analyzer_HeaderDictionaryAdd_Title" xml:space="preserve">
+    <value>Suggest using IHeaderDictionary.Append or the indexer</value>
+  </data>
 </root>

src/Framework/AspNetCoreAnalyzers/src/CodeFixes/Http/HeaderDictionaryAddFixer.cs

@@ -0,0 +1,150 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Collections.Immutable;
+using System.Composition;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.CodeActions;
+using Microsoft.CodeAnalysis.CodeFixes;
+using Microsoft.CodeAnalysis.CSharp;
+using Microsoft.CodeAnalysis.CSharp.Syntax;
+
+namespace Microsoft.AspNetCore.Analyzers.Http.Fixers;
+
+[ExportCodeFixProvider(LanguageNames.CSharp), Shared]
+public class HeaderDictionaryAddFixer : CodeFixProvider
+{
+    public override ImmutableArray<string> FixableDiagnosticIds { get; } = ImmutableArray.Create(DiagnosticDescriptors.DoNotUseIHeaderDictionaryAdd.Id);
+
+    public sealed override FixAllProvider GetFixAllProvider() => WellKnownFixAllProviders.BatchFixer;
+
+    public sealed override Task RegisterCodeFixesAsync(CodeFixContext context)
+    {
+        foreach (var diagnostic in context.Diagnostics)
+        {
+            var appendTitle = "Use IHeaderDictionary.Append";
+            context.RegisterCodeFix(
+                CodeAction.Create(appendTitle,
+                    cancellationToken => ReplaceAddWithAppendAsync(diagnostic, context.Document, cancellationToken),
+                    equivalenceKey: appendTitle),
+                diagnostic);
+
+            var indexerTitle = "Use the indexer";
+            context.RegisterCodeFix(
+                CodeAction.Create(indexerTitle,
+                    cancellationToken => ReplaceAddWithIndexerAsync(diagnostic, context.Document, cancellationToken),
+                    equivalenceKey: indexerTitle),
+                diagnostic);
+        }
+
+        return Task.CompletedTask;
+    }
+
+    private static async Task<Document> ReplaceAddWithAppendAsync(Diagnostic diagnostic, Document document, CancellationToken cancellationToken)
+    {
+        var root = await document.GetSyntaxRootAsync(cancellationToken).ConfigureAwait(false);
+        if (root is not CompilationUnitSyntax compilationUnitSyntax)
+        {
+            return document;
+        }
+
+        var invocation = compilationUnitSyntax.FindNode(diagnostic.Location.SourceSpan);
+
+        if (invocation is InvocationExpressionSyntax { Expression: MemberAccessExpressionSyntax { Name.Identifier: { } identifierToken } })
+        {
+            compilationUnitSyntax = compilationUnitSyntax.ReplaceToken(identifierToken, SyntaxFactory.Identifier("Append"));
+
+            // IHeaderDictionary.Append is defined as an extension method on Microsoft.AspNetCore.Http.HeaderDictionaryExtensions.
+            // We'll need to add the required using directive, when not already present.
+            compilationUnitSyntax = AddRequiredUsingDirectiveForAppend(compilationUnitSyntax);
+
+            return document.WithSyntaxRoot(compilationUnitSyntax);
+        }
+
+        return document;
+    }
+
+    private static CompilationUnitSyntax AddRequiredUsingDirectiveForAppend(CompilationUnitSyntax compilationUnitSyntax)
+    {
+        var usingDirectives = compilationUnitSyntax.Usings;
+
+        var includesRequiredUsingDirective = false;
+        var insertionIndex = 0;
+
+        for (var i = 0; i < usingDirectives.Count; i++)
+        {
+            var namespaceName = usingDirectives[i].Name.ToString();
+
+            // Always insert the new using directive after any 'System' using directives.
+            if (namespaceName.StartsWith("System", StringComparison.Ordinal))
+            {
+                insertionIndex = i + 1;
+                continue;
+            }
+
+            var result = string.Compare("Microsoft.AspNetCore.Http", namespaceName, StringComparison.Ordinal);
+
+            if (result == 0)
+            {
+                includesRequiredUsingDirective = true;
+                break;
+            }
+
+            if (result < 0)
+            {
+                insertionIndex = i;
+                break;
+            }
+        }
+
+        if (includesRequiredUsingDirective)
+        {
+            return compilationUnitSyntax;
+        }
+
+        var requiredUsingDirective =
+            SyntaxFactory.UsingDirective(
+                SyntaxFactory.QualifiedName(
+                    SyntaxFactory.QualifiedName(
+                        SyntaxFactory.IdentifierName("Microsoft"),
+                        SyntaxFactory.IdentifierName("AspNetCore")),
+                    SyntaxFactory.IdentifierName("Http")));
+
+        return compilationUnitSyntax.WithUsings(
+            usingDirectives.Insert(insertionIndex, requiredUsingDirective));
+    }
+
+    private static async Task<Document> ReplaceAddWithIndexerAsync(Diagnostic diagnostic, Document document, CancellationToken cancellationToken)
+    {
+        var root = await document.GetSyntaxRootAsync(cancellationToken).ConfigureAwait(false);
+        if (root == null)
+        {
+            return document;
+        }
+
+        var invocation = root.FindNode(diagnostic.Location.SourceSpan);
+
+        if (invocation is InvocationExpressionSyntax
+            {
+                Expression: MemberAccessExpressionSyntax memberAccessExpression,
+                ArgumentList.Arguments: { Count: 2 } arguments
+            })
+        {
+            var assignmentExpression =
+                SyntaxFactory.AssignmentExpression(
+                    SyntaxKind.SimpleAssignmentExpression,
+                    SyntaxFactory.ElementAccessExpression(
+                        memberAccessExpression.Expression,
+                        SyntaxFactory.BracketedArgumentList(
+                            SyntaxFactory.SeparatedList(new[] { arguments[0] }))),
+                    arguments[1].Expression);
+
+            return document.WithSyntaxRoot(root.ReplaceNode(invocation, assignmentExpression));
+        }
+
+        return document;
+    }
+}

src/Framework/AspNetCoreAnalyzers/test/Http/HeaderDictionaryAddAnalyzerTests.cs

@@ -0,0 +1,65 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Microsoft.CodeAnalysis.Testing;
+using VerifyCS = Microsoft.AspNetCore.Analyzers.Verifiers.CSharpAnalyzerVerifier<
+    Microsoft.AspNetCore.Analyzers.Http.HeaderDictionaryAddAnalyzer>;
+
+namespace Microsoft.AspNetCore.Analyzers.Http;
+
+public class HeaderDictionaryAddAnalyzerTests
+{
+    [Fact]
+    public async Task IHeaderDictionary_WithAdd_ReportsDiagnostics()
+    {
+        // Arrange & Act & Assert
+        await VerifyCS.VerifyAnalyzerAsync(@"
+using Microsoft.AspNetCore.Http;
+namespace HeaderDictionaryAddAnalyzerTests;
+public class Program
+{
+    public static void Main()
+    {
+        var context = new DefaultHttpContext();
+        {|#0:context.Request.Headers.Add(""Accept"", ""text/html"")|};
+    }
+}",
+        new DiagnosticResult(DiagnosticDescriptors.DoNotUseIHeaderDictionaryAdd)
+            .WithLocation(0)
+            .WithMessage(Resources.Analyzer_HeaderDictionaryAdd_Message));
+    }
+
+    [Fact]
+    public async Task IHeaderDictionary_WithAppend_NoDiagnostics()
+    {
+        // Arrange & Act & Assert
+        await VerifyCS.VerifyAnalyzerAsync(@"
+using Microsoft.AspNetCore.Http;
+namespace HeaderDictionaryAddAnalyzerTests;
+public class Program
+{
+    public static void Main()
+    {
+        var context = new DefaultHttpContext();
+        context.Request.Headers.Append(""Accept"", ""text/html"");
+    }
+}");
+    }
+
+    [Fact]
+    public async Task IHeaderDictionary_WithIndexer_NoDiagnostics()
+    {
+        // Arrange & Act & Assert
+        await VerifyCS.VerifyAnalyzerAsync(@"
+using Microsoft.AspNetCore.Http;
+namespace HeaderDictionaryAddAnalyzerTests;
+public class Program
+{
+    public static void Main()
+    {
+        var context = new DefaultHttpContext();
+        context.Request.Headers[""Accept""] = ""text/html"";
+    }
+}");
+    }
+}