diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index b20300bcb804a..4e5618060e500 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -45,11 +45,12 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af | [Default trace context propagator updated to W3C standard](core-libraries/10.0/default-trace-context-propagator.md) | Behavioral change | Preview 4 | | [DriveInfo.DriveFormat returns Linux filesystem types](core-libraries/10.0/driveinfo-driveformat-linux.md) | Behavioral change | Preview 6 | | [DynamicallyAccessedMembers annotation removed from DefaultValueAttribute ctor](core-libraries/10.0/defaultvalueattribute-dynamically-accessed-members.md) | Binary/source incompatible | Preview 7 | +| [Explicit struct Size disallowed with InlineArray](core-libraries/10.0/inlinearray-explicit-size-disallowed.md) | Binary incompatible | Preview 7 | +| [FilePatternMatch.Stem changed to non-nullable](core-libraries/10.0/filepatternmatch-stem-nonnullable.md) | Source incompatible/behavioral change | RC 1 | | [GnuTarEntry and PaxTarEntry no longer includes atime and ctime by default](core-libraries/10.0/tar-atime-ctime-default.md) | Behavioral change | Preview 5 | | [LDAP DirectoryControl parsing is now more stringent](core-libraries/10.0/ldap-directorycontrol-parsing.md) | Behavioral change | Preview 1 | | [MacCatalyst version normalization](core-libraries/10.0/maccatalyst-version-normalization.md) | Behavioral change | Preview 1 | | [.NET runtime no longer provides default termination signal handlers](core-libraries/10.0/sigterm-signal-handler.md) | Behavioral change | Preview 5 | -| [Explicit struct Size disallowed with InlineArray](core-libraries/10.0/inlinearray-explicit-size-disallowed.md) | Binary incompatible | Preview 7 | | [System.Linq.AsyncEnumerable included in core libraries](core-libraries/10.0/asyncenumerable.md) | Source incompatible | Preview 1 | | [YMM embedded rounding removed from AVX10.2](core-libraries/10.0/ymm-embedded-rounding.md) | Behavioral change | Preview 5 | diff --git a/docs/core/compatibility/core-libraries/10.0/filepatternmatch-stem-nonnullable.md b/docs/core/compatibility/core-libraries/10.0/filepatternmatch-stem-nonnullable.md new file mode 100644 index 0000000000000..8dce9c0f851a0 --- /dev/null +++ b/docs/core/compatibility/core-libraries/10.0/filepatternmatch-stem-nonnullable.md @@ -0,0 +1,58 @@ +--- +title: "Breaking change - FilePatternMatch.Stem changed to non-nullable" +description: "Learn about the breaking change in .NET 10 where FilePatternMatch.Stem property was changed from nullable to non-nullable." +ms.date: 09/08/2025 +ai-usage: ai-assisted +ms.custom: https://github.com/dotnet/docs/issues/47914 +--- + +# FilePatternMatch.Stem changed to non-nullable + +The property was previously annotated as nullable because the `PatternTestResult.Stem` property it gets its value from is nullable. While the can indeed be null if the result isn't successful, the `FilePatternMatch` never is because it's only constructed when `PatternTestResult` is successful. + +To accurately reflect nullability, the `[MemberNotNullWhen()]` attribute is applied to the `PatternTestResult.Stem` property to tell the compiler it won't be null if it's successful. Additionally, the `stem` argument passed into the `FilePatternMatch` constructor is no longer nullable, and an `ArgumentNullException` will be thrown if a null `stem` is passed in. + +## Version introduced + +.NET 10 RC 1 + +## Previous behavior + +Previously, the constructor accepted `null` for the `stem` parameter without any compile-time or run-time warnings or errors. + +```csharp +// Allowed in previous versions. +var match = new FilePatternMatch("path/to/file.txt", null); +``` + +The property was also annotated as being nullable. + +## New behavior + +Starting in .NET 10, passing a `null` or possibly-null value to the `stem` argument in the constructor yields a compile-time warning. And, if `null` is passed in, a run-time is thrown. + +The property is now annotated to indicate that the value won't be null if `IsSuccessful` is `true`. + +```csharp +// Generates compile-time warning. +var match = new FilePatternMatch("path/to/file.txt", null); +``` + +## Type of breaking change + +This change can affect [source compatibility](../../categories.md#source-compatibility) and is a [behavioral change](../../categories.md#behavioral-change). + +## 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` can't be paTssed in as `null`. + +If you applied nullability warning suppressions when consuming the `FilePatternMatch.Stem` property, you can remove those suppressions. + +## Affected APIs + +- [FilePatternMatch(String,String) constructor](xref:Microsoft.Extensions.FileSystemGlobbing.FilePatternMatch.%23ctor(System.String,System.String)) +- diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 2308812e76ac7..e3a848bbafc0e 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -48,6 +48,10 @@ items: href: core-libraries/10.0/driveinfo-driveformat-linux.md - name: DynamicallyAccessedMembers annotation removed from DefaultValueAttribute ctor href: core-libraries/10.0/defaultvalueattribute-dynamically-accessed-members.md + - name: Explicit struct Size disallowed with InlineArray + href: core-libraries/10.0/inlinearray-explicit-size-disallowed.md + - name: FilePatternMatch.Stem changed to non-nullable + href: core-libraries/10.0/filepatternmatch-stem-nonnullable.md - name: GnuTarEntry and PaxTarEntry exclude atime and ctime by default href: core-libraries/10.0/tar-atime-ctime-default.md - name: LDAP DirectoryControl parsing is now more stringent @@ -56,8 +60,6 @@ items: href: core-libraries/10.0/maccatalyst-version-normalization.md - name: No default termination signal handlers href: core-libraries/10.0/sigterm-signal-handler.md - - name: Explicit struct Size disallowed with InlineArray - href: core-libraries/10.0/inlinearray-explicit-size-disallowed.md - name: System.Linq.AsyncEnumerable included in core libraries href: core-libraries/10.0/asyncenumerable.md - name: YMM embedded rounding removed from AVX10.2