Een codebasis bijwerken met null-referentietypen om diagnostische waarschuwingen voor null te verbeteren

Met null-verwijzingstypen kunt u declareren of variabelen van een verwijzingstype wel of niet aan een null waarde moeten worden toegewezen. De statische analyse en waarschuwingen van de compiler wanneer uw code mogelijk deductie null het belangrijkste voordeel van deze functie is. Zodra deze functie is ingeschakeld, genereert de compiler waarschuwingen waarmee u kunt voorkomen dat u een System.NullReferenceException code genereert wanneer de code wordt uitgevoerd.

Als uw codebasis relatief klein is, kunt u de functie inschakelen in uw project, adreswaarschuwingen en profiteren van de voordelen van de verbeterde diagnostische gegevens. Voor grotere codebases is mogelijk een meer gestructureerde benadering nodig om waarschuwingen in de loop van de tijd aan te pakken, waardoor de functie voor sommigen kan worden ingeschakeld wanneer u waarschuwingen in verschillende typen of bestanden adresseert. In dit artikel worden verschillende strategieën beschreven voor het bijwerken van een codebasis en de compromissen die aan deze strategieën zijn gekoppeld. Lees het conceptuele overzicht van null-referentietypen voordat u begint met de migratie. Het omvat de statische analyse van de compiler, null-statuswaarden van misschien-null en niet-null en de null-aantekeningen. Zodra u bekend bent met deze concepten en termen, bent u klaar om uw code te migreren.

Uw migratie plannen

Ongeacht hoe u uw codebasis bijwerkt, is het doel dat null-waarschuwingen en null-aantekeningen zijn ingeschakeld in uw project. Zodra u dat doel hebt bereikt, hebt u de <nullable>Enable</nullable> instelling in uw project. U hebt geen van de preprocessor-instructies nodig om instellingen elders aan te passen.

Notitie

U kunt een Nullable instelling voor uw project aanwijzen met behulp van een <Nullable> tag. Raadpleeg de compileropties voor meer informatie.

De eerste keuze is het instellen van de standaardwaarde voor het project. Uw keuzes zijn:

1. Nullable disable as the default: disable is the default if you don't add a Nullable element to your project file. Gebruik deze standaardinstelling wanneer u niet actief nieuwe bestanden toevoegt aan de codebasis. De belangrijkste activiteit is het bijwerken van de bibliotheek voor het gebruik van null-referentietypen. Als u deze standaardwaarde gebruikt, voegt u een nullable preprocessor-instructie toe aan elk bestand wanneer u de code bijwerkt.
2. Nullable inschakelen als de standaardinstelling: stel deze standaard in wanneer u actief nieuwe functies ontwikkelt. U wilt dat alle nieuwe code profiteert van null-referentietypen en statische analyse die null kan worden uitgevoerd. Als u deze standaardwaarde gebruikt, moet u een #nullable disable boven aan elk bestand toevoegen. U verwijdert deze preprocessor-instructies terwijl u de waarschuwingen in elk bestand adresseert.
3. Null-waarschuwingen als de standaardinstelling: kies deze standaardinstelling voor een migratie met twee fasen. In de eerste fase adresseert u waarschuwingen. Schakel in de tweede fase aantekeningen in voor het declareren van de verwachte null-status van een variabele. Als u deze standaardwaarde gebruikt, moet u een #nullable disable boven aan elk bestand toevoegen.
4. Null-aantekeningen als de standaardwaarde. Aantekeningen toevoegen aan code voordat u waarschuwingen adresseert.

Als u nullable inschakelt omdat standaard meer werk vooraf wordt gemaakt om de preprocessor-instructies aan elk bestand toe te voegen. Het voordeel is dat elk nieuw codebestand dat aan het project wordt toegevoegd, null-able is ingeschakeld. Nieuw werk is null-compatibel; alleen bestaande code moet worden bijgewerkt. Het uitschakelen van null-functionaliteit omdat de standaardinstelling beter werkt als de bibliotheek stabiel is en de belangrijkste focus van de ontwikkeling is om null-referentietypen te gebruiken. U schakelt null-referentietypen in terwijl u aantekeningen op API's aantekent. Wanneer u klaar bent, schakelt u null-referentietypen in voor het hele project. Wanneer u een nieuw bestand maakt, moet u de preprocessor-instructies toevoegen en er null-bewust van maken. Als ontwikkelaars in uw team vergeten, bevindt die nieuwe code zich nu in de achterstand van het werk om alle code nullable aware te maken.

Welke van deze strategieën u kiest, is afhankelijk van hoeveel actieve ontwikkeling er in uw project plaatsvindt. Hoe volwassener en stabieler uw project, hoe beter de tweede strategie. Hoe meer functies worden ontwikkeld, hoe beter de eerste strategie.

Belangrijk

De globale null-context is niet van toepassing op gegenereerde codebestanden. Onder een van beide strategieën wordt de null-context uitgeschakeld voor elk bronbestand dat is gemarkeerd als gegenereerd. Dit betekent dat api's in gegenereerde bestanden niet worden geannoteerd. Er zijn vier manieren waarop een bestand wordt gemarkeerd als gegenereerd:

1. Geef generated_code = true in de .editorconfig een sectie op die van toepassing is op dat bestand.
2. Plaats <auto-generated> of <auto-generated/> in een opmerking boven aan het bestand. Het kan op elke regel in die opmerking staan, maar het opmerkingenblok moet het eerste element in het bestand zijn.
3. Start de bestandsnaam met TemporaryGeneratedFile_
4. Beëindig de bestandsnaam met .designer.cs, .generated.cs, .g.cs of .g.i.cs.

Generatoren kunnen zich aanmelden met behulp van de #nullable preprocessorrichtlijn.

Contexten en waarschuwingen begrijpen

Als u waarschuwingen en aantekeningen inschakelt, bepaalt u hoe de compiler referentietypen en null-waarde weergeeft. Elk type heeft een van de drie nullabiliteiten:

• vergetelheid: alle verwijzingstypen kunnen niet worden vergeten wanneer de context van de aantekening is uitgeschakeld.
• niet-inulleerbaar: een niet-geannoteerd verwijzingstype is C niet mogelijk wanneer de aantekeningscontext is ingeschakeld.
• nullable: een geannoteerd verwijzingstype, C?is null-baar, maar er kan een waarschuwing worden weergegeven wanneer de aantekeningscontext is uitgeschakeld. Variabelen die zijn gedeclareerd met var zijn nullable wanneer de aantekeningscontext is ingeschakeld.

De compiler genereert waarschuwingen op basis van die null-baarheid:

• niet-inullable typen veroorzaken waarschuwingen als er een mogelijke null waarde aan hen is toegewezen.
• Null-typen veroorzaken waarschuwingen als ze worden gededucteerd wanneer misschien-null.
• Vergetele typen veroorzaken waarschuwingen als ze worden gededucteerd wanneer misschien null en de waarschuwingscontext is ingeschakeld.

Elke variabele heeft een standaard null-status die afhankelijk is van de null-waarde:

• Null-variabelen hebben een standaard null-status van misschien-null.
• Niet-null-variabelen hebben een standaard null-status van not-null.
• Nullable ob vergetelheidsvariabelen hebben een standaard null-status van not-null.

Voordat u null-verwijzingstypen inschakelt, zijn alle declaraties in uw codebasis nullable. Dat is belangrijk omdat dit betekent dat alle verwijzingstypen een standaard null-status van not-null hebben.

Adreswaarschuwingen

Als uw project Gebruikmaakt van Entity Framework Core, moet u de richtlijnen voor het werken met null-referentietypen lezen.

Wanneer u de migratie start, moet u alleen waarschuwingen inschakelen. Alle declaraties blijven onbeleefd, maar u ziet waarschuwingen wanneer u een waarde deducteert nadat de null-status is gewijzigd in misschien-null. Wanneer u deze waarschuwingen adresseert, controleert u op null op meer locaties en wordt uw codebasis toleranter. Zie het artikel over technieken voor het oplossen van null-waarschuwingen voor specifieke technieken voor verschillende situaties.

U kunt waarschuwingen adresseren en aantekeningen inschakelen in elk bestand of elke klasse voordat u verdergaat met andere code. Het is echter vaak efficiënter om de waarschuwingen aan te pakken die worden gegenereerd terwijl de context waarschuwingen is voordat u de typeaantekeningen inschakelt. Op die manier zijn alle typen vergeten totdat u de eerste set waarschuwingen hebt aangepakt.

Typeaantekeningen inschakelen

Nadat u de eerste set waarschuwingen hebt aangepakt, kunt u de aantekeningscontext inschakelen. Hiermee worden verwijzingstypen gewijzigd van vergeteld tot niet-ullable. Alle variabelen die zijn gedeclareerd met var zijn nullable. Deze wijziging introduceert vaak nieuwe waarschuwingen. De eerste stap bij het aanpakken van de compilerwaarschuwingen is het gebruik ? van aantekeningen voor parameters en retourtypen om aan te geven wanneer argumenten of retourwaarden kunnen zijn null. Als u deze taak uitvoert, is het niet alleen uw doel om waarschuwingen op te lossen. Het belangrijkste doel is om de compiler inzicht te geven in uw intentie voor mogelijke null-waarden.

Kenmerken breiden typeaantekeningen uit

Er zijn verschillende kenmerken toegevoegd om aanvullende informatie over de null-status van variabelen uit te drukken. De regels voor uw API's zijn waarschijnlijk gecompliceerder dan niet-null of misschien null voor alle parameters en retourwaarden. Veel van uw API's hebben complexere regels voor wanneer variabelen wel of niet kunnen zijn null. In deze gevallen gebruikt u kenmerken om deze regels uit te drukken. De kenmerken die de semantiek van uw API beschrijven, vindt u in het artikel over kenmerken die van invloed zijn op null-analyse.

Volgende stappen

Nadat u alle waarschuwingen hebt geadresseerd nadat u aantekeningen hebt ingeschakeld, kunt u de standaardcontext voor uw project instellen op ingeschakeld. Als u pragma's in uw code hebt toegevoegd voor de context van null-aantekening of waarschuwing, kunt u deze verwijderen. Na verloop van tijd ziet u mogelijk nieuwe waarschuwingen. U kunt code schrijven waarmee waarschuwingen worden geïntroduceerd. Een bibliotheekafhankelijkheid kan worden bijgewerkt voor null-verwijzingstypen. Met deze updates worden de typen in die bibliotheek gewijzigd van onbeleefd in niet-ullable of nullable.

U kunt deze concepten ook verkennen in onze Learn-module over nullable veiligheid in C#.