Dela via

CA1710: Identifierare bör ha rätt suffix

  • Artikel
Property Värde
Regel-ID CA1710
Title Identifierare ska ha rätt suffix
Kategori Namngivning
Korrigeringen är icke-bakåtkompatibel Bryta
Aktiverad som standard i .NET 8 Nej

Orsak

En identifierare har inte rätt suffix.

Som standard tittar den här regeln bara på externt synliga identifierare, men det kan konfigureras.

Regelbeskrivning

Enligt konventionen har namnen på typer som utökar vissa bastyper eller som implementerar vissa gränssnitt, eller typer som härletts från dessa typer, ett suffix som är associerat med bastypen eller gränssnittet.

Namngivningskonventioner ger ett vanligt utseende för bibliotek som riktar sig till den gemensamma språkkörningen. Detta minskar inlärningskurvan som krävs för nya programvarubibliotek och ökar kundernas förtroende för att biblioteket har utvecklats av någon som har kunskaper om att utveckla hanterad kod.

I följande tabell visas de bastyper och gränssnitt som har associerade suffix.

Bastyp/gränssnitt Suffix
System.Attribute Attribut
System.EventArgs Eventargs
System.Exception Undantag
System.Collections.ICollection Samling
System.Collections.IDictionary Ordlista
System.Collections.IEnumerable Samling
System.Collections.Generic.IReadOnlyDictionary<TKey,TValue> Ordlista
System.Collections.Queue Samling eller kö
System.Collections.Stack Samling eller stack
System.Collections.Generic.ICollection<T> Samling
System.Collections.Generic.IDictionary<TKey,TValue> Ordlista
System.Data.DataSet Datamängd
System.Data.DataTable Samling eller DataTable
System.IO.Stream Stream
System.Security.IPermission Behörighet
System.Security.Policy.IMembershipCondition Villkor
En händelsehanterardelegat. Eventhandler

Typer som implementerar ICollection och är en generaliserad typ av datastruktur, till exempel en ordlista, stack eller kö, är tillåtna namn som ger meningsfull information om den avsedda användningen av typen.

Typer som implementerar ICollection och är en samling specifika objekt har namn som slutar med ordet "Samling". En samling Queue objekt skulle till exempel ha namnet QueueCollection. Suffixet "Samling" betyder att medlemmarna i samlingen kan räknas upp med hjälp av instruktionen foreach (For Each i Visual Basic).

Typer som implementerar IDictionary eller IReadOnlyDictionary<TKey,TValue> har namn som slutar med ordet "Ordlista" även om typen även implementerar IEnumerable eller ICollection. Namngivningskonventionerna "Samling" och "Ordlista" gör det möjligt för användare att skilja mellan följande två uppräkningsmönster.

Typer med suffixet "Samling" följer det här uppräkningsmönstret.

foreach(SomeType x in SomeCollection) { }

Typer med suffixet Ordlista följer det här uppräkningsmönstret.

foreach(SomeType x in SomeDictionary.Values) { }

Ett DataSet objekt består av en samling DataTable objekt, som bland annat består av samlingar av System.Data.DataColumn och System.Data.DataRow objekt. Dessa samlingar implementeras ICollection via basklassen System.Data.InternalDataCollectionBase .

Så här åtgärdar du överträdelser

Byt namn på typen så att den är suffix med rätt term.

När du ska ignorera varningar

Det är säkert att ignorera en varning om att använda suffixet "Samling" om typen är en generaliserad datastruktur som kan utökas eller som innehåller en godtycklig uppsättning olika objekt. I det här fallet kan ett namn som ger meningsfull information om implementeringen, prestandan eller andra egenskaper hos datastrukturen vara meningsfullt (till exempel BinaryTree). Om typen representerar en samling av en viss typ (till exempel StringCollection) ska du inte ignorera en varning från den här regeln eftersom suffixet anger att typen kan räknas upp med hjälp av en foreach -instruktion.

För andra suffix ska du inte ignorera en varning från den här regeln. Med suffixet kan den avsedda användningen vara tydlig från typnamnet.

Ignorera en varning

Om du bara vill förhindra en enda överträdelse lägger du till förprocessordirektiv i källfilen för att inaktivera och aktiverar sedan regeln igen.

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

Om du vill inaktivera regeln för en fil, mapp eller ett projekt anger du dess allvarlighetsgrad till none i konfigurationsfilen.

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

Mer information finns i Så här utelämnar du kodanalysvarningar.

Konfigurera kod för analys

Använd följande alternativ för att konfigurera vilka delar av kodbasen som regeln ska köras på.

Du kan konfigurera dessa alternativ för just den här regeln, för alla regler som den gäller för eller för alla regler i den här kategorin (namngivning) som den gäller för. Mer information finns i Konfigurationsalternativ för kodkvalitetsregel.

Inkludera specifika API-ytor

Du kan konfigurera vilka delar av kodbasen som ska köras med den här regeln baserat på deras tillgänglighet. Om du till exempel vill ange att regeln endast ska köras mot den icke-offentliga API-ytan lägger du till följande nyckel/värde-par i en .editorconfig-fil i projektet:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Exkludera indirekta bastyper

Du kan konfigurera om du vill undanta indirekta bastyper från regeln. Som standard är det här alternativet inställt på true, vilket begränsar analysen till den aktuella bastypen.

dotnet_code_quality.CA1710.exclude_indirect_base_types = false

Ytterligare nödvändiga suffix

Du kan ange ytterligare nödvändiga suffix eller åsidosätta beteendet för vissa hårdkodade suffix genom att lägga till följande nyckel/värde-par i en .editorconfig-fil i projektet:

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

Avgränsa flera värden med ett | tecken. Typer kan anges i något av följande format:

  • Skriv endast namn (innehåller alla typer med namnet, oavsett vilken typ eller namnrymd som innehåller).
  • Fullständigt kvalificerade namn i symbolens dokumentations-ID-format med ett valfritt T: prefix.

Exempel:

Alternativvärde Sammanfattning
dotnet_code_quality.CA1710.additional_required_suffixes = MyClass->Class Alla typer som ärver från "MyClass" måste ha suffixet Klass.
dotnet_code_quality.CA1710.additional_required_suffixes = MyClass->Class|MyNamespace.IPath->Path Alla typer som ärver från "MyClass" måste ha suffixet Klass och alla typer som implementerar "MyNamespace.IPath" måste ha suffixet "Path".
dotnet_code_quality.CA1710.additional_required_suffixes = T:System.Data.IDataReader->{} Åsidosätter inbyggda suffix. I det här fallet krävs inte längre alla typer som implementerar "IDataReader" för att sluta i "Samling".

CA1711: Identifierare bör inte ha fel suffix

Se även