CA2252: プレビュー機能を使用する前にオプトインする

プロパティ	値
ルール ID	CA2252
Title	プレビュー機能を使用する前にオプトインする
[カテゴリ]	使用方法
修正が中断ありか中断なしか	なし
.NET 8 では既定で有効	エラーとして

原因

クライアントが、ローカルで、あるいはモジュールまたはアセンブリ レベルで明示的にオプトインすることなく、プレビュー API またはそれらのアセンブリ内の型を使用する。

規則の説明

RequiresPreviewFeaturesAttribute 属性で修飾された API またはアセンブリが使用される場合、この規則によって、呼び出しサイトがプレビュー機能をオプトインしているかどうかがチェックされます。 次のいずれかに該当する場合は、呼び出しサイトによってプレビュー機能がオプトインされています。

• RequiresPreviewFeaturesAttribute 注釈のスコープ内である場合。
• プレビュー機能を既にオプトインしているアセンブリまたはモジュールの一部である場合。

次の図は、CA2252 診断の例を示しています。

ここで、Lib は Main メソッド内で構築されるプレビュー型です。 Main 自体にプレビュー メソッドとして注釈が付けられていないため、Main 内の 2 つのコンストラクター呼び出しで診断が生成されます。

違反の修正方法

違反を修正するには、次の 2 つの方法があります。

• 呼び出しサイトを、その親に RequiresPreviewFeaturesAttribute 注釈を付けることで、注釈のスコープ内に入れます。 上記の例では、APreviewMethod に RequiresPreviewFeatures 属性で注釈が付けられているため、APreviewMethod 内ではアナライザーによってプレビュー型の使用が無視されます。 したがって、APreviewMethod の呼び出し元でも同様の処理を行う必要があります。

• アセンブリまたはモジュール レベルでプレビュー機能をオプトインすることもできます。 これは、アナライザーに対して、アセンブリ内でのプレビュー型の使用が必要であることを示します。その結果、この規則によってエラーが生成されなくなります。 これは、プレビューの依存関係を使用する場合に推奨される方法です。 アセンブリ全体内でプレビュー機能を有効にするには、.csproj ファイルで EnablePreviewFeatures プロパティを設定します。

  <PropertyGroup>
    <EnablePreviewFeatures>true</EnablePreviewFeatures>
  </PropertyGroup>

どのようなときに警告を抑制するか

この規則による警告を抑制することをお勧めするのは、API の診断を明示的に無効にする必要がある高度なユース ケースのみです。 この場合は、プレビュー API を適切にマークする責任をご自身で負う必要があります。 たとえば、既存の型で新しいプレビュー インターフェイスを実装する場合を考えてみます。 (下位互換性のために) 型全体をプレビューとしてマークすることはできないため、型定義に関する診断をローカルで無効にすることができます。 さらに、プレビュー インターフェイスの実装をプレビューとしてマークする必要があります。 これで、既存の型は以前と同様に使用できますが、新しいインターフェイス メソッドを呼び出した場合は診断が取得されます。 System.Private.CoreLib.csproj では、この手法を使用して、Int32、Double、Decimal などの数値型に対するジェネリックな数値演算機能が公開されています。

次の図は、CA2252 アナライザーをローカルで無効にする方法を示しています。

Note

次のすべてに該当する場合、このルールから擬陽性の警告が表示される場合があります。

• Visual Studio 2022 バージョン 17.5 以降を NET SDK の古いバージョン (.NET 6 以前) で使用している場合。
• .NET 6 SDK またはそれ以前のバージョンのアナライザー パッケージ (Microsoft.CodeAnalysis.FxCopAnalyzers など) のアナライザーを使用している。

この場合は、擬陽性の警告を抑制しても差しつかえありません。 この擬陽性は、C# コンパイラの破壊的変更が原因です。 擬陽性警告の修正プログラムを含む新しいアナライザーの使用を検討してください。 Microsoft.CodeAnalysis.NetAnalyzers バージョン 7.0.0-preview1.22464.1 以降にアップグレードするか、.NET 7 SDK のアナライザーを使用します。

警告を抑制する

単一の違反を抑制するだけの場合は、ソース ファイルにプリプロセッサ ディレクティブを追加して無効にしてから、規則をもう一度有効にします。

#pragma warning disable CA2252
// The code that's violating the rule is on this line.
#pragma warning restore CA2252

ファイル、フォルダー、またはプロジェクトのルールを無効にするには、構成ファイルでその重要度を none に設定します。

[*.{cs,vb}]
dotnet_diagnostic.CA2252.severity = none

規則のこのカテゴリ全体を無効にするには、構成ファイルでカテゴリの重要度を none に設定します。

[*.{cs,vb}]
dotnet_analyzer_diagnostic.category-Usage.severity = none

詳細については、「コード分析の警告を抑制する方法」を参照してください。

こちらもご覧ください

• EnablePreviewFeatures と GenerateRequiresPreviewFeaturesAttribute
• プレビュー機能の設計に関するドキュメント