C# 12 中的 ExperimentalAttribute

Intro

C# 12 引入了一个 ExperimentalAttribute 我们可以将一些实验性质的 API 通过这个方法暴露出去，用户在使用的时候需要显式声明 NoWarn 才能正常使用，使得用户明白使用这样的 API 后续会有 break 的风险

ExperimentalAttribute

ExperimentalAttribute 定义如下：

namespace System.Diagnostics.CodeAnalysis

/// <summary>
///  Indicates that an API is experimental and it may change in the future.
/// </summary>
/// <remarks>
///   This attribute allows call sites to be flagged with a diagnostic that indicates that an experimental
///   feature is used. Authors can use this attribute to ship preview features in their assemblies.
/// </remarks>
[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 ExperimentalAttribute : Attribute
{
    /// <summary>
    ///  Initializes a new instance of the <see cref="ExperimentalAttribute"/> class, specifying the ID that the compiler will use
    ///  when reporting a use of the API the attribute applies to.
    /// </summary>
    /// <param name="diagnosticId">The ID that the compiler will use when reporting a use of the API the attribute applies to.</param>
    public ExperimentalAttribute(string diagnosticId)
    {
        DiagnosticId = diagnosticId;
    }

    /// <summary>
    ///  Gets or sets the ID that the compiler will use when reporting a use of the API the attribute applies to.
    /// </summary>
    /// <value>The unique diagnostic ID.</value>
    /// <remarks>
    ///  The diagnostic ID is shown in build output for warnings and errors.
    ///  <para>This property represents the unique ID that can be used to suppress the warnings or errors, if needed.</para>
    /// </remarks>
    public string DiagnosticId { get; }

    /// <summary>
    ///  Gets or sets the URL for corresponding documentation.
    ///  The API accepts a format string instead of an actual URL, creating a generic URL that includes the diagnostic ID.
    /// </summary>
    /// <value>The format string that represents a URL to corresponding documentation.</value>
    /// <remarks>An example format string is <c>https://contoso.com/obsoletion-warnings/{0}</c>.</remarks>
    public string? UrlFormat { get; set; }
}

Sample

public static void MainTest()
{
    Helper.Test();

    Helper.Test2();
}

file sealed class Helper
{
    [Experimental("EXP001")]
    public static void Test([CallerMemberName]string callerMemberName = "")
    {
        Console.WriteLine(callerMemberName);
    }
    
    [Experimental("EXP002", UrlFormat = "https://diagnostic.weihan.xyz/{0}")]
    public static void Test2([CallerMemberName]string callerMemberName = "")
    {
        Console.WriteLine(callerMemberName);
    }
}

默认直接使用 Experimental 的 API 会直接报错，如下，但如果添加了 NoWarn 来忽略则可以编译通过

通过前面的错误信息可以看得出来，如果我们配置了 `UrlFormat` 则会在错误信息里出现一个 url ，就相当于是 `string.Format`

配置 NoWarn 则可以编译通过，比如我们在项目文件里添加如下配置

<NoWarn>$(NoWarn);EXP001;EXP002</NoWarn>

References

• https://github.com/WeihanLi/SamplesInPractice/blob/master/CSharp12Sample/ExperimentalSample.cs
• https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.codeanalysis.experimentalattribute
• https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/proposals/csharp-12.0/experimental-attribute
• https://github.com/dotnet/runtime/pull/85444