From e7362c356cad476df60fcb5d2c2a7f38878b6ba8 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 6 Sep 2025 02:36:24 +0000 Subject: [PATCH 1/4] Initial plan From b4ad8a5ac8e27be4714797c2cc2e759f2d6c2e63 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 6 Sep 2025 02:43:01 +0000 Subject: [PATCH 2/4] Add FilePatternMatch.Stem breaking change documentation Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com> --- docs/core/compatibility/10.0.md | 1 + .../10.0/filepatternmatch-stem-nonnullable.md | 67 +++++++++++++++++++ docs/core/compatibility/toc.yml | 2 + 3 files changed, 70 insertions(+) create mode 100644 docs/core/compatibility/core-libraries/10.0/filepatternmatch-stem-nonnullable.md diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index b20300bcb804a..ae7f8e5d6398a 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -50,6 +50,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af | [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 | +| [FilePatternMatch.Stem changed to non-nullable](core-libraries/10.0/filepatternmatch-stem-nonnullable.md) | Source incompatible/behavioral change | RC 1 | | [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..1175d9bd6372a --- /dev/null +++ b/docs/core/compatibility/core-libraries/10.0/filepatternmatch-stem-nonnullable.md @@ -0,0 +1,67 @@ +--- +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: 01/27/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 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, the `FilePatternMatch.Stem` property is now non-nullable and the constructor parameter has been changed accordingly. + +## Version introduced + +.NET 10 RC 1 + +## Previous behavior + +The constructor would accept a `null` for the `stem` parameter without any compile-time or run-time warnings or errors. The property was also annotated as being nullable (`string?`). + +```csharp +// This was allowed in previous versions +var match = new FilePatternMatch("path/to/file.txt", null); +string? stem = match.Stem; // Could be null +``` + +## New behavior + +Passing a `null` or possibly-null value to the `stem` argument in the constructor will yield a compile-time warning, and if `null` is passed in, a run-time will be thrown. The property is now annotated as non-nullable (`string`). + +```csharp +// This now throws ArgumentNullException at runtime +var match = new FilePatternMatch("path/to/file.txt", null); // Throws! + +// The Stem property is now non-nullable +string stem = match.Stem; // No null check needed +``` + +## 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. The `[MemberNotNullWhen()]` attribute is applied to the `PatternTestResult.Stem` property to tell the compiler it will not be null if it is successful. + +## 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 `FilePatternMatch.Stem` property, such suppressions can be removed. + +```csharp +// Before: Check for null +string? stem = match.Stem; +if (stem != null) +{ + // Use stem +} + +// After: No null check needed +string stem = match.Stem; +// Use stem directly +``` + +## Affected APIs + +- +- diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 2308812e76ac7..8c7cbf525df7f 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -58,6 +58,8 @@ items: 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: FilePatternMatch.Stem changed to non-nullable + href: core-libraries/10.0/filepatternmatch-stem-nonnullable.md - name: System.Linq.AsyncEnumerable included in core libraries href: core-libraries/10.0/asyncenumerable.md - name: YMM embedded rounding removed from AVX10.2 From d5a0d1c2fb308813c3178b4e179cc5dac235782f Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 8 Sep 2025 09:29:34 -0700 Subject: [PATCH 3/4] human edits --- docs/core/compatibility/10.0.md | 4 +- .../10.0/filepatternmatch-stem-nonnullable.md | 43 ++++++++----------- docs/core/compatibility/toc.yml | 8 ++-- 3 files changed, 23 insertions(+), 32 deletions(-) diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index ae7f8e5d6398a..4e5618060e500 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -45,12 +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 | -| [FilePatternMatch.Stem changed to non-nullable](core-libraries/10.0/filepatternmatch-stem-nonnullable.md) | Source incompatible/behavioral change | RC 1 | | [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 index 1175d9bd6372a..d87aa8caeba9f 100644 --- a/docs/core/compatibility/core-libraries/10.0/filepatternmatch-stem-nonnullable.md +++ b/docs/core/compatibility/core-libraries/10.0/filepatternmatch-stem-nonnullable.md @@ -1,14 +1,16 @@ --- 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: 01/27/2025 +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 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, the `FilePatternMatch.Stem` property is now non-nullable and the constructor parameter has been changed accordingly. +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 @@ -16,24 +18,24 @@ The constructor would accept a `null` for the `stem` parameter without any compile-time or run-time warnings or errors. The property was also annotated as being nullable (`string?`). +Previously, the constructor accepted `null` for the `stem` parameter without any compile-time or run-time warnings or errors. ```csharp -// This was allowed in previous versions +// Allowed in previous versions. var match = new FilePatternMatch("path/to/file.txt", null); -string? stem = match.Stem; // Could be null ``` +The property was also annotated as being nullable. + ## New behavior -Passing a `null` or possibly-null value to the `stem` argument in the constructor will yield a compile-time warning, and if `null` is passed in, a run-time will be thrown. The property is now annotated as non-nullable (`string`). +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. -```csharp -// This now throws ArgumentNullException at runtime -var match = new FilePatternMatch("path/to/file.txt", null); // Throws! +The property is now annotated to indicate that the value won't be null if `IsSuccessful` is `true`. -// The Stem property is now non-nullable -string stem = match.Stem; // No null check needed +```csharp +// Throws ArgumentNullException at run time. +var match = new FilePatternMatch("path/to/file.txt", null); ``` ## Type of breaking change @@ -42,26 +44,15 @@ This change can affect [source compatibility](../../categories.md#source-compati ## 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. The `[MemberNotNullWhen()]` attribute is applied to the `PatternTestResult.Stem` property to tell the compiler it will not be null if it is successful. +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 `FilePatternMatch.Stem` property, such suppressions can be removed. +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 passed in as `null`. -```csharp -// Before: Check for null -string? stem = match.Stem; -if (stem != null) -{ - // Use stem -} - -// After: No null check needed -string stem = match.Stem; -// Use stem directly -``` +If you applied nullability warning suppressions when consuming the `FilePatternMatch.Stem` property, you can remove those suppressions. ## Affected APIs -- +- - diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 8c7cbf525df7f..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,10 +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: FilePatternMatch.Stem changed to non-nullable - href: core-libraries/10.0/filepatternmatch-stem-nonnullable.md - name: System.Linq.AsyncEnumerable included in core libraries href: core-libraries/10.0/asyncenumerable.md - name: YMM embedded rounding removed from AVX10.2 From 749a7c4f0dca0cb15f5ad1f8399833a809b845ce Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 8 Sep 2025 10:06:24 -0700 Subject: [PATCH 4/4] tweaks --- .../10.0/filepatternmatch-stem-nonnullable.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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 index d87aa8caeba9f..8dce9c0f851a0 100644 --- a/docs/core/compatibility/core-libraries/10.0/filepatternmatch-stem-nonnullable.md +++ b/docs/core/compatibility/core-libraries/10.0/filepatternmatch-stem-nonnullable.md @@ -34,7 +34,7 @@ Starting in .NET 10, passing a `null` or possibly-null value to the `stem` argum The property is now annotated to indicate that the value won't be null if `IsSuccessful` is `true`. ```csharp -// Throws ArgumentNullException at run time. +// Generates compile-time warning. var match = new FilePatternMatch("path/to/file.txt", null); ``` @@ -48,11 +48,11 @@ The previous nullability annotations were inaccurate, and a `null` value for the ## 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 passed in as `null`. +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)) -