Fix for VisualStateManager Setter.TargetName failing when ControlTemplate is applied

[BagavathiPerumal]

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!

Root Cause:

The issue occurs because VisualStateManager setters with TargetName rely on FindByName(), which only resolves elements within the same namescope. Since ControlTemplates create a new namescope, visual states defined inside a template cannot access elements outside it, resulting in the crash: "Cannot resolve [TargetName] as Setter Target."

Fix Description:

The fix involves using element.FindByName() for targets within the same or child namescopes and, if the target is not found, traversing the parent hierarchy to inspect each parent element’s namescope. This approach enables elements defined within a control template to resolve a TargetName outside their own namescope, ensuring reliable target resolution while maintaining compatibility with existing visual state behavior.

Issues Fixed

Fixes #26977

Tested the behaviour in the following platforms

• Android
• Windows
• iOS
• Mac

Output Screenshot

Before Issue Fix	After Issue Fix
26977-BeforeFix.mov	26977-AfterFix.mov

[Copilot]

Pull request overview

This PR fixes a crash in VisualStateManager when using Setter.TargetName with a ControlTemplate. The root cause is that FindByName() only resolves elements within the same namescope, and ControlTemplates create new namescopes. The fix adds a FindTargetByName() helper method that traverses the parent hierarchy to inspect each parent's namescope when the target is not found in the current scope.

Key Changes

• Added namescope traversal logic to resolve targets across ControlTemplate boundaries
• Created UI tests to validate the fix on all platforms
• Improved reliability of visual state setters with named targets in templated scenarios

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
src/Controls/src/Core/Setter.cs	Introduced FindTargetByName() method to walk up parent tree when resolving TargetName, enabling cross-namescope resolution for ControlTemplates
src/Controls/tests/TestCases.HostApp/Issues/Issue26977.xaml	Added UI test page demonstrating VisualStateManager with Setter.TargetName inside a ControlTemplate
src/Controls/tests/TestCases.HostApp/Issues/Issue26977.xaml.cs	Implemented code-behind with state toggling logic for the test scenario
src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue26977.cs	Added NUnit Appium test to verify the fix doesn't crash and correctly applies visual state setters

[Copilot]

The PlatformAffected should be set to PlatformAffected.All instead of PlatformAffected.Android. According to the PR description, this fix was tested on Android, Windows, iOS, and Mac. The issue is a VisualStateManager namescope resolution problem that affects all platforms where ControlTemplates create namescope boundaries, not just Android.

Suggested change

	[Issue(IssueTracker.Github, 26977, "Setter.TargetName + ControlTemplate crash", PlatformAffected.Android)]
	[Issue(IssueTracker.Github, 26977, "Setter.TargetName + ControlTemplate crash", PlatformAffected.All)]

[rmarinho]

🤖 AI Summary

📊 Expand Full Review

---

🔍 Pre-Flight — Context & Validation

---

📝 Review Session — fix-26977-Changes updated. · b89d310

---

Issue: #26977 - Setter.TargetName + ControlTemplate crash
PR: #33208 - Fix for VisualStateManager Setter.TargetName failing when ControlTemplate is applied
Author: BagavathiPerumal
Platforms Affected: All (Android, iOS, Windows, MacCatalyst) per PR testing
Issue Labels: t/bug, area-xaml, platform/android, s/verified, s/triaged, partner/syncfusion

Issue Summary

When using VisualStateManager with Setter.TargetName to target a specific element, the application crashes with XamlParseException: Cannot resolve 'TargetLabel' as Setter Target if the page has a ControlTemplate applied. This blocks usage of TargetName in any scenario where implicit page styles set ControlTemplate.

Reproduction steps:

1. Create a ContentPage with VisualStateManager
2. Add a Setter with TargetName pointing to a Label
3. Apply a ControlTemplate to the page
4. Toggle the visual state
5. App crashes with "Cannot resolve [TargetName] as Setter Target"

Expected behavior: Visual state setters with TargetName should work even when ControlTemplate is applied.

Root Cause (from PR)

The issue occurs because VisualStateManager setters with TargetName rely on FindByName(), which only resolves elements within the same namescope. Since ControlTemplates create a new namescope boundary, visual states defined inside a template cannot access elements outside it.

PR's Fix Approach

The PR introduces a FindTargetByName() helper method in Setter.cs that:

1. First tries standard element.FindByName() lookup (works for same or child namescopes)
2. If not found, walks up the parent hierarchy and inspects each parent element's namescope
3. This enables elements within a ControlTemplate to resolve TargetName outside their own namescope

Files Changed

Implementation files (1):

• src/Controls/src/Core/Setter.cs (+22/-2)
  • Added FindTargetByName() static method with parent hierarchy traversal
  • Updated Apply() and UnApply() to use new lookup method

Test files (3):

• src/Controls/tests/TestCases.HostApp/Issues/Issue26977.xaml (new)
• src/Controls/tests/TestCases.HostApp/Issues/Issue26977.xaml.cs (new)
• src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue26977.cs (new)

Test type: UI Test (Appium-based)

PR Discussion Summary

Copilot Review Feedback:

• File: Issue26977.xaml.cs - Copilot suggested PlatformAffected.All instead of PlatformAffected.Android → Applied (review thread is outdated)

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
PR	PR #33208	Add FindTargetByName() with parent hierarchy traversal to resolve targets across ControlTemplate namescope boundaries	✅ PASS (Gate)	Setter.cs (+22/-2)	Original PR - traverses parent tree when standard FindByName fails

---

🚦 Gate — Test Verification

---

📝 Review Session — fix-26977-Changes updated. · b89d310

---

Result: ✅ PASSED
Platform: android
Mode: Full Verification
Test Filter: Issue26977

Verification Results

Tests WITHOUT fix:

• Status: ❌ FAILED (as expected)
• The app crashed during the test, proving the bug is present
• Error: "The app was expected to be running still, investigate as possible crash"

Tests WITH fix:

• Status: ✅ PASSED (as expected)
• All tests ran successfully with the fix applied

Summary

Check	Expected	Actual	Result
Tests WITHOUT fix	FAIL	FAIL	✅
Tests WITH fix	PASS	PASS	✅

The verification confirms:

1. ✅ Tests correctly detect the bug - They fail when the bug is present (without fix)
2. ✅ Tests validate the fix - They pass when the bug is fixed (with fix)
3. ✅ The fix works as intended - The Setter.cs changes resolve the ControlTemplate namescope issue

Test Details:

• Test Class: SetterTargetNameWithControlTemplateShouldNotCrash
• Base Branch: main
• Fix Files: src/Controls/src/Core/Setter.cs

---

🔧 Fix — Analysis & Comparison

---

📝 Review Session — fix-26977-Changes updated. · b89d310

---

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
1	try-fix (claude-sonnet-4.5)	Modified VisualStateManager to set transientNamescope to root before calling setter.Apply()	❌ FAIL	VisualStateManager.cs (+54/-4)	Why failed: transientNamescope is ignored when GetNameScope() returns a value; doesn't solve the namescope resolution issue
2	try-fix (claude-opus-4.6)	Modified Element.FindByName() to search multiple namescopes up the parent tree when initial lookup fails	✅ PASS	Element.cs (+19/-1)	Works! More general solution at Element level benefits all callers, not just Setter
3	try-fix (gpt-5.2)	Modified NameScope to chain to ParentNameScope, allowing fallback resolution across namescope boundaries	✅ PASS	NameScope.cs (+36/-3)	Works! Links namescopes in a parent chain so FindByName naturally traverses boundaries
4	try-fix (gpt-5.2-codex)	Modified ControlTemplate to register/unregister template names in parent scope during parenting	❌ FAIL	ControlTemplate.cs (+73/-2)	Why failed: Timing issues or incomplete registration prevented resolution at VisualStateManager apply time
5	try-fix (gemini-3-pro-preview)	Environment blocker	⏸️ SKIPPED	N/A	Task agent did not produce response after retry; skipped per autonomous execution rules
PR	PR #33208	Added FindTargetByName() in Setter.cs with parent hierarchy traversal for TargetName resolution	✅ PASS (Gate)	Setter.cs (+22/-2)	Original PR - targeted fix specifically for Setter.TargetName use case

Cross-Pollination (Round 2)

Status: Complete - All 5 models responded

Model	Round 2 Response	Action Taken
claude-sonnet-4.5	NEW IDEA: Modify GetNameScope() to check transientNamescope BEFORE attached scope (invert precedence)	Not tested - sufficient passing alternatives exist
claude-opus-4.6	NEW IDEA: Modify VisualStateManager to pass correct INameScope directly to setter resolution	Not tested - sufficient passing alternatives exist
gpt-5.2	NEW IDEA: Capture namescope owner at XAML load time on Setter when TargetName is parsed	Not tested - sufficient passing alternatives exist
gpt-5.2-codex	NEW IDEA: Capture template root's INameScope on VisualStateGroup when attached	Not tested - sufficient passing alternatives exist
gemini-3-pro-preview	NEW IDEA: Introduce Setter.TargetNameScope property to explicitly define resolution scope	Not tested - sufficient passing alternatives exist

Exhausted: No (Round 2 generated ideas but selected fix is optimal; PR's fix chosen)

Selected Fix: PR's fix — Most conservative approach with minimal blast radius; only affects Setter.TargetName behavior without changing broader framework name resolution

---

📋 Report — Final Recommendation

---

📝 Review Session — fix-26977-Changes updated. · b89d310

---

✅ Final Recommendation: APPROVE

Summary

PR #33208 successfully fixes the VisualStateManager crash when using Setter.TargetName with ControlTemplate. The fix adds a FindTargetByName() helper method in Setter.cs that traverses the parent hierarchy to resolve targets across ControlTemplate namescope boundaries. The implementation is clean, well-tested, and represents the most conservative solution among multiple passing alternatives explored during the Fix phase.

---

PR Finalization Review

✅ Title: Good

Current: "Fix for VisualStateManager Setter.TargetName failing when ControlTemplate is applied"

Assessment: Clear and descriptive. Accurately describes the issue being fixed.

✅ Description: Excellent - Keep As-Is

Quality assessment:

• ✅ Required NOTE block present - Users can test PR artifacts
• ✅ Root cause clearly explained - Namescope boundary issue with ControlTemplate
• ✅ Fix approach documented - Parent hierarchy traversal
• ✅ Issue link present - Fixes Setter.TargetName + ControlTemplate crash #26977
• ✅ Platforms tested - All platforms verified
• ✅ Visual evidence - Before/after videos included

---

Root Cause Analysis

The Problem

When a ControlTemplate is applied to a page:

1. ControlTemplate creates a namescope boundary - Template content gets its own namescope
2. Content gets re-parented - Page content (e.g., RootStackLayout with TargetLabel) is re-parented under the template's ContentPresenter
3. GetNameScope() returns the wrong scope first - Walking up via RealParent finds the ControlTemplate's namescope before the page's namescope
4. Target is registered in different scope - TargetLabel is registered in the page's namescope (outer scope), not the template's namescope
5. FindByName() fails - The template's namescope doesn't contain "TargetLabel", causing the crash

The Solution

The FindTargetByName() method:

1. First tries standard element.FindByName() (works for same or child namescopes)
2. If not found, walks up the parent hierarchy
3. Inspects each parent element's namescope via GetNameScope()
4. Returns the first match found, or null if no match

---

Code Review Findings

✅ Looks Good

Implementation Quality:

• Clean separation of concerns: The FindTargetByName() method is a focused helper that does one thing well
• Fallback pattern: First tries standard FindByName(), only walks parent tree if needed
• Consistent usage: Applied to both Apply() and UnApply() methods
• Good comments: Explains the ControlTemplate namescope boundary scenario
• Proper null handling: Returns null if target not found, allowing exception to be thrown by caller

Test Coverage:

• UI test included: Issue26977.cs verifies the fix with Appium test
• Test scenario matches issue: Uses ControlTemplate with VisualStateManager and TargetName
• Proper test categorization: [Category(UITestCategories.Page)] applied
• Platform attribute correct: PlatformAffected.All matches the tested platforms

🔍 Minor Observations (Not Blocking)

Alternative Approaches Considered:

During the Fix phase (try-fix exploration), two other passing alternatives were found:

1. Attempt 2: Modified Element.FindByName() to search multiple namescopes (more general solution)
2. Attempt 3: Modified NameScope to chain to ParentNameScope (infrastructure-level solution)

Why PR's approach was selected:

• ✅ Minimal blast radius: Only affects Setter.TargetName behavior
• ✅ Clear intent: Method name and location make purpose obvious
• ✅ Conservative: Doesn't change framework-wide name resolution
• ✅ Proven: Gate verification confirmed tests FAIL without it, PASS with it

---

Comparison with Alternatives

Approach	Scope	Pros	Cons	Result
PR's Fix	Setter.cs only	Minimal impact, clear intent, conservative	Only helps Setter.TargetName (not other scenarios)	✅ SELECTED
Attempt 2	Element.FindByName	Benefits all callers, general solution	Changes fundamental framework behavior	✅ Works
Attempt 3	NameScope.FindByName	Infrastructure-level, natural chaining	More complex, performance implications	✅ Works

---

Test Validation

Gate Verification Results:

• ✅ Tests FAIL without fix (app crashes: "Cannot resolve 'TargetLabel' as Setter Target")
• ✅ Tests PASS with fix (VisualStateManager successfully resolves TargetName across ControlTemplate boundary)
• ✅ Platform: Android (representative test - fix applies to all platforms)

---

Recommendation Details

Why APPROVE

1. Fix is correct and proven - Gate verification confirms tests detect the bug and validate the fix
2. Implementation is clean - Well-structured code with appropriate comments
3. Test coverage is adequate - UI test reproduces the issue and validates the fix
4. Description is excellent - No changes needed, already thorough and accurate
5. Conservative approach - Minimal blast radius, only affects the specific scenario that was broken
6. Community contribution - Partner contribution (Syncfusion) solving a real user pain point

For Future Agents

What works:

• ✅ Parent hierarchy traversal in Setter-specific code
• ✅ Fallback pattern (try standard lookup first, then parent walk)
• ✅ Targeted fix over general framework changes

What to avoid:

• ❌ Modifying transientNamescope alone (ignored when GetNameScope() returns a value)
• ❌ Registering names in parent scope during template parenting (timing issues)

---

📋 Expand PR Finalization Review

---

Title: ✅ Good

Current: Fix for VisualStateManager Setter.TargetName failing when ControlTemplate is applied

Description: ✅ Good

Description needs updates. See details below.

✨ Suggested PR Description

[!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!

Root Cause

VisualStateManager setters with TargetName use element.FindByName() to locate the target element. FindByName resolves names within the element's own namescope. When a ControlTemplate is applied to a page, the template creates a new, isolated namescope. Elements defined inside the template (including ContentPresenter and its children) cannot find elements registered in the outer page namescope via FindByName, causing:

XamlParseException: Cannot resolve 'TargetLabel' as Setter Target for 'Microsoft.Maui.Controls.VerticalStackLayout'

This crash occurs whenever a ControlTemplate is used on a page (including via implicit styles) that also uses VisualState.Setters with TargetName.

Description of Change

File: src/Controls/src/Core/Setter.cs

Introduces a new private static helper FindTargetByName(Element element, string name) used by both Apply and UnApply:

1. First, try element.FindByName(name) — fast path that works for same/child namescopes (no behavior change for the common case)
2. If not found, walk up element.Parent hierarchy, calling GetNameScope() at each level and searching that namescope — this crosses ControlTemplate namescope boundaries to find elements in ancestor namescopes

This ensures Setter.TargetName can resolve elements defined outside a ControlTemplate's scope, matching the behavior users intuitively expect.

Issues Fixed

Fixes #26977

Platforms Tested

• Android
• Windows
• iOS
• Mac

Code Review: ✅ Passed

Code Review — PR #33208

Files Changed

• src/Controls/src/Core/Setter.cs — Core fix (+22/-2)
• src/Controls/tests/TestCases.HostApp/Issues/Issue26977.xaml — Test UI page (new)
• src/Controls/tests/TestCases.HostApp/Issues/Issue26977.xaml.cs — Test code-behind (new)
• src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue26977.cs — NUnit UI test (new)

---

🟡 Minor Issues

1. Missing newline at end of Setter.cs

File: src/Controls/src/Core/Setter.cs
Problem: The diff shows \ No newline at end of file — the file does not end with a newline character.
Impact: Low. Some editors and linters warn about this. POSIX standard requires text files to end with newline.
Recommendation: Add a trailing newline after the closing } of the class.

---

2. Potential redundant namescope lookups in FindTargetByName

File: src/Controls/src/Core/Setter.cs:113-127
Code:

static BindableObject FindTargetByName(Element element, string name)
{
    // Try standard lookup first (works for same or child namescopes)
    if (element.FindByName(name) is BindableObject target)
        return target;

    // Walk up parent tree to handle ControlTemplate namescope boundaries
    var current = element.Parent;
    while (current != null)
    {
        var namescope = current.GetNameScope();
        if (namescope?.FindByName(name) is BindableObject parentTarget)
            return parentTarget;
        current = current.Parent;
    }
    return null;
}

Problem: GetNameScope() itself walks up via RealParent until it finds a namescope. For intermediate parent elements that share the same inner (ControlTemplate) namescope, successive iterations of the while loop will call FindByName on the same namescope multiple times — the same namescope that step 1 (element.FindByName) already searched.
Impact: Low performance overhead in deep ControlTemplate hierarchies. Not a correctness bug — a name not in the inner namescope won't be found on repeat searches.
Recommendation: Could be optimized by tracking the last-seen INameScope and skipping if GetNameScope() returns the same instance as the previous iteration. However, given that ControlTemplate hierarchies are typically shallow and this is not a hot path, the current implementation is acceptable.

---

✅ Looks Good

Core fix logic

The two-phase strategy is correct:

1. element.FindByName(name) resolves within the element's own namescope (the ControlTemplate's scope)
2. If not found, walk element.Parent upward, calling GetNameScope() at each level — this correctly crosses the ControlTemplate boundary and reaches the page-level namescope where TargetLabel is registered

Apply and UnApply both updated

Both methods that used element.FindByName(TargetName) now use FindTargetByName, ensuring consistent behavior.

Static helper is well-scoped

FindTargetByName is a private static method with no side effects, making it easy to test and reason about.

Test page accurately reproduces the issue

Issue26977.xaml places a ControlTemplate on ContentPage, then uses VisualState.Setters with TargetName pointing to a Label outside the template scope — this exactly matches the reported issue scenario.

Test validates the fix

SetterTargetNameWithControlTemplateShouldNotCrash() verifies that toggling the switch (triggering a state transition with TargetName setters) does not crash and correctly updates the label text.

---

📎 Pre-existing Issue (Not Introduced by This PR)

UnApply throws ArgumentNullException vs Apply throwing XamlParseException

// Apply (line ~70):
?? throw new XamlParseException($"Cannot resolve '{TargetName}' as Setter Target for '{target}'.");

// UnApply (line ~93):
?? throw new ArgumentNullException(nameof(targetObject));

This exception type mismatch exists in main and predates this PR. The PR correctly preserves both existing behaviors without making them worse. This should be tracked as a separate cleanup item.

---

Test Coverage Observation

The test only verifies State2 → State1 (switch toggled on). It does not verify toggling back (State1 → State2) or that the initial (pre-toggle) state is correct. This is sufficient to catch the crash and verify the fix works in the primary direction. A more thorough test would also verify the reverse transition, but this is acceptable for a crash-fix test.

---

[PureWeen]

@StephaneDelcroix can you review this one?

[StephaneDelcroix]

the test should be a Xaml.UnitTest, not an appium one

[sheiksyedm]

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

[azure-pipelines]

Azure Pipelines successfully started running 2 pipeline(s).

[BagavathiPerumal]

the test should be a Xaml.UnitTest, not an appium one

@StephaneDelcroix, I have added a XAML unit test for the issue fix based on your suggestion.

[sheiksyedm]

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

[azure-pipelines]

Azure Pipelines successfully started running 2 pipeline(s).

[kubaflo]

Could you please review the latest AI's summary comment?

[BagavathiPerumal]

Could you please review the latest AI's summary comment?

I’ve verified that the fix gate has passed for both UI and unit tests in the local machine, and the fix works correctly on the Android platform.