Add description to RequiresPreviewFeaturesAttribute

[JamesNK]

It would be nice if there was a way to provide a description with RequiresPreviewFeaturesAttribute, like you can with ObsoleteAttribute. The description would show up in analyzers/build warnings.

A description would provide more information about why a feature is in preview and what a user should keep in mind if they choose to use the feature.

For example, HTTP/3 in .NET 6 is preview. Kind of detail we want to pass on when someone sees this warning:

• What scenarios HTTP/3 does and doesn't support in .NET 6.
• How to mitigate an app if HTTP/3 is turned on and problems are found.

API Proposal

namespace System.Runtime.Versioning
{
    public sealed class RequiresPreviewFeaturesAttribute : Attribute
    {
        // Existing
        // public RequiresPreviewFeaturesAttribute();
        public RequiresPreviewFeaturesAttribute(string message);
        public string Message { get; }
        public string Url { get; set; }
    }
}

Note: The URL property allows us to surface the URL directly via the Roslyn diagnostic, so that people can click the diagnostic ID in the error list, rather than copy & pasting the URL.

API Usage

 namespace Microsoft.AspNetCore.Server.Kestrel.Core
 {
     [Flags]
     public enum HttpProtocols
     {
         Http1 = 0x1,
         Http2 = 0x2,
         Http1AndHttp2 = Http1 | Http2,
+        [RequiresPreviewFeatures("Kestrel HTTP3 support for .NET 6 is in preview", Url = "https://aka.ms/kestrel-http3")]
         Http3 = 0x4,
+        [RequiresPreviewFeatures("Kestrel HTTP3 support for .NET 6 is in preview", Url = "https://aka.ms/kestrel-http3")]
         Http1AndHttp2AndHttp3 = Http1 | Http2 | Http3
     }
 }

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

[stephentoub]

cc: @jeffhandley, @terrajobst, @pgovind, @tannergooding

Tagging subscribers to this area: @dotnet/area-system-runtime
See info in area-owners.md if you want to be subscribed.

Issue Details

---

It would be nice if there was a way to provide a description with RequiresPreviewFeaturesAttribute, like you can with ObsoleteAttribute. The description would show up in analyzers/build warnings.

A description would provide more information about why a feature is in preview and what a user should keep in mind if they choose to use the feature.

For example, HTTP/3 in .NET 6 is preview. Kind of detail we want to pass on when someone sees this warning:

• What scenarios HTTP/3 does and doesn't support in .NET 6.
• How to mitigate an app if HTTP/3 is turned on and problems are found.

Author:	JamesNK
Assignees:	-
Labels:	area-System.Runtime, untriaged
Milestone:	6.0.0

[terrajobst]

@JamesNK I've added the API proposal and sample information and marked the issue as ready for review. We'll take a look next Tuesday, I'll send you an invite on Monday.

[JamesNK]

Ok. I might not make it because of time zones, but I think the issue is pretty self explanatory.

[terrajobst]

Video

• We discussed whether or not the analyzer should also offer a diagnostic ID, akin to ObsoleteAttribute
  • We're leaning towards no, because that seems to re-introduce the feature names that we considered in the design and decided against due to complexity and test matrix concerns
  • That means we wouldn't have UrlFormat but just Url

namespace System.Runtime.Versioning
{
    public sealed class RequiresPreviewFeaturesAttribute : Attribute
    {
        // Existing
        // public RequiresPreviewFeaturesAttribute();
        public RequiresPreviewFeaturesAttribute(string? message);
        public string? Message { get; }
        public string? Url { get; set; }
    }
}