API предварительной версии

Платформа .NET гордится тем, что она серьезно относится к совместимости. Таким образом, экосистема библиотеки, как правило, не вносит критические изменения, особенно в отношении API.

Тем не менее, при разработке API важно собирать отзывы от пользователей и изменять API на основе этого отзыва при необходимости. Чтобы избежать сюрпризов, важно, чтобы пользователи понимали, какие API считаются стабильными и которые по-прежнему находятся в активной разработке и могут измениться.

Существует несколько способов, которые API может выразить в предварительной версии:

• Весь компонент считается предварительным просмотром:

  • Предоставляется в предварительной версии среды выполнения .NET
  • Предоставляется в пакете NuGet предварительной версии

• В противном случае стабильный компонент специально помечает некоторые API как предварительный просмотр:

  • Отмечено с помощью RequiresPreviewFeaturesAttribute
  • Отмечено с помощью ExperimentalAttribute

В этой статье объясняется, как выбрать между этими параметрами и способом работы каждого из них.

Предварительные версии среды выполнения .NET

За исключением кандидатов на выпуск (RCs) с лицензией go-live, предварительные версии среды выполнения .NET и ПАКЕТА SDK не поддерживаются.

Таким образом, любые API, добавленные в рамках предварительной версии .NET, считаются измененными на основе отзывов о получении предварительных версий. Чтобы использовать предварительную версию среды выполнения .NET, необходимо явно выбрать более новую версию платформы. При этом вы неявно выражаете согласие на использование API, которые могут измениться.

Предварительные версии пакетов NuGet

Пакеты NuGet могут быть стабильными или помечены как предварительные версии, то есть пакет имеет суффикс предварительной версии. Например, System.Text.Json 9.0.0-preview.2.24128.5 имеет суффикс preview.2.24128.5предварительной версии .

Авторы пакетов обычно не поддерживают предварительно подготовленные пакеты и используют их в качестве средства для сбора отзывов от ранних разработчиков.

При установке пакетов с помощью интерфейса командной строки или пользовательского интерфейса обычно необходимо явно указать, нужно ли устанавливать предварительную версию, опять же неявно выразив согласие на использование API, которые могут измениться.

RequiresPreviewFeaturesAttribute

С .NET 6 платформа включает RequiresPreviewFeaturesAttribute атрибут.

Этот атрибут используется для API, требующих предварительного просмотра поведения в стеке, включая среду выполнения, компилятор C# и библиотеки. При использовании API, помеченных этим атрибутом, вы получите ошибку сборки, если только наборы проектов не будут <EnablePreviewFeatures>true</EnablePreviewFeatures>. Установка этого свойства true также позволяет <LangVersion>Preview</LangVersion>использовать функции языка предварительной версии.

Команда .NET использовала RequiresPreviewFeaturesAttribute атрибут в .NET 6 для тестирования универсальной математики, так как она требовала статических элементов интерфейса, которые были в предварительной версии в то время.

ExperimentalAttribute

Добавлен . ExperimentalAttributeNET 8, который не требует каких-либо функций среды выполнения или предварительной версии языка и просто указывает, что данный API еще не является стабильным.

При сборке с экспериментальным API компилятор создаст ошибку. Каждая функция, помеченная как экспериментальная, имеет свой собственный идентификатор диагностики. Чтобы выразить согласие на использование, вы подавляете определенную диагностику. Это можно сделать с помощью любого из средств подавления диагностика, но рекомендуется добавить диагностику в свойство проекта<NoWarn>.

Так как каждая экспериментальная функция имеет отдельный идентификатор, согласие на использование одной экспериментальной функции не дает согласия на использование другого.

Выбор между параметрами

Разработчики библиотеки должны использовать только предварительно подготовленные пакеты NuGet или пометить API с помощью [Experimental]:

• Для новых API, представленных в предварительной версии пакета, вам не нужно ничего делать; Пакет уже выражает качество предварительной версии.

• Если вы хотите отправить стабильный пакет, содержащий некоторые api качества предварительной версии, следует пометить эти API с помощью [Experimental]. Убедитесь, что вы используете собственный идентификатор диагностики и укажите его для этих функций. Если у вас есть несколько независимых функций, рассмотрите возможность использования нескольких идентификаторов.

Атрибут [RequiresPreviewFeatures] предназначен только для компонентов самой платформы .NET. И даже там он используется только для API, для которых требуются функции среды выполнения и предварительной версии языка. Если это просто API, который находится в предварительной версии, платформа .NET использует [Experimental] атрибут.

Исключением из этого правила является создание стабильной библиотеки и предоставление определенных функций, которые, в свою очередь, зависят от поведения среды выполнения или предварительной версии языка. В этом случае следует использовать [RequiresPreviewFeatures] для точек входа этой функции. Однако необходимо учитывать, что пользователям таких API также необходимо включить предварительные версии функций, которые предоставляют их всем средам выполнения, библиотеке и поведению предварительной версии языка.