Document breaking change: Disallow loading non-Explicit types with explicit field offsets

[Copilot]

Summary

This PR documents a breaking change introduced in .NET 10 Preview 4 where the runtime now enforces stricter validation for type layouts. The runtime throws a TypeLoadException if a type with non-explicit layout (Auto or Sequential) specifies explicit field offsets using the [FieldOffset] attribute.

Changes

• Created docs/core/compatibility/interop/10.0/explicit-field-offset-validation.md - comprehensive breaking change documentation
• Updated docs/core/compatibility/10.0.md - added entry to the Interop section
• Updated docs/core/compatibility/toc.yml - added TOC entry for the new document

Breaking Change Details

Previous behavior: The runtime ignored explicit field offsets on types with Auto or Sequential layouts, which was non-compliant with the ECMA-335 specification.

New behavior: Starting in .NET 10 Preview 4, attempting to load such types throws a TypeLoadException.

Recommended action: Developers should update their code to use LayoutKind.Explicit for types that specify explicit field offsets, or remove the [FieldOffset] attributes if not required.

Example

// This now throws TypeLoadException
[StructLayout(LayoutKind.Sequential)]
public struct MyStruct
{
    [FieldOffset(0)]
    public int Field1;
}

// Use this instead
[StructLayout(LayoutKind.Explicit)]
public struct MyStruct
{
    [FieldOffset(0)]
    public int Field1;
}

Fixes #496358

Related Resources

• ECMA-335 specification
• PR dotnet/runtime#113500

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Breaking change]: Disallow loading non-Explicit types with explicit field offsets</issue_title>
<issue_description>### Breaking Change: Disallow loading non-Explicit types with explicit field offsets

Description

Starting in .NET 10 Preview 4, the .NET runtime enforces stricter validation for type layouts. Specifically, the runtime now throws a TypeLoadException if a type with a non-explicit layout (e.g., Auto or Sequential) specifies explicit field offsets using the [FieldOffset] attribute. This change aligns the runtime's behavior with the ECMA-335 specification, which only permits explicit field offsets for types with an Explicit layout.

Previously, the runtime ignored explicit field offsets on non-explicit layout types, which could lead to unexpected behavior or incorrect assumptions about memory layout.

This change was introduced in PR dotnet/docs#113500.

Version

This breaking change was introduced in .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:

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 TypeLoadException if a type with Auto or Sequential layout specifies explicit field offsets. The following code will now throw an exception:

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:

System.TypeLoadException: Explicit field offsets are not allowed on types with Sequential or Auto layout.

Type of breaking change

• Binary incompatible: Existing binaries that define non-explicit layout types with explicit field offsets will fail to load.
• Behavioral change: Existing binaries might behave differently at runtime due to the stricter validation.

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, developers should update their code to use LayoutKind.Explicit for types that specify explicit field offsets. For example:

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 are not required, remove the [FieldOffset] attributes and rely on the default behavior of Sequential or Auto layout.

Affected APIs

This change does not directly affect specific APIs but impacts the runtime behavior of types defined with the following attributes:

• [StructLayout(LayoutKind.Sequential)]
• [StructLayout(LayoutKind.Auto)]
• [FieldOffset]

Feature area

• Interop

Additional resources

• ECMA-335 Specification
• StructLayoutAttribute documentation
• FieldOffsetAttribute documentation

For further assistance, please contact .NET Breaking Change Notifications.

---

Associated WorkItem - 496358</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #48897

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

---

Internal previews

📄 File	🔗 Preview link
docs/core/compatibility/10.0.md	Breaking changes in .NET 10
docs/core/compatibility/interop/10.0/explicit-field-offset-validation.md	Disallow loading non-Explicit types with explicit field offsets
docs/core/compatibility/toc.yml	docs/core/compatibility/toc

[Copilot]

Pull Request Overview

Documents a .NET 10 Preview 4 breaking change enforcing validation that disallows explicit field offsets on non-Explicit layout types, adding a new compatibility article and linking it in the TOC and 10.0 summary table.

• Adds dedicated breaking change doc describing previous/new behavior, exception, guidance.
• Updates 10.0 compatibility index and TOC with the new entry.

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
docs/core/compatibility/interop/10.0/explicit-field-offset-validation.md	New breaking change article detailing the enforced validation and remediation steps.
docs/core/compatibility/10.0.md	Adds row referencing the new breaking change in the Interop section.
docs/core/compatibility/toc.yml	Adds TOC entry pointing to the new article.

[jkoritzinsky]

@gewarren I went back and checked the PR that this refers to. We changed the implementation, and I forgot to update the tags. We don't need a breaking change notice for the change as it is only reachable through IL that is not supported in C#, VB.NET, or F#.