Mark Color as immutable and make Font a readonly struct by StephaneDelcroix · Pull Request #33824 · dotnet/maui

StephaneDelcroix · 2026-02-01T16:23:43Z

Note

Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

Description

This PR improves type safety and documents immutability for core Graphics types.

Intent

These changes enable future XAML Source Generator (XSG) enhancements. By explicitly marking types as immutable, the source generator can make better optimization decisions, such as:

Caching instances safely
Avoiding defensive copies
Generating more efficient code paths for immutable value assignments

Changes

Color class: Added [ImmutableObject(true)] attribute
- Color was already effectively immutable (all fields are readonly)
- The attribute documents this intent for tooling and developers
Font struct: Converted to readonly struct
- Changed from struct to readonly struct
- Changed properties from { get; private set; } to { get; }
- The private set was only used in the constructor, so this is not a breaking change

Why

Enables XSG optimizations for immutable types
Better compiler optimizations for readonly struct
Documents immutability intent explicitly
Enables better static analysis and tooling support
No breaking changes for consumers

API Changes

None - these are non-breaking enhancements that formalize existing immutability guarantees.

Copilot

Pull request overview

This PR enhances type safety and documents immutability guarantees for two core Graphics types by adding explicit immutability markers.

Changes:

Added [ImmutableObject(true)] attribute to the Color class to document its existing immutability
Converted the Font struct from struct to readonly struct and changed auto-properties from { get; private set; } to { get; }

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
src/Graphics/src/Graphics/Color.cs	Added ImmutableObjectAttribute to formalize Color's existing immutability contract
src/Graphics/src/Graphics/Font.cs	Converted to readonly struct with get-only properties, matching patterns used in other MAUI readonly structs

pictos · 2026-02-01T17:12:29Z

 	[DebuggerDisplay("Red={Red}, Green={Green}, Blue={Blue}, Alpha={Alpha}")]
 	[TypeConverter(typeof(Converters.ColorTypeConverter))]
+	[ImmutableObject(true)]
 	public class Color


For Immutability wouldn't make sense to change this to be record? I'm not sure if it will be a binary breaking change thought

record is C# syntax and doesn't alter the object signature, but implements IEquatable for free

but roslyn can detect that, so why not

simonrozsival · 2026-02-09T10:53:58Z

+		/// <summary>
+		/// Determines whether the specified <see cref="Color"/> is equal to the current color using byte-precision comparison.
+		/// </summary>
+		public virtual bool Equals(Color other)


I'm confused. Why isn't this override?

simonrozsival

ship it

PureWeen

build is failing

StephaneDelcroix · 2026-02-25T12:32:50Z

Hi @PureWeen — the builds are now passing (macOS Debug/Release, Windows Debug/Release, Helix unit tests all green ✅). The only failures are 'Run Integration Tests Build macOS' and 'RunOnAndroid' which are pre-existing on the net11.0 branch baseline.

Regarding the record class Color change: this intentionally changes == from reference equality to value equality. This is the desired behavior — two Colors with the same RGBA values should be equal. The SourceGen optimization relies on this for resource deduplication.

Could you re-review when you get a chance?

no longer

github-actions · 2026-02-27T10:49:49Z

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.sh | bash -s -- 33824

Or

Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.ps1) } 33824"

- Add [ImmutableObject(true)] attribute to Color class to document its immutability - Convert Font from struct to readonly struct - Change Font properties from { get; private set; } to { get; }

- Change Color from class to record class for IEquatable<Color> support - Add explicit Equals(Color) using ToInt() to preserve byte-precision semantics - All equality paths (==, !=, Equals) use consistent int comparison - Add PublicAPI.Unshipped.txt entries for compiler-generated record members

…rd class CS8872: 'Color.Equals(Color)' must allow overriding because the containing record is not sealed. The virtual modifier is mandatory for record class types.

…lor record - GetHashCode() now returns ToInt() to be consistent with Equals(Color? other), which also uses ToInt() for byte-precision comparison. Previously GetHashCode() hashed raw float values while Equals() quantized to bytes, violating the contract (two equal Colors could have different hash codes). - Equals(Color? other) now checks EqualityContract to properly distinguish Color from derived record types, matching standard record equality semantics. - Parameter type changed from Color to Color? to match the record-generated Equals pattern and allow proper null handling. - Updated PublicAPI.Unshipped.txt for all TFMs to reflect the nullable parameter. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings February 1, 2026 16:23

Copilot started reviewing on behalf of StephaneDelcroix February 1, 2026 16:24 View session

StephaneDelcroix added this to the .NET 11.0-preview1 milestone Feb 1, 2026

Copilot AI reviewed Feb 1, 2026

View reviewed changes

pictos reviewed Feb 1, 2026

View reviewed changes

PureWeen modified the milestones: .NET 11.0-preview1, .NET 11.0-preview2 Feb 3, 2026

simonrozsival previously approved these changes Feb 9, 2026

View reviewed changes

StephaneDelcroix dismissed simonrozsival’s stale review via 04e3c28 February 9, 2026 09:11

StephaneDelcroix requested review from pictos and simonrozsival February 9, 2026 09:28

simonrozsival reviewed Feb 9, 2026

View reviewed changes

simonrozsival previously approved these changes Feb 9, 2026

View reviewed changes

PureWeen previously requested changes Feb 9, 2026

View reviewed changes

StephaneDelcroix dismissed simonrozsival’s stale review via b155ba1 February 11, 2026 08:54

StephaneDelcroix force-pushed the feature/immutable-color-font branch from 9a551d3 to b155ba1 Compare February 11, 2026 08:54

build-analysis Bot mentioned this pull request Feb 11, 2026

System.Exception : Failed to launch Test AVD. #33862

Closed

StephaneDelcroix changed the base branch from main to net11.0 February 11, 2026 13:25

StephaneDelcroix force-pushed the feature/immutable-color-font branch from b155ba1 to dbca93f Compare February 12, 2026 14:22

This was referenced Feb 12, 2026

[android-arm64] The Operation will be canceled. The next steps may not contain expected logs. dotnet/dnceng#6408

Closed

The Operation will be canceled. The next steps may not contain expected logs. dotnet/dnceng#3008

Open

StephaneDelcroix force-pushed the feature/immutable-color-font branch from dbca93f to b20ac49 Compare February 24, 2026 11:28

pictos approved these changes Feb 25, 2026

View reviewed changes

StephaneDelcroix added 4 commits February 27, 2026 16:20

Mark Color as immutable and make Font a readonly struct

874561c

- Add [ImmutableObject(true)] attribute to Color class to document its immutability - Convert Font from struct to readonly struct - Change Font properties from { get; private set; } to { get; }

Remove 'virtual' from Color.Equals(Color)

ec6c23c

Restore virtual on Color.Equals(Color) - required for non-sealed reco…

6f2cb99

…rd class CS8872: 'Color.Equals(Color)' must allow overriding because the containing record is not sealed. The virtual modifier is mandatory for record class types.

StephaneDelcroix force-pushed the feature/immutable-color-font branch from 18af7df to f6643c9 Compare February 27, 2026 15:20

StephaneDelcroix merged commit 797df24 into net11.0 Feb 27, 2026
24 of 29 checks passed

StephaneDelcroix deleted the feature/immutable-color-font branch February 27, 2026 19:36

This was referenced Mar 1, 2026

[repo-status] Daily Status Report - March 1, 2026 #34289

Closed

[repo-status] Daily Status Report - March 2, 2026 #34290

Closed

github-actions Bot locked and limited conversation to collaborators Mar 30, 2026

PureWeen modified the milestones: .NET 11.0-preview2, .NET 11.0-preview3 Jun 10, 2026

Navigation Menu

Uh oh!

Mark Color as immutable and make Font a readonly struct - #33824

Mark Color as immutable and make Font a readonly struct#33824
StephaneDelcroix merged 5 commits into
net11.0from
feature/immutable-color-font

StephaneDelcroix commented Feb 1, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

pictos Feb 1, 2026

Uh oh!

StephaneDelcroix Feb 2, 2026

Uh oh!

StephaneDelcroix Feb 9, 2026

Uh oh!

simonrozsival Feb 9, 2026

Uh oh!

simonrozsival left a comment

Uh oh!

PureWeen left a comment

Uh oh!

StephaneDelcroix commented Feb 25, 2026

Uh oh!

github-actions Bot commented Feb 27, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

StephaneDelcroix commented Feb 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Intent

Changes

Why

API Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

pictos Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

StephaneDelcroix Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

StephaneDelcroix Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

simonrozsival Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

simonrozsival left a comment

Choose a reason for hiding this comment

Uh oh!

PureWeen left a comment

Choose a reason for hiding this comment

Uh oh!

StephaneDelcroix commented Feb 25, 2026

Uh oh!

github-actions Bot commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

StephaneDelcroix commented Feb 1, 2026 •

edited

Loading

github-actions Bot commented Feb 27, 2026 •

edited

Loading