プレビュー API
.NET プラットフォームは互換性を重視しています。 そのため、ライブラリ エコシステムは、特に API に関して重大な変更を行うことを避ける傾向があります。
ただし、API を設計するときは、ユーザーからフィードバックを収集し、必要に応じてそのフィードバックに基づいて API に変更を加えることができることが重要です。 驚きを避けるために、使用する API が安定と見なされ、どの API がまだアクティブな開発中であり、変更される可能性があるかを理解する必要があります。
API がプレビュー形式であることを表す方法は複数あります。
コンポーネント全体が公開されている場合、プレビューと見なされます。
- .NET ランタイムのプレビュー リリースの際に。
- プレリリース NuGet パッケージ内。
それ以外の場合、安定したコンポーネントは、特定の API をプレビューとして次の属性でマークします。
この記事では、各オプションのしくみと、ライブラリ開発者向けに、これらのオプションを選択する方法について説明します。
.NET ランタイムのプレビュー
公開ライセンスを持つリリース候補 (VC) を除き、.NET ランタイムと SDK のプレビュー バージョンはサポートされていません。
そのため、.NET プレビューの一部として追加された API は、プレビューが受け取るフィードバックに基づいて変更される可能性があるとみなされます。 .NET ランタイム プレビューを使用するには、プロジェクトの新しいフレームワーク バージョンを明示的にターゲットにする必要があります。 これにより、変更される可能性のある API を使用することに対する同意を暗黙的に表明できます。
プレリリース NuGet パッケージ
NuGet パッケージには安定版かプレリリースを使用できます。 プレリリース パッケージは、そのバージョンにプレリリース サフィックスを付け、そのようにマークされます。 たとえば、System.Text.Json 9.0.0-preview.2.24128.5 のプレリリース サフィックスは preview.2.24128.5です。
プレリリース パッケージは、早期導入者からのフィードバックを収集する手段として一般的に使用されます。 一般に、それらは作者によってサポートされていません。
CLI または UI を使用してパッケージをインストールする場合は、プレリリース バージョンをインストールするかどうかを明示的に指定する必要があります。 これにより、変更される可能性のある API を使用することに対する同意を暗黙的に表明できます。
RequiresPreviewFeaturesAttribute
RequiresPreviewFeaturesAttribute 属性は、ランタイム、C# コンパイラ、ライブラリなど、スタック全体でプレビュー動作を必要とする API に使用されます。 この属性でマークされた API を使用すると、プロジェクト ファイルにプロパティ <EnablePreviewFeatures>true</EnablePreviewFeatures>が含まれている場合を除き、ビルド エラーが発生します。 このプロパティを true に設定すると、<LangVersion>Preview</LangVersion>も設定され、プレビュー言語機能を使用できるようになります。
たとえば、.NET 6 では、ジェネリック数学 ライブラリは、その時点でプレビュー段階にあった静的インターフェイス メンバーが必要なため、RequiresPreviewFeaturesAttribute でマークされていました。
ExperimentalAttribute
.NET 8 では、ExperimentalAttributeが追加されました。ランタイムや言語のプレビュー機能は必要なく、特定の API がまだ安定していないことを示すだけです。
実験用 API に対してビルドすると、コンパイラによってエラーが生成されます。 試験段階としてマークされている各機能には、独自の個別の診断 ID があります。 実験用 API の使用に同意するには、特定の診断を抑制します。 これは、診断を抑制するための任意の方法で行うことができますが、推奨される方法は、プロジェクトの <NoWarn> プロパティに診断を追加することです。
実験用の各機能には個別の ID があるため、ある実験機能を使用することに同意しても、別の実験機能の使用には同意しません。
詳細については、試験的な機能 と、一般的な属性に関する C# ガイドの記事を参照してください。
ライブラリ開発者向けのガイダンス
ライブラリ開発者は、通常、API がプレビュー段階であることを次の 2 つの方法のいずれかで表現する必要があります。
- プレリリース バージョンのパッケージで導入された新しい API の場合、何もする必要はありません。パッケージは既にプレビュー品質を表しています。
- プレビュー品質の API を含む安定したパッケージを出荷する場合は、
[Experimental]を使用してそれらの API をマークする必要があります。 自分の診断 ID を使用し、それをこれらの機能に特化させてください。 複数の独立した機能がある場合は、複数の ID を使用することを検討してください。
[RequiresPreviewFeatures] 属性は、.NET プラットフォーム自体のコンポーネントのみを対象としています。 その場合でも、ランタイムと言語のプレビュー機能を必要とする API にのみ使用されます。 プレビュー段階の API だけの場合、.NET プラットフォームでは [Experimental] 属性が使用されます。
この規則の例外は、安定したライブラリを構築していて、ランタイムまたは言語プレビューの動作に依存する特定の機能を公開する場合です。 その場合は、その機能のエントリ ポイントに [RequiresPreviewFeatures] を使用する必要があります。 ただし、このような API のユーザーもプレビュー機能を有効にする必要があることを考慮する必要があります。これにより、すべてのランタイム、ライブラリ、言語プレビューの動作に公開されます。
.NET