CA1700:列挙型値に 'Reserved' という名前を指定しません

  • [アーティクル]
プロパティ 値
ルール ID CA1700
Title 列挙型値に 'Reserved' という名前を指定しません
[カテゴリ] 名前を付ける
修正が中断ありか中断なしか あり
.NET 8 では既定で有効 いいえ

原因

列挙型メンバーの名前に "reserved" という語が含まれています。

規則の説明

この規則では、"reserved" を含む名前の列挙体のメンバーは、現在使用されていなくても、将来的なバージョンでは名前を変更するか削除されるプレースホルダーと想定しています。 メンバーの名前変更や削除は、互換性に影響する変更点です。 メンバー名に "reserved" が含まれているからといって、ユーザーがそのメンバーを必ず無視するとは考えないでください。また、ユーザーが必ずドキュメントを読み、それに従うと期待することもできません。 さらに、予約されたメンバーはオブジェクト ブラウザーおよびスマート統合開発環境に表示されるため、実際に使用されているメンバーについて混乱を招く可能性があります。

予約されたメンバーを使用する代わりに、新しいバージョンの列挙型には新しいメンバーを追加します。 ほとんどの場合、新しいメンバーを追加しても、それによって元のメンバーの値が変更されない限り、破壊的変更となることはありません。

限られたケースではありますが、元のメンバーが元の値を保持している場合でも、メンバーの追加によって破壊的変更となる場合があります。 まず、メンバー リスト全体を含み、既定のケースで例外をスローする戻り値に対して switch (Visual Basic では Select) ステートメントを使用する呼び出し元を中断せずに、既存のコード パスから新しいメンバーを返すことはできません。 2 つ目の懸念事項として、クライアント コードが、System.Enum.IsDefined などのリフレクション メソッドからの動作の変更を処理しない可能性があります。 したがって、既存のメソッドから新しいメンバーを返す必要がある場合、またはリフレクションの使用率が低いために互換性のない既知のアプリケーションが発生した場合、唯一の非破壊的な解決策は次のようになります。

  1. 元のメンバーと新しいメンバーを含む新しい列挙型を追加します。

  2. 元の列挙型を System.ObsoleteAttribute 属性にします。

    元の列挙型を公開する外部から参照できる型またはメンバーについても、同じ手順を実行します。

違反の修正方法

この規則違反を修正するには、メンバーを削除するか、その名前を変更します。

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

現在使用されているメンバー、または以前に出荷されたライブラリに対しては、この規則による警告を抑制しても問題ありません。

警告を抑制する

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

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

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

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

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

分析するコードを構成する

次のオプションを使用して、コードベースのどの部分に対してこの規則を実行するか構成します。

このオプションを構成できる対象は、この規則だけ、それを適用するすべての規則、それを適用するこのカテゴリ (名前付け) のすべての規則のいずれかです。 詳細については、「コード品質規則の構成オプション」を参照してください。

特定の API サーフェイスを含める

ユーザー補助に基づいて、この規則を実行するコードベースの部分を構成できます。 たとえば、非パブリック API サーフェイスでのみ規則を実行するように指定するには、プロジェクトの .editorconfig ファイルに次のキーと値のペアを追加します。

dotnet_code_quality.CAXXXX.api_surface = private, internal

CA2217:列挙型を FlagsAttribute に設定しません

CA1712:列挙型値を型名のプレフィックスにしません

CA1028:列挙ストレージは Int32 でなければなりません

CA1008:Enums は 0 値を含んでいなければなりません

CA1027:列挙型を FlagsAttribute に設定します