.NET 9 Preview 1 breaking changes (#39198)

docs/core/compatibility/9.0.md

@@ -15,6 +15,19 @@ If you're migrating an app to .NET 9, the breaking changes listed here might aff
 >
 > This article is a work in progress. It's not a complete list of breaking changes in .NET 9. To query breaking changes that are still pending publication, see [Issues of .NET](https://issuesof.net/?q=%20is:open%20-label:Documented%20is:issue%20(label:%22Breaking%20Change%22%20or%20label:breaking-change)%20(repo:dotnet/docs%20or%20repo:aspnet/Announcements)%20group:repo%20(label:%22:checkered_flag:%20Release:%20.NET%209%22%20or%20label:9.0.0)%20sort:created-desc).
 
+## Core .NET libraries
+
+| Title                                                                                    | Type of change      | Introduced version |
+|------------------------------------------------------------------------------------------|---------------------|--------------------|
+| [Creating type of array of System.Void not allowed](core-libraries/9.0/type-instance.md) | Behavioral change   | Preview 1          |
+| [RuntimeHelpers.GetSubArray returns different type](core-libraries/9.0/getsubarray-return.md) | Behavioral change   | Preview 1          |
+
+## Networking
+
+| Title                                                                             | Type of change      | Introduced version |
+|-----------------------------------------------------------------------------------|---------------------|--------------------|
+| [HttpListenerRequest.UserAgent is nullable](networking/9.0/useragent-nullable.md) | Source incompatible | Preview 1          |
+
 ## SDK and MSBuild
 
 | Title                                                                         | Type of change    | Introduced version |

docs/core/compatibility/core-libraries/9.0/getsubarray-return.md

@@ -0,0 +1,56 @@
+---
+title: "Breaking change: RuntimeHelpers.GetSubArray returns different type"
+description: Learn about the .NET 9 breaking change in core .NET libraries where the type of array instance returned by RuntimeHelpers.GetSubArray matches the source array.
+ms.date: 01/18/2024
+---
+# RuntimeHelpers.GetSubArray returns different type
+
+The type of array instance returned by <xref:System.Runtime.CompilerServices.RuntimeHelpers.GetSubArray%60%601(%60%600[],System.Range)?displayProperty=nameWithType> has changed to match the source array. `RuntimeHelpers.GetSubArray` is used by C# compiler to implement [range operator](../../../../csharp/language-reference/operators/member-access-operators.md#range-operator-) for arrays.
+
+This behavior change can be observed only by code that uses covariant array conversions.
+
+## Previous behavior
+
+Previously, `RuntimeHelpers.GetSubArray<T>(T[] array, Range range)` returned an array instance of type `T[]`.
+
+For example, the type of array instance returned by `RuntimeHelpers.GetSubArray<object>(new string[1], ...)` was `object[]`.
+
+## New behavior
+
+Starting in .NET 9, `RuntimeHelpers.GetSubArray<T>(T[] array, Range range)` returns an array instance of the same type as the `array` parameter.
+
+For example, the type of array instance returned by `RuntimeHelpers.GetSubArray<object>(new string[1], ...)` is `string[]`.
+
+## Version introduced
+
+.NET 9 Preview 1
+
+## Type of breaking change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+The design of C# pattern-matching features assumes that the type of array instance returned by <xref:System.Runtime.CompilerServices.RuntimeHelpers.GetSubArray%60%601(%60%600[],System.Range)?displayProperty=nameWithType> matches the source array. The previous behavior led to unexpected behavior of certain complex pattern expressions that used slicing of covariant arrays. For more information, see [dotnet/roslyn#69053](https://github.com/dotnet/roslyn/issues/69053).
+
+## Recommended action
+
+The recommended action is to remove dependency of the affected code on array covariance.
+
+For example, change:
+
+```csharp
+object[] arr = new string[1];
+M(arr[1..2]);
+```
+
+to:
+
+```csharp
+string[] arr = new string[1];
+M(arr[1..2]);
+```
+
+## Affected APIs
+
+- <xref:System.Runtime.CompilerServices.RuntimeHelpers.GetSubArray%60%601(%60%600[],System.Range)?displayProperty=fullName>

docs/core/compatibility/core-libraries/9.0/type-instance.md

@@ -0,0 +1,38 @@
+---
+title: "Breaking change: Creating type of array of System.Void not allowed"
+description: Learn about the .NET 9 breaking change in core .NET libraries where it's no longer allowed to create a type of array of System.Void.
+ms.date: 01/18/2024
+---
+# Creating type of array of System.Void not allowed
+
+It's no longer permitted to create a <xref:System.Type?displayProperty=fullName> instance for an array of <xref:System.Void?displayProperty=fullName>.
+
+## Previous behavior
+
+Previously, `typeof(void).MakeArrayType()` returned a <xref:System.Type?displayProperty=fullName> instance.
+
+## New behavior
+
+Starting in .NET 9, `typeof(void).MakeArrayType()` throws an exception.
+
+## Version introduced
+
+.NET 9 Preview 1
+
+## Type of breaking change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+Array of <xref:System.Void?displayProperty=fullName> is an invalid type. This type is rejected in some cases (for example, `void[]` in C# does not compile) and it's not possible to create arrays of this type.
+
+.NET runtimes allowed this invalid type to be created in some situations. However, attempts to use this invalid type in other .NET runtime APIs often lead to unexpected behaviors. To make the behavior robust and consistent, it's better to disallow creating these invalid array types in all situations.
+
+## Recommended action
+
+Remove code that tries to create a type for an array of <xref:System.Void?displayProperty=fullName>.
+
+## Affected APIs
+
+- <xref:System.Type.MakeArrayType?displayProperty=fullName>

docs/core/compatibility/networking/9.0/useragent-nullable.md

@@ -0,0 +1,36 @@
+---
+title: "Breaking change: HttpListenerRequest.UserAgent is nullable"
+description: Learn about the .NET 9 breaking change in networking where the HttpListenerRequest.UserAgent property is annotated as being nullable.
+ms.date: 01/18/2024
+---
+# HttpListenerRequest.UserAgent is nullable
+
+The <xref:System.Net.HttpListenerRequest.UserAgent?displayProperty=nameWithType> property was previously annotated as being non-nullable, but it was actually nullable in practice. The nullable annotation for this properties has been updated to indicate that it's nullable. This can result in new build warnings related to use of nullable members.
+
+## Previous behavior
+
+Previously, the property was annotated as not being nullable. You could consume its value and assume it could not be `null` without getting any warnings during build.
+
+## New behavior
+
+Starting in .NET 9, the property is annotated as being nullable. If you consume the value without checking for `null`, you'll get a build warning.
+
+## Version introduced
+
+.NET 9 Preview 1
+
+## Type of breaking change
+
+This change can affect [source compatibility](../../categories.md#source-compatibility).
+
+## Reason for change
+
+The annotations of this property was incorrect. This change applies the appropriate behavior for the property and ensures callers understand the value can be `null`.
+
+## Recommended action
+
+Update calling code to guard against `null` for this property.
+
+## Affected APIs
+
+- <xref:System.Net.HttpListenerRequest.UserAgent?displayProperty=fullName>

docs/core/compatibility/toc.yml

@@ -8,6 +8,16 @@ items:
     items:
     - name: Overview
       href: 9.0.md
+    - name: Core .NET libraries
+      items:
+      - name: Creating type of array of System.Void not allowed
+        href: core-libraries/9.0/type-instance.md
+      - name: RuntimeHelpers.GetSubArray returns different type
+        href: core-libraries/9.0/getsubarray-return.md
+    - name: Networking
+      items:
+      - name: HttpListenerRequest.UserAgent is nullable
+        href: networking/9.0/useragent-nullable.md
     - name: SDK and MSBuild
       items:
       - name: "'dotnet workload' commands output change"
@@ -1124,6 +1134,12 @@ items:
         href: containers/8.0/app-user.md
   - name: Core .NET libraries
     items:
+    - name: .NET 9
+      items:
+      - name: Creating type of array of System.Void not allowed
+        href: core-libraries/9.0/type-instance.md
+      - name: RuntimeHelpers.GetSubArray returns different type
+        href: core-libraries/9.0/getsubarray-return.md
     - name: .NET 8
       items:
       - name: Activity operation name when null
@@ -1500,6 +1516,10 @@ items:
         href: maui/7.0/iwindowstatemanager-apis-removed.md
   - name: Networking
     items:
+    - name: .NET 9
+      items:
+      - name: HttpListenerRequest.UserAgent is nullable
+        href: networking/9.0/useragent-nullable.md
     - name: .NET 8
       items:
       - name: SendFile throws NotSupportedException for connectionless sockets