Consider shipping RequiresPreviewFeaturesAttribute as a downlevel assembly

[terrajobst]

Attributes for analyzers and compilers are usually matched by name such that downlevel consumers can carry an internal copy to give their consumers a better experience without having to depend on extra assemblies.

The downside is that internal attribute applications won't show up in documentation. For preview APIs it would be desirable to have information available in the docs. Now, rendering the attribute as part of the syntax is only one way to express that. The alternative design is to add a banner-style warning. At that point, the attribute application being visible seems less important.

The downside of shipping this attribute downlevel is added complexity. The design for this would look as follows:

Design Sketch

Component	Name
NuGet Package	Microsoft.CodeAnalysis.NetAnalyzers
Assembly	System.Runtime.Versioning.RequiresPreviewFeaturesAttribute.dll
Frameworks	netstandard2.0, net461, net6.0

#if NET6_0_OR_GREATER

using System.Runtime.CompilerServices;
using System.Runtime.Versioning;
[assembly: TypeForwardedTo(typeof(RequiresPreviewFeaturesAttribute))]

#else

namespace System.Runtime.Versioning;

[AttributeUsage(AttributeTargets.Assembly | AttributeTargets.Module | AttributeTargets.Class | AttributeTargets.Struct | AttributeTargets.Enum | AttributeTargets.Constructor | AttributeTargets.Method | AttributeTargets.Property | AttributeTargets.Field | AttributeTargets.Event | AttributeTargets.Interface | AttributeTargets.Delegate, Inherited = false)]
public sealed class RequiresPreviewFeaturesAttribute : Attribute
{
    public RequiresPreviewFeaturesAttribute()
    {
    }

    public RequiresPreviewFeaturesAttribute(string/*?*/ message)
    {
    }

    public string/*?*/ Message { get; }

    public string/*?*/ Url { get; set; }
}

#endif

/cc @geeknoid @stephentoub

[dotnet-issue-labeler]

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.

[ghost]

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

Issue Details

---

Attributes for analyzers and compilers are usually matched by name such that downlevel consumers can carry an internal copy to give their consumers a better experience without having to depend on extra assemblies.

The downside is that internal attribute applications won't show up in documentation. For preview APIs it would be desirable to have information available in the docs. Now, rendering the attribute as part of the syntax is only one way to express that. The alternative design is to add a banner-style warning. At that point, the attribute application being visible seems less important.

The downside of shipping this attribute downlevel is added complexity. The design for this would look as follows:

Design Sketch

Component	Name
NuGet Package	Microsoft.CodeAnalysis.NetAnalyzers
Assembly	System.Runtime.Versioning.RequiresPreviewFeaturesAttribute.dll
Frameworks	netstandard2.0, net461, net6.0

#if NET6_0_OR_GREATER

using System.Runtime.CompilerServices;
using System.Runtime.Versioning;
[assembly: TypeForwardedTo(typeof(RequiresPreviewFeaturesAttribute))]

#else

namespace System.Runtime.Versioning;

[AttributeUsage(AttributeTargets.Assembly | AttributeTargets.Module | AttributeTargets.Class | AttributeTargets.Struct | AttributeTargets.Enum | AttributeTargets.Constructor | AttributeTargets.Method | AttributeTargets.Property | AttributeTargets.Field | AttributeTargets.Event | AttributeTargets.Interface | AttributeTargets.Delegate, Inherited = false)]
public sealed class RequiresPreviewFeaturesAttribute : Attribute
{
    public RequiresPreviewFeaturesAttribute()
    {
    }

    public RequiresPreviewFeaturesAttribute(string/*?*/ message)
    {
    }

    public string/*?*/ Message { get; }

    public string/*?*/ Url { get; set; }
}

#endif

/cc @geeknoid @stephentoub

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

[terrajobst]

Moving forward, we don't expect third parties to use [RequiresPreviewFeatures] and instead use the upcoming [Experimental] attribute instead, so I don't think this will be necessary.