Add CompletedTaskAttribute to TplExtensions and remove special-case code

Co-authored-by: drewnoakes <350947+drewnoakes@users.noreply.github.com>

Author: Copilot

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

@@ -148,16 +148,7 @@ private static bool IsSymbolAlwaysOkToAwait(ISymbol? symbol, Compilation compila
             }
         }
 
-        if (symbol is IFieldSymbol field)
-        {
-            // Allow the TplExtensions.CompletedTask and related fields.
-            if (field.ContainingType.Name == Types.TplExtensions.TypeName && field.BelongsToNamespace(Types.TplExtensions.Namespace) &&
-                (field.Name == Types.TplExtensions.CompletedTask || field.Name == Types.TplExtensions.CanceledTask || field.Name == Types.TplExtensions.TrueTask || field.Name == Types.TplExtensions.FalseTask))
-            {
-                return true;
-            }
-        }
-        else if (symbol is IPropertySymbol property)
+        if (symbol is IPropertySymbol property)
         {
             // Explicitly allow Task.CompletedTask
             if (property.ContainingType.Name == Types.Task.TypeName && property.BelongsToNamespace(Types.Task.Namespace) &&

src/Microsoft.VisualStudio.Threading/CompletedTaskAttribute.cs

@@ -0,0 +1,46 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using System;
+
+namespace Microsoft.VisualStudio.Threading;
+
+/// <summary>
+/// Indicates that a property, method, or field returns a task that is already completed.
+/// 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 = "ExternalLibrary.ExternalClass.CompletedTaskProperty")]
+/// </code>
+/// </para>
+/// </remarks>
+[AttributeUsage(AttributeTargets.Property | AttributeTargets.Method | AttributeTargets.Field | AttributeTargets.Assembly, Inherited = false, AllowMultiple = true)]
+public sealed class CompletedTaskAttribute : 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: "ExternalLibrary.ExternalClass.CompletedTaskProperty".
+    /// </remarks>
+    public string? Member { get; set; }
+}

src/Microsoft.VisualStudio.Threading/TplExtensions.cs

@@ -20,22 +20,26 @@ public static partial class TplExtensions
     /// A singleton completed task.
     /// </summary>
     [Obsolete("Use Task.CompletedTask instead.")]
+    [CompletedTask]
     public static readonly Task CompletedTask = Task.FromResult(default(EmptyStruct));
 
     /// <summary>
     /// A task that is already canceled.
     /// </summary>
     [Obsolete("Use Task.FromCanceled instead.")]
+    [CompletedTask]
     public static readonly Task CanceledTask = Task.FromCanceled(new CancellationToken(canceled: true));
 
     /// <summary>
     /// A completed task with a <see langword="true" /> result.
     /// </summary>
+    [CompletedTask]
     public static readonly Task<bool> TrueTask = Task.FromResult(true);
 
     /// <summary>
     /// A completed task with a <see langword="false" /> result.
     /// </summary>
+    [CompletedTask]
     public static readonly Task<bool> FalseTask = Task.FromResult(false);
 
     /// <summary>