API предварительного просмотра
Платформа .NET серьезно относится к совместимости. Таким образом, экосистема библиотеки, как правило, не вносит критические изменения, особенно в отношении API.
Тем не менее, при разработке API важно иметь возможность собирать отзывы от пользователей и вносить изменения в API на основе этой обратной связи при необходимости. Чтобы избежать сюрпризов, следует понять, какие API, которые вы используете, считаются стабильными и которые по-прежнему находятся в активной разработке и могут измениться.
Существует несколько способов, которые API может выразить, что он находится в предварительной версии:
Весь компонент считается предварительным просмотром, если он предоставляется:
- В предварительной версии среды выполнения .NET.
- В предварительном выпуске пакета NuGet.
В общем стабильный компонент помечает определенные API как предварительные с использованием следующих атрибутов:
В этой статье объясняется, как работает каждый вариант, и разработчикам библиотеки — как выбрать между этими вариантами.
Предварительные версии среды выполнения .NET
За исключением кандидатов на выпуск (RC) с лицензией 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
Атрибут RequiresPreviewFeaturesAttribute используется для API, требующих предварительного просмотра поведения в стеке, включая среду выполнения, компилятор C# и библиотеки. При использовании API, помеченных этим атрибутом, вы получите ошибку сборки, если файл проекта не содержит свойство <EnablePreviewFeatures>true</EnablePreviewFeatures>. Задание этого свойства true также задает <LangVersion>Preview</LangVersion>, что позволяет использовать функции языка предварительной версии.
Например, в .NET 6 библиотека универсальной математической была помечена RequiresPreviewFeaturesAttribute, поскольку требовала статических элементов интерфейса, которые в то время находились в предварительной версии.
ExperimentalAttribute
В .NET 8 добавлено ExperimentalAttribute, что не требует каких-либо функций среды выполнения или предварительных версий языка и просто указывает на то, что данный API еще не является стабильным.
При сборке с экспериментальным API компилятор создает ошибку. Каждая функция, помеченная как экспериментальная, имеет собственный отдельный идентификатор диагностики. Чтобы выразить согласие на использование экспериментального API, вы подавляете конкретную диагностику. Это можно сделать с помощью любого из средств для подавления диагностики, но рекомендуется добавить диагностику в свойство <NoWarn> проекта.
Так как каждая экспериментальная функция имеет отдельный идентификатор, согласие на использование одной экспериментальной функции не дает согласия на использование другого.
Дополнительные сведения см. в разделе Экспериментальные функции и статью в руководстве по C# по общим атрибутам.
Руководство для разработчиков библиотек
Разработчики библиотеки обычно должны выразить, что API находится в предварительной версии одним из двух способов:
- Для новых API, введённых в предварительной версии вашего пакета, вам не нужно ничего делать; пакет уже выражает качество предварительной версии.
- Если вы хотите отправить стабильный пакет, содержащий некоторые api качества предварительной версии, следует пометить эти API с помощью
[Experimental]. Обязательно используйте ваш идентификатор диагностики и сделайте его специфичным применительно к этим функциям. Если у вас есть несколько независимых функций, рассмотрите возможность использования нескольких идентификаторов.
Атрибут [RequiresPreviewFeatures] предназначен только для компонентов самой платформы .NET. Даже там, он используется только для API, для которых требуются функции среды выполнения и предварительной версии языка. Если это просто API, который находится в предварительной версии, платформа .NET использует атрибут [Experimental].
Исключением из этого правила является создание стабильной библиотеки и предоставление определенных функций, которые, в свою очередь, зависят от поведения среды выполнения или предварительной версии языка. В этом случае следует использовать [RequiresPreviewFeatures] для точек входа этой функции. Однако необходимо учитывать, что пользователям таких API также необходимо включить функции предварительного просмотра, что подвергает их всем возможным поведениям среды выполнения, библиотеки и языка в режиме предварительного просмотра.
