Sdílet prostřednictvím

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 9 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 Attribute
System.EventArgs EventArgs
System.Exception Exception
System.Collections.ICollection Collection
System.Collections.IDictionary Dictionary
System.Collections.IEnumerable Collection
System.Collections.Generic.IReadOnlyDictionary<TKey,TValue> Dictionary
System.Collections.Queue Collection nebo Queue
System.Collections.Stack Collection nebo Stack
System.Collections.Generic.ICollection<T> Collection
System.Collections.Generic.IDictionary<TKey,TValue> Dictionary
System.Data.DataSet DataSet
System.Data.DataTable Collection nebo DataTable
System.IO.Stream Stream
System.Security.IPermission Permission
System.Security.Policy.IMembershipCondition Condition
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 Collection. 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í příkazu foreach (For Each v jazyce Visual Basic).

Typy, které implementují IDictionary nebo IReadOnlyDictionary<TKey,TValue> mají názvy, které končí slovem Dictionary i v případě, že typ také implementuje IEnumerable nebo ICollection. Zásady vytváření názvů přípon 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í

Je bezpečné potlačit upozornění na použití přípony Collection, pokud je typ generalizovanou datovou strukturou, která může být rozšířena nebo která bude obsahovat libovolnou sadu různorodých položek. 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í pro, nebo pro všechna pravidla v této kategorii (pojmenování), na která se vztahují. Další informace naleznete v tématu Možnosti konfigurace pravidla kvality kódu.

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

Nastavením možnosti api_surface můžete nakonfigurovat, na kterých částech základu kódu se má toto pravidlo spouštět na základě jejich přístupnosti. 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

Poznámka

Nahraďte XXXX část CAXXXX ID příslušného pravidla.

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é