[Validation] Analyzer diagnostics for Virtualize item identity

[oroztocil]

Scenario contact: @ilonatommy

Scenario

A virtualized list that loads items on demand can make the viewport jump when the underlying data changes, and the cause is hard to trace: the component cannot tell one item from another, so it cannot work out whether items arrived before or after what the user is looking at. This validates that the build now warns about it, and that following the advice actually fixes the behavior.

Minimum build

.NET 11 Preview 7 or later.

Configurations to cover

• Blazor Web App
  • Static SSR
  • Interactive Server
  • Interactive WebAssembly
  • Interactive Auto
• Standalone WebAssembly
• Hybrid (MAUI)

These diagnostics are produced by the compiler, so they do not vary by render mode. The configuration below is the one needed to reproduce the runtime behavior the warning predicts, not a matrix to work through.

Also exercise

• Published output
• An existing .NET 10 app upgraded to .NET 11
• Trimming or ahead-of-time compilation
• More than one server instance, or a proxy in front
• Hot Reload
• An IDE as well as the command line
• Container

Setup

The diagnostic this scenario covers is:

Id	Title	Code fix
BL0011	Virtualize with ItemsProvider requires ItemComparer	No

What to build

A page with a long virtualized list whose items come from an ItemsProvider, so that you can insert items at the top and at the bottom while the user is scrolled into the middle of the list. Write it first without setting ItemComparer, and make the item type a class rather than a record, since the default comparer falls back to reference equality for classes and that is what the warning is about.

Add controls to insert items above and below the visible range, and show each item's index so you can tell where the viewport ended up.

Things to try

• Building at the command line and in an IDE, and reading the messages that appear.
• Scrolling into the middle of the list and then adding items above and below the visible range.
• Setting ItemComparer, then repeating the scrolling test.
• A Virtualize that supplies Items directly rather than through ItemsProvider, to see whether it is flagged.
• An item type that is a record rather than a class, to see whether that changes the warning.
• The same list rendered through QuickGrid rather than Virtualize.

Expected behavior

The problem is reported at build time, and setting ItemComparer fixes the runtime behavior the warning predicted.

Must hold

• The list written without ItemComparer produces a BL0011 warning at the correct line.
• Before ItemComparer is set, inserting items above the visible range moves the scroll position.
• After ItemComparer is set, the list keeps its scroll position when items are inserted above the visible range.
• A Virtualize that supplies Items directly, rather than through ItemsProvider, produces no BL0011 warning.
• The warning appears both at the command line and in the IDE, at the same line.

Expected differences between configurations

• None. The warning is produced at compile time and is identical in every configuration.

Documentation to use

• ASP.NET Core Razor component virtualization

What to report

Report results using the format described in the validation testing manual. Include link to a repository with the test app.

[VigneshwaranGovindharajan]

Test report

• Build tested: 11.0.100-preview.7.26381.103
• Configurations tested: Interactive Server
• Also exercised: Visual Studio IDE and command-line build
• OS, browser, IDE: Windows 11, Microsoft Edge, Visual Studio
• Sample app: https://github.com/VigneshwaranGovindharajan/validation-68485-virtualize-item-identity/tree/main/src/BlazorVirtualizeIdentityApp/BlazorVirtualizeIdentityApp
• Detailed test report: https://github.com/VigneshwaranGovindharajan/validation-68485-virtualize-item-identity/blob/main/test-report/ValidationReport.docx
• Outcome: Validation completed

Checks

Check	Result	Evidence
Virtualize with ItemsProvider and without ItemComparer produces BL0011 analyzer warning	pass	tc-001-build-output.png
BL0011 warning is reported on the correct Virtualize component usage	pass	tc-008-ide-errorlist.png
BL0011 warning appears in Visual Studio Error List	pass	tc-008-ide-errorlist.png
BL0011 warning appears during command-line build with the same warning ID and count	pass	tc-001-build-output.png
Verified scroll behavior when items are inserted above the visible range without ItemComparer viewport jump confirmed in .NET 10 sample and not observed in .NET 11 Preview 7	Not Reproduced in .NET11	tc-003-net10-viewport-jump.mp4
Adding ItemComparer removes BL0011 warning	pass	Source changes and rebuild validation
Scroll position remains stable after adding ItemComparer and inserting items above the viewport	pass	tc-004-scroll-stable
Using Virtualize with the Items parameter instead of ItemsProvider does not produce BL0011	pass	tc-005-items-source.png
Record types are analyzed and produce BL0011 when ItemComparer is not supplied	pass	tc-006-record-source.png
QuickGrid usage does not produce BL0011	pass	tc-007-quickgrid-source.png
Release publish reports the same BL0011 warning when applicable	pass	tc-010-publish-output.png
Application behavior remains correct after adding ItemComparer	pass	Runtime validation

Observations

1. Record types are analyzed the same way as classes

   • BL0011 is reported for record types when Virtualize uses ItemsProvider without ItemComparer.
   • Analyzer behavior was consistent across both class and record item models.

2. Diagnostic location differs between Visual Studio and command-line output

   • Visual Studio reports BL0011 directly on the .razor source file, while command-line build output reports the warning against the generated .g.cs file. The warning identifier and message are consistent, but the reported source locations differ between IDE and CLI output.

3. Visual Studio provides a good authoring experience

   • When BL0011 is reported in Visual Studio, the warning is shown directly on the ItemsProvider attribute with a tooltip explaining the issue. Visual Studio also displays the standard Quick Actions (Alt+.) UI.
   • No BL0011-specific analyzer code fix was validated, which is consistent with the scenario documentation indicating that BL0011 has no code fix.

4. QuickGrid setup requires package installation

   • QuickGrid scenarios built and executed successfully after adding the required package reference.
   • No BL0011 warning was reported for QuickGrid usage.

Findings

Finding 1

Visual Studio reports BL0011 against the .razor source file, while command-line build output reports the warning against the generated .g.cs file. The reported source locations differ between IDE and CLI output.

Problems

No functional issues found during validation.

Runtime validation note

The viewport jump described by the scenario was reproduced in an equivalent .NET 10 sample. However, the same behavior could not be reproduced in .NET 11 Preview 7 during testing, even after recreating item instances and destroying reference equality. Therefore, the runtime difference between the scenarios with and without ItemComparer could not be demonstrated in .NET 11.

Summary

Validation of analyzer diagnostics for Virtualize item identity was completed successfully. BL0011 is correctly reported when Virtualize uses ItemsProvider without ItemComparer, and the diagnostic is consistently surfaced in Visual Studio, command-line builds, and publish scenarios. Adding ItemComparer removes the warning and the application continued to behave correctly during testing.

[ilonatommy]

Verified scroll behavior when items are inserted above the visible range without ItemComparer viewport jump confirmed in .NET 10 sample and not observed in .NET 11 Preview 7

Try append. I had it tested with 2 Virtualize components without stable references, one with ItemComparer, the other without:

ItemComparer.needed.proof.mp4

VirtualizeUnstableItems.razor

[ilonatommy]

You can also update InsertBelow to not use stable references:
https://github.com/VigneshwaranGovindharajan/validation-68485-virtualize-item-identity/blob/b92dd072c0a917db564f2c2efa31ca486b2a49ca/src/BlazorVirtualizeIdentityApp/BlazorVirtualizeIdentityApp/Components/Pages/VirtualizeWithoutComparer.razor#L53
to see that.