День 1782. #ЧтоНовенького
Помечаем Экспериментальные API Атрибутом Experimental
При написании библиотек и фреймворков, которые используют другие, иногда нужно сообщить клиентам, что данный API по-прежнему считается «экспериментальным». Например, предоставить другим возможность работать с частью кода, оставив для себя возможность что-то ломать. В C# 12 это можно сделать с помощью ExperimentalAttribute.

Например, в JetBrains Space SDK есть метод MapSpaceAttachmentProxy, который пока является экспериментальной функцией:

using System.Diagnostics.CodeAnalysis;

public static class SpaceMapAttachmentProxyExtensions
{
  [Experimental("SPC101")]
  public static IEndpointConventionBuilder 
   MapSpaceAttachmentProxy(
    this IEndpointRouteBuilder endpoints, 
    string path)
  {
    //…
  }
}

Сборка проекта, использующего этот метод, по умолчанию завершается неудачей с ошибкой “Error SPC101: ‘MapSpaceAttachmentProxy(…)’ is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.” (Ошибка SPC101: 'MapSpaceAttachmentProxy(…)' предназначен только для ознакомительных целей и может быть изменён или удалён в будущих обновлениях. Подавите эту диагностику, чтобы продолжить.)

Также с помощью свойства UrlFormat в атрибут можно добавить URL, где люди смогут найти дополнительную информацию об API. Здесь заместитель {0} MSBuild заменит диагностическим идентификатором:

[Experimental("SPC101", UrlFormat = "https://www.example.com/diagnostics/{0}.html")]

Вы можете подавить диагностику экспериментальных атрибутов в файле проекта, добавив свойство <NoWarn>:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <!-- ... -->
  <PropertyGroup>
    <NoWarn>SPC101</NoWarn>
  </PropertyGroup>
</Project>

Либо с помощью директивы pragma в коде:

#pragma warning disable SPC001

Что делать в старых версиях языка?
Как вариант, можно использовать атрибут Obsolete. Хотя он по умолчанию отображается только как предупреждение, но, по крайней мере, это будет видно в журнале сборки. Начиная с .NET6, вы также можете добавить к атрибуту диагностический идентификатор, давая людям возможность подавить сообщение, если они согласны использовать этот экспериментальный API:

[Obsolete("'MapSpaceAttachmentProxy(...)' is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to remove this warning.", DiagnosticId = "SPC101")]

Источник: https://blog.maartenballiauw.be/post/2023/11/08/opt-in-to-experimental-apis-using-csharp-12-experimentalattribute.html