Steeltoe icon indicating copy to clipboard operation
Steeltoe copied to clipboard

Adopt nullable reference types

Open bart-vmware opened this issue 3 years ago • 0 comments

This issue tracks annotating the codebase for nullable reference types.

General guidance:

  • Compile/test against .NET 7 or higher (only the core libraries are annotated in .NET 6, and several are wrong)
  • Always declare collection properties using interfaces (IList<JsonService> instead of List<JsonService>)
  • IOptions pattern
    • Declare collection properties as non-nullable get-only and initialize with an empty collection
      • They cannot be set to null from JSON, see https://github.com/dotnet/extensions/issues/1341
      • The configuration binder supports adding to an existing collection instance
    • Always declare scalar reference-type properties as nullable (and null-check before use)
      • There's no guarantee that IConfigureOptions<> has executed before usage
      • Developers may register their own IConfigureOptions<> that sets the value to null
      • The property may be explicitly set to null from appsettings.json
  • Types used in JSON serialization
    • Declare collection properties with both a getter and a setter
      • Although [JsonObjectCreationHandling(JsonObjectCreationHandling.Populate)] was added in .NET 8, it cannot be combined with custom converters (so adding one later would require a breaking change)
    • Deserialization
      • Declare collection properties as nullable if null has a semantic meaning that differs from an empty collection, or when it's unknown whether the source may produce nulls.
      • Initialize with an empty collection if not declared as nullable
    • Serialization
      • It's safest to declare all reference-type properties as nullable, because it affects the JSON output
        • If a collection is conditionally populated (ie null has meaning), make the property nullable
        • If a collection is always populated, declare it as non-nullable and initialize with an empty collection
  • Other types
    • Declare all required properties as non-nullable
      • Replace property setters with a constructor that takes all required properties, and add guard checks
  • Try to minimize the use of the ! operator to suppress nullability warnings; consider adding a comment when unobvious

bart-vmware avatar Jul 29 '22 15:07 bart-vmware