Limit MaxItemCount in Virtualize

Author: SteveSandersonMS

src/Components/Web/src/Virtualization/Virtualize.cs

@@ -25,6 +25,14 @@ public sealed class Virtualize<TItem> : ComponentBase, IVirtualizeJsCallbacks, I
 
     private int _visibleItemCapacity;
 
+    // If the client reports a viewport so large that it could show more than MaxItemCount items,
+    // we keep track of the "unused" capacity, which is the amount of blank space we want to leave
+    // at the bottom of the viewport (as a number of items). If we didn't leave this blank space,
+    // then the bottom spacer would always stay visible and the client would request more items in an
+    // infinite (but asynchronous) loop, as it would believe there are more items to render and
+    // enough space to render them into.
+    private int _unusedItemCapacity;
+
     private int _itemCount;
 
     private int _loadedItemsStartIndex;
@@ -118,6 +126,22 @@ public sealed class Virtualize<TItem> : ComponentBase, IVirtualizeJsCallbacks, I
     [Parameter]
     public string SpacerElement { get; set; } = "div";
 
+    /*
+    This API will be added in .NET 9 but cannot be added in a .NET 8 or earlier patch,
+    as we can't change public API in patches.
+
+    /// <summary>
+    /// Gets or sets the maximum number of items that will be rendered, even if the client reports
+    /// that its viewport is large enough to show more. The default value is 100.
+    ///
+    /// This should only be used as a safeguard against excessive memory usage or large data loads.
+    /// Do not set this to a smaller number than you expect to fit on a realistic-sized window, because
+    /// that will leave a blank gap below and the user may not be able to see the rest of the content.
+    /// </summary>
+    [Parameter]
+    public int MaxItemCount { get; set; } = 100;
+    */
+
     /// <summary>
     /// Instructs the component to re-request data from its <see cref="ItemsProvider"/>.
     /// This is useful if external data may have changed. There is no need to call this
@@ -264,18 +288,23 @@ protected override void BuildRenderTree(RenderTreeBuilder builder)
         var itemsAfter = Math.Max(0, _itemCount - _visibleItemCapacity - _itemsBefore);
 
         builder.OpenElement(7, SpacerElement);
-        builder.AddAttribute(8, "style", GetSpacerStyle(itemsAfter));
+        builder.AddAttribute(8, "style", GetSpacerStyle(itemsAfter, _unusedItemCapacity));
         builder.AddElementReferenceCapture(9, elementReference => _spacerAfter = elementReference);
 
         builder.CloseElement();
     }
 
+    private string GetSpacerStyle(int itemsInSpacer, int numItemsGapAbove)
+        => numItemsGapAbove == 0
+        ? GetSpacerStyle(itemsInSpacer)
+        : $"height: {(itemsInSpacer * _itemSize).ToString(CultureInfo.InvariantCulture)}px; flex-shrink: 0; transform: translateY({(numItemsGapAbove * _itemSize).ToString(CultureInfo.InvariantCulture)}px);";
+
     private string GetSpacerStyle(int itemsInSpacer)
         => $"height: {(itemsInSpacer * _itemSize).ToString(CultureInfo.InvariantCulture)}px; flex-shrink: 0;";
 
     void IVirtualizeJsCallbacks.OnBeforeSpacerVisible(float spacerSize, float spacerSeparation, float containerSize)
     {
-        CalcualteItemDistribution(spacerSize, spacerSeparation, containerSize, out var itemsBefore, out var visibleItemCapacity);
+        CalcualteItemDistribution(spacerSize, spacerSeparation, containerSize, out var itemsBefore, out var visibleItemCapacity, out var unusedItemCapacity);
 
         // Since we know the before spacer is now visible, we absolutely have to slide the window up
         // by at least one element. If we're not doing that, the previous item size info we had must
@@ -286,12 +315,12 @@ void IVirtualizeJsCallbacks.OnBeforeSpacerVisible(float spacerSize, float spacer
             itemsBefore--;
         }
 
-        UpdateItemDistribution(itemsBefore, visibleItemCapacity);
+        UpdateItemDistribution(itemsBefore, visibleItemCapacity, unusedItemCapacity);
     }
 
     void IVirtualizeJsCallbacks.OnAfterSpacerVisible(float spacerSize, float spacerSeparation, float containerSize)
     {
-        CalcualteItemDistribution(spacerSize, spacerSeparation, containerSize, out var itemsAfter, out var visibleItemCapacity);
+        CalcualteItemDistribution(spacerSize, spacerSeparation, containerSize, out var itemsAfter, out var visibleItemCapacity, out var unusedItemCapacity);
 
         var itemsBefore = Math.Max(0, _itemCount - itemsAfter - visibleItemCapacity);
 
@@ -304,15 +333,16 @@ void IVirtualizeJsCallbacks.OnAfterSpacerVisible(float spacerSize, float spacerS
             itemsBefore++;
         }
 
-        UpdateItemDistribution(itemsBefore, visibleItemCapacity);
+        UpdateItemDistribution(itemsBefore, visibleItemCapacity, unusedItemCapacity);
     }
 
     private void CalcualteItemDistribution(
         float spacerSize,
         float spacerSeparation,
         float containerSize,
         out int itemsInSpacer,
-        out int visibleItemCapacity)
+        out int visibleItemCapacity,
+        out int unusedItemCapacity)
     {
         if (_lastRenderedItemCount > 0)
         {
@@ -326,11 +356,21 @@ private void CalcualteItemDistribution(
             _itemSize = ItemSize;
         }
 
+        // This AppContext data exists as a stopgap for .NET 8 and earlier, since this is being added in a patch
+        // where we can't add new public API.
+        var maxItemCount = AppContext.GetData("Microsoft.AspNetCore.Components.Web.Virtualization.Virtualize.MaxItemCount") switch
+        {
+            int val => val, // In .NET 9, this will be Math.Min(val, MaxItemCount)
+            _ => 1000       // In .NET 9, this will be MaxItemCount
+        };
+
         itemsInSpacer = Math.Max(0, (int)Math.Floor(spacerSize / _itemSize) - OverscanCount);
         visibleItemCapacity = (int)Math.Ceiling(containerSize / _itemSize) + 2 * OverscanCount;
+        unusedItemCapacity = Math.Max(0, visibleItemCapacity - maxItemCount);
+        visibleItemCapacity -= unusedItemCapacity;
     }
 
-    private void UpdateItemDistribution(int itemsBefore, int visibleItemCapacity)
+    private void UpdateItemDistribution(int itemsBefore, int visibleItemCapacity, int unusedItemCapacity)
     {
         // If the itemcount just changed to a lower number, and we're already scrolled past the end of the new
         // reduced set of items, clamp the scroll position to the new maximum
@@ -340,10 +380,11 @@ private void UpdateItemDistribution(int itemsBefore, int visibleItemCapacity)
         }
 
         // If anything about the offset changed, re-render
-        if (itemsBefore != _itemsBefore || visibleItemCapacity != _visibleItemCapacity)
+        if (itemsBefore != _itemsBefore || visibleItemCapacity != _visibleItemCapacity || unusedItemCapacity != _unusedItemCapacity)
         {
             _itemsBefore = itemsBefore;
             _visibleItemCapacity = visibleItemCapacity;
+            _unusedItemCapacity = unusedItemCapacity;
             var refreshTask = RefreshDataCoreAsync(renderOnSuccess: true);
 
             if (!refreshTask.IsCompleted)

src/Components/test/E2ETest/Tests/VirtualizationTest.cs

@@ -262,6 +262,25 @@ public void CanRenderHtmlTable()
         Assert.Contains(expectedInitialSpacerStyle, bottomSpacer.GetAttribute("style"));
     }
 
+    [Fact]
+    public void CanLimitMaxItemsRendered()
+    {
+        Browser.MountTestComponent<VirtualizationMaxItemCount>();
+
+        // Despite having a 600px tall scroll area and 30px high items (600/30=20),
+        // we only render 10 items due to the MaxItemCount setting
+        var scrollArea = Browser.Exists(By.Id("virtualize-scroll-area"));
+        var getItems = () => scrollArea.FindElements(By.ClassName("my-item"));
+        Browser.Equal(10, () => getItems().Count);
+        Browser.Equal("Id: 0; Name: Thing 0", () => getItems().First().Text);
+
+        // Scrolling still works and loads new data, though there's no guarantee about
+        // exactly how many items will show up at any one time
+        Browser.ExecuteJavaScript("document.getElementById('virtualize-scroll-area').scrollTop = 300;");
+        Browser.NotEqual("Id: 0; Name: Thing 0", () => getItems().First().Text);
+        Browser.True(() => getItems().Count > 3 && getItems().Count <= 10);
+    }
+
     [Fact]
     public void CanMutateDataInPlace_Sync()
     {

src/Components/test/testassets/BasicTestApp/Index.razor

@@ -108,6 +108,7 @@
         <option value="BasicTestApp.TouchEventComponent">Touch events</option>
         <option value="BasicTestApp.VirtualizationComponent">Virtualization</option>
         <option value="BasicTestApp.VirtualizationDataChanges">Virtualization data changes</option>
+        <option value="BasicTestApp.VirtualizationMaxItemCount">Virtualization MaxItemCount</option>
         <option value="BasicTestApp.VirtualizationTable">Virtualization HTML table</option>
         <option value="BasicTestApp.HotReload.RenderOnHotReload">Render on hot reload</option>
         <option value="BasicTestApp.SectionsTest.ParentComponentWithTwoChildren">Sections test</option>

src/Components/test/testassets/BasicTestApp/VirtualizationMaxItemCount.razor

@@ -0,0 +1,48 @@
+@implements IDisposable
+<p>
+    MaxItemCount is a safeguard against the client reporting a giant viewport and causing the server to perform a
+    correspondingly giant data load and then tracking a lot of render state.
+</p>
+
+<p>
+    If MaxItemCount is exceeded (which it never should be for a well-behaved client), we don't offer any guarantees
+    that the behavior will be nice for the end user. We just guarantee to limit the .NET-side workload. As such this
+    E2E test deliberately does a bad thing of setting MaxItemCount to a low value for test purposes. Applications
+    should not do this.
+</p>
+
+<div id="virtualize-scroll-area" style="height: 600px; overflow-y: scroll; outline: 1px solid red; background: #eee;">
+    @* In .NET 8 and earlier, the E2E test uses an AppContext.SetData call to set MaxItemCount *@
+    @* In .NET 9 onwards, it's a Virtualize component parameter *@
+    <Virtualize ItemsProvider="GetItems" ItemSize="30">
+        <div class="my-item" @key="context" style="height: 30px; outline: 1px solid #ccc">
+            Id: @context.Id; Name: @context.Name
+        </div>
+    </Virtualize>
+</div>
+
+@code {
+    protected override void OnInitialized()
+    {
+        // This relies on Xunit's default behavior of running tests in the same collection sequentially,
+        // not in parallel. From .NET 9 onwards this can be removed in favour of a Virtualize parameter.
+        AppContext.SetData("Microsoft.AspNetCore.Components.Web.Virtualization.Virtualize.MaxItemCount", 10);
+    }
+
+    private async ValueTask<ItemsProviderResult<MyThing>> GetItems(ItemsProviderRequest request)
+    {
+        const int numThings = 100000;
+
+        await Task.Delay(100);
+        return new ItemsProviderResult<MyThing>(
+            Enumerable.Range(request.StartIndex, request.Count).Select(i => new MyThing(i, $"Thing {i}")),
+            numThings);
+    }
+
+    record MyThing(int Id, string Name);
+
+    public void Dispose()
+    {
+        AppContext.SetData("Microsoft.AspNetCore.Components.Web.Virtualization.Virtualize.MaxItemCount", null);
+    }
+}