プレビュー API

  • [アーティクル]

.NET プラットフォームは互換性を重視することに誇りを持っています。 そのため、ライブラリ エコシステムは、特に API に関して破壊的変更を加えることを避ける傾向があります。

ただし、API を設計するときは、ユーザーからフィードバックを収集し、必要に応じてそのフィードバックに基づいて API を変更することが重要です。 予期しない事態を避けるには、どの API が安定していると見なされ、どの API がまだ開発中で変更される可能性があるかをユーザーが理解することが重要です。

API がプレビュー形式であることを表現できる方法は複数あります。

  • コンポーネント全体がプレビューと見なされる:

    • .NET ランタイムのプレビュー リリースで公開された
    • プレリリース NuGet パッケージで公開された

  • それ以外の場合で、安定したコンポーネントで特定の API がプレビューとしてマークされる:

この記事では、これらのオプションを選ぶ方法と、それぞれのしくみについて説明します。

.NET ランタイム プレビュー

公開ライセンス付きのリリース候補 (RC) を除き、.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

.NET 6 以降、プラットフォームには RequiresPreviewFeaturesAttribute 属性が含まれています。

この属性は、ランタイム、C# コンパイラ、ライブラリなど、スタック全体でのプレビュー動作を必要とする API に使われます。 プロジェクトで <EnablePreviewFeatures>true</EnablePreviewFeatures> を設定していない状態でこの属性でマークした API を使うと、ビルド エラーを受け取ります。 このプロパティを true に設定すると、<LangVersion>Preview</LangVersion> も設定され、プレビュー言語機能を使用できるようになります。

.NET チームは、一般的な数学をテストするために .NET 6 で RequiresPreviewFeaturesAttribute 属性を使いました。これは、当時プレビュー段階だった静的インターフェイス メンバーが必要だったためです。

ExperimentalAttribute

.NET 8 では ExperimentalAttribute が追加されました。これはランタイムや言語プレビューの機能を必要とせず、単に特定の API がまだ安定していないことを示します。

実験的な API に対してビルドすると、コンパイラによってエラーが生成されます。 実験的とマークされた各機能には、独自の個別の診断 ID があります。 これらを使うことに同意を表明するには、特定の診断を抑制します。 診断を抑制する任意の手段でこれを実行できますが、プロジェクトの <NoWarn> プロパティに診断を追加することをお勧めします。

実験的な各機能には個別の ID があるため、ある実験的な機能の使用に同意したとしても、別の実験的機能の使用に同意することにはなりません。

オプションから選ぶ

ライブラリ開発者は、プレリリース NuGet パッケージのみを使うか、API に [Experimental] でマークする必要があります。

  • パッケージのプレリリース バージョンで導入された新しい API の場合は、何もする必要はありません。パッケージが既にプレビュー品質であることを表現しています。

  • いくつかのプレビュー品質 API を含む安定したパッケージをリリースする場合は、[Experimental] を使ってそれらの API をマークする必要があります。 必ず独自の診断 ID を使い、それらの機能に固有のものにしてください。 複数の独立した機能がある場合は、複数の ID を使うことを検討してください。

[RequiresPreviewFeatures] 属性は、.NET プラットフォーム自体のコンポーネントのみを対象としています。 また、その場合でも、ランタイムと言語プレビューの機能を必要とする API にのみ使われます。 プレビュー段階にある 1 つの API のみの場合、.NET プラットフォームは [Experimental] 属性を使います。

この規則の例外は、安定したライブラリをビルドしていて、ランタイムまたは言語プレビューの動作に依存する特定の機能を公開する場合です。 その場合、その機能のエントリ ポイントとして [RequiresPreviewFeatures] を使う必要があります。 ただし、このような API ユーザーはプレビュー機能も有効にする必要があるため、ランタイム、ライブラリ、言語のすべてのプレビュー動作に公開されることを考慮する必要があります。