Project Windows Runtime struct fields as C# fields

[Sergio Pedri (Sergio0694)]

Summary

Projects the fields of Windows Runtime struct types as C# fields instead of { readonly get; set; } properties, across the projection writer, the manually projected types in WinRT.Runtime, and the custom-mapped XAML types defined by addition files.

Motivation

Projecting struct fields as properties turned out to be problematic, and confusing.

The biggest issue is authoring. cswinrtwinmdgen.exe maps the public instance fields of an authored struct to Windows Runtime struct fields, which is the only shape that can round-trip: an author writing a struct against the projected shape (properties) would silently produce an empty struct in the generated .winmd. Projecting fields as fields makes consumption and authoring symmetrical: the shape you consume is exactly the shape you author.

Beyond authoring, Windows Runtime structs are plain data — there is no accessor to run any logic behind, so a property only obscures that, and it prevents callers from taking a reference to a member (e.g. to pass it as a ref argument, or to mutate an element of an array of structs in place). This also matches what C++/WinRT does, and what CsWinRT 2.x did for generated struct projections.

Changes

Projection writer

• src/WinRT.Projection.Writer/Builders/ProjectionFileBuilder.cs: WriteStruct now emits a public field per Windows Runtime struct field, declared before the constructor so declaration order (which drives the sequential layout of the struct) mirrors the metadata order.
• src/WinRT.Projection.Writer/Factories/AbiStructFactory.cs, src/WinRT.Projection.Writer/Factories/StructEnumMarshallerFactory.cs: refresh comments that justified the mapped-struct special cases by claiming their projected public fields don't match the WinMD field layout, which is no longer accurate.

Manually projected types

• src/WinRT.Runtime2/Windows.Foundation/Point.cs, Rect.cs, Size.cs, src/WinRT.Runtime2/InteropServices/Events/EventRegistrationToken.cs: X, Y, Width, Height and Value become public fields. The negative-value validation that lived in the Rect/Size setters moves into the constructors that document it (which is also what CsWinRT 2.x did). Managed-only members (Left, Top, Right, Bottom, IsEmpty, Empty, ...) are unchanged.

Custom-mapped XAML types (addition files, both the Microsoft.UI.Xaml and Windows.UI.Xaml copies)

• …/Microsoft.UI.Xaml.CornerRadius.cs: TopLeft, TopRight, BottomRight, BottomLeft
• …/Microsoft.UI.Xaml.GridLength.cs: Value, GridUnitType
• …/Microsoft.UI.Xaml.Duration.cs: TimeSpan, Type
• …/Microsoft.UI.Xaml.Media.Animation.KeyTime.cs: TimeSpan
• …/Microsoft.UI.Xaml.Media.Animation.RepeatBehavior.cs: Count, Duration, Type
• …/Microsoft.UI.Xaml.Media.Media3D.Matrix3D.cs: M11-M34, OffsetX, OffsetY, OffsetZ, M44

These types are defined in full by their addition files, so they kept the property-over-private-backing-field shape inherited from the UWP/WPF managed projections. Leaving them alone would have made them inconsistent with their own siblings, since Thickness, Matrix, GeneratorPosition and Color are generated types in CsWinRT 3.0 and therefore now expose fields. Field declaration order (and therefore the sequential layout each of these blittable structs marshals with) is unchanged, and validation that lived in the removed setters is preserved where the constructors already performed it. GridLength and KeyTime are no longer readonly struct-s, since Windows Runtime structs are mutable data. Members that are not Windows Runtime struct fields are left untouched (GridLength.IsAbsolute/IsAuto/IsStar/Auto, Duration.HasTimeSpan/Automatic/Forever, RepeatBehavior.HasCount/HasDuration/Forever, Matrix3D.Identity/IsIdentity/HasInverse, and all operators, conversions and formatting helpers).

There is one deliberate behavior change on top of that: the GridLength constructors no longer reject negative (or non-finite) values. Negative GridLength values turn out to be a valid pattern that real apps rely on (e.g. the Microsoft Store uses them in several custom layout panels), and now that Value is a public mutable field the check was trivially bypassable anyway. The GridUnitType validation is unchanged, GridUnitType.Auto still normalizes the value to the default, and the IsFinite helper the removed check was the only user of goes away with it.

Tests and docs

• src/Tests/ProjectionWriterTest/Test_ProjectedStructs.cs: new tests asserting that projected struct fields are emitted as C# fields, and that no projected struct member is emitted as an auto-property, in both projection modes.
• docs/cswinrt3.0-spec.md: documents the projection rule, and renames the neighbouring Point/Rect/Size section (which was already about their fields rather than properties).
• docs/event-infrastructure.md: refreshes the EventRegistrationToken snippet.

Validation

• ProjectionWriterTest (16), WinMDGeneratorTest (17) and SourceGenerator2Test (129) all pass.
• The Windows, Windows.UI.Xaml and WinAppSDK projections were regenerated end-to-end and compile cleanly, which covers the emitted structs, their marshallers, and all of the addition files.
• Both GridLength addition files were compiled standalone and exercised to confirm negative, NaN and infinite values now construct successfully, that GridUnitType.Auto still normalizes to the default, and that an out-of-range GridUnitType still throws.

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.