[Controls][Net11][WIP]VisualElement: Obsolete BackgroundColor in favor of Background by KarthikRajaKalaimani · Pull Request #36130 · dotnet/maui

KarthikRajaKalaimani · 2026-06-25T12:57:38Z

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 of Change

VisualElement.BackgroundColor overlaps with Background, which already supports solid colors through the implicit Color to SolidColorBrush conversion and also supports gradient brushes. Maintaining both APIs has caused mapper and control behavior to diverge.

This change marks the legacy color APIs obsolete in favor of their brush-based replacements:

VisualElement.BackgroundColor and BackgroundColorProperty -> Background and BackgroundProperty
IBorderElement.BackgroundColor and IsBackgroundColorSet() -> Background and IsBackgroundSet()
VisualElement.MapBackgroundColor() -> MapBackground()

Existing applications remain runtime-compatible. Values set through BackgroundColor still flow through IView.Background, and the legacy mapper entry remains available while forwarding to MapBackground.

Implementation Details

Migrates framework-owned handlers, compatibility renderers, controls, templates, CSS registration, and sample template XAML to Background.
Keeps narrowly scoped compatibility bridges for RadioButton and TitleBar template bindings that must continue reacting to the obsolete property.
Preserves Page.BackgroundImageSource behavior: a locally set image can override an implicit Page.Background style, while an equally specific or local Background keeps its existing precedence.
Keeps the TitleBar property-change bridge active when the same title bar is detached and reattached.
Removes the project-wide device-test CS0618 suppression. Framework-owned test setup now uses Background; tests intentionally validating BackgroundColor use scoped pragmas.
Corrects an Android Shell handler teardown failure exposed by the latest net11.0 device tests: FragmentManager retains ownership of its wrapper fragment, and the test host now waits for fragment destruction before starting the next test.

Tests

Adds unit coverage for implicit Page background styles, local background precedence, and BackgroundImageSource.
Adds unit coverage for TitleBar bridge notifications after detach/reattach.
Builds the Controls device-test project for Android, iOS, and Mac Catalyst without a project-wide obsolete-warning suppression.
Runs the Android Shell device-test category through full fragment teardown.

Migration Guide

Before	After
`view.BackgroundColor = Colors.Red;`	`view.Background = Colors.Red;`
`<Label BackgroundColor="Red" />`	`<Label Background="Red" />`
`VisualElement.MapBackgroundColor(handler, view);`	`VisualElement.MapBackground(handler, view);`

Compatibility Guidance

Do not suppress CS0618 for an entire project. Framework code should migrate to Background; scoped suppressions should be limited to compatibility paths and tests that intentionally exercise the obsolete API.

Issues Fixed

Fixes #28854

github-actions · 2026-06-25T12:57:48Z

🚀 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 -- 36130

Or

Run remotely in PowerShell:

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

dotnet-policy-service · 2026-06-25T12:58:23Z

Hey there @@KarthikRajaKalaimani! Thank you so much for your PR! Someone from the team will get assigned to your PR shortly and we'll get it reviewed.

vishnumenon2684 · 2026-06-26T04:53:14Z

/azp run maui-pr-uitests , maui-pr-devicetests

azure-pipelines · 2026-06-26T04:53:31Z

Azure Pipelines successfully started running 2 pipeline(s).

vishnumenon2684 · 2026-06-26T11:02:43Z

/azp run

azure-pipelines · 2026-06-26T11:02:59Z

Azure Pipelines successfully started running 3 pipeline(s).

vishnumenon2684 · 2026-07-02T11:43:41Z

/azp run

azure-pipelines · 2026-07-02T11:44:03Z

Azure Pipelines successfully started running 3 pipeline(s).

vishnumenon2684 · 2026-07-03T12:45:28Z

/azp run maui-pr-uitests

azure-pipelines · 2026-07-03T12:45:39Z

Azure Pipelines successfully started running 1 pipeline(s).

MauiBot

Expert Review — 2 findings

See inline comments for details.

kubaflo · 2026-07-06T10:32:04Z

@jfversluis could you please have a look?

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Preserve BackgroundImageSource precedence over implicit styles, keep the TitleBar compatibility bridge active after reattachment, and scope obsolete warnings in device tests. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 51b16329-8bf7-4952-960e-d9e9313e204d

kubaflo · 2026-07-31T12:13:05Z

/azp run

azure-pipelines · 2026-07-31T12:13:31Z

Azure Pipelines: Successfully started running 3 pipeline(s).

kubaflo · 2026-07-31T13:17:08Z

/azp run maui-pr-devicetests

azure-pipelines · 2026-07-31T13:17:25Z

Azure Pipelines: Successfully started running 1 pipeline(s).

kubaflo · 2026-07-31T14:25:12Z

/azp run maui-pr-devicetests

azure-pipelines · 2026-07-31T14:25:28Z

Azure Pipelines: Successfully started running 1 pipeline(s).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 51b16329-8bf7-4952-960e-d9e9313e204d

kubaflo · 2026-07-31T15:44:11Z

/azp run

azure-pipelines · 2026-07-31T15:44:30Z

Azure Pipelines: Successfully started running 3 pipeline(s).

kubaflo

Why it has the label do-not-merge?

KarthikRajaKalaimani · 2026-08-04T05:14:23Z

Why it has the label do-not-merge?

We plan to include this in .NET 12 as part of the full migration from BackgroundColor to the Background property across all source files.

MauiBot · 2026-08-10T13:19:22Z

⚠️ Merge Conflict Detected — This PR has merge conflicts with its target branch. Please rebase onto the target branch and resolve the conflicts.

KarthikRajaKalaimani temporarily deployed to gh-aw-agents June 25, 2026 12:58 — with GitHub Actions Inactive

dotnet-policy-service Bot added the community ✨ Community Contribution label Jun 25, 2026

dotnet-policy-service Bot added the partner/syncfusion Issues / PR's with Syncfusion collaboration label Jun 25, 2026

KarthikRajaKalaimani temporarily deployed to gh-aw-agents June 25, 2026 12:59 — with GitHub Actions Inactive

This was referenced Jun 25, 2026

[Release Readiness] .NET 11.0 preview6 — release/11.0.1xx-preview6 #35866

Closed

[Release Readiness] .NET 11.0 preview7 — release/11.0.1xx-preview7 #36138

Open

build-analysis Bot mentioned this pull request Jun 26, 2026

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

Open

3 tasks

KarthikRajaKalaimani force-pushed the fix-28854 branch 2 times, most recently from 31ec74e to ef245cd Compare July 2, 2026 09:23

This was referenced Jul 2, 2026

slow macOS - "##[error]The job running on agent Azure Pipelines 9 ran longer than the maximum time of 60 minutes." dotnet/dnceng#1883

Open

File upload failed even after retry dotnet/dnceng#1916

Open

This comment has been minimized.

Sign in to view

github-actions Bot added the s/agent-review-in-progress AI review is currently running for this PR label Jul 5, 2026

MauiBot reviewed Jul 5, 2026

View reviewed changes

Comment thread src/Controls/src/Core/VisualElement/VisualElement.cs

MauiBot added s/agent-gate-failed AI could not verify tests catch the bug s/agent-fix-pr-picked AI could not beat the PR fix - PR is the best among all candidates s/agent-reviewed PR was reviewed by AI agent workflow (full 4-phase review) labels Jul 5, 2026

This comment was marked as outdated.

Sign in to view

MauiBot removed the s/agent-review-in-progress AI review is currently running for this PR label Jul 6, 2026

KarthikRajaKalaimani and others added 15 commits July 31, 2026 13:52

Addressed concerns

f4fe2af

Fixed. The RS0036 error was caused by missing nullability markers

8a51337

fixed the Error RS0017

0dca974

Api related changes

5f588cf

Apply suggestions from code review, unshipped file changes

7bbd558

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Fix method signature for MapBackground in PublicAPI

2054580

Potential fix for pull request finding

0198244

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

removed unnecessary changes

f54a8d2

Fixed nullability error

bb12d94

Fixed the error

f014973

Fixed the build error

7c5862f

unrelated changes removed

e93e5c7

removed unwanted changes

5e38766

improved code readability

f13e612

[net11.0][Android] Fix Shell fragment teardown

ac14204

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 51b16329-8bf7-4952-960e-d9e9313e204d

This was referenced Jul 31, 2026

Checkout failure: "Git fetch failed with exit code 128" dotnet/arcade#9009

Open

Unable to checkout dotnet/dnceng#4115

Open

kubaflo requested changes Aug 1, 2026

View reviewed changes

This comment has been minimized.

Sign in to view

Uh oh!

Conversation

KarthikRajaKalaimani commented Jun 25, 2026 • edited by kubaflo Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of Change

Implementation Details

Tests

Migration Guide

Compatibility Guidance

Issues Fixed

Uh oh!

github-actions Bot commented Jun 25, 2026

Uh oh!

dotnet-policy-service Bot commented Jun 25, 2026

Uh oh!

vishnumenon2684 commented Jun 26, 2026

Uh oh!

azure-pipelines Bot commented Jun 26, 2026

Uh oh!

vishnumenon2684 commented Jun 26, 2026

Uh oh!

azure-pipelines Bot commented Jun 26, 2026

Uh oh!

vishnumenon2684 commented Jul 2, 2026

Uh oh!

azure-pipelines Bot commented Jul 2, 2026

Uh oh!

vishnumenon2684 commented Jul 3, 2026

Uh oh!

azure-pipelines Bot commented Jul 3, 2026

Uh oh!

This comment has been minimized.

MauiBot left a comment

Choose a reason for hiding this comment

Expert Review — 2 findings

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

kubaflo commented Jul 6, 2026

Uh oh!

kubaflo commented Jul 31, 2026

Uh oh!

azure-pipelines Bot commented Jul 31, 2026

Uh oh!

kubaflo commented Jul 31, 2026

Uh oh!

azure-pipelines Bot commented Jul 31, 2026

Uh oh!

kubaflo commented Jul 31, 2026

Uh oh!

azure-pipelines Bot commented Jul 31, 2026

Uh oh!

kubaflo commented Jul 31, 2026

Uh oh!

azure-pipelines Bot commented Jul 31, 2026

Uh oh!

kubaflo left a comment

Choose a reason for hiding this comment

Uh oh!

KarthikRajaKalaimani commented Aug 4, 2026

Uh oh!

This comment has been minimized.

MauiBot commented Aug 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

KarthikRajaKalaimani commented Jun 25, 2026 •

edited by kubaflo

Loading