Migreringsstrategier som kan upphävas

När du aktiverar nullbara referenstyper i ett stort projekt som startades innan nullbara referenstyper introducerades, genererar kompilatorn många varningar samtidigt. Migrering handlar om sekvensering av arbetet: att välja en standardkontext, exponera varningsfilen efter fil eller avsnitt efter avsnitt och konvergera <Nullable>enable</Nullable> för hela projektet. Rätt sekvens beror på hur aktiv kodbasen är och hur stor risk du kan ta i ett enda pass.

Sluttillståndet är detsamma i alla fall: projektet anger <Nullable>enable</Nullable> och innehåller inga #nullable förprocessordirektiv.

Välj en standardkontext

Kontexten för nullbarhet har två oberoende flaggor: annoteringar (om ? deklarerar en nullbar referenstyp) och varningar (om kompilatorn avger diagnostik). Ställ in dem som ett enda <Nullable> värde:

Välj den strategi som bäst matchar målen för projektmigreringen:

• Inaktivera som standard. Ange <Nullable>disable</Nullable> och lägg till #nullable enable överst i varje fil när du migrerar den. Befintliga filer förblir nullable-oblivious tills du rör dem. Det här alternativet har den lägsta friktionen för stabila bibliotek eftersom det är ovanligt med nytt funktionsarbete.
• Aktivera som standard. Ange <Nullable>enable</Nullable> och lägg till #nullable disable överst i varje fil som du inte har migrerat ännu. Varje ny fil är nullable-aware från början, så migreringsloggen kan bara krympa. Det här valet är bättre när utvecklingen är aktiv.
• Varningar som standard. Ange <Nullable>warnings</Nullable>. Välj den här standardinställningen för en tvåfasmigrering: hantera varningar medan varje referenstyp fortfarande behandlas som icke-annoterad och aktivera sedan annoteringar. Tvåfasdelningen håller varje stegs diff fokuserat.
• Anteckningar som standard. Ange <Nullable>annotations</Nullable>. Börja med att annotera ditt offentliga API (? på medlemmar som tillåter null) innan du åtgärdar varningar. Kompilatorn genererar ännu inga varningar, så du kan fastställa API:ets utformning utan att bli distraherad.

Projektfilen styr det globala standardvärdet. #nullable preprocessor-direktiv åsidosätter den standardinställningen för en kodregion:

<PropertyGroup>
  <Nullable>enable</Nullable>
</PropertyGroup>

I källfilerna väljer direktivet en region in eller ut ur projektets null-inställning:

#nullable disable
public static class LegacyHelper
{
    // This file is nullable-oblivious. Reference types use the legacy rules.
    public static string GetGreeting(string name) =>
        name == null ? "hello" : $"hello {name}";
}
#nullable restore

#nullable enable
public static class MigratedHelper
{
    // This file is fully migrated. Reference types are non-nullable by default.
    public static string GetGreeting(string? name) =>
        name is null ? "hello" : $"hello {name}";
}
#nullable restore

Migrera fil efter fil

Det mest förutsägbara sättet att migrera ett stort projekt är att aktivera varningar eller anteckningar fil för fil. Mönstret är detsamma oavsett vilken standard du väljer:

1. Välj en fil. Börja med de djupaste lövtyperna i beroendediagrammet och flytta sedan utåt. Att kommentera en typ orsakar nya varningar i anroparna, så att arbeta nedifrån och upp minimerar omarbetet.
2. Lägg till det #nullable direktiv som väljer filen i det nya beteendet. Använd #nullable enable om du vill ha båda flaggorna. Använd #nullable enable warnings endast för varning.
3. Åtgärda varningarna i filen med hjälp av teknikerna i Lös nullbara varningar.
4. Upprepa för nästa fil.
5. När varje fil i projektet har sitt direktiv tar du bort direktiven och ställer in <Nullable>enable</Nullable> dem på projektnivå.

Om din kodbas redan har <Nullable>enable</Nullable>kör du motsatt riktning. Ignorera varningar i omigrerade filer tills du är klar. Använd #nullable disable för att välja bort filer och ta sedan bort undertryckningarna en i taget.

Migrera i två faser

En migrering i två steg separerar de två typerna av arbete som nullbara referenstyper innebär. Du kan ordna faserna i valfri ordning, beroende på vilken form av stabilitet som betyder mest för dig.

Varningar först, sedan anteckningar

Börja med varningar när det är prioriterat att åtgärda latenta System.NullReferenceException buggar:

1. Fas 1: Åtgärda varningar. Ange standardvärdet för projektet till warnings. Referenstyper förblir nullable-oblivious, så typsystemet ändras inte ännu. Kompilatorn genererar varningar överallt där din befintliga kod kanske redan genererar en System.NullReferenceException. Lägg till nullkontroller, omstrukturera flödet eller använd attribut tills projektet är fritt från varningar. Varje korrigering gör produktionskoden mer elastisk även innan anteckningar finns.
2. Fas 2: Lägg till anteckningar. Växla standardvärdet för projektet till enable. Referenstyper är nu icke-nullbara som standard, och var lokala variabler blir nullbara. Nya varningar återspeglar deklarationer som inte matchar hur variablerna används. Lägg till ? i typer som ska tillåta null. Dra åt API:er som ska kräva indata som inte är null.

Anteckningar först och sedan varningar

Prioritera annoteringar när det är prioriterat att stabilisera den offentliga API-ytan. Den här sekvensen passar bibliotek: du kan skicka kommenterade signaturer så att användarna ser rätt kontrakt och sedan stänga de interna varningarna enligt ditt eget schema.

1. Fas 1: Lägg till anteckningar. Ange standardvärdet för projektet till annotations. Referenstyper blir inte nullbara som standard, men kompilatorn avger inte varningar, så bruset förblir ur vägen. Gå igenom det offentliga API:et och lägg till ? för varje medlem som med rätta kan returnera eller acceptera null. Dra åt signaturerna som inte borde göra det. Eftersom varningar är avstängda kan du fastställa API:ets utformning i avgränsade incheckningar utan att samtidigt behöva reda ut implementeringen.
2. Fas 2: Åtgärda varningar. Växla standardvärdet för projektet till enable. Anteckningarna som du lade till i fas 1 matar nu in null-tillståndsanalys, så varningarna som kompilatorn genererar är av högre kvalitet från början: var och en pekar på kod vars beteende inte matchar det kontrakt som du redan har publicerat. Lös dem med teknikerna i Lös nullbara varningar.

Välja mellan beställningarna

Varje ordningsföljd delar upp faserna i mindre diffar som är lättare att granska. Den ena fasen ändrar bara beteendet, och den andra ändrar bara typerna. Nackdelen är att du besöker varje fil två gånger. För mogen, stabil kod där varje ändring medför risk är de två passen vanligtvis värda det. Välj varningar först om du framför allt vill härda kod som körs. Välj annoteringar först när du helst vill publicera ett stabilt kontrakt.

Genererad kod undantas

Kompilatorn behandlar filer som markerats som genererade som om den nullbara kontexten inaktiverades, oavsett projektets inställning. En fil anses genereras när något av följande villkor är uppfyllda:

• En .editorconfig regel anger generated_code = true för filen.
• Den första kommentaren i filen innehåller <auto-generated> eller <auto-generated/>.
• Filnamnet börjar med TemporaryGeneratedFile_.
• Filnamnet slutar med .designer.cs, .generated.cs, .g.cseller .g.i.cs.

Generatorer som producerar nullmedvetna utdata kan välja att åter aktivera detta genom att skriva ut #nullable enable längst upp i den genererade filen.

När du är klar

När varje fil har deltagit i projektets standardvärde och elementet <Nullable>enable</Nullable> har angetts:

• Ta bort alla #nullable direktiv i källan.
• Ta bort null! och default! initierare som du bara har lagt till för att tysta varningar under migreringen. Ersätt dem med rätt initiering eller gör typen till en nullbar referenstyp.
• Kontrollera det offentliga API:et på plats. Varje medlem som returnerar eller accepterar null ska kommenteras med ?. Anteckningarna är en del av ditt kontrakt när paketet levereras.

Nu är du i samma läge som nya projekt: referenstyper som kan ha värdet null är en del av typsystemet, och alla nya varningar återspeglar en verklig inkonsekvens mellan deklarationer och kod. Använd Lös null-varningar för att åtgärda dem när de kommer upp.

Relaterat innehåll

• Referenstyper som kan ogiltigförklaras
• Lösa null-varningar
• Statiska analysattribut som kan ogiltigförklaras
• Arbeta med null-referenstyper i EF Core