CA1700: Namnge inte uppräkningsvärdena "Reserverade"
| Property | Värde |
|---|---|
| Regel-ID | CA1700 |
| Title | Namnge inte uppräkningsvärdena "Reserverade" |
| Kategori | Namngivning |
| Korrigeringen är icke-bakåtkompatibel | Brott |
| Aktiverad som standard i .NET 9 | Nej |
Orsak
Namnet på en uppräkningsmedlem innehåller ordet "reserverad".
Regelbeskrivning
Den här regeln förutsätter att en uppräkningsmedlem som har ett namn som innehåller "reserverad" inte används för närvarande, men är en platshållare som ska byta namn eller tas bort i en framtida version. Att byta namn på eller ta bort en medlem är en icke-bakåtkompatibel ändring. Du bör inte förvänta dig att användarna ignorerar en medlem bara för att namnet innehåller "reserverat" och du kan inte heller lita på att användarna läser eller följer dokumentationen. Eftersom reserverade medlemmar visas i objektwebbläsare och smarta integrerade utvecklingsmiljöer kan de dessutom orsaka förvirring om vilka medlemmar som faktiskt används.
I stället för att använda en reserverad medlem lägger du till en ny medlem i uppräkningen i den framtida versionen. I de flesta fall är tillägget av den nya medlemmen inte en icke-bakåtkompatibel ändring, så länge tillägget inte gör att de ursprungliga medlemmarnas värden ändras.
I ett begränsat antal fall är tillägget av en medlem en icke-bakåtkompatibel ändring även när de ursprungliga medlemmarna behåller sina ursprungliga värden. Den nya medlemmen kan i första hand inte returneras från befintliga kodsökvägar utan att anropare som använder en switch (Select i Visual Basic) -instruktion på returvärdet som omfattar hela medlemslistan och som utlöser ett undantag i standardfallet. Ett sekundärt problem är att klientkoden kanske inte hanterar beteendeförändringen från reflektionsmetoder som System.Enum.IsDefined. Om den nya medlemmen därför måste returneras från befintliga metoder eller om ett känt program är inkompatibilitet på grund av dålig reflektionsanvändning är den enda icke-inbrytande lösningen att:
Lägg till en ny uppräkning som innehåller de ursprungliga och nya medlemmarna.
Markera den ursprungliga uppräkningen med attributet System.ObsoleteAttribute .
Följ samma procedur för alla externt synliga typer eller medlemmar som exponerar den ursprungliga uppräkningen.
Så här åtgärdar du överträdelser
Om du vill åtgärda ett brott mot den här regeln tar du bort eller byter namn på medlemmen.
När du ska ignorera varningar
Det är säkert att ignorera en varning från den här regeln för en medlem som för närvarande används eller för bibliotek som tidigare har levererats.
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 CA1700
// The code that's violating the rule is on this line.
#pragma warning restore CA1700
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.CA1700.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 det här alternativet för bara 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
Relaterade regler
CA2217: Markera inte uppräkningar med FlagsAttribute
CA1712: Ange inte prefixvärden med typnamn
CA1028: Uppräkningslagring ska vara Int32
