Post
Ask Question

Experimental Attribute in .NET & C#

Introduction

The Experimental attribute is a new C# 12 feature that allows you to add the Experimental attribute to your types, methods, or assemblies to indicate that it is an experimental feature. By doing this, the compiler will issue an error when someone tries to use the method or the type. In this article, I present how to use this feature.

For demonstration purposes, I created a console application with .NET 8 and ran it using the Visual Studio 2022 Preview version. Until the date of this article, it’s necessary to use the Preview version. Otherwise, this feature will not work.

The Experimental attribute comes from the namespace System.Diagnostics.CodeAnalysis. In the code below, you can see an example of a class that has this attribute:

using System.Diagnostics.CodeAnalysis;

namespace DotNet8Examples
{
    [Experimental(diagnosticId: "Test001")]
    public class ExperimentalAttributeDemo
    {
        public void Print()
        {
            Console.WriteLine("Hello Experimental Attribute");
        }
    }
}
  • On line 1, there is the namespace for the Experimental attribute.
  • On line 5, there is the Experimental attribute, with the diagnosticId. For the diagnosticId, you can specify an Id, which will be used by the compiler, to report a usage of the API the attribute applies to.
  • On line 8, there is a method for this class.

Now, if you try to create an instance of this class, the compiler will complain about it:

var experimentalAttributeDemo = new ExperimentalAttributeDemo();

Test

Note. You can use the Experimental attribute on the class, on the method, or in both.

To make use of this class and ignore this error, you can use the NoWarn in the .csproj property, and this will be on a global level, which means that every time you try to use the class or the method, it will not be necessary to suppress the error, or you can suppress it directly on the code, and this will be necessary to do every time you need to use the class or the method.

In the example below, I’m suppressing the error Test001 in the code directly. For that, you need to use the #pragma warning disable Test001 and the #pragma warning restore Test001 and add your code in between:

#pragma warning disable Test001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
var demo = new ExperimentalAttributeDemo();
#pragma warning restore Test001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.

You can also specify the Experimental element on the method level, and you can use the same or a different diagnosticId, for example:

Now, if you try to call this method, the compiler will also complain, and it will be necessary to suppress the error for Test002, too.

In the example below, you can see how to suppress this error on a global level by configuring it on the .csproj file:

<PropertyGroup>
  <NoWarn>Test002</NoWarn>
</PropertyGroup>

With this configuration, the compiler will not complain anymore when the method is being used:

demo.Print();

// Output:
Hello Experimental Attribute

Conclusion

This feature can be useful when you want to create an experimental feature such as a testing, a preview or even a temporary feature, that might change in the future, and you want to make sure that this feature is not accidentally used by someone, as the compiler will complain about it - unless you suppress the error.


Similar Articles