Attribute für die statische Analyse des NULL-Zustands, die vom C#-Compiler interpretiert wird

In einem Nullable-Kontext führt der Compiler eine statische Analyse des Codes durch, um den NULL-Zustand aller Verweistypvariablen zu bestimmen:

• not-null: Die statische Analyse ermittelt, dass einer Variablen ein Wert ungleich NULL zugewiesen ist.
• maybe-null: Die statische Analyse kann nicht ermittelt, ob einer Variablen ein Wert ungleich NULL zugewiesen ist.

Diese Zustände ermöglichen es dem Compiler, Warnungen bereitzustellen, wenn Sie einen Verweis auf einen NULL-Wert aufheben und dadurch eine System.NullReferenceException auslösen könnten. Diese Attribute stellen dem Compiler semantische Informationen zum NULL-Zustand von Argumenten, Rückgabewerten und Objektmembern basierend auf dem Zustand von Argumenten und Rückgabewerten bereit. Der Compiler gibt genauere Warnungen an, wenn Ihre APIs ordnungsgemäß mit diesen semantischen Informationen versehen wurden.

In diesem Artikel werden diese Attribute der Nullable-Verweistypen und ihre Verwendung kurz beschrieben.

Beginnen wir mit einem Beispiel. Angenommen, Ihre Bibliothek verfügt über die folgende API zum Abrufen einer Ressourcenzeichenfolge. Diese Methode wurde ursprünglich in einem nullable-oblivious-Kontext kompiliert:

bool TryGetMessage(string key, out string message)
{
    if (_messageMap.ContainsKey(key))
        message = _messageMap[key];
    else
        message = null;
    return message != null;
}

Das vorstehende Beispiel folgt dem bekannten Try*-Muster in .NET. Für diese API sind zwei Verweisparameter vorhanden: key und message. In Bezug auf den NULL-Zustand dieser Parameter umfasst diese API die folgenden Regeln:

• Aufrufer dürfen nicht null als Argument für key übergeben.
• Aufrufer können eine Variable übergeben, deren Wert null als Argument für message lautet.
• Wenn die Methode TryGetMessage den Wert true zurückgibt, ist der Wert von message ungleich NULL. Wenn der Rückgabewert lautet, ist falseder Wert null message .

Die Regel für key kann kurz und bündig ausgedrückt werden: key muss ein Non-Nullable-Verweistyp sein. Der Parameter message ist komplexer. Er lässt eine Variable mit dem Wert null als Argument zu, garantiert aber bei einem erfolgreichen Vorgang, dass das out-Argument nicht null ist. Für diese Szenarien ist ein umfangreicheres Vokabular zum Beschreiben der Erwartungen erforderlich. Das unten beschriebene Attribut NotNullWhen beschreibt den NULL-Zustand für das Argument, das für den message-Parameter verwendet wird.

Die vorherigen Beschreibungen sind eine kurze Referenz zur Funktionsweise jedes Attributs. In den folgenden Abschnitten werden Verhalten und Bedeutung dieser Attribute ausführlicher beschrieben.

Vorbedingungen: AllowNull und DisallowNull

Betrachten Sie eine Eigenschaft mit Lese-/Schreibzugriff, die niemals null zurückgibt, weil sie einen angemessen Standardwert aufweist. Aufrufer übergeben null an die set-Zugriffsmethode, wenn diese auf den Standardwert festgelegt wird. Denken Sie zum Beispiel an ein Messagingsystem, das in einem Livechat nach einem Benutzernamen fragt. Wenn kein Name angegeben wird, erzeugt das System einen zufälligen Namen:

public string ScreenName
{
    get => _screenName;
    set => _screenName = value ?? GenerateRandomScreenName();
}
private string _screenName;

Wenn Sie den vorstehenden Code in einem Kontext ohne Nullable-Beachtung kompilieren, ist alles in Ordnung. Sobald Sie Nullable-Verweistypen aktivieren, wird die ScreenName-Eigenschaft zu einem Non-Nullable-Verweis. Dies ist für die get-Zugriffsmethode korrekt: sie gibt nie null zurück. Aufrufer müssen die zurückgegebene Eigenschaft für null nicht überprüfen. Aber bei Festlegung der Eigenschaft auf null wird jetzt eine Warnung generiert. Um diese Art von Code zu unterstützen, fügen Sie der Eigenschaft das Attribut System.Diagnostics.CodeAnalysis.AllowNullAttribute hinzu, wie im folgenden Code gezeigt:

[AllowNull]
public string ScreenName
{
    get => _screenName;
    set => _screenName = value ?? GenerateRandomScreenName();
}
private string _screenName = GenerateRandomScreenName();

Sie müssen möglicherweise eine using-Direktive für System.Diagnostics.CodeAnalysis hinzufügen, um diese und weitere Attribute zu verwenden, die in diesem Artikel besprochen werden. Das Attribut wird auf die Eigenschaft angewendet, nicht auf die set-Zugriffsmethode. Das AllowNull-Attribut gibt Vorbedingungen an und wird nur auf Argumente angewendet. Die get-Zugriffsmethode umfasst einen Rückgabewert, aber keine Parameter. Deshalb gilt das AllowNull-Attribut nur für die set-Zugriffsmethode.

Das vorangehende Beispiel veranschaulicht, wonach beim Hinzufügen des AllowNull-Attributs für ein Argument gesucht werden muss:

1. Der allgemeine Vertrag für diese Variable sieht vor, dass sie nicht null sein darf, deshalb wird ein Non-Nullable-Verweistyp benötigt.
2. Es gibt Szenarien, in denen ein Aufrufer null als Argument übergibt. Diese sind jedoch nicht die Regel.

In den meisten Fällen verwenden Sie dieses Attribut für Eigenschaften oder in-, out- und ref-Argumente. Das AllowNull-Attribut stellt die beste Wahl dar, wenn eine Variable typischerweise ungleich NULL ist, Sie aber null als Vorbedingung zulassen müssen.

Vergleichen Sie dies mit Szenarien für die Verwendung von DisallowNull: Mit diesem Attribut legen Sie fest, dass ein Argument eines Nullwerte zulassenden Verweistyps nicht null sein darf. Nehmen wir als Beispiel eine Eigenschaft, bei der null der Standardwert ist und Clients die Eigenschaft nur auf einen Wert ungleich NULL festlegen können. Betrachten Sie folgenden Code:

public string ReviewComment
{
    get => _comment;
    set => _comment = value ?? throw new ArgumentNullException(nameof(value), "Cannot set to null");
}
string _comment;

Der vorstehende Code ist der beste Weg, um in Ihrem Entwurf auszudrücken, dass ReviewComment den Wert null annehmen könnte, aber nicht auf null festgelegt werden kann. Sobald dieser Code Nullable-fähig ist, können Sie dieses Konzept für Aufrufer mit System.Diagnostics.CodeAnalysis.DisallowNullAttribute klarer ausdrücken:

[DisallowNull]
public string? ReviewComment
{
    get => _comment;
    set => _comment = value ?? throw new ArgumentNullException(nameof(value), "Cannot set to null");
}
string? _comment;

In einem Nullable-Kontext kann die get-Zugriffsmethode von ReviewComment den Standardwert null zurückgeben. Der Compiler gibt eine Warnung aus, dass vor dem Zugriff eine Überprüfung erforderlich ist. Darüber hinaus werden Aufrufer gewarnt, dass der Wert null zwar möglich ist, Aufrufer aber den Wert null nicht explizit festlegen sollten. Das DisallowNull-Attribut gibt ebenfalls eine Vorbedingung an, es hat keine Auswirkung auf die get-Zugriffsmethode. Sie verwenden das DisallowNull-Attribut, wenn folgende Punkte zutreffen:

1. Die Variable könnte in wichtigen Szenarien den Wert null annehmen, häufig bei der ersten Instanziierung.
2. Die Variable darf nicht explizit auf null festgelegt werden.

Diese Situationen sind häufig in Code anzutreffen, in dem NULL-Werte ursprünglich nicht beachtet wurden. Es kann vorkommen, dass Objekteigenschaften in zwei unterschiedlichen Initialisierungsvorgängen festgelegt werden. Einige Eigenschaften werden nur festgelegt, nachdem einige asynchrone Vorgänge ausgeführt wurden.

Mit den Attributen AllowNull und DisallowNull können Sie festlegen, dass Vorbedingungen für Variablen nicht den Nullable-Anmerkungen für diese Variablen entsprechen dürfen. Sie liefern zusätzliche Informationen zu den Merkmalen Ihrer API. Diese zusätzlichen Informationen helfen Aufrufern, Ihre API korrekt zu verwenden. Wie bereits erwähnt, geben Sie Vorbedingungen mit den folgenden Attributen an:

• AllowNull: Ein Non-Nullable-Argument darf NULL sein.
• DisallowNull: Ein Nullwerte zulassendes Argument darf nie NULL sein.

Nachbedingungen: MaybeNull undNotNull

Angenommen, Sie verfügen über eine Methode mit der folgenden Signatur:

public Customer FindCustomer(string lastName, string firstName)

Sie haben wahrscheinlich schon eine Methode wie diese geschrieben, um null zurückzugeben, wenn ein gesuchter Name nicht gefunden wurde. Durch den Wert null wird klar ausgedrückt, dass der Datensatz nicht gefunden wurde. In diesem Beispiel ändern Sie den Rückgabetyp wahrscheinlich von Customer in Customer?. Durch das Deklarieren des Rückgabetyps als Nullable-Verweistyp wird die Absicht dieser API klar ausgedrückt:

public Customer? FindCustomer(string lastName, string firstName)

Aus Gründen, die unter NULL-Zulässigkeit von Generics behandelt werden, führt diese Technik möglicherweise nicht zu der statischen Analyse, die Ihrer API entspricht. Angenommen, Sie verfügen über eine generische Methode, die einem ähnlichen Muster folgt:

public T Find<T>(IEnumerable<T> sequence, Func<T, bool> predicate)

Die Methode gibt null zurück, wenn das gesuchte Element nicht gefunden wird. Sie können festlegen, dass die Methode null zurückgibt, wenn ein Element nicht gefunden wird, indem Sie der Methodenrückgabe die Anmerkung MaybeNull hinzufügen:

[return: MaybeNull]
public T Find<T>(IEnumerable<T> sequence, Func<T, bool> predicate)

Der obige Code informiert Aufrufer darüber, dass der Rückgabewert tatsächlich NULL sein darf. Außerdem wird der Compiler darüber informiert, dass die Methode einen null-Ausdruck zurückgeben kann, obwohl der Typ keine NULL-Werte zulässt. Wenn Sie über eine generische Methode verfügen, die eine Instanz ihres Typparameters (T) zurückgibt, können Sie mithilfe des NotNull-Attributs ausdrücken, dass sie niemals null zurückgibt.

Sie können auch angeben, dass ein Rückgabewert oder ein Argument nicht NULL sein darf, obwohl der Typ ein Nullable-Verweistyp ist. Die folgende Methode ist eine Hilfsmethode, die ausgelöst wird, wenn das erste Argument null ist:

public static void ThrowWhenNull(object value, string valueExpression = "")
{
    if (value is null) throw new ArgumentNullException(nameof(value), valueExpression);
}

Sie können diese Routine folgendermaßen aufrufen:

public static void LogMessage(string? message)
{
    ThrowWhenNull(message, $"{nameof(message)} must not be null");

    Console.WriteLine(message.Length);
}

Nach dem Aktivieren von NULL-Verweistypen möchten Sie sicherstellen, dass der vorstehende Code ohne Warnungen kompiliert wird. Wenn die Methode ein Ergebnis zurückgibt, wird garantiert, dass der value-Parameter ungleich NULL ist. Es ist jedoch weiterhin zulässig, ThrowWhenNull mit einem NULL-Verweis aufzurufen. Sie können value als Nullable-Verweistyp festlegen und die Nachbedingung NotNull zur Parameterdeklaration hinzufügen:

public static void ThrowWhenNull([NotNull] object? value, string valueExpression = "")
{
    _ = value ?? throw new ArgumentNullException(nameof(value), valueExpression);
    // other logic elided

Der vorangehende Code drückt den vorhandenen Vertrag klar aus: Aufrufer können eine Variable mit dem Wert null übergeben, aber es wird garantiert, dass das Argument nie NULL ist, wenn die Methode ohne Auslösen einer Ausnahme zurückgegeben wird.

Sie geben nicht bedingte Nachbedingungen mit den folgenden Attributen an:

• MaybeNull: Ein Non-Nullable-Rückgabewert darf NULL sein.
• NotNull: Ein Nullable-Rückgabetyp ist niemals NULL.

Bedingte Nachbedingungen: NotNullWhen, MaybeNullWhen und NotNullIfNotNull

Ihnen ist die string-Methode String.IsNullOrEmpty(String) wahrscheinlich vertraut. Diese Methode gibt true zurück, wenn das Argument NULL oder eine leere Zeichenfolge ist. Die Methode ist eine Form der NULL-Überprüfung: Aufrufer müssen eine NULL-Überprüfung des Arguments durchführen, wenn die Methode false zurückgibt. Um eine Methode wie diese NULL-fähig zu machen, legen Sie das Argument auf einen Nullable-Verweistyp fest und fügen das NotNullWhen-Attribut hinzu:

bool IsNullOrEmpty([NotNullWhen(false)] string? value)

Auf diese Weise wird der Compiler darüber informiert, dass jeglicher Code mit Rückgabewert false nicht auf NULL überprüft werden muss. Durch das Hinzufügen des Attributs wird die statische Analyse des Compilers darüber informiert, dass IsNullOrEmpty die erforderliche NULL-Überprüfung durchführt: bei Rückgabe von false ist das Argument nicht null.

string? userInput = GetUserInput();
if (!string.IsNullOrEmpty(userInput))
{
    int messageLength = userInput.Length; // no null check needed.
}
// null check needed on userInput here.

Die String.IsNullOrEmpty(String)-Methode wird für .NET Core 3.0 wie oben gezeigt mit Anmerkungen versehen. Sie verwenden möglicherweise ähnliche Methoden in Ihrer Codebasis, die den Zustand von Objekten auf NULL-Werte überprüfen. Der Compiler erkennt keine benutzerdefinierten Methoden für die NULL-Überprüfung, und Sie müssen die Anmerkungen selbst hinzufügen. Wenn Sie das Attribut hinzufügen, hat die statische Analyse des Compilers Kenntnis darüber, wann die getestete Variable auf NULL-Werte überprüft wurde.

Eine weitere Verwendung für diese Attribute ist das Try*-Muster. Die Nachbedingungen für ref- und out-Argumente werden über den Rückgabewert kommuniziert. Betrachten Sie diese oben gezeigte Methode (in einem Non-Nullable-Kontext):

bool TryGetMessage(string key, out string message)
{
    if (_messageMap.ContainsKey(key))
        message = _messageMap[key];
    else
        message = null;
    return message != null;
}

Die vorstehende Methode folgt einem typischen .NET-Idiom: Der Rückgabewert gibt an, ob message auf den gefunden Wert oder – falls „message“ nicht gefunden wird – auf den Standardwert festgelegt wurde. Wenn die Methode true zurückgibt, ist der Wert von message ungleich NULL. Andernfalls legt die Methode message auf NULL fest.

In einem Nullable-Kontext können Sie dieses Idiom mithilfe des Attributs NotNullWhen kommunizieren. Wenn Sie Parameter für Nullable-Verweistypen mit Anmerkungen versehen, ändern Sie message in string?, und fügen Sie ein Attribut hinzu:

bool TryGetMessage(string key, [NotNullWhen(true)] out string? message)
{
    if (_messageMap.ContainsKey(key))
        message = _messageMap[key];
    else
        message = null;
    return message is not null;
}

Im vorstehenden Beispiel ist der Wert von message bekanntermaßen ungleich NULL, wenn TryGetMessage den Wert true zurückgibt. Sie sollten ähnliche Methoden in Ihrer Codebasis in gleicher Weise mit Anmerkungen versehen: Die Argumente könnten null entsprechen und sind bekanntermaßen ungleich NULL, wenn die Methode true zurückgibt.

Es gibt ein letztes Attribut, das Sie möglicherweise ebenfalls benötigen. Gelegentlich hängt der NULL-Zustand eines Rückgabewerts vom NULL-Zustand von mindestens einem Argument ab. Diese Methoden geben einen Nicht-NULL-Wert zurück, wenn bestimmt Argumente nicht null sind. Um diese Methoden korrekt mit Anmerkungen zu versehen, verwenden Sie das NotNullIfNotNull-Attribut. Sehen Sie sich die folgende Methode an:

string GetTopLevelDomainFromFullUrl(string url)

Wenn das url-Argument ungleich NULL ist, ist die Ausgabe nicht null. Sobald Nullable-Verweise aktiviert sind, müssen Sie weitere Anmerkungen hinzufügen, falls Ihre API ein NULL-Argument akzeptieren kann. Sie können den Rückgabetyp wie im folgenden Code gezeigt mit Anmerkungen versehen:

string? GetTopLevelDomainFromFullUrl(string? url)

Dies funktioniert ebenfalls, zwingt die Aufrufer aber häufig dazu, zusätzliche null-Überprüfungen zu implementieren. Der Vertrag sieht vor, dass der Rückgabewert nur dann null lautet, wenn das Argument url den Wert null aufweist. Um diesen Vertrag auszudrücken, versehen Sie die Methode wie im folgenden Code gezeigt mit Anmerkungen:

[return: NotNullIfNotNull(nameof(url))]
string? GetTopLevelDomainFromFullUrl(string? url)

Im obigen Beispiel wird der nameof-Operator für den Parameter url verwendet. Dieses Feature steht in C# 11 zur Verfügung. Vor C# 11 müssen Sie den Namen des Parameters als Zeichenfolge eingeben. Der Rückgabewert und das Argument wurden beide um ? ergänzt, um darauf hinzuweisen, dass beide den Wert null annehmen können. Das Attribut verdeutlicht außerdem, dass der Rückgabewert ungleich NULL ist, wenn das url-Argument ungleich null ist.

Sie geben bedingte Nachbedingungen mit diesen Attributen an:

• MaybeNullWhen: Ein Non-Nullable-Argument darf NULL sein, wenn die Methode den angegebenen bool-Wert zurückgibt.
• NotNullWhen: Ein Nullwerte zulassendes Argument ist nicht NULL, wenn die Methode den angegebenen bool-Wert zurückgibt.
• NotNullIfNotNull: Ein Rückgabewert ist nicht NULL, wenn das Argument für den angegebenen Parameter nicht NULL ist.

Hilfsmethoden: MemberNotNull und MemberNotNullWhen

Diese Attribute geben ihre Absicht an, wenn Sie allgemeinen Code von Konstruktoren in Hilfsmethoden umgestaltet haben. Der C#-Compiler analysiert Konstruktoren und Feldinitialisierer, um sicherzustellen, dass alle Verweisfelder, die keine NULL-Werte zulassen, initialisiert sind, bevor jeder Konstruktor zurückgegeben wird. Der C#-Compiler verfolgt jedoch nicht in allen Hilfsmethoden Feldzuweisungen. Der Compiler gibt die Warnung CS8618 aus, wenn Felder nicht direkt im Konstruktor initialisiert werden, sondern in einer Hilfsmethode. Sie fügen die MemberNotNullAttribute-Klasse einer Methodendeklaration hinzu und geben die Felder an, die mit einem Wert ungleich NULL in der Methode initialisiert werden. Betrachten Sie etwa das folgende Beispiel:

public class Container
{
    private string _uniqueIdentifier; // must be initialized.
    private string? _optionalMessage;

    public Container()
    {
        Helper();
    }

    public Container(string message)
    {
        Helper();
        _optionalMessage = message;
    }

    [MemberNotNull(nameof(_uniqueIdentifier))]
    private void Helper()
    {
        _uniqueIdentifier = DateTime.Now.Ticks.ToString();
    }
}

Sie können mehrere Feldnamen als Argumente für den MemberNotNull-Attributkonstruktor angeben.

Das MemberNotNullWhenAttribute verfügt über ein bool-Argument. Sie verwenden MemberNotNullWhen, wenn die Hilfsmethode ein bool zurückgibt, das angibt, ob Ihre Hilfsmethode Felder initialisiert.

Beenden der Nullable-Analyse bei Auslösen der aufgerufenen Methode

Einige Methoden, typischerweise Ausnahmehilfsmethoden oder andere Hilfsmethoden, werden immer mit Ausgabe einer Ausnahme beendet. Eine Hilfsmethode kann eine Ausnahme basierend auf dem Wert eines booleschen Arguments auslösen.

Im ersten Fall können Sie das DoesNotReturnAttribute-Attribut zur Methodendeklaration hinzufügen. Bei der vom Compiler durchgeführten Analyse des NULL-Zustands wird kein Code in einer Methode überprüft, die auf den Aufruf einer Methode mit der Anmerkung DoesNotReturn folgt. Betrachten Sie diese Methode:

[DoesNotReturn]
private void FailFast()
{
    throw new InvalidOperationException();
}

public void SetState(object containedField)
{
    if (containedField is null)
    {
        FailFast();
    }

    // containedField can't be null:
    _field = containedField;
}

Der Compiler gibt nach dem Aufruf von FailFast keine Warnungen aus.

Im zweiten Fall fügen Sie das System.Diagnostics.CodeAnalysis.DoesNotReturnIfAttribute-Attribut einem booleschen Parameter der Methode hinzu. Sie können das vorherige Beispiel folgendermaßen abändern:

private void FailFastIf([DoesNotReturnIf(true)] bool isNull)
{
    if (isNull)
    {
        throw new InvalidOperationException();
    }
}

public void SetFieldState(object? containedField)
{
    FailFastIf(containedField == null);
    // No warning: containedField can't be null here:
    _field = containedField;
}

Wenn der Wert des Arguments dem Wert des DoesNotReturnIf-Konstruktors entspricht, führt der Compiler nach dieser Methode keine Analyse des NULL-Zustands durch.

Zusammenfassung

Das Hinzufügen von Nullable-Verweistypen ermöglicht eine Beschreibung der Erwartungen für Ihre APIs für Variablen, die den Wert null annehmen könnten. Die Attribute erweitern die Möglichkeiten zur Beschreibung des NULL-Zustands von Variablen als Vor- und Nachbedingungen. Durch diese Attribute werden Ihre Erwartungen klarer beschrieben und verbessern das Benutzererlebnis für Entwickler, die Ihre APIs nutzen.

Wenn Sie Bibliotheken für einen Nullable-Kontext aktualisieren, fügen Sie diese Attribute hinzu, um Benutzer bei der richtigen Verwendung Ihrer APIs zu unterstützen. Diese Attribute unterstützen Sie bei der vollständigen Beschreibung des NULL-Zustands von Argumenten und Rückgabewerten.

• AllowNull: Non-Nullable-Felder, -Parameter oder -Eigenschaften dürfen NULL sein.
• DisallowNull: Nullable-Felder, -Parameter oder -Eigenschaften dürfen niemals NULL sein.
• MaybeNull: Non-Nullable-Felder, -Parameter, -Eigenschaften oder -Rückgabewerte dürfen NULL sein.
• NotNull: Nullable-Felder, -Parameter, -Eigenschaften oder -Rückgabewerte sind niemals NULL.
• MaybeNullWhen: Ein Non-Nullable-Argument darf NULL sein, wenn die Methode den angegebenen bool-Wert zurückgibt.
• NotNullWhen: Ein Nullwerte zulassendes Argument ist nicht NULL, wenn die Methode den angegebenen bool-Wert zurückgibt.
• NotNullIfNotNull: Parameter, Eigenschaften oder Rückgabewerte sind nicht NULL, wenn das Argument für den angegebenen Parameter nicht NULL ist.
• DoesNotReturn: Eine Methode oder Eigenschaft gibt niemals ein Ergebnis zurück. Anders ausgedrückt: Die Methode löst immer eine Ausnahme aus.
• DoesNotReturnIf: Diese Methode oder Eigenschaft gibt niemals ein Ergebnis zurück, wenn der zugeordnete bool-Parameter den angegebenen Wert aufweist.