Uppdatera en kodbas med null-referenstyper för att förbättra diagnostikvarningar för null

Artikel
03/02/2024

Med nullbara referenstyper kan du deklarera om variabler av en referenstyp ska eller inte ska tilldelas ett null värde. Kompilatorns statiska analys och varningar när koden kan avreferera null är den viktigaste fördelen med den här funktionen. När den är aktiverad genererar kompilatorn varningar som hjälper dig att undvika att utlösa en System.NullReferenceException när koden körs.

Om din kodbas är relativt liten kan du aktivera funktionen i projektet, åtgärda varningar och dra nytta av fördelarna med den förbättrade diagnostiken. Större kodbaser kan kräva en mer strukturerad metod för att hantera varningar över tid, vilket aktiverar funktionen för vissa när du hanterar varningar i olika typer eller filer. Den här artikeln beskriver olika strategier för att uppdatera en kodbas och de kompromisser som är associerade med dessa strategier. Innan du påbörjar migreringen läser du den konceptuella översikten över null-referenstyper. Den omfattar kompilatorns statiska analys, null-state-värden för kanske-null och not-null och de nullbara anteckningarna. När du är bekant med dessa begrepp och termer är du redo att migrera koden.

Planera migrationen

Oavsett hur du uppdaterar din kodbas är målet att nullbara varningar och ogiltiga anteckningar är aktiverade i projektet. När du når det målet har du inställningen <nullable>Enable</nullable> i projektet. Du behöver inte något av förprocessordirektiven för att justera inställningarna någon annanstans.

Det första valet är att ange standardvärdet för projektet. Alternativen är:

Nullbar inaktivera som standard: inaktivera är standard om du inte lägger till ett Nullable element i projektfilen. Använd den här standardinställningen när du inte aktivt lägger till nya filer i kodbasen. Huvudaktiviteten är att uppdatera biblioteket så att det använder nullbara referenstyper. Med den här standardinställningen lägger du till ett null-direktiv för förprocessorer i varje fil när du uppdaterar koden.
Nullbar aktivering som standard: Ange den här standardinställningen när du aktivt utvecklar nya funktioner. Du vill att all ny kod ska dra nytta av nullbara referenstyper och statisk analys som kan upphävas. Om du använder den här standardinställningen måste du lägga till en #nullable disable överst i varje fil. Du tar bort de här förprocessordirektiven när du hanterar varningarna i varje fil.
Nullbara varningar som standard: Välj det här standardvärdet för en tvåfasmigrering. I den första fasen ska du åtgärda varningar. I den andra fasen aktiverar du anteckningar för att deklarera en variabels förväntade null-tillstånd. Om du använder den här standardinställningen måste du lägga till en #nullable disable överst i varje fil.
Ogiltiga anteckningar som standard. Kommentera kod innan du åtgärdar varningar.

Om du aktiverar null som standard skapas mer arbete i förväg för att lägga till förprocessordirektiven i varje fil. Fördelen är att varje ny kodfil som läggs till i projektet är nullaktiverad. Alla nya arbeten kommer att vara null-medvetna. endast befintlig kod måste uppdateras. Det går bättre att inaktivera null eftersom standardvärdet fungerar bättre om biblioteket är stabilt och huvudfokus för utvecklingen är att använda nullbara referenstyper. Du aktiverar nullbara referenstyper när du kommenterar API:er. När du är klar aktiverar du nullbara referenstyper för hela projektet. När du skapar en ny fil måste du lägga till förprocessordirektiven och göra den nullbar. Om några utvecklare i ditt team glömmer bort att den nya koden nu är i kvarvarande arbete för att göra all kod nullable medveten.

Vilka av dessa strategier du väljer beror på hur mycket aktiv utveckling som sker i ditt projekt. Ju mognare och stabilare ditt projekt är, desto bättre blir den andra strategin. Ju fler funktioner som utvecklas, desto bättre är den första strategin.

Viktigt!

Den globala nullbara kontexten gäller inte för genererade kodfiler. Under någon av strategierna inaktiveras den nullbara kontexten för alla källfiler som har markerats som genererade. Det innebär att alla API:er i genererade filer inte kommenteras. Det finns fyra sätt som en fil markeras som genererad:

I .editorconfig anger du generated_code = true i ett avsnitt som gäller för filen.
Placera <auto-generated> eller <auto-generated/> i en kommentar överst i filen. Det kan finnas på valfri rad i kommentaren, men kommentarsblocket måste vara det första elementet i filen.
Starta filnamnet med TemporaryGeneratedFile_
Avsluta filnamnet med .designer.cs, .generated.cs, .g.cs eller .g.i.cs.

Generatorer kan välja att använda #nullable förprocessordirektivet.

Förstå kontexter och varningar

Aktivering av varningar och anteckningar styr hur kompilatorn visar referenstyper och nullabilitet. Varje typ har en av tre null-skulder:

omedveten: Alla referenstyper är ogiltiga när anteckningskontexten är inaktiverad.
icke-inullerbar: En ej kommenterad referenstyp C kan inte visas när anteckningskontexten är aktiverad.
nullable: En kommenterad referenstyp, C?, är null, men en varning kan utfärdas när anteckningskontexten är inaktiverad. Variabler som deklareras med var är nullbara när anteckningskontexten är aktiverad.

Kompilatorn genererar varningar baserat på den nullabiliteten:

icke-inullerbara typer orsakar varningar om ett potentiellt null värde tilldelas dem.
nullable types orsakar varningar om de avrefererade när kanske-null.
ovetande typer orsakar varningar om de avrefereras när kanske null och varningskontexten är aktiverad.

Varje variabel har ett nullbart standardtillstånd som är beroende av dess nullbarhet:

Nullbara variabler har ett standard-null-tillstånd på kanske-null.
Variabler som inte kan null-värden har ett null-standardtillstånd som inte är null.
Ogiltiga omedvetna variabler har standardvärdet null-statenot-null.

Innan du aktiverar nullbara referenstyper är alla deklarationer i kodbasen ogiltiga. Det är viktigt eftersom det innebär att alla referenstyper har null-standardtillståndet not-null.

Adressvarningar

Om ditt projekt använder Entity Framework Core bör du läsa deras vägledning om Att arbeta med referenstyper som kan användas som null.

När du påbörjar migreringen bör du bara börja med att aktivera varningar. Alla deklarationer är fortfarande ogiltiga, men du ser varningar när du avreferera ett värde efter dess null-tillståndsändringar till kanske-null. När du hanterar dessa varningar kontrollerar du mot null på fler platser och din kodbas blir mer motståndskraftig. Mer information om specifika tekniker för olika situationer finns i artikeln om tekniker för att lösa nullbara varningar.

Du kan åtgärda varningar och aktivera anteckningar i varje fil eller klass innan du fortsätter med annan kod. Det är dock ofta mer effektivt att hantera de varningar som genereras medan kontexten är varningar innan du aktiverar typanteckningarna. På så sätt är alla typer omedvetna tills du har tagit itu med den första uppsättningen varningar.

Aktivera typanteckningar

När du har tagit itu med den första uppsättningen varningar kan du aktivera anteckningskontexten. Detta ändrar referenstyper från omedveten till icke-inullbar. Alla variabler som deklareras med var är nullbara. Den här ändringen introducerar ofta nya varningar. Det första steget för att hantera kompilatorvarningarna är att använda ? anteckningar på parametern och returnera typer för att ange när argument eller returvärden kan vara null. När du gör den här uppgiften är målet inte bara att åtgärda varningar. Det viktigaste målet är att få kompilatorn att förstå din avsikt med potentiella null-värden.

Attribut utökar typkommentarer

Flera attribut har lagts till för att uttrycka ytterligare information om null-tillståndet för variabler. Reglerna för dina API:er är sannolikt mer komplicerade än inte null eller kanske null för alla parametrar och returvärden. Många av dina API:er har mer komplexa regler för när variabler kan eller inte kan vara null. I dessa fall använder du attribut för att uttrycka dessa regler. De attribut som beskriver semantiken för ditt API finns i artikeln om attribut som påverkar nullbar analys.

Nästa steg

När du har åtgärdat alla varningar när du har aktiverat anteckningar kan du ange standardkontexten för projektet till aktiverad. Om du har lagt till några pragmas i koden för den nullbara kommentaren eller varningskontexten kan du ta bort dem. Med tiden kan du se nya varningar. Du kan skriva kod som introducerar varningar. Ett biblioteksberoende kan uppdateras för null-referenstyper. Dessa uppdateringar ändrar typerna i biblioteket från nullbar omedveten till antingen icke-inullerbar eller nullbar.

Du kan också utforska dessa begrepp i vår Learn-modul om nullbar säkerhet i C#.