Share via

CA1700: Namnge inte uppräkningsvärdena "Reserverade"

  • Artikel
Property Värde
Regel-ID CA1700
Rubrik Namnge inte uppräkningsvärdena "Reserverade"
Kategori Namngivning
Korrigeringen är icke-bakåtkompatibel Bryta
Aktiverad som standard i .NET 8 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:

  1. Lägg till en ny uppräkning som innehåller de ursprungliga och nya medlemmarna.

  2. 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

CA2217: Markera inte uppräkningar med FlagsAttribute

CA1712: Ange inte prefixvärden med typnamn

CA1028: Uppräkningslagring ska vara Int32

CA1008: Uppräkningar bör ha noll värde

CA1027: Markera uppräkningar med FlagsAttribute