Experimental Attribute in C#

Back to: C# New Features Tutorials

Experimental Attribute in C# with Examples

In this article, I will discuss Experimental Attribute in C# with Examples. Please read our previous article discussing Alias Any Type in C# with Examples. The Experimental attribute introduced in C# 12 allows developers to mark certain features in their code as experimental. This feature helps developers communicate that a class, method, or property is not yet stable and may undergo significant changes or even be removed in future releases. This is particularly useful when working with features under development or being tested in a pre-release state.

What’s New in C# 12 Related to the Experimental Attribute?

Before C# 12, there wasn’t a built-in way to label certain APIs as experimental. Developers had to rely on documentation or comments to indicate that a feature was experimental. With C# 12, the [Experimental] attribute was introduced, which allows us to explicitly mark certain features as experimental, providing better clarity and compiler-enforced warnings.

What is the Experimental Attribute?

The [Experimental] attribute is a new feature in C# 12 that you can apply to classes, methods, properties, or even assemblies. It marks these features as experimental, signalling to developers that the functionality may be subject to change or removal in future releases. This feature is particularly useful for:

• Testing new functionality: When you introduce new features or methods that may change based on feedback or further development.
• Preview features: Marking parts of the codebase that are meant for experimentation or preview purposes only.

The following example shows how to use the [Experimental] attribute:

using System.Diagnostics.CodeAnalysis;

namespace CSharp12NewFeatures
{
    // Apply the Experimental attribute to the class
    [Experimental(diagnosticId: "Test001")]
    public class ExperimentalFeature
    {
        // Experimental method
        [Experimental(diagnosticId: "Test002")]
        public void Execute()
        {
            Console.WriteLine("This is an experimental method.");
        }
    }

    class Program
    {
        static void Main()
        {
            // Compiler will issue a warning or error if you use this
            var feature = new ExperimentalFeature();
            feature.Execute();
        }
    }
}

Code Explanation:

• [Experimental] on Class: The Experimental attribute is applied to the ExperimentalFeature class, indicating that this class is experimental.
• [Experimental] on Method: Similarly, the Experimental attribute is applied to the Execute method, signaling that the method is also experimental.

If you try to use the ExperimentalFeature class or its Execute method, the compiler will issue a warning or error, indicating that these features are experimental. This ensures that these features are not accidentally used in production code.

Suppressing the Experimental Attribute Warning

While the [Experimental] attribute warns developers about using experimental features, you can suppress these warnings if you wish to use the experimental feature temporarily.

Method 1: Suppressing the Warning in Code

You can suppress the warning for the experimental feature in specific places using #pragma warning.

namespace CSharp12NewFeatures
{
    // Apply the Experimental attribute to the class
    [Experimental(diagnosticId: "Test001")]
    public class ExperimentalFeature
    {
        // Experimental method
        [Experimental(diagnosticId: "Test002")]
        public void Execute()
        {
            Console.WriteLine("This is an experimental method.");
        }
    }

    class Program
    {
        static void Main()
        {
            // Suppress warning for the experimental feature temporarily

            #pragma warning disable Test001 // Experimental class warning
            var feature = new ExperimentalFeature();
            #pragma warning restore Test001 // Restore the warning

            #pragma warning disable Test002 // Experimental method warning
            feature.Execute();
            #pragma warning restore Test001 // Restore the warning
        }
    }
}

Method 2: Suppressing the Warning Globally in .csproj

Alternatively, you can suppress the warning globally by modifying the <NoWarn> property in the .csproj file. This will suppress the warning across the entire project for the specified diagnostic IDs.

<PropertyGroup>
  <NoWarn>Test001;Test002</NoWarn>
</PropertyGroup>

Key Features of the Experimental Attribute:

• Flagging Experimental Features: The Experimental attribute allows developers to mark classes, methods, or properties as experimental, warning other developers that these features are subject to change or removal.
• Error or Warning Notifications: The compiler issues an error when an experimental feature is used unless explicitly suppressed. This is an essential feature that prevents accidental use of unstable APIs in production code.
• Customizable Diagnostics: Developers can assign a diagnostic ID to experimental features, making it easier to track and manage the usage of experimental APIs across a project.
• Encapsulation: The attribute helps encapsulate features that are still in development and ensures that these features don’t inadvertently become part of the stable public API.

Why Do We Need the Experimental Attribute?

In modern software development, especially when introducing new or evolving features, there’s a need to signal to other developers that certain parts of the system are not yet stable and may undergo significant changes. The Experimental attribute addresses this need by explicitly marking the feature as “not production-ready” and ensuring that consumers of the code understand its temporary and changeable nature.

The Experimental attribute serves several purposes:

• Communication: It helps communicate to developers that the marked feature is not yet stable and might change.
• Encapsulation: Allows developers to isolate new or unfinished features while still allowing others to test or experiment with them.
• Documentation: Directly documents that the feature is experimental within the code itself, providing clarity to all stakeholders.

Real-Time Example: Feature Prototyping in a Payment Processing System

Imagine you are working on a Payment Processing System for an e-commerce application. As part of the system, you are prototyping a new fraud detection algorithm that is still being tested. The algorithm could be modified significantly or even discarded based on feedback and performance results.

You want to implement this feature in the system, but don’t want other developers to accidentally use it in production code. This is where the [Experimental] attribute comes in handy. It allows you to mark the algorithm as experimental, signaling to other developers that it is still in development and may change in the future.

using System.Diagnostics.CodeAnalysis;

namespace PaymentProcessingSystem
{
    // The experimental fraud detection algorithm class
    [Experimental(diagnosticId: "FP001")]
    public class FraudDetectionAlgorithm
    {
        // Experimental method to check for fraudulent transactions
        [Experimental(diagnosticId: "FP002")]
        public bool IsFraudulentTransaction(decimal transactionAmount, string paymentMethod)
        {
            Console.WriteLine("Running experimental fraud detection algorithm...");

            // Simple logic for demonstration
            if (transactionAmount > 10000 && paymentMethod == "Credit Card")
            {
                return true; // Mark as fraudulent
            }

            return false; // Not fraudulent
        }
    }

    // Main application to demonstrate usage
    public class Program
    {
        static void Main()
        {
            try
            {
                // Creating an instance of the experimental fraud detection algorithm
                var fraudDetection = new FraudDetectionAlgorithm();

                // Trying to call the experimental method (compiler will give a warning/error)
                bool isFraudulent = fraudDetection.IsFraudulentTransaction(20000, "Credit Card");

                Console.WriteLine($"Fraudulent Transaction Detected: {isFraudulent}");
            }
            catch (Exception ex)
            {
                Console.WriteLine($"ERROR: {ex.GetType().Name} - {ex.Message}");
            }
        }
    }
}

Code Explanation:

• [Experimental] on the Class: The FraudDetectionAlgorithm class is marked as experimental using the [Experimental] attribute. This signals to developers that the class is not finalized and may change or be removed in the future.
• [Experimental] on the Method: The IsFraudulentTransaction method is also marked as experimental. This method contains the core logic for the fraud detection algorithm, which is still being tested.
• diagnosticId: The diagnosticId is used to uniquely identify this experimental feature. It helps when managing warnings or errors that arise from using the experimental code.
• Using the Experimental Feature: When trying to create an instance of the FraudDetectionAlgorithm class and call the IsFraudulentTransaction method, the compiler will issue a warning or error, informing the developer that the feature is experimental.

Suppressing the Warning:

If you, as a developer, want to bypass the warning and use the experimental feature temporarily, you can suppress the warning in the code:

using System.Diagnostics.CodeAnalysis;

namespace PaymentProcessingSystem
{
    // The experimental fraud detection algorithm class
    [Experimental(diagnosticId: "FP001")]
    public class FraudDetectionAlgorithm
    {
        // Experimental method to check for fraudulent transactions
        [Experimental(diagnosticId: "FP002")]
        public bool IsFraudulentTransaction(decimal transactionAmount, string paymentMethod)
        {
            Console.WriteLine("Running experimental fraud detection algorithm...");

            // Simple logic for demonstration
            if (transactionAmount > 10000 && paymentMethod == "Credit Card")
            {
                return true; // Mark as fraudulent
            }

            return false; // Not fraudulent
        }
    }

    // Main application to demonstrate usage
    public class Program
    {
        static void Main()
        {
            try
            {
                #pragma warning disable FP001 // Experimental feature: Fraud detection algorithm
                #pragma warning disable FP002 // Experimental method: IsFraudulentTransaction

                // Creating an instance of the experimental fraud detection algorithm
                var fraudDetection = new FraudDetectionAlgorithm();

                // Trying to call the experimental method (compiler will give a warning/error)
                bool isFraudulent = fraudDetection.IsFraudulentTransaction(20000, "Credit Card");

                Console.WriteLine($"Fraudulent Transaction Detected: {isFraudulent}");

                #pragma warning restore FP001 // Experimental feature: Fraud detection algorithm
                #pragma warning restore FP002 // Experimental method: IsFraudulentTransaction
            }
            catch (Exception ex)
            {
                Console.WriteLine($"ERROR: {ex.GetType().Name} - {ex.Message}");
            }
        }
    }
}

This code temporarily disables the warnings for using the experimental class and method. After the feature is fully tested and ready for production, you can remove the suppression and start using it without warnings.

Why Use the Experimental Attribute?

• Feature Prototyping: As demonstrated in the example, the [Experimental] attribute allows you to prototype new features (such as the fraud detection algorithm) without the risk of them being used in production prematurely.
• Control Over Use: By marking features as experimental, you gain more control over which parts of the code are being used by developers. You can easily prevent the accidental usage of unstable or incomplete features.
• Testing and Feedback: Experimental features can be tested in isolation and refined before becoming part of the stable API. The [Experimental] attribute serves as a useful communication tool to notify developers that a feature is still in development.

The [Experimental] attribute in C# 12 is a powerful tool for marking features, classes, methods, and properties as experimental. It provides developers with a way to indicate that the feature is in a testing phase and may undergo significant changes or even be removed in future releases.

In the next article, I will discuss Interceptors in C# with Examples. In this article, I explain Experimental Attribute in C# with Examples. I want your feedback. Please post your feedback, questions, or comments about this article.