Add assembly-level CompletedTaskAttribute support for external types

Co-authored-by: drewnoakes <[email protected]>

Author: Copilot

docfx/analyzers/VSTHRD003.md

@@ -26,6 +26,17 @@ async Task MyMethodAsync()
 }
 ```
 
+### Marking external types
+
+You can also apply the attribute at the assembly level to mark members in external types that you don't control:
+
+```csharp
+[assembly: Microsoft.VisualStudio.Threading.CompletedTask(Member = "ExternalLibrary.ExternalClass.CompletedTaskProperty")]
+```
+
+This is useful when you're using third-party libraries that have pre-completed tasks but aren't annotated with the attribute.
+The `Member` property should contain the fully qualified name of the member in the format `Namespace.TypeName.MemberName`.
+
 The analyzer already recognizes the following as safe to await without the attribute:
 - `Task.CompletedTask`
 - `Task.FromResult(...)`

src/Microsoft.VisualStudio.Threading.Analyzers.CSharp/VSTHRD003UseJtfRunAsyncAnalyzer.cs

@@ -71,16 +71,42 @@ public override void Initialize(AnalysisContext context)
         context.RegisterSyntaxNodeAction(Utils.DebuggableWrapper(this.AnalyzeLambdaExpression), SyntaxKind.ParenthesizedLambdaExpression);
     }
 
-    private static bool IsSymbolAlwaysOkToAwait(ISymbol? symbol)
+    private static bool IsSymbolAlwaysOkToAwait(ISymbol? symbol, Compilation compilation)
     {
-        // Check if the symbol has the CompletedTaskAttribute
-        if (symbol?.GetAttributes().Any(attr =>
+        if (symbol is null)
+        {
+            return false;
+        }
+
+        // Check if the symbol has the CompletedTaskAttribute directly applied
+        if (symbol.GetAttributes().Any(attr =>
             attr.AttributeClass?.Name == Types.CompletedTaskAttribute.TypeName &&
-            attr.AttributeClass.BelongsToNamespace(Types.CompletedTaskAttribute.Namespace)) == true)
+            attr.AttributeClass.BelongsToNamespace(Types.CompletedTaskAttribute.Namespace)))
         {
             return true;
         }
 
+        // Check for assembly-level CompletedTaskAttribute
+        foreach (AttributeData assemblyAttr in compilation.Assembly.GetAttributes())
+        {
+            if (assemblyAttr.AttributeClass?.Name == Types.CompletedTaskAttribute.TypeName &&
+                assemblyAttr.AttributeClass.BelongsToNamespace(Types.CompletedTaskAttribute.Namespace))
+            {
+                // Look for the Member named argument
+                foreach (KeyValuePair<string, TypedConstant> namedArg in assemblyAttr.NamedArguments)
+                {
+                    if (namedArg.Key == "Member" && namedArg.Value.Value is string memberName)
+                    {
+                        // Check if this symbol matches the specified member name
+                        if (IsSymbolMatchingMemberName(symbol, memberName))
+                        {
+                            return true;
+                        }
+                    }
+                }
+            }
+        }
+
         if (symbol is IFieldSymbol field)
         {
             // Allow the TplExtensions.CompletedTask and related fields.
@@ -103,6 +129,45 @@ private static bool IsSymbolAlwaysOkToAwait(ISymbol? symbol)
         return false;
     }
 
+    private static bool IsSymbolMatchingMemberName(ISymbol symbol, string memberName)
+    {
+        // Build the fully qualified name of the symbol
+        string fullyQualifiedName = GetFullyQualifiedName(symbol);
+
+        // Compare with the member name (case-sensitive)
+        return string.Equals(fullyQualifiedName, memberName, StringComparison.Ordinal);
+    }
+
+    private static string GetFullyQualifiedName(ISymbol symbol)
+    {
+        if (symbol.ContainingType is null)
+        {
+            return symbol.ToDisplayString(SymbolDisplayFormat.FullyQualifiedFormat);
+        }
+
+        // For members (properties, fields, methods), construct: Namespace.TypeName.MemberName
+        List<string> parts = new List<string>();
+
+        // Add member name
+        parts.Add(symbol.Name);
+
+        // Add containing type hierarchy
+        INamedTypeSymbol? currentType = symbol.ContainingType;
+        while (currentType is not null)
+        {
+            parts.Insert(0, currentType.Name);
+            currentType = currentType.ContainingType;
+        }
+
+        // Add namespace
+        if (symbol.ContainingNamespace is not null && !symbol.ContainingNamespace.IsGlobalNamespace)
+        {
+            parts.Insert(0, symbol.ContainingNamespace.ToDisplayString());
+        }
+
+        return string.Join(".", parts);
+    }
+
     private void AnalyzeArrowExpressionClause(SyntaxNodeAnalysisContext context)
     {
         var arrowExpressionClause = (ArrowExpressionClauseSyntax)context.Node;
@@ -191,7 +256,7 @@ private void AnalyzeAwaitExpression(SyntaxNodeAnalysisContext context)
                 symbolType = localSymbol.Type;
                 dataflowAnalysisCompatibleVariable = true;
                 break;
-            case IPropertySymbol propertySymbol when !IsSymbolAlwaysOkToAwait(propertySymbol):
+            case IPropertySymbol propertySymbol when !IsSymbolAlwaysOkToAwait(propertySymbol, context.Compilation):
                 symbolType = propertySymbol.Type;
 
                 if (focusedExpression is MemberAccessExpressionSyntax memberAccessExpression)
@@ -285,7 +350,7 @@ private void AnalyzeAwaitExpression(SyntaxNodeAnalysisContext context)
                                 }
 
                                 ISymbol? definition = declarationSemanticModel.GetSymbolInfo(memberAccessSyntax, cancellationToken).Symbol;
-                                if (IsSymbolAlwaysOkToAwait(definition))
+                                if (IsSymbolAlwaysOkToAwait(definition, context.Compilation))
                                 {
                                     return null;
                                 }
@@ -297,7 +362,7 @@ private void AnalyzeAwaitExpression(SyntaxNodeAnalysisContext context)
                 break;
             case IMethodSymbol methodSymbol:
                 // Check if the method itself has the CompletedTaskAttribute
-                if (IsSymbolAlwaysOkToAwait(methodSymbol))
+                if (IsSymbolAlwaysOkToAwait(methodSymbol, context.Compilation))
                 {
                     return null;
                 }

src/Microsoft.VisualStudio.Threading.Analyzers.CodeFixes/buildTransitive/AdditionalFiles/CompletedTaskAttribute.cs

@@ -11,15 +11,40 @@ namespace Microsoft.VisualStudio.Threading;
 /// This suppresses VSTHRD003 warnings when awaiting the returned task.
 /// </summary>
 /// <remarks>
+/// <para>
 /// Apply this attribute to properties, methods, or fields that return cached, pre-completed tasks
 /// such as singleton instances with well-known immutable values.
 /// The VSTHRD003 analyzer will not report warnings when these members are awaited,
 /// as awaiting an already-completed task does not pose a risk of deadlock.
+/// </para>
+/// <para>
+/// This attribute can also be applied at the assembly level to mark members in external types
+/// that you don't control:
+/// <code>
+/// [assembly: CompletedTask(Member = "System.Threading.Tasks.TplExtensions.TrueTask")]
+/// </code>
+/// </para>
 /// </remarks>
-[System.AttributeUsage(System.AttributeTargets.Property | System.AttributeTargets.Method | System.AttributeTargets.Field, Inherited = false, AllowMultiple = false)]
+[System.AttributeUsage(System.AttributeTargets.Property | System.AttributeTargets.Method | System.AttributeTargets.Field | System.AttributeTargets.Assembly, Inherited = false, AllowMultiple = true)]
 #pragma warning disable SA1649 // File name should match first type name
 internal sealed class CompletedTaskAttribute : System.Attribute
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CompletedTaskAttribute"/> class.
+    /// </summary>
+    public CompletedTaskAttribute()
+    {
+    }
+
+    /// <summary>
+    /// Gets or sets the fully qualified name of the member that returns a completed task.
+    /// This is only used when the attribute is applied at the assembly level.
+    /// </summary>
+    /// <remarks>
+    /// The format should be: "Namespace.TypeName.MemberName".
+    /// For example: "System.Threading.Tasks.TplExtensions.TrueTask".
+    /// </remarks>
+    public string? Member { get; set; }
 }
 #pragma warning restore SA1649 // File name should match first type name
 

test/Microsoft.VisualStudio.Threading.Analyzers.Tests/VSTHRD003UseJtfRunAsyncAnalyzerTests.cs

@@ -1642,6 +1642,216 @@ void TestMethod()
         await CSVerify.VerifyAnalyzerAsync(test);
     }
 
+    [Fact]
+    public async Task DoNotReportWarningWhenAwaitingPropertyMarkedByAssemblyLevelAttribute()
+    {
+        var test = @"
+using System.Threading.Tasks;
+
+[assembly: Microsoft.VisualStudio.Threading.CompletedTask(Member = ""ExternalLibrary.ExternalClass.CompletedTaskProperty"")]
+
+namespace Microsoft.VisualStudio.Threading
+{
+    [System.AttributeUsage(System.AttributeTargets.Property | System.AttributeTargets.Method | System.AttributeTargets.Field | System.AttributeTargets.Assembly, Inherited = false, AllowMultiple = true)]
+    internal sealed class CompletedTaskAttribute : System.Attribute
+    {
+        public CompletedTaskAttribute() { }
+        public string? Member { get; set; }
+    }
+}
+
+namespace ExternalLibrary
+{
+    public static class ExternalClass
+    {
+        public static Task CompletedTaskProperty { get; } = Task.CompletedTask;
+    }
+}
+
+class Tests
+{
+    async Task TestMethod()
+    {
+        await ExternalLibrary.ExternalClass.CompletedTaskProperty;
+    }
+}
+";
+        await CSVerify.VerifyAnalyzerAsync(test);
+    }
+
+    [Fact]
+    public async Task DoNotReportWarningWhenAwaitingFieldMarkedByAssemblyLevelAttribute()
+    {
+        var test = @"
+using System.Threading.Tasks;
+
+[assembly: Microsoft.VisualStudio.Threading.CompletedTask(Member = ""ExternalLibrary.ExternalClass.CompletedTaskField"")]
+
+namespace Microsoft.VisualStudio.Threading
+{
+    [System.AttributeUsage(System.AttributeTargets.Property | System.AttributeTargets.Method | System.AttributeTargets.Field | System.AttributeTargets.Assembly, Inherited = false, AllowMultiple = true)]
+    internal sealed class CompletedTaskAttribute : System.Attribute
+    {
+        public CompletedTaskAttribute() { }
+        public string? Member { get; set; }
+    }
+}
+
+namespace ExternalLibrary
+{
+    public static class ExternalClass
+    {
+        public static readonly Task CompletedTaskField = Task.FromResult(true);
+    }
+}
+
+class Tests
+{
+    async Task TestMethod()
+    {
+        await ExternalLibrary.ExternalClass.CompletedTaskField;
+    }
+}
+";
+        await CSVerify.VerifyAnalyzerAsync(test);
+    }
+
+    [Fact]
+    public async Task DoNotReportWarningWhenAwaitingMethodMarkedByAssemblyLevelAttribute()
+    {
+        var test = @"
+using System.Threading.Tasks;
+
+[assembly: Microsoft.VisualStudio.Threading.CompletedTask(Member = ""ExternalLibrary.ExternalClass.GetCompletedTask"")]
+
+namespace Microsoft.VisualStudio.Threading
+{
+    [System.AttributeUsage(System.AttributeTargets.Property | System.AttributeTargets.Method | System.AttributeTargets.Field | System.AttributeTargets.Assembly, Inherited = false, AllowMultiple = true)]
+    internal sealed class CompletedTaskAttribute : System.Attribute
+    {
+        public CompletedTaskAttribute() { }
+        public string? Member { get; set; }
+    }
+}
+
+namespace ExternalLibrary
+{
+    public static class ExternalClass
+    {
+        public static Task GetCompletedTask() => Task.CompletedTask;
+    }
+}
+
+class Tests
+{
+    async Task TestMethod()
+    {
+        await ExternalLibrary.ExternalClass.GetCompletedTask();
+    }
+}
+";
+        await CSVerify.VerifyAnalyzerAsync(test);
+    }
+
+    [Fact]
+    public async Task DoNotReportWarningWhenReturningPropertyMarkedByAssemblyLevelAttribute()
+    {
+        var test = @"
+using System.Threading.Tasks;
+
+[assembly: Microsoft.VisualStudio.Threading.CompletedTask(Member = ""ExternalLibrary.ExternalClass.CompletedTaskProperty"")]
+
+namespace Microsoft.VisualStudio.Threading
+{
+    [System.AttributeUsage(System.AttributeTargets.Property | System.AttributeTargets.Method | System.AttributeTargets.Field | System.AttributeTargets.Assembly, Inherited = false, AllowMultiple = true)]
+    internal sealed class CompletedTaskAttribute : System.Attribute
+    {
+        public CompletedTaskAttribute() { }
+        public string? Member { get; set; }
+    }
+}
+
+namespace ExternalLibrary
+{
+    public static class ExternalClass
+    {
+        public static Task CompletedTaskProperty { get; } = Task.CompletedTask;
+    }
+}
+
+class Tests
+{
+    Task GetTask() => ExternalLibrary.ExternalClass.CompletedTaskProperty;
+}
+";
+        await CSVerify.VerifyAnalyzerAsync(test);
+    }
+
+    [Fact]
+    public async Task ReportWarningWhenAwaitingPropertyNotMarkedByAssemblyLevelAttribute()
+    {
+        var test = @"
+using System.Threading.Tasks;
+
+namespace ExternalLibrary
+{
+    public static class ExternalClass
+    {
+        public static Task SomeTaskProperty { get; } = Task.Run(() => {});
+    }
+}
+
+class Tests
+{
+    async Task TestMethod()
+    {
+        await [|ExternalLibrary.ExternalClass.SomeTaskProperty|];
+    }
+}
+";
+        await CSVerify.VerifyAnalyzerAsync(test);
+    }
+
+    [Fact]
+    public async Task DoNotReportWarningWithMultipleAssemblyLevelAttributes()
+    {
+        var test = @"
+using System.Threading.Tasks;
+
+[assembly: Microsoft.VisualStudio.Threading.CompletedTask(Member = ""ExternalLibrary.ExternalClass.Task1"")]
+[assembly: Microsoft.VisualStudio.Threading.CompletedTask(Member = ""ExternalLibrary.ExternalClass.Task2"")]
+
+namespace Microsoft.VisualStudio.Threading
+{
+    [System.AttributeUsage(System.AttributeTargets.Property | System.AttributeTargets.Method | System.AttributeTargets.Field | System.AttributeTargets.Assembly, Inherited = false, AllowMultiple = true)]
+    internal sealed class CompletedTaskAttribute : System.Attribute
+    {
+        public CompletedTaskAttribute() { }
+        public string? Member { get; set; }
+    }
+}
+
+namespace ExternalLibrary
+{
+    public static class ExternalClass
+    {
+        public static Task Task1 { get; } = Task.CompletedTask;
+        public static Task Task2 { get; } = Task.FromResult(true);
+    }
+}
+
+class Tests
+{
+    async Task TestMethod()
+    {
+        await ExternalLibrary.ExternalClass.Task1;
+        await ExternalLibrary.ExternalClass.Task2;
+    }
+}
+";
+        await CSVerify.VerifyAnalyzerAsync(test);
+    }
+
     private DiagnosticResult CreateDiagnostic(int line, int column, int length) =>
         CSVerify.Diagnostic().WithSpan(line, column, line, column + length);
 }