[Breaking change]: FilePatternMatch.Stem annotated as non-nullable

[jeffhandley]

Description

The FilePatternMatch.Stem property was previously annotated as nullable purely because the PatternTestResult.Stem property it gets its value from is nullable. While the PatternTestResult can indeed be null if the result is not successful, the FilePatternMatch never is because it is only ever constructed when PatternTestResult is successful.

To accurately reflect nullability here, the [MemberNotNullWhen()] attribute is applied to the PatternTestResult.Stem property to tell the compiler it will not be null if it is successful and then pass it along to the new non-nullable string constructor of FilePatternMatch. Additionally, the stem argument passed into the FilePatternMatch constructor is changed to no longer be nullable.

See dotnet/runtime#118410 and dotnet/runtime#116982 for more info.

Version

.NET 10 RC 1

Previous behavior

The FilePatternMatch constructor would accept a null for stem without any compile-time or run-time warnings or errors. The PatternTestResult.Stem property was also annotated as being nullable.

New behavior

Passing a null or possibly-null value to the stem argument in the FilePatternMatch constructor will yield a compile-time warning, and if null is passed in, a run-time ArgumentNullException will be thrown. Additionally, the PatternTestResult.Stem property is annotated indicating the value will not be null IsSuccessful is true.

Type of breaking change

• Binary incompatible: Existing binaries might encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code might require source changes to compile successfully.
• Behavioral change: Existing binaries might behave differently at run time.

Reason for change

The previous nullability annotations were inaccurate, and a null value for the stem argument was unexpected but not properly guarded against. This change reflects the expected behavior of the API and guards against unpredictable behavior while also producing design-time guidance around usage.

Recommended action

If a possibly-null value was passed in for the stem argument, review usage and update the call site to ensure stem cannot be passed in as null. If nullability warning suppressions were applied when consuming the PatternTestMatch.Stem property, such suppressions can be removed.

Feature area

Core .NET libraries

Affected APIs

1. FilePatternMatch(String, String) Constructor (Microsoft.Extensions.FileSystemGlobbing)
2. FilePatternMatch.Stem Property (Microsoft.Extensions.FileSystemGlobbing)