CA1710: Identifikátory by měly mít správnou příponu

  • Článek
Vlastnost Hodnota
ID pravidla CA1710
Název Identifikátory by měly mít správnou příponu
Kategorie Pojmenování
Oprava způsobující chybu nebo chybu způsobující chybu Narušující
Povoleno ve výchozím nastavení v .NET 8 No

Příčina

Identifikátor nemá správnou příponu.

Ve výchozím nastavení toto pravidlo sleduje jenom externě viditelné identifikátory, ale dá se konfigurovat.

Popis pravidla

Podle konvence mají názvy typů, které rozšiřují určité základní typy nebo implementují určitá rozhraní nebo typy odvozené z těchto typů, příponu přidruženou k základnímu typu nebo rozhraní.

Konvence vytváření názvů poskytují společný vzhled knihoven, které cílí na modul CLR (Common Language Runtime). To snižuje křivku učení, která je nutná pro nové softwarové knihovny, a zvyšuje důvěru zákazníků, že knihovna byla vyvinuta někým, kdo má zkušenosti s vývojem spravovaného kódu.

Následující tabulka uvádí základní typy a rozhraní, která mají přidružené přípony.

Základní typ/rozhraní Přípona
System.Attribute Atribut
System.EventArgs Eventargs
System.Exception Výjimka
System.Collections.ICollection Kolekce
System.Collections.IDictionary Slovník
System.Collections.IEnumerable Kolekce
System.Collections.Generic.IReadOnlyDictionary<TKey,TValue> Slovník
System.Collections.Queue Kolekce nebo fronta
System.Collections.Stack Kolekce nebo zásobník
System.Collections.Generic.ICollection<T> Kolekce
System.Collections.Generic.IDictionary<TKey,TValue> Slovník
System.Data.DataSet DataSet
System.Data.DataTable Shromažďování nebo datová tabulka
System.IO.Stream Stream
System.Security.IPermission Oprávnění
System.Security.Policy.IMembershipCondition Podmínka
Delegát obslužné rutiny události. Eventhandler

Typy, které implementují ICollection a jsou generalizovaným typem datové struktury, jako je slovník, zásobník nebo fronta, jsou povolené názvy, které poskytují smysluplné informace o zamýšleném použití typu.

Typy, které implementují ICollection a jsou kolekcí konkrétních položek, mají názvy, které končí slovem "Kolekce". Například kolekce Queue objektů by měla název QueueCollection. Přípona Collection označuje, že členové kolekce mohou být výčet pomocí foreach příkazu (For Each v jazyce Visual Basic).

Typy, které implementují IDictionary nebo IReadOnlyDictionary<TKey,TValue> mají názvy, které končí slovem "Slovník", i když typ také implementuje IEnumerable nebo ICollection. Zásady vytváření názvů přípony Collection a Dictionary umožňují uživatelům rozlišovat mezi následujícími dvěma vzory výčtu.

Typy s příponou Collection se řídí tímto vzorem výčtu.

foreach(SomeType x in SomeCollection) { }

Typy s příponou Dictionary se řídí tímto vzorem výčtu.

foreach(SomeType x in SomeDictionary.Values) { }

Objekt DataSet se skládá z kolekce DataTable objektů, která se skládá z kolekcí System.Data.DataColumn a System.Data.DataRow objektů, mimo jiné. Tyto kolekce implementují ICollection prostřednictvím základní System.Data.InternalDataCollectionBase třídy.

Jak opravit porušení

Typ přejmenujte tak, aby byl příponován správným termínem.

Kdy potlačit upozornění

Pokud je typ zobecněnou datovou strukturou, která může být rozšířena nebo která bude obsahovat libovolnou sadu různorodých položek, je bezpečné potlačit upozornění na použití přípony Kolekce. V tomto případě může mít název, který poskytuje smysluplné informace o implementaci, výkonu nebo jiných vlastnostech datové struktury (například BinaryTree). V případech, kdy typ představuje kolekci určitého typu (například StringCollection), nepotlačujte upozornění z tohoto pravidla, protože přípona označuje, že typ lze vytvořit výčet pomocí foreach příkazu.

U jiných přípon nepotlačujte upozornění z tohoto pravidla. Přípona umožňuje, aby zamýšlené použití bylo zřejmé z názvu typu.

Potlačení upozornění

Pokud chcete pouze potlačit jedno porušení, přidejte do zdrojového souboru direktivy preprocesoru, abyste pravidlo zakázali a znovu povolili.

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

Pokud chcete pravidlo pro soubor, složku nebo projekt zakázat, nastavte jeho závažnost v none konfiguračním souboru.

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

Další informace naleznete v tématu Jak potlačit upozornění analýzy kódu.

Konfigurace kódu pro analýzu

Pomocí následujících možností můžete nakonfigurovat, pro které části základu kódu se má toto pravidlo spouštět.

Tyto možnosti můžete nakonfigurovat jenom pro toto pravidlo, pro všechna pravidla, která platí, nebo pro všechna pravidla v této kategorii (pojmenování), na která platí. Další informace naleznete v tématu Možnosti konfigurace pravidla kvality kódu.

Zahrnutí konkrétních povrchů rozhraní API

Na základě přístupnosti můžete nakonfigurovat, na kterých částech základu kódu se má toto pravidlo spouštět. Pokud chcete například určit, že pravidlo by se mělo spouštět jenom na neveřejné ploše rozhraní API, přidejte do souboru .editorconfig v projektu následující pár klíč-hodnota:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Vyloučení nepřímých základních typů

Můžete nakonfigurovat, jestli chcete vyloučit nepřímé základní typy z pravidla. Ve výchozím nastavení je tato možnost nastavená na hodnotu True, která omezuje analýzu na aktuální základní typ.

dotnet_code_quality.CA1710.exclude_indirect_base_types = false

Další požadované přípony

Můžete zadat další požadované přípony nebo přepsat chování některých pevně zakódovaných přípon přidáním následujícího páru klíč-hodnota do souboru .editorconfig v projektu:

dotnet_code_quality.CA1710.additional_required_suffixes = [type]->[suffix]

Oddělte více hodnot znakem | . Typy lze zadat v některém z následujících formátů:

  • Pouze název typu (zahrnuje všechny typy s názvem bez ohledu na typ nebo obor názvů).
  • Plně kvalifikované názvy ve formátu ID dokumentace symbolu s volitelnou T: předponou.

Příklady:

Hodnota možnosti Shrnutí
dotnet_code_quality.CA1710.additional_required_suffixes = MyClass->Class Všechny typy, které dědí z myClass, musí mít příponu Class.
dotnet_code_quality.CA1710.additional_required_suffixes = MyClass->Class|MyNamespace.IPath->Path Všechny typy, které dědí z myClass, musí mít příponu Class A všechny typy, které implementují MyNamespace.IPath, musí mít příponu Path.
dotnet_code_quality.CA1710.additional_required_suffixes = T:System.Data.IDataReader->{} Přepíše předdefinované přípony. V tomto případě už nejsou všechny typy, které implementují "IDataReader", nutné k ukončení kolekce.

CA1711: Identifikátory by neměly mít nesprávnou příponu

Viz také