Document InlineArray explicit Size breaking change for .NET 10 (#47906)

Author: Copilot

docs/core/compatibility/10.0.md

@@ -48,6 +48,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 | [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 SIGTERM signal handler](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 |
 

docs/core/compatibility/core-libraries/10.0/inlinearray-explicit-size-disallowed.md

@@ -0,0 +1,47 @@
+---
+title: "Breaking change: Specifying explicit struct Size disallowed with InlineArray"
+description: "Learn about the breaking change in .NET 10 where specifying explicit Size to a struct decorated with InlineArrayAttribute now throws TypeLoadException."
+ms.date: 08/08/2025
+ai-usage: ai-assisted
+---
+
+# Specifying explicit struct Size disallowed with InlineArray
+
+Applying explicit `Size` to a struct decorated with <xref:System.Runtime.CompilerServices.InlineArrayAttribute> is ambiguous and no longer supported in the type loader. Previously, specifying explicit `Size` would result in implementation-specific behavior that might or might not match user expectations.
+
+## Version introduced
+
+.NET 10 Preview 7
+
+## Previous behavior
+
+Previously, specifying <xref:System.Runtime.InteropServices.StructLayoutAttribute.Size> on a struct decorated with <xref:System.Runtime.CompilerServices.InlineArrayAttribute> was allowed, but resulted in implementation-specific behavior that might or might not match user expectations.
+
+```csharp
+[InlineArray(8)]
+[StructLayout(LayoutKind.Explicit, Size=32)]
+struct Int8InlineArray
+{
+    private int _value;
+}
+```
+
+## New behavior
+
+Starting in .NET 10, specifying <xref:System.Runtime.InteropServices.StructLayoutAttribute.Size> on a struct decorated with <xref:System.Runtime.CompilerServices.InlineArrayAttribute> is disallowed. If you attempt to create an instance of such a struct, you'll get a <xref:System.TypeLoadException>.
+
+## Type of breaking change
+
+This change can affect [binary compatibility](../../categories.md#binary-compatibility).
+
+## Reason for change
+
+Specifying <xref:System.Runtime.InteropServices.StructLayoutAttribute.Size> for an inline array struct is ambiguous and any interpretation would contradict the specification.
+
+## Recommended action
+
+In the unlikely case you need to specify explicit size either for the array element or for the whole inline array, introduce a struct wrapping the element type or the whole array type. In the layout of the wrapper, specify <xref:System.Runtime.InteropServices.StructLayoutAttribute.Size> accordingly.
+
+## Affected APIs
+
+- Type loader

docs/core/compatibility/toc.yml

@@ -54,6 +54,8 @@ items:
                 href: core-libraries/10.0/maccatalyst-version-normalization.md
               - name: No default SIGTERM signal handler
                 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