Rozwiązywanie ostrzeżeń o wartości null

Wskazówka

Nie znasz typów referencyjnych dopuszczających wartość null? Najpierw przeczytaj artykuł Typy referencyjne dopuszczające wartość null, aby zrozumieć adnotacje i analizę stanu null. W tym artykule założono, że w projekcie są wyświetlane ostrzeżenia, w których funkcja jest włączona.

Szukasz określonego kodu błędu kompilatora? Artykuł referencyjny Rozwiązywanie ostrzeżeń dotyczących typów dopuszczających wartość null zawiera wykaz wszystkich ostrzeżeń CS86xx wraz z odpowiadającą im techniką.

Po włączeniu typów referencyjnych dopuszczających wartość null kompilator generuje ostrzeżenia wszędzie tam, gdzie zachowanie kodu nie jest zgodne z jego adnotacjami. Większość ostrzeżeń należy do małego zestawu wzorców. Po rozpoznaniu wzorca poprawka jest zwykle jedną z pięciu technik:

  • Dodaj sprawdzanie wartości null.
  • Dodaj lub usuń adnotację ?lub!.
  • Dodaj atrybut opisujący kontrakt o wartości null.
  • Zainicjuj zmienne poprawnie.
  • Sprawdź ustawienie projektu.

W tym artykule przedstawiono poszczególne techniki z reprezentatywnym przykładem. Celem nie jest wyciszenie ostrzeżeń. Chodzi o to, aby jawnie określić intencję kodu dotyczącą obsługi wartości null, tak by kompilator doszedł do tych samych wniosków co ty.

Stan null: co śledzi kompilator

Zanim zapoznasz się z technikami, pomoże to dowiedzieć się, jak kompilator śledzi potencjalne naruszenia stanu null. Podczas analizy Twojego kodu kompilator śledzi stan null każdego wyrażenia: określa, czy w danym miejscu w kodzie wyrażenie może mieć wartość null. Stan null jest jedną z dwóch wartości:

  • not-null — kompilator może udowodnić, że wyrażenie tutaj nie jest null. Można go bezpiecznie używać bez sprawdzania.
  • może mieć wartość null — kompilator nie może wykluczyć null. Użycie wyrażenia bez sprawdzania powoduje wygenerowanie ostrzeżenia.

Stan wartości null zmiennej zmienia się, gdy kompilator śledzi kod. Metoda, która może zwracać null , generuje wynik może o wartości null . Sprawdzenie if (x is not null) zawęża x do wartości różnej od null wewnątrz bloku if. Ostrzeżenia, które widzisz, to komunikaty kompilatora informujące, że ustalił on, iż wyrażenie może mieć wartość null, a Ty zamierzasz użyć go tak, jakby nie miało wartości null. Każda technika w pozostałej części tego artykułu to inny sposób na nadanie kompilatorowi informacji potrzebnych do zapewnienia, że wyrażenie nie ma wartości null przed jego użyciem.

Dodaj sprawdzenie null

Najczęstszym ostrzeżeniem jest możliwe odwołanie do wartości null. Kompilator ustalił, że stan null zmiennej to maybe-null, i wykrył, że została ona użyta bez sprawdzenia:

public static int LengthOfMessageUnsafe(string? message)
{
    // Warning CS8602: dereference of a possibly null reference.
    return message.Length;
}

Poprawka to zwykle klauzula ochronna. Klauzula ochronna to sprawdzenie na początku metody lub bloku, które powoduje zwrot lub zgłoszenie wyjątku, gdy dane wejściowe są nieprawidłowe. Tylko bezpieczna ścieżka będzie kontynuowana. Po wykonaniu sprawdzenia kompilator aktualizuje stan nullowalności zmiennej na not-null na bezpiecznej ścieżce:

public static int DereferenceFixed(string? message)
{
    if (message is null)
    {
        return 0;
    }

    // No warning: the compiler knows message is not-null on this path.
    return message.Length;
}

Dopasowywanie do wzorca (wyrażenia, takie jak is null lub is { }, które sprawdzają strukturę wartości), ?? i ??= obejmują sprawdzenia wartości null:

public static int NullOperatorsFix(string? message)
{
    // ?. evaluates to null if message is null; ?? supplies the fallback value.
    int length = message?.Length ?? 0;

    // Pattern matching narrows the type on the matching branch.
    if (message is { Length: > 0 })
    {
        length = message.Length;
    }

    return length;
}

Wzorzec właściwości { Length: > 0 } pasuje tylko wtedy, gdy message nie ma wartości null i właściwość Length ma wartość większą od zera, więc kompilator traktuje message jako niemające wartości null wewnątrz bloku if. Prostszy test is not null daje to samo zawężenie do stanu null bez sprawdzania żadnych właściwości.

Aby zapoznać się ze szczegółowym omówieniem operatorów, zobacz temat Operatory null.

Dostosowywanie adnotacji

Kompilator ostrzega również, gdy w kodzie przypisujesz wyrażenie mogące mieć wartość null do zmiennej niedopuszczającej wartości null. To ostrzeżenie oznacza jedną z dwóch rzeczy:

  • Zmienna powinna zezwalać na wartości null. W takim przypadku dodaj element ? do typu .
  • Wyrażenie nigdy nie generuje wartości null. Dodaj adnotację do interfejsu API, który go wygenerował.
public static void AssignmentWarning()
{
    // Warning CS8600: converting null literal or possible null value to non-nullable type.
    string name = Lookup("nobody");
    Console.WriteLine(name);
}

Jeśli Lookup legalnie zwraca wartość null, zmień witrynę wywołania, aby akceptowała brakującą wartość:

public static void AssignmentFixed()
{
    string? name = Lookup("somebody");
    if (name is not null)
    {
        Console.WriteLine(name);
    }
}

Jeśli Lookup nigdy nie zwraca wartości null, zmień jego sygnaturę tak, aby zwracała typ referencyjny niedopuszczający wartości null. Scenariusze, w których stan null zwracanej wartości zależy od danych wejściowych, zobacz następującą sekcję dotyczącą atrybutów analizy wartości null.

Użyj operatora ! tłumiącego ostrzeżenie o wartości null tylko wtedy, gdy masz pewność, że wartość nie jest null, ale nie możesz wyrazić tej gwarancji w systemie typów. Każde ! to miejsce, w którym kompilator nie jest już w stanie cię chronić, dlatego lepiej dodać sprawdzenie lub adnotację do źródłowego interfejsu API.

Dodaj atrybut analizy null

Czasami właściwa poprawka nie znajduje się w lokacji połączenia. Podpis metody nie przechwytuje relacji między jego danymi wejściowymi i wyjściowymi wystarczająco dokładnie, a kompilator wyświetla ostrzeżenia wewnątrz kodu bezpiecznego w inny sposób:

public static bool IsPresent(string? text) =>
    !string.IsNullOrEmpty(text);

public static void CallerWithoutAttribute(string? text)
{
    if (IsPresent(text))
    {
        // Warning CS8602: dereference of a possibly null reference.
        // The signature doesn't tell the compiler text is not-null here.
        Console.WriteLine(text.Length);
    }
}

Treść elementu IsPresent dowodzi, że argument nie ma wartości null, gdy metoda zwraca true, ale sygnatura tego nie wskazuje. Dodaj atrybut analizy dopuszczającego wartość null , aby utworzyć część kontraktu interfejsu API:

public static bool AttributedIsPresent([NotNullWhen(true)] string? text) =>
    !string.IsNullOrEmpty(text);

public static void CallerWithAttribute(string? text)
{
    if (AttributedIsPresent(text))
    {
        // No warning: the attribute tells the compiler text is not-null.
        Console.WriteLine(text.Length);
    }
}

Typowe atrybuty obejmują:

Pełna lista znajduje się w sekcji Atrybuty analizy statycznej dopuszczające wartość null.

Inicjowanie elementów członkowskich nieprzyjmujących wartości null

Ostrzeżenie konstruktora oznacza, że pole, właściwość lub właściwość automatyczna nie dopuszczające wartości null (właściwość korzystająca z pola zapasowego wygenerowanego przez kompilator, na przykład public string Name { get; set; }) po zakończeniu działania konstruktora pozostaje bez przypisanej wartości innej niż null:

public class PersonUninitialized
{
    // Warning CS8618: Non-nullable property 'Name' is uninitialized.
    public string Name { get; set; }
}

Istnieje kilka sposobów, aby rozwiązać ten problem. Wybierz ten, który najlepiej pasuje do intencji projektu.

Wymagaj wartości jako argumentu konstruktora. Użyj konstruktora podstawowego (parametry zadeklarowane dla samego typu, dostępnego w całej treści) lub zwykłego konstruktora, który inicjuje właściwość:

public class PersonInjected(string name)
{
    public string Name { get; } = name;
}

Ustaw właściwość required. Kod wywołujący musi zainicjować go za pomocą inicjalizatora obiektu (składni { Property = value }, która występuje po new):

public class PersonRequired
{
    public required string Name { get; init; }
}

Zainicjuj wartością domyślną. Gdy typ ma sensowną pustą wartość, zainicjuj go przy deklaracji:

public class PersonInitialized
{
    public string Name { get; set; } = "John Doe";
}

Wskazówka

Wybierz tę technikę tylko wtedy, gdy typ ma naprawdę dobrą wartość domyślną: taką, która jest prawidłowym, w pełni funkcjonalnym wystąpieniem używanym przez osoby wywołujące. Przykłady obejmują puste kolekcje. Nie wymyślaj wartości wartownika (wartości zastępczej, takiej jak String.Empty, "N/A", "unknown" lub -1, traktowanej jako „brak wartości”) jako zastępstwa dla null: wycisza ona ostrzeżenie, ale każdy kod wywołujący musi wiedzieć o istnieniu tej wartości i ją sprawdzać, a system typów nie może w tym pomóc. Jeśli nie istnieje dobra wartość domyślna, zamiast tego ustaw właściwość na wartość null.

Ustaw właściwość na wartość null. Gdy wartość rzeczywiście może być pusta, zmień typ na dopuszczający wartość null:

public class PersonOptional
{
    public string? Name { get; set; }
}

Jeśli metoda pomocnicza inicjalizuje składową, oznacz ją adnotacją MemberNotNullAttribute, aby kompilator mógł przypisać do niej wywołania.

Weryfikowanie ustawienia projektu

Nowe projekty w języku C# domyślnie włączają typy referencyjne dopuszczające wartość null, więc większość kodu, który piszesz lub czytasz, ma już tę funkcję włączoną. Zazwyczaj nie trzeba nic konfigurować. Jeśli zastanawiasz się, czy projekt ma to włączone, lub musisz zmienić to ustawienie, poszukaj elementu <Nullable> w elemencie .csproj:

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

Typowe obsługiwane wartości to enable (wartość domyślna dla nowych projektów) i disable. Jeśli brakuje elementu, projekt używa dowolnego domyślnego zestawu SDK i platformy docelowej.

Jeśli musisz włączyć obsługę wartości null tylko w części pliku za pomocą dyrektyw #nullable, albo użyć trybów częściowych warnings i annotations podczas migrowania istniejącej bazy kodu, zobacz Strategie migracji obsługi wartości null.

Gdzie iść dalej

Jeśli ostrzeżenie nie pasuje do żadnego z tych wzorców, artykuł referencyjny Rozwiązywanie ostrzeżeń o wartości null zawiera listę technik dla każdego ostrzeżenia CS86xx emitowanego przez kompilator.

Aby zaplanować migrację, która stopniowo włącza typy referencyjne dopuszczające wartość null w istniejącej bazie kodu, zobacz Strategie migracji typów referencyjnych dopuszczających wartość null.