From 0456734ca246c6c1cba0b2bfb06537bdaf0e1c2d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 13 Oct 2025 19:51:12 +0000 Subject: [PATCH 1/4] Initial plan From 04bc2d722884e072c6da4646de5c1dff80432913 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 13 Oct 2025 19:59:37 +0000 Subject: [PATCH 2/4] Add breaking change documentation for explicit field offset validation Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com> --- docs/core/compatibility/10.0.md | 1 + .../10.0/explicit-field-offset-validation.md | 123 ++++++++++++++++++ docs/core/compatibility/toc.yml | 2 + 3 files changed, 126 insertions(+) create mode 100644 docs/core/compatibility/interop/10.0/explicit-field-offset-validation.md diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 7d0c66625293f..d3e327eb4b23f 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -89,6 +89,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af | Title | Type of change | Introduced version | |-------|-------------------|--------------------| +| [Disallow loading non-Explicit types with explicit field offsets](interop/10.0/explicit-field-offset-validation.md) | Binary incompatible/behavioral change | Preview 4 | | [Single-file apps no longer look for native libraries in executable directory](interop/10.0/native-library-search.md) | Behavioral change | Preview 6 | | [Specifying DllImportSearchPath.AssemblyDirectory only searches the assembly directory](interop/10.0/search-assembly-directory.md) | Behavioral change | Preview 5 | diff --git a/docs/core/compatibility/interop/10.0/explicit-field-offset-validation.md b/docs/core/compatibility/interop/10.0/explicit-field-offset-validation.md new file mode 100644 index 0000000000000..4ba8a414ea8a6 --- /dev/null +++ b/docs/core/compatibility/interop/10.0/explicit-field-offset-validation.md @@ -0,0 +1,123 @@ +--- +title: "Breaking change: Disallow loading non-Explicit types with explicit field offsets" +description: "Learn about the breaking change in .NET 10 where the runtime enforces stricter validation for type layouts and throws TypeLoadException if non-explicit layout types specify explicit field offsets." +ms.date: 10/13/2025 +ai-usage: ai-assisted +--- + +# Disallow loading non-Explicit types with explicit field offsets + +Starting in .NET 10 Preview 4, the .NET runtime enforces stricter validation for type layouts. Specifically, the runtime now throws a if a type with a non-explicit layout (for example, `Auto` or `Sequential`) specifies explicit field offsets using the . This change aligns the runtime's behavior with the ECMA-335 specification, which only permits explicit field offsets for types with an `Explicit` layout. + +## Version introduced + +.NET 10 Preview 4 + +## Previous behavior + +In earlier versions of .NET, the runtime ignored explicit field offsets on types with `Auto` or `Sequential` layouts. For example: + +```csharp +using System; +using System.Runtime.InteropServices; + +[StructLayout(LayoutKind.Sequential)] +public struct MyStruct +{ + [FieldOffset(0)] // Ignored in .NET versions prior to 10 Preview 4 + public int Field1; + + [FieldOffset(4)] // Ignored in .NET versions prior to 10 Preview 4 + public int Field2; +} + +class Program +{ + static void Main() + { + Console.WriteLine("Struct loaded successfully."); + } +} +``` + +The above code would execute without error, and the `[FieldOffset]` attributes would be ignored. + +## New behavior + +Starting in .NET 10 Preview 4, the runtime enforces the ECMA-335 specification and throws a if a type with `Auto` or `Sequential` layout specifies explicit field offsets. The following code now throws an exception: + +```csharp +using System; +using System.Runtime.InteropServices; + +[StructLayout(LayoutKind.Sequential)] +public struct MyStruct +{ + [FieldOffset(0)] // Causes a TypeLoadException in .NET 10 Preview 4 and later + public int Field1; + + [FieldOffset(4)] // Causes a TypeLoadException in .NET 10 Preview 4 and later + public int Field2; +} + +class Program +{ + static void Main() + { + Console.WriteLine("Struct loaded successfully."); + } +} +``` + +**Exception thrown:** + +```output +System.TypeLoadException: Explicit field offsets are not allowed on types with Sequential or Auto layout. +``` + +## Type of breaking change + +This change can affect [binary compatibility](../../categories.md#binary-compatibility) and is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +This change was introduced to align the .NET runtime with the ECMA-335 specification, which explicitly disallows explicit field offsets on types with `Auto` or `Sequential` layouts. The previous behavior of ignoring these offsets was non-compliant and could lead to unexpected behavior or incorrect assumptions about memory layout. + +## Recommended action + +To resolve this issue, update your code to use `LayoutKind.Explicit` for types that specify explicit field offsets. For example: + +```csharp +using System; +using System.Runtime.InteropServices; + +[StructLayout(LayoutKind.Explicit)] // Use Explicit layout +public struct MyStruct +{ + [FieldOffset(0)] + public int Field1; + + [FieldOffset(4)] + public int Field2; +} + +class Program +{ + static void Main() + { + Console.WriteLine("Struct loaded successfully."); + } +} +``` + +Alternatively, if explicit field offsets aren't required, remove the attributes and rely on the default behavior of `Sequential` or `Auto` layout. + +## Affected APIs + +- +- + +## See also + +- [ECMA-335 specification](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/) +- [Customize structure marshalling](../../../../standard/native-interop/customize-struct-marshalling.md) diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 18c08be85a233..4127d642a4292 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -98,6 +98,8 @@ items: href: globalization/10.0/version-override.md - name: Interop items: + - name: Disallow loading non-Explicit types with explicit field offsets + href: interop/10.0/explicit-field-offset-validation.md - name: Single-file apps no longer look for native libraries in executable directory href: interop/10.0/native-library-search.md - name: Specifying DllImportSearchPath.AssemblyDirectory only searches the assembly directory From 3fd1271a4e9be4f64a35a5aaade2904360180223 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 13 Oct 2025 18:46:13 -0700 Subject: [PATCH 3/4] Apply suggestions from code review --- .../10.0/explicit-field-offset-validation.md | 25 ++++++++++--------- 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/core/compatibility/interop/10.0/explicit-field-offset-validation.md b/docs/core/compatibility/interop/10.0/explicit-field-offset-validation.md index 4ba8a414ea8a6..35612822cfc37 100644 --- a/docs/core/compatibility/interop/10.0/explicit-field-offset-validation.md +++ b/docs/core/compatibility/interop/10.0/explicit-field-offset-validation.md @@ -7,7 +7,7 @@ ai-usage: ai-assisted # Disallow loading non-Explicit types with explicit field offsets -Starting in .NET 10 Preview 4, the .NET runtime enforces stricter validation for type layouts. Specifically, the runtime now throws a if a type with a non-explicit layout (for example, `Auto` or `Sequential`) specifies explicit field offsets using the . This change aligns the runtime's behavior with the ECMA-335 specification, which only permits explicit field offsets for types with an `Explicit` layout. +The .NET runtime now enforces stricter validation for type layouts. Specifically, the runtime throws a if a type with a non-explicit layout (for example, or ) specifies explicit field offsets using . This change aligns the runtime's behavior with the ECMA-335 specification, which only permits explicit field offsets for types with an `Explicit` layout. ## Version introduced @@ -15,7 +15,7 @@ Starting in .NET 10 Preview 4, the .NET runtime enforces stricter validation for ## Previous behavior -In earlier versions of .NET, the runtime ignored explicit field offsets on types with `Auto` or `Sequential` layouts. For example: +In earlier versions of .NET, the runtime ignored explicit field offsets on types with `Auto` or `Sequential` layouts. For example, the following code executed without error, and the `[FieldOffset]` attributes were ignored.: ```csharp using System; @@ -24,10 +24,10 @@ using System.Runtime.InteropServices; [StructLayout(LayoutKind.Sequential)] public struct MyStruct { - [FieldOffset(0)] // Ignored in .NET versions prior to 10 Preview 4 + [FieldOffset(0)] // Ignored prior to .NET 10. public int Field1; - [FieldOffset(4)] // Ignored in .NET versions prior to 10 Preview 4 + [FieldOffset(4)] // Ignored prior to .NET 10. public int Field2; } @@ -40,11 +40,9 @@ class Program } ``` -The above code would execute without error, and the `[FieldOffset]` attributes would be ignored. - ## New behavior -Starting in .NET 10 Preview 4, the runtime enforces the ECMA-335 specification and throws a if a type with `Auto` or `Sequential` layout specifies explicit field offsets. The following code now throws an exception: +Starting in .NET 10, the runtime enforces the ECMA-335 specification and throws a if a type with `Auto` or `Sequential` layout specifies explicit field offsets. The following code now throws an exception: ```csharp using System; @@ -53,10 +51,10 @@ using System.Runtime.InteropServices; [StructLayout(LayoutKind.Sequential)] public struct MyStruct { - [FieldOffset(0)] // Causes a TypeLoadException in .NET 10 Preview 4 and later + [FieldOffset(0)] // TypeLoadException. public int Field1; - [FieldOffset(4)] // Causes a TypeLoadException in .NET 10 Preview 4 and later + [FieldOffset(4)] // TypeLoadException. public int Field2; } @@ -85,7 +83,7 @@ This change was introduced to align the .NET runtime with the ECMA-335 specifica ## Recommended action -To resolve this issue, update your code to use `LayoutKind.Explicit` for types that specify explicit field offsets. For example: +To resolve this issue, update your code to use for types that specify explicit field offsets. For example: ```csharp using System; @@ -114,8 +112,11 @@ Alternatively, if explicit field offsets aren't required, remove the -- +This change does not directly affect specific APIs but impacts the run-time behavior of types defined with the following attributes: + +- `[StructLayout(LayoutKind.Sequential)]` +- `[StructLayout(LayoutKind.Auto)]` +- `[FieldOffset]` ## See also From e290dcfc4998d0a3ecd3e15b5a27ef041f955c18 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 13 Oct 2025 19:03:09 -0700 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../interop/10.0/explicit-field-offset-validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/compatibility/interop/10.0/explicit-field-offset-validation.md b/docs/core/compatibility/interop/10.0/explicit-field-offset-validation.md index 35612822cfc37..11e80db71e982 100644 --- a/docs/core/compatibility/interop/10.0/explicit-field-offset-validation.md +++ b/docs/core/compatibility/interop/10.0/explicit-field-offset-validation.md @@ -15,7 +15,7 @@ The .NET runtime now enforces stricter validation for type layouts. Specifically ## Previous behavior -In earlier versions of .NET, the runtime ignored explicit field offsets on types with `Auto` or `Sequential` layouts. For example, the following code executed without error, and the `[FieldOffset]` attributes were ignored.: +In earlier versions of .NET, the runtime ignored explicit field offsets on types with `Auto` or `Sequential` layouts. For example, the following code executed without error, and the `[FieldOffset]` attributes were ignored: ```csharp using System;