Release status. Everything in this article was built and tested on .NET 11 RC1 (SDK 11.0.100-rc.1.26425.128, runtime 11.0.0-rc.1.26425.128, released September 8, 2026). RC1 has a go-live license, but it isn't the final release. APIs, generated markup, defaults, and browser behavior can still change before .NET 11 GA, which is planned for .NET Conf in November 2026. Rerun the sample's tests against each new SDK before you ship.

.NET 11 makes Virtualize<TItem> a viable choice for dynamic feeds, chats, logs, and variable-height collections. Before, it was mostly a component for predictable, uniform lists. It also works under a strict Content Security Policy for the first time. This article covers the changes behind that. It shows them in a runnable sample app, and it reports what I measured in Chrome, Firefox, and WebKit, including the rough edges that RC1 still has.

TL;DR

• Variable heights: Virtualize now measures rendered items and keeps a running average item height. ItemSize is only the starting estimate.

• Scroll anchoring: When something above the viewport changes height, what you're reading now normally stays put. Lists built from divs use the browser's native CSS scroll anchoring. <table> layouts, and browsers without overflow-anchor, use a ResizeObserver-based fallback.

• AnchorMode: A new parameter of the [Flags] enum VirtualizeAnchorMode. Start, the default, shows new items when you're at the top. End follows new items when you're at the bottom. None does neither. Away from the edges, every mode keeps the content you're reading in place when items are inserted.

• Scroll APIs: InitialItemIndex and ScrollToItemAsync finally let you open a list at a given item and jump to any item.

• Overscan: The OverscanCount default went from 3 to 15. That means more DOM, and bigger ItemsProvider requests.

• CSP: Spacer heights now travel in data-blazor-virtualize-* attributes and are applied through CSSOM, so style-src 'self' no longer breaks virtualization. On .NET 10, the same policy collapsed a 100,000-item list to a 1,227 px scroll range.

• RC1 caveats I measured:

  • <table> rows that grow right after scrolling are only partly compensated.
  • The first render after InitialItemIndex can move the content by 53–82 px.
  • AnchorMode.End sometimes stops 29–77 px short of the bottom after an append. In Playwright's WebKit build that happened in 10 of 30 checks; in Chrome and Firefox, in 1–2 of 30.
  • In Playwright's WebKit build, a Start list jumps when items are appended at the very end.
  • The docs' AnchorMode="Start" shorthand doesn't compile.

  Details and workarounds are below.

Large lists are not just a rendering problem

Picture an operations dashboard that shows 100,000 events. New events arrive every second and descriptions vary in length. Users have to be able to inspect older entries without being yanked back to the newest one every time something happens.

A naive @foreach over those events runs into trouble on several fronts at once:

• DOM size. In the sample, 100,000 simple three-cell rows produced 400,078 DOM elements. Layout, style recalculation, and memory all grow with that number, and richer rows are worse.
• Render cost. Blazor has to diff and describe every row. On Blazor Server, that description is a render batch sent over SignalR. On Blazor WebAssembly, it runs on the browser's main thread.
• Prerendered HTML. With prerendering, which the Blazor Web App template has on by default, every row is also rendered into the initial HTML document. The foreach version of the sample's 100,000-item list produced a 28.6 MB HTML response, compared with 11.7 KB for the virtualized version. The foreach page also took almost two minutes to become interactive (section 12).
• Constant change. Feeds, chats, and log viewers change while people read them. Prepending an item or expanding a card above the viewport moves the content under the reader's eyes.

Three separate ideas are at play here. Real apps usually need all three, but they solve different problems:

| Concept | What it solves | Blazor feature | |---|---|---| | Virtualization | Only render what's (nearly) visible | Virtualize<TItem> | | Incremental loading | Only fetch what's (nearly) visible | ItemsProvider + ItemsProviderRequest | | Scroll anchoring | Keep what the user is reading still while data changes | .NET 11 anchoring + AnchorMode |

What Virtualize<TItem> actually does

Virtualize<TItem> renders a window of items inside a scroll container. It stands in for everything outside that window with two spacer elements.

Figure 1. The two spacers reserve the height of the items that aren't rendered. An IntersectionObserver watches the spacers and tells .NET when one of them scrolls into view.

Here's how it works:

1. It finds the closest scrollable ancestor. In RC1, that's the first ancestor whose overflow-y is not visible, hidden, or clip. If there's none, it uses the document itself.
2. It renders the visible items plus OverscanCount extra items before and after them.
3. It renders a spacer before and after the window. Each spacer's height is number of items it replaces × average item height.
4. An IntersectionObserver (50 px root margin) watches both spacers. When one becomes visible, JavaScript reports the sizes to .NET, which computes a new window and renders it.

This foreach:

<div class="stream-viewport">
    @foreach (var item in items)
    {
        <ActivityCard @key="item.Id" Item="item" />
    }
</div>

becomes this:

<div class="stream-viewport" tabindex="0">
    <Virtualize Items="items" Context="item">
        <ActivityCard @key="item.Id" Item="item" />
    </Virtualize>
</div>

Virtualize doesn't require the whole collection to be in memory:

• Items takes an in-memory ICollection<TItem>. The component slices it directly.
• ItemsProvider takes a delegate. It receives an ItemsProviderRequest (StartIndex, Count, CancellationToken) and returns an ItemsProviderResult<TItem> (the slice plus TotalItemCount). Only the requested range needs to be loaded from the backend.

Prerendering emits (almost) no items. During static prerendering, Virtualize normally emits only its spacers. Real items appear once the component becomes interactive, which is why the virtualized HTML above was only 11.7 KB.

• With Items, the prerendered trailing spacer is item count × ItemSize.
• With an ItemsProvider, the provider isn't called during prerendering, so both spacers are 0 px. The sample's /feed and /grid pages prerender data-blazor-virtualize-reserved-height="0" twice.
• One exception in RC1: with in-memory Items and InitialItemIndex greater than 0, the window moves to the target before the first render. Up to 2 × OverscanCount + 1 items around it are then prerendered. The sample's /chat page prerenders messages #99,985–#100,000.

If you need all items in the initial HTML, for SEO or for no-JS clients, virtualization isn't the right tool. See section 20.

What changed in .NET 11

| | .NET 10 | .NET 11 RC1 | Introduced in | |---|---|---|---| | Variable-height items | Assumed uniform height (ItemSize) | Running average of measured heights | Preview 3 | | Default OverscanCount | 3 | 15 (QuickGrid stays at 3) | Preview 3 | | Content stability when items above resize | Native scroll anchoring disabled, so content jumped | Native CSS anchoring or ResizeObserver compensation | Preview 4 | | Edge pinning | Hand-written JS | AnchorMode (None, Start, End, combinable) | Preview 4 (renamed in Preview 7) | | Prepend/append detection for providers | — | ItemComparer (defaults to EqualityComparer<T>.Default) | Preview 4 / Preview 7 | | Open at / jump to an item | Hand-written JS | InitialItemIndex, ScrollToItemAsync | Preview 6 (renamed in Preview 7) | | Strict style-src 'self' | Spacers render style="height:…", which the policy blocks | Spacer sizes rendered as data-* attributes and applied via CSSOM | Preview 6 |

To avoid relying only on the docs, I dumped the public surface from the RC1 shared framework with reflection, using a small file-based C# app. Abridged output, with TItem shown generically:

Assembly: Microsoft.AspNetCore.Components.Web 11.0.0-rc.1.26425.128
[Parameter] VirtualizeAnchorMode AnchorMode = Start
[Parameter] Int32 InitialItemIndex = 0
[Parameter] IEqualityComparer`1 ItemComparer = (EqualityComparer<TItem>.Default)
[Parameter] Single ItemSize = 50
[Parameter] Int32 MaxItemCount = 100
[Parameter] Int32 OverscanCount = 15
[Parameter] String SpacerElement = div
method Task ScrollToItemAsync(Int32 itemIndex, CancellationToken cancellationToken = default)
enum VirtualizeAnchorMode [Flags]  None = 0, Start = 1, End = 2

Reading older preview blog posts? Preview 7 renamed three APIs: VirtualizeAnchorMode.Beginning → Start, InitialIndex → InitialItemIndex, and ScrollToIndexAsync → ScrollToItemAsync. Code from Preview 4–6 posts won't compile on RC1 until you apply those renames.

Variable-height items

Earlier versions assumed that every item had the height given by ItemSize. In .NET 11, ItemSize is only the initial estimate. Once items render, the JavaScript side measures the total height of everything rendered between the two spacers, using a DOM Range. It sends that total to .NET along with the spacer and container sizes. .NET adds it to a running total and uses totalMeasuredHeight / measuredItemCount for every spacer calculation after that. Measurements are only taken when no placeholders are on screen, so placeholder heights don't distort the average.

You can see this in the sample. The activity feed starts with ItemSize="96" and 100,000 items, so the first scroll range is 100,000 × 96 ≈ 9.6 million px. After the first measurements it settles at about 8.4 million px, an average of about 84 px per card.

Two consequences:

• Virtualize doesn't know the exact height of each item. It estimates the unrendered ones from the average. When you jump by dragging the scrollbar far into an unmeasured region, the first position is an estimate and may be corrected slightly.
• A better ItemSize still helps, because it makes the first render and the first scroll range closer to reality.

3.2 Hybrid scroll anchoring

In .NET 10, Virtualize turned off the browser's native scroll anchoring, because spacer resizes could otherwise start a feedback loop. As a result, content jumped whenever an item above the viewport changed height. .NET 11 uses one of two paths instead:

Figure 2. The path is chosen by feature detection (CSS.supports('overflow-anchor', 'auto')) and by whether the spacers' parent is a table section. RC1 does no user-agent sniffing.

You can see the choice in the DOM:

• In the sample's div-based feed, the scroll container keeps overflow-anchor: auto and only the spacers get overflow-anchor: none.
• In the <table> grid, the container itself gets overflow-anchor: none and the manual path takes over.

Chrome, Firefox, and Playwright's WebKit build all behaved this way, and all three report overflow-anchor support. Real Safari is a different story: according to MDN's compatibility data it supports overflow-anchor only from Safari 27. On older Safari and iOS versions, even div lists take the manual path. Playwright's WebKit build doesn't exercise that path.

The OverscanCount default changed from 3 to 15

More overscan means fewer blank moments during fast scrolling and more items to average heights over. It also means:

• More DOM. The sample's feed renders 37–38 cards at the top of a 100,000-item list, compared with about 7 visible ones.
• Bigger ItemsProvider requests. With 15 items before and after the visible range, a request asks for roughly visible + 30 items instead of visible + 6.
• No breaking-change notice. The change isn't listed on the .NET 11 or ASP.NET Core 11 breaking-changes pages, so check for it yourself when you upgrade.

QuickGrid deliberately keeps OverscanCount = 3, because grid rows are heavier. See section 13 for how to choose.

The sample application: LiveStream

The sample is a Blazor Web App (Interactive Server) that renders a deterministic dataset of 100,000 synthetic events. Every scenario in this article is a page in it. The sample isn't published with this article. The code blocks below are excerpts from it, and the layout shows where each excerpt lives.

LiveStream/
├── global.json                      # pins the .NET 11 RC1 SDK
├── src/LiveStream/
│   ├── Components/
│   │   ├── Pages/ActivityFeed.razor  # ItemsProvider + AnchorMode.Start
│   │   ├── Pages/LiveChat.razor      # Items + AnchorMode.End + InitialItemIndex
│   │   ├── Pages/DataGrid.razor      # <table> + ScrollToItemAsync
│   │   ├── Pages/Labs/AnchorLab.razor
│   │   ├── Pages/Labs/PerfLab.razor
│   │   └── Stream/                   # ActivityCard, ChatMessage, StatsBar, ReadyMarker
│   ├── Models/StreamItem.cs
│   ├── Services/SyntheticDataset.cs  # shared, immutable 100k items
│   ├── Services/ActivityFeedStore.cs # per-circuit view + ItemsProvider
│   ├── Security/ContentSecurityPolicy.cs
│   └── wwwroot/js/                   # csp-monitor.js, stream-interop.js
├── baseline/CspBaseline.Net10/       # same CSP on .NET 10, for comparison
├── tests/LiveStream.Tests/           # xUnit + WebApplicationFactory
├── tools/ApiSurface.cs              # dumps the Virtualize API (section 3)
└── e2e/                              # Playwright tests, measurement scripts, results/

Technical choices:

• Interactive Server keeps the sample easy to run. The virtualization code is the same on WebAssembly. Section 17 covers the differences.
• net11.0, with the SDK pinned in global.json.
• 100,000 records, with messages ranging from one to six lines. About 18% have an expandable diagnostics block.
• 150–400 ms simulated latency in the feed's provider, with cancellation.
• A strict CSP header on every page: style-src 'self' and a per-request nonce for the one inline script (the import map). A badge in the corner counts violations live.

To try the ideas yourself, start from the Blazor Web App template on the .NET 11 SDK:

dotnet new blazor --interactivity Server --all-interactive -o LiveStream
cd LiveStream
dotnet run

Then add the pieces from the excerpts: the model and provider (next section), the feed and chat pages, and the CSP middleware (Content Security Policy).

The data model and the ItemsProvider

The model is a record:

public sealed record StreamItem(
    long Id,
    string Author,
    string Message,
    string? Details,
    DateTimeOffset CreatedAt,
    StreamItemKind Kind)
{
    /// <summary>
    /// Identity by key. Virtualize uses ItemComparer to tell whether items were prepended
    /// or appended between ItemsProvider calls. The default (record value equality) compares
    /// every field, so an edited item would look like a different item; the Id doesn't change.
    /// </summary>
    public static IEqualityComparer<StreamItem> ById { get; } =
        EqualityComparer<StreamItem>.Create((a, b) => a?.Id == b?.Id, item => item.Id.GetHashCode());
}

Why a comparer, when records already have value equality? When data comes from an ItemsProvider and the total count grows, Virtualize compares the first item it rendered before with the first item of the new result. A mismatch means "items were inserted above". Record equality works until that first rendered item is edited in a refresh where the count also grew, which happens constantly in a live feed. The old and new versions then compare unequal, and an edit looks like a prepend. A key-based comparer avoids that.

The RC1 SDK agrees. Building the sample without a comparer produced a new analyzer warning:

warning BL0011: Virtualize uses 'ItemsProvider' without 'ItemComparer'.
Set ItemComparer to an IEqualityComparer that identifies items by a unique key.

(With in-memory Items, Virtualize ignores ItemComparer and uses EqualityComparer<TItem>.Default.)

The provider is the store method that Virtualize calls:

private async ValueTask<ItemsProviderResult<StreamItem>> GetAsync(ItemsProviderRequest request, bool newestFirst)
{
    Interlocked.Increment(ref _providerCalls);
    LastRequest = (request.StartIndex, request.Count);

    try
    {
        var (min, max) = Latency;
        if (max > 0)
        {
            // Simulated network + database time. Virtualize cancels this token
            // when the user scrolls on before the response arrives.
            await Task.Delay(Random.Shared.Next(min, max + 1), request.CancellationToken);
        }
    }
    catch (OperationCanceledException)
    {
        Interlocked.Increment(ref _canceledCalls);
        throw;
    }

    return GetRange(request.StartIndex, request.Count, newestFirst);
}

• request.StartIndex is the index of the first item to return.
• request.Count covers the visible range plus overscan on both sides. It's larger in .NET 11 because of the new default.
• request.CancellationToken is canceled when a newer request replaces this one. In the browser test, scrolling quickly through the feed produced canceled provider calls in all three engines. Pass the token all the way down to your database or HTTP call.
• TotalItemCount (the second constructor argument of the result) sets the spacer sizes. It has to be accurate and cheap.

Offset pagination gets expensive. Skip(n).Take(m) is fine for a demo. Deep offsets can be slow in relational databases, and running COUNT(*) on every request adds up. For production feeds, consider keyset (cursor) pagination behind a layer that maps virtual indexes to stable cursors, and cache the total count.

One design detail in the sample is worth copying. The 100,000 base records are a shared, immutable singleton. Each circuit keeps only its own new events in a small list, so adding an item costs O(1) and a new circuit costs a few hundred bytes instead of a copy of the dataset.

Scenario 1: an activity feed with AnchorMode.Start

New activity arrives at the top of the feed. It's newest first, and index 0 is the newest event.

<div class="stream-viewport" tabindex="0" @ref="viewport" aria-label="Activity feed, newest first">
    <Virtualize @ref="virtualize" TItem="StreamItem" ItemsProvider="provider" ItemComparer="StreamItem.ById"
                Context="item" ItemSize="96" AnchorMode="VirtualizeAnchorMode.Start">
        <ItemContent>
            <ActivityCard @key="item.Id" Item="item" Expanded="expanded.Contains(item.Id)" OnToggle="ToggleDetails" />
        </ItemContent>
        <Placeholder>
            <div class="activity-card activity-card--placeholder" aria-hidden="true">…</div>
        </Placeholder>
        <EmptyContent>
            <p class="stream-empty">No activity has been recorded yet.</p>
        </EmptyContent>
    </Virtualize>
</div>

provider is assigned once in OnInitialized (provider = Store.GetNewestFirstAsync;), so every render passes the same delegate instance. New events, whether from the simulated live stream or the "+5 events" button, aren't pushed to the UI one at a time. They go into a queue, and a 250 ms PeriodicTimer flushes them in batches:

private async Task FlushAsync()
{
    List<StreamItem> batch = [];
    while (pending.TryDequeue(out var item))
    {
        batch.Add(item);
    }

    if (batch.Count == 0 || virtualize is null)
    {
        return;
    }

    Store.Add(batch);

    if (!atTop)
    {
        unseen += batch.Count;
        announcement = $"{unseen} new events above.";
    }

    // ItemsProvider data changed outside of Virtualize: ask it to re-request the visible range.
    await virtualize.RefreshDataAsync();
    StateHasChanged();
}

atTop comes from a small JS helper, shown in the next section, that reports when the user reaches or leaves the top edge. It uses the same definition as AnchorMode.Start in RC1: scrollTop < 1. A looser threshold would create a gap. The page would think the user was at the top and skip the pill, while Virtualize would already be keeping the new events out of view.

Expected UI behavior, and what I measured

| Situation | Expected | Measured (Chrome, Firefox, WebKit) | |---|---|---| | At the top, 5 events arrive | The view stays at the top and shows the new events | scrollTop stays 0; the first visible card is the newest | | Reading older events, 5 events arrive | What you're reading doesn't move; an "↑ 5 new events" pill appears | Same first visible card, offset changed by ≤ 1 px | | A card above the viewport expands | Visible content stays put | 0 px shift (wheel scrolling, 6/6 runs per engine) | | DOM size | Only a window of the 100,000 events | 37–38 cards rendered | | Fast scrolling with 150–400 ms latency | Stale requests are canceled | Canceled provider calls > 0 in every run of the test |

The pill calls ScrollToItemAsync(0). The GIF is a screen recording of the sample in Chrome.

Scenario 2: a chat or log viewer with AnchorMode.End

In a chat or log viewer, new items arrive at the bottom, and the list should open there too:

<div class="stream-viewport stream-viewport--chat" tabindex="0" @ref="viewport" aria-label="Chat messages, oldest first">
    <Virtualize @ref="virtualize" Items="messages" Context="message"
                ItemSize="72" AnchorMode="VirtualizeAnchorMode.End"
                InitialItemIndex="@(messages.Count - 1)">
        <ChatMessage @key="message.Id" Message="message" Mine="@(message.Author == Me)" />
    </Virtualize>
</div>

• Items is a List<StreamItem>. With in-memory Items, Virtualize re-reads the collection on every render, so appending is just messages.Add(...) followed by StateHasChanged(). You don't need RefreshDataAsync.
• InitialItemIndex="@(messages.Count - 1)" opens the list at the latest message. It's applied once, on the first interactive render.
• AnchorMode.End follows new messages only while the user is at the bottom. In RC1, "at the bottom" means less than 2 px away.

The core UX rule for chat UIs is to follow new messages only while the user is already following the live edge. AnchorMode.End implements that rule. The sample adds the other half: an unread counter and a way back to the bottom. A tiny JS module reports when the user leaves or reaches an edge, using the same thresholds as Virtualize (1 px for the top, 2 px for the bottom). It calls .NET only when that state flips, not on every scroll event:

export function watchEdge(element, dotNetRef, edge, threshold) {
    let atEdge = null;
    let frame = 0;

    const check = () => {
        frame = 0;
        const distance = edge === 'end'
            ? element.scrollHeight - element.clientHeight - element.scrollTop
            : element.scrollTop;
        const now = distance < threshold;
        if (now !== atEdge) {
            atEdge = now;
            dotNetRef.invokeMethodAsync('OnEdgeChanged', now);
        }
    };
    // … a scroll listener and a ResizeObserver schedule check() once per animation frame
}

@if (unread > 0)
{
    <button type="button" class="new-items-pill new-items-pill--bottom" @onclick="JumpToLatestAsync">
        ↓ @unread new @(unread == 1 ? "message" : "messages")
    </button>
}

Expected UI behavior, and what I measured

| Situation | Expected | Measured | |---|---|---| | Page opens | At the bottom, message #100,000 visible | ✔ all engines (InitialItemIndex) | | At the bottom, a message arrives | Scrolls to show it | With the sample's guard: ✔ 30/30 follow checks per engine. AnchorMode.End alone: Chrome 29/30, Firefox 28/30, WebKit 20/30 (see below) | | Scrolled up, 20 messages arrive | View stays put; "↓ 20 new messages" pill | ✔ all engines, scrollTop unchanged | | User returns to the bottom | Following resumes | ✔ all engines |

An RC1 caveat: End-follow sometimes stops short

I ran the chat tests 10 times per engine with the sample's safety net turned off. Each run contains three checks that depend on AnchorMode.End following an append: a new message, a message sent from the composer, and a new message after returning to the bottom. They passed 29/30 in Chrome, 28/30 in Firefox, and 20/30 in Playwright's WebKit. In every failure, the list ended 29–77 px short of the bottom 600 ms after the append (Chrome 72 px, Firefox 61 px, WebKit 29–77 px), so the new message was only partly visible. Outside the test suite the miss was rare: in isolated WebKit runs.

The sample therefore adds a small, explicit safety net. It only acts if the page's edge watcher considered the user to be at the live edge (less than 2 px, the same as AnchorMode.End) when the message arrived, and the list then ended up between 1 and 120 px short of the bottom:

export function stickToBottom(element, tolerance) {
    requestAnimationFrame(() => {
        const distance = element.scrollHeight - element.clientHeight - element.scrollTop;
        if (distance > 1 && distance <= tolerance) {
            element.scrollTop = element.scrollHeight;
        }
    });
}

With the guard on (the sample's default), the same 10× run passed all 40 chat tests, including 30/30 follow checks, in every engine. The guard-off numbers above were measured with the guard disabled, to observe AnchorMode.End on its own. An End-anchoring fix is already merged for RC2 (dotnet/aspnetcore#69388). It changes exactly the condition that decides when to pin, so retest before you keep or remove a workaround like this. Playwright's WebKit on Windows is also not Safari on macOS or iOS, so test on real devices too.

Understanding every AnchorMode, measured

The docs describe the modes in terms of scroll position. To find out what they actually do, the sample's AnchorMode lab (/lab/anchor) prepends or appends 5 items at the top, middle, and bottom of a 2,000-item variable-height list. It runs every mode with both Items and ItemsProvider, in Chrome, Firefox, and WebKit.

| Where the user is | What arrives | None | Start (default) | End | Start \| End | |---|---|---|---|---|---| | At the top | 5 items prepended | Keeps place | Shows the new items | Keeps place | Shows the new items | | At the top | 5 items appended | Keeps place | Keeps place | Keeps place | Keeps place | | In the middle | 5 items prepended | Keeps place | Keeps place | Keeps place | Keeps place | | In the middle | 5 items appended | Keeps place | Keeps place | Keeps place | Keeps place | | At the bottom | 5 items prepended | Keeps place | Keeps place | Keeps place | Keeps place | | At the bottom | 5 items appended | Keeps place | Keeps place ⚠️ | Follows the new items | Follows the new items |

"Keeps place" means the item that was first visible before the change was still the first visible item afterward. The matrix records which item that was, not its pixel offset; sections 6 and 10 report pixel shifts. Items and ItemsProvider fell into the same category in every cell. 46 of the 48 scenarios gave the same result in Chrome, Firefox, and WebKit (144 measurements in total). The ⚠️ cell covers both exceptions, which were WebKit with Start, for Items and for ItemsProvider.

Three conclusions:

1. Keeping your place is the default everywhere. AnchorMode doesn't turn anchoring on or off. It decides what happens at the edges: Start shows new items when you're at the very top (scrollTop < 1), and End follows new items when you're at the very bottom (within 2 px).
2. None keeps the content still, not the scrollTop number. The docs say None keeps "the current scroll position". With None, though, prepending 5 items at the top increased scrollTop by about 400 px, so that the same item stayed in view. If you want new items at the top to become visible, that's Start.
3. Between the edges, all four modes behave the same.

⚠️ WebKit and infinite lists. In Playwright's WebKit build, appending items while the user was at the very end of a Start list (the default) moved the visible content. It moved 214 px with Items and 366–486 px with ItemsProvider, in 3 of 3 runs. With AnchorMode.None it moved 0 px, and Chrome and Firefox moved 0 px in both modes. That's exactly the classic infinite-scroll pattern: reach the end, and more items load. If a list only ever grows at the end and doesn't need top pinning, set AnchorMode="VirtualizeAnchorMode.None" and test on real Safari.

Gotcha: the docs' Razor shorthand doesn't compile

The release notes and the virtualization docs show this:

<Virtualize AnchorMode="Start" ...>   @* from the docs *@

On RC1, that fails with CS0103: The name 'Start' does not exist in the current context. Razor treats non-string component parameters as C# expressions, so write the enum out in full:

<Virtualize AnchorMode="VirtualizeAnchorMode.Start" ...>
<Virtualize AnchorMode="VirtualizeAnchorMode.Start | VirtualizeAnchorMode.End" ...>

Other details worth knowing

• Upgraded lists get Start automatically. It's the default because it matches how lists behaved before. If a list shouldn't pin to anything, such as a sortable grid or an infinite list that grows at the end, set None explicitly.
• AnchorMode can change at runtime. Virtualize sends the new value to JavaScript after the next render.
• Keyboard: Pressing End in the scroll container turns on bottom-following even when End isn't set, and Home clears it. ScrollToItemAsync also clears it.
• Deletions above the viewport are not anchored. Inserts and height changes are, but removing items above the reader still moves content. That's an open backlog request (dotnet/aspnetcore#66509).
• Start | End is allowed, but the design discussion admits there's no known real use case for it.

Refreshing virtualized data without thrashing

With an ItemsProvider, Virtualize can't know that your data changed. Call RefreshDataAsync(). When the change comes from outside Blazor's event pipeline, such as a timer, a SignalR client, or a message-bus handler, marshal it onto the renderer first. The handler below is illustrative. The sample does the same thing with its PumpAsync loop, which calls InvokeAsync(FlushAsync) (section 6):

// Called from a timer, a SignalR client, or a message-bus handler, not from a Blazor event.
private Task OnEventsArrivedAsync(IReadOnlyList<StreamItem> batch) => InvokeAsync(async () =>
{
    Store.Add(batch);

    if (virtualize is not null)
    {
        await virtualize.RefreshDataAsync(); // re-requests the current window
    }

    StateHasChanged(); // RefreshDataAsync doesn't render by itself
});

Rules that matter in practice:

• Get back onto the renderer's synchronization context with InvokeAsync, as above. RefreshDataAsync must run there too.
• Call StateHasChanged() afterwards when the refresh doesn't come from a Blazor event handler. RefreshDataAsync fetches, but it doesn't render.
• Batch. In RC1, RefreshDataAsync() also resets the running average item height, so every refresh starts measuring from scratch. Refreshing on every message of a busy stream means more provider calls, more renders, and less accurate spacer estimates. The sample drains its queue with a 250 ms PeriodicTimer, so the list refreshes at most four times per second, however fast events arrive.
• Clean up. Implement IAsyncDisposable: cancel timers and loops, dispose DotNetObjectReferences and JS module references, and catch JSDisconnectedException when the circuit is already gone. The RC1 SDK nudges you here too, with a new analyzer warning: BL0016: JS interop call 'InvokeAsync' is not guarded with a try/catch block.
• Pass the cancellation token through. When a newer request supersedes an older one, the older token is canceled. Ignoring it just wastes backend work.

Variable heights and expansion

Every card in the sample's feed has a different height, and about 18% can expand a diagnostics block. Three rules make that work well:

1. Keep per-item UI state in the parent, not in the item component. Virtualize disposes item components that scroll out of the window. An Expanded field inside ActivityCard would be lost as soon as the card scrolled away. The sample keeps a HashSet<long> of expanded IDs in the page and passes Expanded down as a parameter.
2. Give each item one root element, and no vertical margins. Heights are measured from the rendered content between the spacers, and collapsing margins between siblings make that fragile. Use padding and borders inside the item instead.
3. Reserve space for content that loads later. An image without width and height (or aspect-ratio) changes the row height after it loads. Anchoring compensates, but it's better not to cause the shift in the first place.

How stable is it? Measurements

In this test I scrolled with real mouse-wheel input, then expanded an item rendered just above the viewport, and recorded how far the first visible item moved. Six runs per cell:

| Layout (anchoring path) | Chrome | Firefox | WebKit | |---|---|---|---| | div feed (native CSS anchoring) | 0 px ×6 | 0 px ×6 | 0 px ×6 | | <table> grid (manual ResizeObserver) | 41–42 px ×4, 222 px ×1, 0 px ×1 | 41–42 px ×4, 0 px ×2 | 0–1 px ×5, 42 px ×1 | | <table> grid, after ordinary renders first | ≤ 1 px ×6 | 0 px ×6 | ≤ 1 px ×6 |

What's behind the table numbers:

• Tables have a gap in RC1. On the manual path, rows are added to the ResizeObserver after ordinary renders but not after scroll-triggered renders. A row that changes height right after a scroll can be observed for the first time with its new height already applied, so there's nothing to compensate against. When I triggered ordinary renders first (expanding and collapsing another row), the shift was ≤ 1 px in 6/6 runs in every engine. Right after scrolling, Chrome and Firefox usually shifted by one row line (41–42 px; 16 of 24 runs), and Chrome occasionally by about 220 px (2 of 12 runs). WebKit shifted 42 px in 1 of 12 runs and ≤ 1 px otherwise.
• Programmatic jumps are harder than wheel scrolling. I also set scrollTop directly, let the list settle, and then expanded an item above the viewport. In Chrome and WebKit, the div feed didn't move in any run. Firefox moved it 168 px in 1 of 7 runs, and 132–186 px in 3 of 7 runs in an earlier session. The grid moved 41–132 px in Chrome, 0–42 px in Firefox, and 0 px in WebKit. If your app scrolls programmatically and then changes content above the viewport, test that combination.

Data grids: tables, jumping to rows, and QuickGrid

The sample's grid virtualizes <tr> elements inside <tbody>. The visible column header lives in a separate table outside the scroll container:

@* The visible header sits outside the scroll container. A sticky <thead> inside it would cover the
   row that InitialItemIndex / ScrollToItemAsync align to the container's top edge. *@
<div class="grid-frame">
    <div class="grid-header" aria-hidden="true">
        <table class="event-grid"><colgroup>…</colgroup><thead>…</thead></table>
    </div>

    <div class="stream-viewport grid-viewport" tabindex="0" aria-label="Event log">
        <table class="event-grid">
            <colgroup>…</colgroup>
            <thead class="visually-hidden">…</thead> @* column headers for assistive technology *@
            <tbody>
                <Virtualize @ref="virtualize" TItem="StreamItem" ItemsProvider="provider" ItemComparer="StreamItem.ById"
                            Context="row" SpacerElement="tr" ItemSize="62" AnchorMode="VirtualizeAnchorMode.None"
                            InitialItemIndex="@(StartRow is int start ? start - 1 : 0)">
                    <ItemContent>
                        <tr @key="row.Id" data-id="@row.Id" @onclick="() => Toggle(row.Id)">…</tr>
                    </ItemContent>
                </Virtualize>
            </tbody>
        </table>
    </div>
</div>

/* Same <colgroup> and table-layout: fixed in both tables; scrollbar-gutter keeps the columns aligned. */
.grid-header { flex: none; overflow-y: hidden; scrollbar-gutter: stable; }
.grid-frame .grid-viewport { flex: 1 1 0; scrollbar-gutter: stable; }
.event-grid { width: 100%; table-layout: fixed; }

private async Task JumpAsync()
{
    if (virtualize is not null && jumpTo is int row)
    {
        await virtualize.ScrollToItemAsync(row - 1);
    }
}

• SpacerElement="tr" keeps the markup valid. Virtualize gives the spacer rows display: table-row itself.
• AnchorMode.None is set explicitly, because a grid that users sort and filter shouldn't pin to an edge.
• ScrollToItemAsync ("Go to row") and InitialItemIndex (/grid?row=500) put the requested row at the top of the viewport in every engine. Keep in mind:
  • ScrollToItemAsync scrolls instantly (no smooth scrolling). It aligns the item with the top edge of the scroll container and cancels any earlier call that's still running (the last call wins).
  • A sticky <thead> inside the scroll container would cover exactly that row. That's why the sample keeps the header outside the container, as shown above.
  • It throws InvalidOperationException if called before the first interactive render. Use InitialItemIndex for the starting position.
  • The index is a position in the list, not a database identity. If your provider's ordering isn't stable, the jump can land on a different record.
• An RC1 issue with InitialItemIndex: When the grid opened with ?row=75000, the next ordinary render (expanding a visible row) moved the rows by 82 px in Chrome, −53 px in Firefox, and 63 px in WebKit, in 3/3 runs each, while scrollTop stayed the same. The top spacer is recomputed once positioning ends. After ScrollToItemAsync the same action moved them 0 px. RC2 freezes the spacer item size during initial positioning (dotnet/aspnetcore#69170).
• Size ItemSize for the real rows. The grid's rows average about 62 px (38.6–122 px), because messages wrap. The sample keeps the short columns on one line (white-space: nowrap) so that only the message column wraps.
• <table> layouts use the manual compensation path. See the measurements in section 10.

QuickGrid forwards InitialItemIndex and ScrollToItemAsync in .NET 11. Its AnchorMode and ItemComparer parameters are marked [Experimental("ASP0030")] in RC1, and that attribute has already been removed for RC2. It keeps OverscanCount = 3. Two QuickGrid issues filed against RC1 are still open: Start anchoring drifts after prepends in Server render modes, and the grid sends duplicate provider requests (#69380, #69381). If you rely on QuickGrid anchoring, test it specifically.

Performance: what I measured

I didn't want illustrative numbers here, so the sample's Perf lab (/lab/perf) renders the same row markup in three ways: a plain foreach, Virtualize with Items, and Virtualize with an ItemsProvider. A Playwright script measured each variant three times in fresh Chrome contexts and took the median.

| Variant (100,000 items unless noted) | HTML | First row painted | Interactive | DOM elements | Rows rendered | JS heap | WebSocket until interactive | |---|---|---|---|---|---|---|---| | foreach, 10,000 items | 2.9 MB | 77 ms | 2.8 s | 40,078 | 10,000 | 21.2 MB | 5.6 MB | | foreach | 28.6 MB | 248 ms | 112.4 s | 400,078 | 100,000 | 189.5 MB | 111.9 MB | | Virtualize Items, fixed heights, overscan 15 | 11.7 KB | 106 ms | 125 ms | 288 | 52 | 2.7 MB | 39 KB | | Virtualize Items, variable heights, overscan 15 | 11.7 KB | 109 ms | 128 ms | 256 | 44 | 2.7 MB | 34 KB | | Virtualize ItemsProvider, variable heights, overscan 15 | 11.7 KB | 108 ms | 125 ms | 256 | 44 | 2.7 MB | 34 KB |

Published Release build, Production environment, Blazor Server on localhost. Chrome 153 on an AMD Ryzen 9 5900HX. Median of 3 fresh browser contexts per variant. "Interactive" is the time from navigation until the first interactive render batch was applied. JS heap is in MiB; HTML and WebSocket sizes use decimal units (1 MB = 1,000,000 bytes).

What the numbers say:

• Prerendering hides the problem for a moment. The foreach page painted its first row after 248 ms, because the rows are in the HTML. It then took 112 seconds to become interactive. The circuit had to send 112 MB of render batches for 100,000 rows, and the browser recorded 92 seconds of long tasks on the main thread. Even at 10,000 items it took 2.8 s.
• With Virtualize, the rendered window sets the cost, not the list length. For 100,000 items it took about 125 ms to become interactive, with 256–288 DOM elements, 2.7 MB of JS heap, and 34–39 KB over the WebSocket.
• Items and ItemsProvider cost the same on the UI side. The difference is on the server: Items needs the collection in memory, while a provider fetches only the window.

The overscan trade-off

To stress each configuration, the harness "flings" the list: 60 mouse-wheel events of 600 px each in about 2.4 seconds (≈ 15,000 px/s). After each event it checks whether the center of the viewport shows a row or an empty spacer.

• Fixed heights: Moving from overscan 3 to 15 cut blank samples from 55 to 3 out of 60, at the cost of 52 instead of 28 rendered rows.
• Variable heights: Overscan helps less here: 52, 39, and 32 blank samples for overscan 3, 15, and 30. Every window change must be measured and rendered, and the running average is still converging while you fling through unmeasured regions.
• Server traffic while scrolling was 0.6–1.2 MB per fling on Blazor Server. That's the render batches for each new window, and it grows with overscan and row complexity.

Treat these numbers as a relative comparison, taken on one machine with the server on localhost. Over a real network, Blazor Server adds a round trip to every window change, which makes overscan more valuable. On WebAssembly there's no round trip, but rendering competes with everything else on the main thread.

The main message: Virtualize limits how much UI you render. It doesn't make your data access faster. If your provider runs an expensive COUNT(*) on every request, slows down at deep offsets, returns far more columns than the row needs, or ignores the cancellation token, virtualization won't hide that.

Choosing ItemSize and OverscanCount

ItemSize

• It's the starting estimate. Virtualize uses it before any measurements exist and for the first scroll range.
• Set it close to your real average item height. Measure it in the browser, as the sample did for its grid (about 62 px). A value that's far off makes the first layout and scrollbar noticeably wrong until measurements arrive.
• Variable-height support doesn't make it irrelevant. Changing ItemSize at runtime resets the measured average.

OverscanCount

| Lower (e.g. 3) | Higher (e.g. 15–30) | |---|---| | Fewer DOM nodes and components | Fewer blank moments during fast scrolling | | Smaller render batches and provider requests | More items to average variable heights over | | More risk of placeholders or empty space when scrolling fast | More DOM, more component instances, bigger batches |

Start with the .NET 11 default of 15, then profile with your real row template on the slowest devices you support. Heavy rows, such as grids with many cells or rich cards, may justify going back down. QuickGrid stays at 3 for exactly that reason. MaxItemCount (default 100) still caps how many items are rendered, plus 2 × OverscanCount. Don't set it lower than what a tall window can show.

Content Security Policy: why virtualization used to break

A strict policy like the following blocks inline style attributes:

Content-Security-Policy: default-src 'self'; style-src 'self'

That applies both to attributes in the server-rendered markup and to attributes set with element.setAttribute('style', …). Browsers report them as style-src-attr violations. Nonces don't help, because they never apply to attributes, and 'unsafe-hashes' doesn't scale to values that change on every scroll.

Up to .NET 10, Virtualize rendered its spacers like this (captured from the sample's .NET 10.0.10 baseline):

<div style="height: 0px; flex-shrink: 0;" aria-hidden="true"></div>
<div aria-hidden="true" style="height: 9598560px; flex-shrink: 0;"></div>

With the same strict policy as the .NET 11 app, the baseline logged 5 style-src-attr violations, with samples such as height: 9600000px; flex-shrink: 0;. They came from both the prerendered HTML and blazor.web.js. Worse, the list collapsed. The spacers had no height, so a 100,000-item list had a scroll range of 1,227 px, and about 15 rows were all anyone could reach. Chrome, Firefox, and WebKit gave identical results.

What .NET 11 does instead

In .NET 11, the C# side renders numbers, not styles:

<!-- prerendered by .NET 11 RC1 (/lab/perf?mode=items: 100,000 items × ItemSize 64) -->
<div data-blazor-virtualize-reserved-height="0" aria-hidden="true"></div>
<div aria-hidden="true" data-blazor-virtualize-reserved-height="6400000"></div>

• data-blazor-virtualize-reserved-height holds the height as a unitless number, for both spacers and default placeholders.
• data-blazor-virtualize-loop-breaker-transform holds a vertical offset for the trailing spacer, when one is needed.
• A MutationObserver in blazor.web.js watches those two attributes on the spacers. It parses each value, accepts only finite numbers, and applies it through the CSS Object Model, with element.style.setProperty('height', …) or translateY(…).

Browsers don't apply style-src to properties set through an element's style object. MDN documents this, and the web-platform-tests confirm it for current Chrome, Firefox, and Safari. If you explain this to your security team, be precise: the CSP specification doesn't formally exempt CSSOM. It even describes gating some CSSOM setters on 'unsafe-eval'. The guarantee is how browsers actually behave, and that's what the framework relies on.

Don't test for "no style attribute in the DOM". After hydration, the .NET 11 spacers do show a style attribute in DevTools:

<div aria-hidden="true" data-blazor-virtualize-reserved-height="9596352"
     style="flex-shrink: 0; height: 9.59635e+06px; overflow-anchor: none;"></div>

That's the serialization of the properties set through CSSOM, and it's allowed. The .NET 10 spacers show a style attribute too, but there it's inert, because the browser refused it. Instead, check for violations, and check that the computed height equals the reserved height.

Sending a strict CSP from a Blazor Web App

Send the policy as an HTTP response header, not a <meta> tag. Only a header supports frame-ancestors, report-to, and Content-Security-Policy-Report-Only. The sample generates a nonce per request, because the Blazor Web App's <ImportMap /> is an inline <script>:

public static string Build(string nonce) => string.Join("; ",
    "default-src 'self'",
    "base-uri 'self'",
    "object-src 'none'",
    "frame-ancestors 'none'",
    "form-action 'self'",
    "img-src 'self' data:",
    "font-src 'self'",
    "style-src 'self' 'report-sample'",
    $"script-src 'self' 'nonce-{nonce}' 'report-sample'",
    "connect-src 'self'");

public static IApplicationBuilder UseStrictContentSecurityPolicy(this IApplicationBuilder app, CspMode mode)
{
    // …
    return app.Use(async (context, next) =>
    {
        // UseStatusCodePagesWithReExecute and UseExceptionHandler run the rest of the pipeline
        // again for the same HttpContext. Create the nonce and register the header callback once,
        // or the header and the re-rendered <ImportMap /> end up with different nonces.
        if (!context.Items.ContainsKey(NonceKey))
        {
            var nonce = Convert.ToBase64String(RandomNumberGenerator.GetBytes(16));
            context.Items[NonceKey] = nonce;

            context.Response.OnStarting(() =>
            {
                if (context.Response.ContentType?.StartsWith("text/html", StringComparison.OrdinalIgnoreCase) == true)
                {
                    context.Response.Headers[headerName] = Build(nonce);
                }

                return Task.CompletedTask;
            });
        }

        await next();
    });
}

@* App.razor (abridged) *@
<ImportMap nonce="@nonce" />

@code {
    private string? nonce;

    [CascadingParameter]
    private HttpContext? HttpContext { get; set; }

    protected override void OnInitialized() => nonce = HttpContext.GetCspNonce();
}

The ContainsKey guard fixes a real bug that the article review caught in the first version of this middleware. Without it, a 404 page re-executed by UseStatusCodePagesWithReExecute got one nonce in the header and a different one in the import map, so the import map was blocked on error pages. The sample now has an integration test for exactly that case.

Notes on the directives:

• 'report-sample' doesn't relax anything. It only adds the first 40 characters of a blocked inline style or script to violation reports. That's how the .NET 10 samples above were captured.
• img-src 'self' data: is needed because the template's Bootstrap and navigation icons use data: SVGs in CSS.
• connect-src 'self' covers the Blazor Server WebSocket. Under CSP Level 3, 'self' matches same-host ws:/wss:, and current browsers implement that. Very old browsers needed explicit ws:/wss: sources.
• The template's <ReconnectModal /> is CSP-friendly. Apps created before .NET 10 that still use the built-in JS reconnect UI get an injected <style> element, which violates style-src 'self'.
• The .NET 11 template no longer puts an inline onclick on NavMenu. It uses a collocated NavMenu.razor.js module instead. (The .NET 10 template still has the inline handler; the sample's baseline removes it so that only Virtualize is compared.) In RC1, that module binds to the prerendered menu element, which interactive render modes replace, so the mobile menu stays open after navigation. RC2 fixes this (dotnet/aspnetcore#68951, a backport of #68768). Because the sample is fully interactive, it keeps the menu's open/closed state in the component instead.
• Blazor WebAssembly also needs 'wasm-unsafe-eval' in script-src. Microsoft's Blazor CSP docs give a starting policy for each render mode.
• Nonces must be unique per response. Don't let a CDN or output cache serve one nonce to many users.
• Roll out with Content-Security-Policy-Report-Only first. Add report-to csp-endpoint to the policy and declare the endpoint in a Reporting-Endpoints: csp-endpoint="https://…/csp-reports" response header. Also add report-uri https://…/csp-reports for browsers that don't support report-to yet. Switch to enforcing once the reports are clean.

Security framing

.NET 11 removes an important source of CSP incompatibility from Virtualize, but it doesn't make an application "CSP-secure". Your complete policy still depends on your render mode, scripts, styles, third-party components, and hosting. CSP reduces the impact of XSS and clickjacking. It doesn't replace output encoding, CSRF protection, or authorization. Virtualize decides which records are rendered; your backend still has to decide which records a user may see.

Testing strict CSP compatibility

A test plan that catches real problems:

1. Enable style-src 'self' (and a nonce-based script-src) as an HTTP header, in every environment you test in.
2. Don't add 'unsafe-inline'.
3. Listen for securitypolicyviolation events from the very start of the page. The sample loads a tiny csp-monitor.js from 'self' as the first script in <head>, so it also sees violations raised while the prerendered HTML is parsed.
4. Load every virtualized page, then scroll to the start, middle, and end.
5. Prepend and append items, and expand variable-height items.
6. Assert zero violations, and assert that each spacer's computed height matches its data-blazor-virtualize-reserved-height.
7. Include error pages (404, 500), which render through a re-executed pipeline.
8. Run the tests in Chromium, Firefox, and WebKit, and check real Safari/iOS manually.

The sample's Playwright test is short:

test(`${path}: no CSP violations while loading and scrolling`, async ({ page }) => {
    await page.goto(APP + path);
    await waitForList(page, row);
    for (const f of [0.25, 0.75, 1, 0]) {
        await scrollViewportTo(page, f);
        await settle(page, 300);
    }

    expect(await cspViolations(page)).toEqual([]);
});

The integration tests also check the prerendered HTML without a browser, using WebApplicationFactory. They verify that the HTML of every page contains no style=", that the import map carries the response's nonce, and that a re-executed 404 page uses the same nonce in its header and its markup.

Accessibility and UX

• Make the scroll container focusable. Since Chrome 132, Chromium makes a scroll container keyboard-focusable automatically only when it has no focusable children. Lists whose items contain buttons or links, like the feed's "Show details", don't qualify. Give the container tabindex="0" and an aria-label, as the sample does. If there's no tabindex, RC1 adds tabindex="-1" so the container can receive Home/End, but that doesn't make it reachable with Tab.
• Don't force-scroll readers. AnchorMode.End already follows new items only at the live edge. Pair it with a visible "N new messages" control.
• Announce summaries, not every item. Use a single polite live region with an updating count ("12 new messages below.") rather than announcing each message. A busy log would flood a screen reader.
• Keep placeholders close to real item heights, so loading states don't shift the layout.
• Use stable @keys (the item ID, never the loop index).
• Watch focus. If a focused row scrolls out of the window, it's removed from the DOM and focus is lost. Keep focus on the container, or scroll the focused item into view before changing data.
• Keep table semantics when you split the header. The sample's visible grid header is aria-hidden, and the body table keeps a visually hidden <thead>, so screen readers still announce the column names.
• Respect prefers-reduced-motion in skeleton animations. The sample turns its shimmer off.

Browser and layout caveats

• The scroll container needs a real height and overflow-y: auto or scroll. In a flex layout, give the list flex: 1; min-height: 0. If a sibling (like a header) sits in the same flex column, give that sibling flex: none. The list's flex basis is its virtual height, which can be millions of pixels, so flexbox would otherwise shrink the sibling to nothing. That happened to the sample's grid header during development.
• Single column only. Variable-height support assumes a vertical stack. Items that share a row (flex-wrap, CSS grid with several columns, horizontal lists) aren't supported.
• Don't style the spacers. No borders, margins, or ::before/::after content on them.
• Tables and divs behave differently. They use different anchoring paths (section 3.2), so test the layout you actually ship.
• Safari and iOS: Safari 26 and earlier don't support overflow-anchor, so they take the manual path even for div lists. Playwright's WebKit build doesn't exercise that path. Test on devices.
• Lazy-loaded media changes row heights after render. Reserve its space.
• Very uneven height distributions (a few rows 100× taller than the rest) make the running average less representative, so expect the scrollbar to be approximate.
• Nested scroll containers and document-level scrolling both work, but the scroll container is detected as the first scrollable ancestor. Check that it's the one you expect.
• WebAssembly. The same component and markup apply. Spacer styles are applied by a MutationObserver callback, which runs asynchronously in every render mode. On WebAssembly, though, the .NET side can refresh synchronously before that callback has run. That's why the RC2 End-anchoring fix (#69388, a backport of #69310) also flushes pending spacer styles before reading scrollHeight. Your CSP also needs 'wasm-unsafe-eval'.

Preview/RC status and production readiness

Tested against: .NET SDK 11.0.100-rc.1.26425.128 · ASP.NET Core 11.0.0-rc.1.26425.128 · Microsoft.AspNetCore.Components.Web 11.0.0-rc.1.26425.128

Support facts

• RC1 ships with a go-live license, which means Microsoft supports it in production. The go-live support window for RC1 ends October 13, 2026, and you're expected to move to RC2 and then GA.
• .NET 11 is an STS release with two years of support. The dotnet/core release notes currently give November 10, 2026 – November 9, 2028. So far, the support-policy page lists only the RC1 go-live release, not .NET 11's GA support dates.
• .NET 10 is LTS and is supported until November 14, 2028. That's the same month .NET 11 support ends, because STS releases are now supported for 24 months. Upgrading doesn't meaningfully change your support window (the published end dates are five days apart), so decide based on features and risk.

Known RC1 issues relevant to this article (as of September 21, 2026)

| Issue | Status | |---|---| | AnchorMode.End stays at the top after the initial ItemsProvider load (#69302) | Fixed for RC2 (#69388). The RC1 workaround is a small initial fetch followed by the regular one | | InitialItemIndex positioning can oscillate or finish at the wrong item; in the sample, the next render moved rows by 53–82 px | Fixed for RC2 (#69170). Observed in section 11 | | False-positive prepend detection causes backward scroll jumps with ItemsProvider and ongoing updates (#69362) | Open PR, RC2 milestone | | User scrolling doesn't reliably cancel an in-flight ScrollToItemAsync (#69288) | Open PR | | QuickGrid: Start anchoring in Server modes, and duplicate provider requests (#69380, #69381) | Open | | Deleting items above the viewport isn't anchored (#66509) | Backlog | | The template's mobile NavMenu stays open after navigation in interactive render modes (#68951, a backport of #68768) | Fixed for RC2 | | <table> rows that grow right after scrolling are only partly compensated: usually 41–42 px in Chrome and Firefox, sometimes ~220 px in Chrome | Observed in this sample (section 10) | | AnchorMode.End sometimes stops 29–77 px short of the bottom after an append. WebKit: 20/30 checks passed; Chrome and Firefox: 1–2 misses in 30 | Observed in this sample (section 7). Playwright WebKit 26.6 on Windows, not verified in Safari | | A Start list moves 214–486 px when items are appended at the very end; None doesn't | Observed in this sample (section 8). Playwright WebKit 26.6 on Windows only, not verified in Safari |

Docs inconsistencies to be aware of in RC1

• The docs and release notes use AnchorMode="Start", which doesn't compile in Razor. Use VirtualizeAnchorMode.Start.
• The "Advanced styles" section of the virtualization docs still says all items must have identical height. That text predates variable-height support.
• The .NET 10 version of the virtualization docs suggests using data-blazor-virtualize-reserved-height for CSP compliance. .NET 10 doesn't read that attribute: the sample's .NET 10.0.10 baseline renders and needs inline styles.

Build and verification results

Test environment

| | | |---|---| | .NET SDK | 11.0.100-rc.1.26425.128 (installed side by side with dotnet-install.ps1 in ~/.dotnet11) | | Runtime | .NET 11.0.0-rc.1.26425.128; baseline: .NET 10.0.10 (SDK 10.0.301) | | App model | Blazor Web App, Interactive Server, prerendering on | | Builds | Debug (dotnet run) for tests and probes; published Release build in the Production environment for the perf numbers | | OS / hardware | Windows 11 Pro (build 26200), AMD Ryzen 9 5900HX (8 cores / 16 threads), 32 GB RAM | | Browsers | Google Chrome 153.0.8010.50, Playwright Firefox, Playwright WebKit 26.6 (Playwright 1.63.0) | | Dataset | 100,000 generated records (deterministic seed) |

How it was verified

The sample was checked at three levels:

• dotnet build for the app and the test project.
• xUnit tests (dotnet test), including WebApplicationFactory integration tests that inspect the prerendered HTML and the CSP headers.
• Playwright browser tests in Chrome, Firefox, and WebKit against the running .NET 11 app and the .NET 10 baseline. The baseline ran on the .NET 10 SDK.

Results

| Check | Result | |---|---| | dotnet build (Debug and Release) | 0 warnings, 0 errors | | dotnet test | 17/17 passed, 3 consecutive runs | | npx playwright test (Chrome, Firefox, WebKit) | 72 tests: 65 passed, 0 failed, 0 flaky, 7 skipped. The skipped tests are fixme markers for the RC1 issues below: the table gap and the InitialItemIndex shift in each engine, plus AnchorMode.End without the guard in WebKit |

| Test | Expected result | Actual result | |---|---|---| | Initial activity feed render | Only viewport items are rendered | Pass: 37–38 of 100,000 cards in the DOM (all engines) | | Prepend at the top | The viewport stays pinned to the start and shows the new items | Pass (all engines) | | Prepend while reading older items | Visible content doesn't move; a pill appears | Pass: ≤ 1 px (all engines) | | Append at the chat bottom | The new message is followed | Pass with the sample's guard (30/30 follow checks per engine). AnchorMode.End alone: Chrome 29/30, Firefox 28/30, WebKit 20/30 | | Append while reading history | The user isn't pulled to the bottom | Pass (all engines) | | Expand a variable-height item above the viewport (div list) | No disruptive jump | Pass: 0 px (18/18 wheel runs) | | Expand a row above the viewport (<table>) | No disruptive jump | Partial: ≤ 1 px after an ordinary render. Right after scrolling: usually 41–42 px in Chrome and Firefox (occasionally ~220 px in Chrome), and ≤ 1 px in 11 of 12 WebKit runs | | Open at a row / jump to a row | The target row is at the top | Pass for both. RC1: after InitialItemIndex, the next render moves the rows by 53–82 px | | Append at the end of a Start list (infinite scroll) | No movement | Pass in Chrome and Firefox; fail in Playwright WebKit (214–486 px). With None: pass everywhere | | Strict CSP (style-src 'self') | No virtualization style violations | Pass: 0 violations, 5 pages × 3 engines; error pages keep the header and markup nonces in sync | | Same CSP on .NET 10.0.10 | (baseline for comparison) | 5 style-src-attr violations; the list collapsed to 1,227 px (all engines) | | Fast scrolling with latency | Stale provider calls are canceled | Pass: canceled calls > 0 (all engines) | | Performance, 100,000 items | Virtualize ≪ foreach | 125 ms vs 112.4 s to interactive; 256 vs 400,078 DOM elements (section 12) |

When not to use Virtualize

Virtualization is a trade-off. It's not the right choice when:

• The list has only 20–50 simple rows. The overhead isn't worth it.
• The full content must be in the initial HTML for SEO or no-JS clients. Virtualize prerenders at most a small window of items, and usually none.
• Users need the browser's find-in-page (Ctrl+F) across all rows. Unrendered rows can't be found.
• All rows must print or export from the page. Do that on the server instead.
• The layout isn't a single vertical stack (masonry, multi-column wraps, horizontal carousels).
• Classic pagination gives users a clearer mental model, as with "page 3 of the invoices".

Virtualization and pagination can also work together. Large data grids often combine server-side paging, filtering, and sorting with viewport virtualization inside the current result set.

References

• What's new in ASP.NET Core in .NET 11
• ASP.NET Core Razor component virtualization
• Enforce a Content Security Policy for ASP.NET Core Blazor
• ASP.NET Core Blazor security overview
• .NET 11 downloads and the .NET support policy
• dotnet/aspnetcore pull requests: #64964 (variable heights), #65951 (hybrid anchoring), #66262 (AnchorMode), #66680 (CSP), #66753 (scroll to item), #67934 (anchoring regression fix)
• MDN: CSP style-src, style-src-attr, and overflow-anchor
• W3C Content Security Policy Level 3
• Chrome for Developers: Keyboard-focusable scrollers

Article Overview

This article provides a guide to ASP.NET Core Dependency Injection, a fundamental element of .NET development. We'll examine the built in Inversion of Control (IoC) container, examining the critical differences between service lifecycles (scoped, singleton, or transient), and comparing constructor injection to property injection.

You'll learn how to effectively register your services with patterns like TryAdd methods and the Options Pattern, how to adhere to established best practices like avoiding captive dependencies and asynchronous constructor logic, how to understand patterns like decorators and explicit generics, how to leverage manual scope management with IServiceScopeFactory, how to implement proper asynchronous disposal with IAsyncDisposable, and how to analyze the performance impact of your DI strategy, including the new compile time source generation features that enable native AOT support in .NET 9. Ultimately, you'll have the knowledge to create loosely coupled, maintainable, and testable applications using the advanced dependency injection patterns in .NET 9. Of course, the explanations here are general, if you'd like to delve deeper, you can check out the references section.

Introduction to Dependency Injection

Dependency Injection (DI) is a design pattern used to implement Inversion of Control (IoC), in which control of object creation and binding is transferred from the object itself to another container or framework. In the context of ASP.NET Core, DI is a tool integrated into the framework for managing the lifecycle and creation of application components.

The Evolution from .NET Framework to .NET Core and .NET 9

The journey of dependency injection in the .NET ecosystem represents a sweeping architectural shift. .NET Framework applications (prior to 2016) typically relied on third party IoC containers such as

• Unity (Microsoft's own container, often used in enterprise applications)
• Autofac (popular for its advanced features and fluent API)
• Ninject (known for its simplicity)
• StructureMap (one of the earliest .NET IoC containers)
• Castle Windsor (powerful but complex)

Many legacy applications have fallen back to anti patterns like the Service Locator pattern, which hides dependencies and makes testing difficult.

When ASP.NET Core was released in 2016, Microsoft made a decision to integrate dependency injection directly into the runtime. This meant:

• Standardization: Creating a consistent DI approach across all .NET Core applications.
• Performance: Creating a lightweight, optimized container designed for workloads.
• Simplicity: No need to choose third party containers for basic scenarios.
• Cloud Native Ready: Designed for microservices, containers, and serverless architectures.

Now, with .NET 9, the DI container has become even more advanced as follows:

• Source generated DI for faster startup and AOT compatibility.
• Keyed services for advanced solution scenarios.
• Lifetime validation to catch common errors during development.

Unlike .NET Framework applications, which required installing these containers as third-party packages and often present issues with consistency, in ASP.NET Core, and now in .NET 9, dependency injection is a fundamental part of the architecture.

Why is Dependency Injection important?

The key benefits of adopting a DI strategy would be.

• Loose Coupling: Components don't create their dependencies directly. Instead, they get them from the DI container. This means you can change the implementation of a dependency without changing the component that uses it.
• Testability: Once dependencies are added, you can easily replace them with mocks or mock implementations in your unit tests. This will allow you to test components in isolation.
• Maintenance and Scalability: A loosely coupled architecture is easier to manage, refactor, and extend. New features can be added with minimal changes to existing code.

This article provides a guide for developers covering the basic mechanisms of Dependency Injection in .NET and the performance models available in .NET 9.

The Built in IoC Container in ASP.NET Core

ASP.NET Core ships with the lightweight yet comprehensive ASP.NET Core IoC container. It's not designed to have all the features of third party tools, but it provides the basic functionality needed for most applications.

The two basic interfaces representing the structure are as follows:

• IServiceCollection: This is the "registration" side of the structure. When the application starts up, you add your services or dependencies to this collection.
• IServiceProvider: This is the "resolving" side of the structure. After the application is created, IServiceProvider is used to retrieve instances of registered services.

Comparison with Third Party Tools

While the internal structure is sufficient for many scenarios, you can easily modify it if you need more features, such as:

• Automatic registration / Assembly Scan: Automatically register types based on contracts.
• Interception / Decorators: Providing more support for packaging services with cross cutting concerns.
• Child Containers: Some tools, such as Autofac, allow you to create nested sub containers with their own lifetimes, which can be useful for isolating components in complex applications. The built in framework uses a simpler scoping mechanism.

Service Lifetimes in ASP.NET Core

When registering a service, you must specify its lifetime. The lifetime determines how long a service instance will be valid. Understanding the difference between scoped, singleton, and transient is important for building stable and optimized applications.

Transient

A new instance of a transient service is created each time it is requested from the container.

• When to use: For lightweight, stateless services.
• builder.Services.AddTransient<IMessageSender, EmailSender>();

Scoped

A single instance of a scoped service is created once per client request (or per scope). The same instance is shared within that single request.

• When to use: It is more appropriate to use it for services that need to maintain state within a single request, such as DbContext or Unit of Work.
• builder.Services.AddScoped<IUserRepository, UserRepository>();

Singleton

A single instance of the service is created once during the entire application lifetime.

• When to use: Commonly used for stateless services that are source intensive to create or need to share their state extensively, such as application configuration or caching services.
• builder.Services.AddSingleton<IAppCache, MemoryCacheService>();

Considered Best Practice: Avoid Captive Dependencies A common mistake is injecting a deep, scoped service (for example, MyDbContext) into a singleton service. Because the singleton service lives forever, it will keep the scoped service in the container structure for the lifetime of the application, converting it to a singleton service. This can lead to memory leaks and erratic behavior across requests. ASP.NET Core throws an exception at runtime to help you detect this during development.

Manual Scope Management with IServiceScopeFactory

In scenarios where you need to manually create and manage scopes (background workers, singleton services, or long running tasks), you can use IServiceScopeFactory to create scopes.

This would be particularly useful when properly controlling when a singleton service needs to use scoped dependencies without causing captive dependency problems.

Within continuously running services, you must not directly inject objects that require short lifespans, such as database connections. This code example solves this problem by creating a temporary workspace for each task using a "throw away" approach. The environment and necessary services are created when the process starts, and all are automatically cleaned up when the task ends. This method utilizes sources efficiently and prevents memory leaks.

public class DataProcessingService
{
    private readonly IServiceScopeFactory _scopeFactory;

    public DataProcessingService(IServiceScopeFactory scopeFactory)
    {
        _scopeFactory = scopeFactory;
    }

    public async Task ProcessDataAsync()
    {
        // Create a new scope for this unit of work
        await using (var scope = _scopeFactory.CreateAsyncScope())
        {
            var dbContext = scope.ServiceProvider.GetRequiredService<AppDbContext>();
            var repository = scope.ServiceProvider.GetRequiredService<IDataRepository>();
            
            // Perform scoped work
            var data = await repository.GetPendingDataAsync();
            await dbContext.SaveChangesAsync();
        }
        // Scope is disposed here, releasing all scoped services
    }
}

Key Points:

• We should use CreateAsyncScope() when working with asynchronous disposal.
• It would be logical to use CreateScope() for synchronous scenarios.
• Always destroying scopes appropriately using using or await using statements is important for scope management and optimization.

Here is the detailed explanation, incorporating your text and adding the requested details for property injection.

Constructor Injection vs. Property Injection

There are several ways a class can receive its dependencies. The two most common patterns are constructor and property injection.

Constructor Injection

With constructor injection, a class retrieves its dependencies from the container via constructor parameters. With dependency injection (DI), the container will be responsible for creating instances of these dependencies and fetching them when the class is generated. This is one of the most common and recommended approaches to ASP.NET Core Dependency Injection.

// Primary Constructors
public class OrderService(IOrderRepository orderRepository, ILogger<OrderService> logger)
{
    private readonly IOrderRepository _orderRepository = orderRepository;

    private readonly ILogger<OrderService> _logger = logger;
    public async Task<Order> GetOrderAsync(int orderId)
    {
        _logger.LogInformation("Fetching order {OrderId}", orderId);
        return await _orderRepository.GetByIdAsync(orderId);
    }
}

// Traditional Class Constructor
public class OrderService
{
    private readonly IOrderRepository _orderRepository;
    private readonly ILogger<OrderService> _logger;

    public OrderService(IOrderRepository orderRepository, ILogger<OrderService> logger)
    {
        _orderRepository = orderRepository;
        _logger = logger;
    }

    public async Task<Order> GetOrderAsync(int orderId)
    {
        _logger.LogInformation("Fetching order {OrderId}", orderId);
        return await _orderRepository.GetByIdAsync(orderId);
    }
}

Pros:

• Explicit Dependencies: The constructor's signature explicitly states all required dependencies. A developer will immediately see what the class needs to function when calling it.
• Immutability: Dependencies can be assigned to readonly fields so that they cannot be changed after the object is created. This will lead to more stable and predictable class behavior.
• Availability: The class is guaranteed to have the required dependencies when created. It will not need to perform null checks on required services.
• Startup Validation: If a required dependency is not registered in the DI container, the application will fail on startup (at runtime), making errors easy to detect early.

Best Practice: Avoid Asynchronous Operations in Constructors A constructor is expected to be simple and fast. We should not perform asynchronous operations (await) or long running tasks within a constructor. This can lead to deadlocks and unpredictable application startup behavior. Using asynchronous factory patterns or IHostedService for asynchronous startup logic will fix this issue in most scenarios.

Property Injection

With property injection (also known as "setter injection"), dependencies are provided through publicly settable properties on the class. The dependency is injected after the class is created.

This pattern is less common in ASP.NET Core because the built in DI container will not support it out of the box (other third party containers like Autofac or Ninject do support it).

Property injection is almost exclusively used for optional dependencies, which would be services that the class could use but doesn't need to perform its core functionality.

public class ProductService
{
    private readonly IProductRepository _productRepository;

    // Injected via a public property
    public ILogger<ProductService>? Logger { get; set; }

    // Still injected via the constructor
    public ProductService(IProductRepository productRepository)
    {
        _productRepository = productRepository ?? throw new ArgumentNullException(nameof(productRepository));
    }

    public async Task<Product> GetProductAsync(int productId)
    {
        // Must check if the optional dependency was injected before using it
        Logger?.LogInformation("Fetching product {ProductId}", productId);
        
        return await _productRepository.GetByIdAsync(productId);
    }
}

Since the built in container doesn't automatically set the Logger property, you would either have to use a different container or set it manually (which partially defeats the purpose of DI). This is why it's strongly discouraged for required dependencies.

Pros:

• Optional Dependencies: Can be used to provide optional services. The class can function without the dependency, but if a dependency is provided, its behavior needs to be improved.
• Decoupling: It can help to break up large classes or prevent over injection in the constructor (constructors with too many parameters), but this usually indicates that the class is doing too much (Single Responsibility Principle).

Cons:

• Hidden Dependencies: It won't be immediately obvious from the constructor what the class might depend on. Because of the way it's implemented, this means a developer will need to examine the class's properties.
• Mutability: This means that the dependency will not be readonly and can be changed at any time, which may lead to unforeseen situations and changes.
• Null Check: The class should always check if the optional dependency is null before using it.
• No Container Support: The default ASP.NET Core container will not inject properties. This makes this pattern unusable unless you use a different container or manually add dependencies.

Registering Services in ASP.NET Core

Services are registered in the DI container in Program.cs. This means adding the services to the IServiceCollection.

Basic and Factory based Registrations

You can add an interface to a concrete class or use a factory based registration style for complex initialization.

In Program.cs

var builder = WebApplication.CreateBuilder(args);

// Simple registration
builder.Services.AddScoped<ISimpleService, SimpleService>();

// Factory based registration
builder.Services.AddScoped<ISomeComplexService>(provider =>
{
    // Resolve other service
    var logger = provider.GetRequiredService<ILogger<SomeComplexService>>();
    var someValue = "CalculatedOrRetrievedValue";
    
    // Manually build with dependencies
    return new SomeComplexService(logger, someValue);
});

Conditional TryAdd Registrations

When developing reusable libraries or building dependent applications, you may want to register a service only if another application has not already registered it, and you may want to check for it. The TryAdd method is used for this scenario.

Available Methods:

• TryAddSingleton<TService, TImplementation>() Adds the singleton if it is not already registered
• TryAddScoped<TService, TImplementation>() Adds scoped if not already registered.
• TryAddTransient<TService, TImplementation>() Adds a transient if not already registered.
• TryAddEnumerable() Adds to a service collection (for IEnumerable<T> resolution).

builder.Services.AddSingleton<ILogger, CustomLogger>();

builder.Services.TryAddSingleton<ILogger, DefaultLogger>();

// CustomLogger is used because it was registered first
// TryAdd* only adds if the service type isn't already registered

The Options Pattern (IOptions<T>, IOptionsSnapshot<T>, IOptionsMonitor<T>)

The Options Pattern is the recommended way to add configuration to your services. It provides type safe access to configuration sections and integrates with DI.

Three different options:

1. IOptions<T> Singleton, will be loaded once at startup.
2. IOptionsSnapshot<T> Scoped, will be reloaded per request. (useful for multi tenant scenarios.)
3. IOptionsMonitor<T> Individually triggered changes will be reloaded when the configuration changes.

public class ApiSettings
{
    public string BaseUrl { get; set; } = string.Empty;
    public string ApiKey { get; set; } = string.Empty;
    public int TimeoutSeconds { get; set; } = 30;
}

In appsettings.json

{
  "ExternalApi": {
    "BaseUrl": "https://api.example.com",
    "ApiKey": "your-api-key",
    "TimeoutSeconds": 60
  }
}

Inject and use in a service

public class ExternalApiClient
{
    private readonly ApiSettings _settings;
    private readonly ILogger<ExternalApiClient> _logger;
    private readonly HttpClient _httpClient;

    // Use IOptions<T> for singleton services
    public ExternalApiClient(
        IOptions<ApiSettings> options, 
        ILogger<ExternalApiClient> logger,
        HttpClient httpClient)
    {
        _settings = options.Value;
        _logger = logger;
        _httpClient = httpClient;

        _httpClient.BaseAddress = new Uri(_settings.BaseUrl);
        _httpClient.DefaultRequestHeaders.Add("X-API-Key", _settings.ApiKey);
        _httpClient.Timeout = TimeSpan.FromSeconds(_settings.TimeoutSeconds);
    }

    public async Task<string> FetchDataAsync()
    {
        return await _httpClient.GetStringAsync("/data");
    }
}

public class DynamicConfigService
{
    private readonly IOptionsMonitor<ApiSettings> _optionsMonitor;

    public DynamicConfigService(IOptionsMonitor<ApiSettings> optionsMonitor)
    {
        _optionsMonitor = optionsMonitor;
        
        _optionsMonitor.OnChange(settings =>
        {
            Console.WriteLine($"Configuration changed! New URL: {settings.BaseUrl}");
        });
    }

    public ApiSettings GetCurrentSettings() => _optionsMonitor.CurrentValue;
}

In Program.cs

builder.Services.Configure<ApiSettings>(builder.Configuration.GetSection("ExternalApi"));
builder.Services.AddHttpClient<ExternalApiClient>();

When to use each:

• IOptions<T>: Used for settings that do not change during runtime.
• IOptionsSnapshot<T>: Used in scoped services where the configuration may differ per request.
• IOptionsMonitor<T>: Used when you need to react to configuration changes without restarting the application.

Automating Registration with Assembly Scanning

In large projects, manually registering each service can be time consuming and error prone. While the built in container doesn't offer native assembly scanning, you can use reflection based utilities or third party libraries like Scrutor to automate service registration based on conventions.

Example: Using Scrutor

using Scrutor;

var builder = WebApplication.CreateBuilder(args);

// It will scan the services according to the contract and automatically register them.
builder.Services.Scan(scan => scan
    .FromAssemblyOf<Program>()                    // Scan the current assembly
    .AddClasses(classes => classes.Where(type => 
        type.Name.EndsWith("Service")))           // Find all classes ending with "Service"
    .AsImplementedInterfaces()                    // Register them by their interfaces
    .WithScopedLifetime());                       // Use scoped lifetime

// More specific scanning
builder.Services.Scan(scan => scan
    .FromAssemblies(typeof(IRepository<>).Assembly)
    .AddClasses(classes => classes.AssignableTo(typeof(IRepository<>)))
    .AsImplementedInterfaces()
    .WithTransientLifetime());

Example: Custom reflection based scanning (without external library).

namespace MyApp.Services;

using System.Reflection;

public static class ServiceCollectionExtensions
{
    public static IServiceCollection AddApplicationServices(this IServiceCollection services)
    {
        var assembly = Assembly.GetExecutingAssembly();
        
        // Find all classes implementing IService marker interface
        var serviceTypes = assembly.GetTypes()
            .Where(t => t is { IsClass: true, IsAbstract: false } 
                     && t.GetInterfaces().Any(i => i.Name == "IService"));

        foreach (var serviceType in serviceTypes)
        {
            var interfaceType = serviceType.GetInterfaces()
                .FirstOrDefault(i => i.Name == $"I{serviceType.Name}");
            
            if (interfaceType != null)
            {
                services.AddScoped(interfaceType, serviceType);
            }
        }

        return services;
    }
}

// Usage in Program.cs
builder.Services.AddApplicationServices();

Best Practices:

• Using assembly scanning will be easier in large projects where many services are used in accordance with the rules.
• Your naming conventions should be clearly documented (for example, all classes ending in "Service" are automatically registered).
• In performance critical scenarios, the assembly scan should be performed carefully to avoid potential problems, as this may result in startup costs.
• For true reflection overhead in .NET 9, consider using source generators.

Best Practices and Common Mistakes

Design for Explicit Dependencies

This principle states that parent modules should not depend directly on lower level modules (such as services for data access, sending email, or specific API clients). Instead, both should depend on abstractions (interfaces).

This reverses the normal flow of dependencies, decoupling your code and making it more flexible and testable.

Example

Bad: Violates DIP (Tight Coupling)

Here, the top level NotificationService depends directly on the low level, concrete EmailSender class.

// Low level service
public class EmailSender
{
    public void SendEmail(string message)
    {
        Console.WriteLine($"Sending email: {message}");
    }
}

// High level service
public class NotificationService
{
    // A direct dependency on a CONCRETE class
    private readonly EmailSender _emailSender;

    public NotificationService()
    {
        // The top level class is responsible for creating its own dependencies.
        _emailSender = new EmailSender(); 
    }

    public void NotifyUser(string message)
    {
        _emailSender.SendEmail(message);
    }
}

Problems:

1. Difficult to Test: You will not be able to test NotificationService without sending an email.
2. Not Flexible: But what if you want to send an SMS instead? You will need to modify the NotificationService class.

Good: Following DIP (Loose Coupling)

Here both classes depend on the IMessageSender interface.

// The Abstraction (Interface)
public interface IMessageSender
{
    void Send(string message);
}

// Low level service (depends on the abstraction)
public class EmailSender : IMessageSender
{
    public void Send(string message)
    {
        Console.WriteLine($"Sending email: {message}");
    }
}

// Another low level service
public class SmsSender : IMessageSender
{
    public void Send(string message)
    {
        Console.WriteLine($"Sending SMS: {message}");
    }
}

// High level service (also depends on the abstraction)
public class NotificationService
{
    // Dependency is on the Interface, not a concrete class
    private readonly IMessageSender _messageSender;

    // The dependency is injected via the constructor
    public NotificationService(IMessageSender messageSender)
    {
        _messageSender = messageSender;
    }

    public void NotifyUser(string message)
    {
        _messageSender.Send(message);
    }
}

Benefits:

• Flexible: NotificationService doesn't care whether it is EmailSender or SmsSender. The DI container can be configured to provide both because it is dependent on an interface.
• Testable: You can create a MockMessageSender class that implements IMessageSender to use in your unit tests without sending a real message and perform your operations without needing any real information.

Service Disposal and IAsyncDisposable

If your service contains disposable sources (such as network connections or file streams), it must implement IDisposable or IAsyncDisposable. The DI container will automatically call Dispose or DisposeAsync for you at the end of the service's lifetime. This is an important behavior to prevent source issues.

In .NET 9, asynchronous disposal is the preferred model for services that perform I/O operations during cleanup. The container manages both asynchronous and synchronous disposal operations in a controlled manner.

In this example, MyNetworkService gets HttpClient via DI (which it will not dispose of) but also creates its own FileStream resource, which it is responsible for disposing of asynchronously.

public class MyNetworkService : IAsyncDisposable
{
    private readonly HttpClient _httpClient; 
    
    private readonly FileStream _logStream; 
    private bool _disposed = false;

    public MyNetworkService(HttpClient httpClient)
    {
        _httpClient = httpClient;
        
        _logStream = new FileStream($"log_{Guid.NewGuid()}.txt", 
            FileMode.CreateNew, FileAccess.Write, FileShare.None, 
            4096, useAsync: true);
    }

    public async Task<string> FetchDataAsync()
    {
        var data = await _httpClient.GetStringAsync("https://api.example.com/data");
        await _logStream.WriteAsync(System.Text.Encoding.UTF8.GetBytes(data));
        return data;
    }

    // The container calls this automatically when the scope ends
    public async ValueTask DisposeAsync()
    {
        if (_disposed)
        {
            return;
        }

        // Asynchronous cleanup for resources WE OWN
        // We do NOT dispose of _httpClient here.
        await _logStream.FlushAsync();
        await _logStream.DisposeAsync();
        
        _disposed = true;
        GC.SuppressFinalize(this);
    }
}

Using await using for Manual disposal:

When you manually create service instances outside of the DI container, you should use the await using syntax to ensure proper asynchronous disposal.

// Assume HttpClient is coming from somewhere
public async Task ProcessDataAsync(HttpClient httpClient)
{
    await using var service = new MyNetworkService(httpClient);
    await service.FetchDataAsync();
    // DisposeAsync() is called automatically here
}

Best Practices:

• If your cleanup operation involves asynchronous operations (file I/O, database connections, network calls), it would be more appropriate to implement IAsyncDisposable.
• If your service can be used in both synchronous and asynchronous contexts, you can implement both IDisposable and IAsyncDisposable.
• The DI container will call DisposeAsync() if present; otherwise it will fallback to Dispose().
• It is recommended to always call GC.SuppressFinalize(this) at the end of your disposal method to avoid unnecessary terminations.

Handling Circular Dependencies

A circular dependency occurs when Service A depends on Service B, and Service B, in turn, depends on Service A. The ASP.NET Core container automatically detects this situation during object resolution (at parse time) and throws an InvalidOperationException to prevent a stack overflow, usually with a message detailing the dependency loop.

To resolve this, you must refactor your design to break the circular reference. The most common solution is to introduce a new intermediary abstraction (like an interface) that one of the services can depend on, breaking the direct loop.

You Should Avoid Asynchronous Logic in Constructors

• Constructors must be fast and synchronous. You should not perform await or long running operations.
• Asynchronous operation in constructors can lead to deadlocks and unpredictable initialization behavior.

For asynchronous initialization you should use IHostedService, factory patterns or lazy initialization.

// Bad: Async work in constructor
public class BadService
{
    public BadService(IDataService dataService)
    {
        // This will deadlock or fail!
        var data = dataService.GetDataAsync().Result;
    }
}

// Good: Use IHostedService for async initialization
public class GoodInitializationService : IHostedService
{
    private readonly IDataService _dataService;

    public GoodInitializationService(IDataService dataService)
    {
        _dataService = dataService;
    }

    public async Task StartAsync(CancellationToken cancellationToken)
    {
        // Proper async initialization
        var data = await _dataService.GetDataAsync();
    }

    public Task StopAsync(CancellationToken cancellationToken) => Task.CompletedTask;
}

Captive Dependency Issues

• It is created by injecting a shorter lived service (Scoped) into a longer lived service (Singleton).
• The scoped service becomes "captive" and lives as long as the singleton service, which can lead to stale data and memory leaks.
• The container's ValidateScopes option will detect this at runtime.

// Bad: Scoped service captured by singleton
builder.Services.AddSingleton<MySingletonService>(); // Holds DbContext forever!
builder.Services.AddScoped<AppDbContext>();

// Good: Use IServiceScopeFactory in singletons
public class MySingletonService
{
    private readonly IServiceScopeFactory _scopeFactory;
    
    public MySingletonService(IServiceScopeFactory scopeFactory)
    {
        _scopeFactory = scopeFactory;
    }
    
    public async Task DoWorkAsync()
    {
        await using var scope = _scopeFactory.CreateAsyncScope();
        var dbContext = scope.ServiceProvider.GetRequiredService<AppDbContext>();
        // Use dbContext safely within this scope
    }
}

Avoiding Static Shared State in Singleton Services

• Singleton services should be stateless or have thread safe state management.
• Avoid using static fields or shared mutable states that can cause race conditions.

For immutable objects, the ConcurrentDictionary or appropriate locking mechanisms must be used.

// Bad: Shared mutable state in singleton
public class BadCacheService
{
    private Dictionary<string, string> _cache = new(); // Not thread safe!

    public void Add(string key, string value) => _cache[key] = value;
}

// Good: Thread safe state management
public class GoodCacheService
{
    private readonly ConcurrentDictionary<string, string> _cache = new();

    public void Add(string key, string value) => _cache[key] = value;
}

Testing, Isolation, and Readability

One of the primary goals of DI is testability. In integration tests, you can use the WebApplicationFactory to override service registrations with mock applications.

await using var application = new WebApplicationFactory<Program>()
    .WithWebHostBuilder(builder =>
    {
        builder.ConfigureTestServices(services =>
        {
            services.AddScoped<IExternalService, MockExternalService>();
        });
    });

Performance Considerations

The performance of Dependency injection in ASP.NET Core is adequate for most applications, but it's worth being aware of the mechanics.

Resolution Cost, Service Graph Caching, and Object Pooling

• Service Graph Caching: When a service graph is first parsed, the container creates and caches an execution plan. This plan includes the entire dependency tree and how each object will be created. Subsequent solutions will use this cached plan, making them extremely fast.
• Transient and Singleton Resolving: Transient services have a slightly higher creation cost because a new instance is created each time. However, this cost is generally negligible unless you are resolving thousands of transient services per request.
• Object Pool: For high performance scenarios, it would be beneficial for performance management to consider using ObjectPool<T> from Microsoft.Extensions.ObjectPool to reuse expensive objects instead of creating new transient instances.

Benchmarking DI Performance

Here is an example of a minimum benchmark comparing transient and singleton resolution times using BenchmarkDotNet.

using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Running;
using Microsoft.Extensions.DependencyInjection;

public class DependencyInjectionBenchmark
{
    private ServiceProvider _serviceProvider = null!;

    [GlobalSetup]
    public void Setup()
    {
        var services = new ServiceCollection();
        services.AddTransient<ITransientService, TransientService>();
        services.AddSingleton<ISingletonService, SingletonService>();
        services.AddScoped<IScopedService, ScopedService>();
        _serviceProvider = services.BuildServiceProvider();
    }

    [Benchmark]
    public ITransientService ResolveTransient()
    {
        return _serviceProvider.GetRequiredService<ITransientService>();
    }

    [Benchmark]
    public ISingletonService ResolveSingleton()
    {
        return _serviceProvider.GetRequiredService<ISingletonService>();
    }

    [Benchmark]
    public IScopedService ResolveScoped()
    {
        using var scope = _serviceProvider.CreateScope();
        return scope.ServiceProvider.GetRequiredService<IScopedService>();
    }
}

public interface ITransientService { }
public class TransientService : ITransientService { }
public interface ISingletonService { }
public class SingletonService : ISingletonService { }
public interface IScopedService { }
public class ScopedService : IScopedService { }

// Results:
// | Method           | Mean      | Error    | StdDev   |
// |----------------- |----------:|---------:|---------:|
// | ResolveSingleton |  3.5 ns   | 0.02 ns  | 0.02 ns  | ← Fastest (cached instance)
// | ResolveTransient | 45.2 ns   | 0.31 ns  | 0.29 ns  | ← Allocation overhead
// | ResolveScoped    | 78.4 ns   | 0.52 ns  | 0.48 ns  | ← Scope creation + resolution

Key Points:

• Singleton resolution is almost instantaneous (cached instance invocation).
• Transient solution requires cost but is still fast.
• Scoped solution includes the overhead of creating scope.

For most applications, these differences are not noticeable. It should only be optimized if profiling reveals that DI is a bottleneck.

Startup Time and Compile Time DI

Application startup time is the primary driver of performance. .NET uses Source Generated Dependency Injection to move dependency graph resolution from runtime to compile time.

Benefits:

• Faster Startup: There is no runtime reflection to create the service graph.
• Reduced Memory Usage: It produces smaller runtime.
• AOT Friendly: Provides support for Native AOT compilation, which is critical for cloud native and containerized applications.
• Compile Time Validation: Allows catching missing service records at compile time rather than runtime.

How to Enable

1. For Core Dependency Injection (DI) Generation

This is used as the main constructor that creates the optimized service provider for AddScoped, AddSingleton, etc.

• Activation This will be automatically enabled when you publish with native AOT.
• Project file

  <PropertyGroup>
      <PublishAot>true</PublishAot>
  </PropertyGroup>
  

2. For Configuration Binding Generation

This is used to bind settings from sources like appsettings.json to your C# classes (Bind, Configure).

• Project file:

  <PropertyGroup>
      <EnableConfigurationBindingGenerator>true</EnableConfigurationBindingGenerator>
  </PropertyGroup>
  

Example Code (using all generators):

var builder = WebApplication.CreateBuilder(args);

// This call is optimized by 'EnableConfigurationBindingGenerator'
builder.Services.Configure<MyOptions>(builder.Configuration.GetSection("MyOptions"));

// These calls are optimized by the Core DI generator (when PublishAot=true)
builder.Services.AddScoped<IMyService, MyService>();
var app = builder.Build();

When all generators are enabled, the compiler generates optimized service registration and parsing code, eliminating the reflection overhead.

When to Use:

• Microservices and serverless functions (when it is desired to minimize cold start time).
• Native AOT scenarios (e.g. containerized applications, edge computing).
• Large applications with complex dependency graphs.

Advanced Dependency Injection Patterns in .NET

Keyed Services

Keyed services, introduced in .NET 8, allow you to register multiple implementations of an interface and resolve a specific implementation using a key. This will be a useful feature for polymorphic scenarios where you need to choose a strategy at runtime.

// Registration
builder.Services.AddKeyedSingleton<INotificationService, EmailNotificationService>("email");
builder.Services.AddKeyedSingleton<INotificationService, SmsNotificationService>("sms");

// Resolution in a consumer class
public class NotificationController([FromKeyedServices("email")] INotificationService emailService)
{
    // ...
}

Open Generic Registrations

To avoid manually registering each generic implementation (e.g., IRepository<User>, IRepository<Product>), you can use an explicit global registration.

// This single line registers the Repository<T> for any T requested via IRepository<T>
builder.Services.AddScoped(typeof(IRepository<>), typeof(Repository<>));

The Decorator Pattern

Decorators allow you to add functionality to a service without modifying it. This is a perfect example of the Open/Closed Principle. You can register a decorator that wraps the original service and adds cross cutting functionality like logging, caching, or validation.

Without third party libraries (manual approach):

// Original service interface
public interface IOrderProcessor
{
    Task ProcessOrderAsync(Order order);
}

// Base implementation
public class OrderProcessor : IOrderProcessor
{
    public async Task ProcessOrderAsync(Order order)
    {
        await Task.Delay(100);
        Console.WriteLine($"Order {order.Id} processed.");
    }
}

// Logging decorator
public class LoggingOrderProcessorDecorator : IOrderProcessor
{
    private readonly IOrderProcessor _inner;
    private readonly ILogger<LoggingOrderProcessorDecorator> _logger;

    public LoggingOrderProcessorDecorator(IOrderProcessor inner, ILogger<LoggingOrderProcessorDecorator> logger)
    {
        _inner = inner;
        _logger = logger;
    }

    public async Task ProcessOrderAsync(Order order)
    {
        _logger.LogInformation("Processing order {OrderId}...", order.Id);
        try
        {
            await _inner.ProcessOrderAsync(order);
            _logger.LogInformation("Order {OrderId} processed successfully.", order.Id);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Failed to process order {OrderId}.", order.Id);
            throw;
        }
    }
}

// Manual registration (layering decorators)
builder.Services.AddScoped<OrderProcessor>();
builder.Services.AddScoped<IOrderProcessor>(provider =>
{
    var baseProcessor = provider.GetRequiredService<OrderProcessor>();
    var logger = provider.GetRequiredService<ILogger<LoggingOrderProcessorDecorator>>();
    return new LoggingOrderProcessorDecorator(baseProcessor, logger);
});

With Scrutor library (recommended for complex scenarios):

builder.Services.AddScoped<IOrderProcessor, OrderProcessor>();
builder.Services.Decorate<IOrderProcessor, LoggingOrderProcessorDecorator>();
// Add more decorators
builder.Services.Decorate<IOrderProcessor, CachingOrderProcessorDecorator>();

Middleware Integration Context

Decorators work in a similar way with ASP.NET Core middleware. While the middleware operates at the HTTP pipeline level, decorators operate at the service level, allowing you to apply cross cutting concerns to business logic independent of HTTP concerns.

Conditional Registrations

You can conditionally register services based on runtime configuration or environment.

var builder = WebApplication.CreateBuilder(args);

// You can register different applications depending on the environment
if (builder.Environment.IsDevelopment())
{
    builder.Services.AddScoped<IEmailService, FakeEmailService>();
}
else
{
    builder.Services.AddScoped<IEmailService, SmtpEmailService>();
}

// Register based on configuration
var useRedis = builder.Configuration.GetValue<bool>("UseRedisCache");
if (useRedis)
{
    builder.Services.AddStackExchangeRedisCache(options => { /* ... */ });
}
else
{
    builder.Services.AddDistributedMemoryCache();
}

Child Containers and Nested Scopes

While the built in ASP.NET Core container doesn't support "subcontainers" like Autofac or other third party containers, you can achieve similar isolation using scopes.

It's important to differentiate this from the Service Locator anti pattern, which involves directly injecting IServiceProvider to manually resolve dependencies. Instead, the correct approach (especially within Singleton services) is to inject IServiceScopeFactory.

Comprehensive embedded approach

public class ParentService
{
    private readonly IServiceScopeFactory _scopeFactory;

    public ParentService(IServiceScopeFactory scopeFactory)
    {
        _scopeFactory = scopeFactory;
    }

    public async Task DoIsolatedWorkAsync()
    {
        await using var scope = _scopeFactory.CreateAsyncScope();
        
        // Resolve services from the new scope's provider
        var isolatedService = scope.ServiceProvider.GetRequiredService<IIsolatedService>();
        await isolatedService.DoWorkAsync();
        // All services resolved from 'scope.ServiceProvider' are disposed here
    }
}

Third party containers (Autofac example)

// Autofac supports real subcontainers with invalid records
var childLifetimeScope = container.BeginLifetimeScope(builder =>
{
    builder.RegisterType<MockDatabaseService>().As<IDatabaseService>();
});

The built in container's scoping mechanism is simpler but sufficient for most scenarios. You can use third party containers only when you need advanced features like property injection, assembly scanning with rules, or complex lifetime management.

Testing with DI and ConfigureTestServices

One of DI's greatest strengths is testability. In integration tests, you can replace real services with mock or simulated services using WebApplicationFactory and ConfigureTestServices.

using Microsoft.AspNetCore.Mvc.Testing;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection.Extensions;

public class OrderControllerTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly WebApplicationFactory<Program> _factory;

    public OrderControllerTests(WebApplicationFactory<Program> factory)
    {
        _factory = factory;
    }

    [Fact]
    public async Task ProcessOrder_ReturnsSuccess()
    {
        //Replace real service with mock
        var client = _factory.WithWebHostBuilder(builder =>
        {
            builder.ConfigureTestServices(services =>
            {
                //Remove actual service
                services.RemoveAll<IOrderProcessor>();
                
                // Add mock service
                services.AddScoped<IOrderProcessor, MockOrderProcessor>();
                
                // Or use a mocking framework
                var mockProcessor = new Mock<IOrderProcessor>();
                mockProcessor.Setup(x => x.ProcessOrderAsync(It.IsAny<Order>()))
                            .ReturnsAsync(true);
                services.AddScoped(_ => mockProcessor.Object);
            });
        }).CreateClient();

        // Act
        var response = await client.PostAsJsonAsync("/api/orders", new Order { Id = 1 });

        // Assert
        response.EnsureSuccessStatusCode();
    }
}

Key Benefits:

• You can replace expensive external dependencies with in memory mocks.
• You can test business logic in isolation.
• You can run fast and accurate tests without needing external dependencies.

Example: A Background Service

A common scenario where DI lifecycle management is critical is with singletons, such as background workers or IHostedServices. You cannot directly add a scoped service like DbContext to this service. Instead, you'd be better off adding an IServiceScopeFactory to manually create scopes.

Hosted Service (OrderProcessorWorker.cs):

public class OrderProcessorWorker : BackgroundService
{
    private readonly ILogger<OrderProcessorWorker> _logger;
    private readonly IServiceScopeFactory _scopeFactory;

    // Inject IServiceScopeFactory, not DbContext
    public OrderProcessorWorker(ILogger<OrderProcessorWorker> logger, IServiceScopeFactory scopeFactory)
    {
        _logger = logger;
        _scopeFactory = scopeFactory;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            _logger.LogInformation("Processing new orders...");

            // Create a new scope for this unit of work
            await using (var scope = _scopeFactory.CreateAsyncScope())
            {
                var orderRepository = scope.ServiceProvider.GetRequiredService<IOrderRepository>();
                var newOrders = await orderRepository.GetNewOrdersAsync();
                
                foreach (var order in newOrders)
                {
                    // Process order...
                }
                
                await orderRepository.SaveChangesAsync();
            }

            await Task.Delay(TimeSpan.FromMinutes(1), stoppingToken);
        }
    }
}

Registration (Program.cs):

builder.Services.AddDbContext<AppDbContext>(/* ... */);
builder.Services.AddScoped<IOrderRepository, OrderRepository>();
builder.Services.AddHostedService<OrderProcessorWorker>();

This pattern ensures that each run of the worker uses a new DbContext, preventing problems such as memory leaks or stale data.

While this example uses a simple Task.Delay loop within the BackgroundService, a robust pattern for managing decoupled background tasks involves an in memory queue. You can learn how to build this system by following this guide: How to Build an In Memory Background Job Queue in ASP.NET Core From Scratch.

Conclusion

Understanding the ASP.NET Core Dependency Injection framework is essential for any .NET developer. By understanding the built in IoC container, choosing the right service lifecycles, and opting for explicit constructor injection, you can create modular, testable, and maintainable applications.

.NET brings significant enhancements to the DI ecosystem

• Source Generated DI for faster startup and Native AOT support
• Keyed Services for advanced polymorphic resolution scenarios
• Enhanced lifetime validation catches captive dependencies at development time
• Improved IAsyncDisposable support for proper source cleanup*
• Good integration with C# features such as primary constructors

By embracing these features and implementing patterns such as decorators, manual scoping with IServiceScopeFactory, the Option Pattern for configuration, and proper asynchronous disposal, you can solve complex architectural challenges cleanly and efficiently.

Key Points

• Always inject dependencies via constructors explicit, immutable, testable
• Understanding lifetime implications avoid dependent dependencies, you can use IServiceScopeFactory on singletons
• Leverage the Option Pattern type safe, validated configuration injection
• You can use TryAdd methods create mergeable records
• Leverage DI in your tests you can use ConfigureTestServices to inject mocks
• Measure performance first; don't assume DI is a bottleneck The internal container is efficient. Use a profiler to find real slowdowns before trying to optimize DI.
• Consider source generation for microservices, serverless and AOT scenarios

The transition from legacy, fragmented DI environments to a unified, performant, and compile time optimized dependency injection system represents a significant development in the platform's history. Understanding and leveraging these capabilities is crucial for building high performance, cloud native .NET applications.

Further Reading

• ABP Dependency Injection
• Official Microsoft Docs on Dependency Injection in ASP.NET Core
• Source Generators for Dependency Injection
• IHttpClientFactory with .NET
• Keyed Services DI Container
• Use Scoped Services Within a Scoped Service
• Scrutor

In web applications, providing a fast and responsive API is crucial for the user experience. However, some operations, such as sending emails, generating reports, or adding users in bulk, can take significant time. Performing these tasks during a request can block threads, resulting in slow response times.

To significantly alleviate this issue, it would be more effective to run long running tasks in a background process. Instead of waiting for the request to complete, we can queue the task, provide an immediate response to the user, and perform the work in a separate background process.

While libraries like Hangfire or message brokers like RabbitMQ exist for this purpose, you don't need any external dependencies. In this blog post, we'll build an in memory background job queue from scratch in ASP.NET Core using only built in .NET features.

Core Components of Background Job System

Before implementing the code, it is important to first understand the basic parts that make up the background job system and how they work to process queued tasks.

What are IHostedService and BackgroundService?

IHostedService is an interface used in ASP.NET Core to implement long running background tasks managed by the application's lifecycle. When your application starts, it starts all registered IHostedService applications. When it shuts down, it instructs them to stop.

BackgroundService is an abstract base class that implements IHostedService. It gives you a more efficient way to create a timed service by giving you a single overridable method ExecuteAsync(CancellationToken stoppingToken). We'll use this as the basis for our job processor.

The Producer/Consumer Structure

• Producer: This is the part of your application that creates jobs and adds them to the queue. In our example, the producer will be an API Controller.
• Consumer: This is a background service that constantly monitors the queue, pulls jobs from the queue, and executes them. Our BackgroundService application will be the consumer.
• Queue: This is the data structure between the producer and consumer that holds jobs waiting to be processed.

Why System.Threading.Channels?

Introduced in .NET Core 3.0, System.Threading.Channels provides a synchronization data structure designed for asynchronous producer, consumer scenarios.

• Thread Safety: Handles all complex locking and synchronization operations internally, making it usable as a whole from multiple threads (for example, when multiple API requests are adding work simultaneously).
• Async Native: Designed for use with async/await, preventing thread blocking. You can asynchronously wait for an item in the queue to become available.
• Performance: Optimized for speed and low memory allocation. Generally superior to legacy constructs like ConcurrentQueue for asynchronous workflows because it eliminates the need for polling.

Implementing the Background Job Queue

Now that we understand the architecture, we can implement the background job queue.

Create the Project

First, create a new ASP.NET Core Web API project using the .NET CLI.

dotnet new sln -n BackgroundJobQueue

dotnet new webapi -n BackgroundJobQueue.Api

dotnet sln BackgroundJobQueue.sln add BackgroundJobQueue.Api/BackgroundJobQueue.Api.csproj

Define the Job Queue Interface

For dependency injection and testability, we'll start by defining an interface for our queue. This interface will define methods for adding a job (EnqueueAsync) and removing a job (DequeueAsync).

Create a new file named IBackgroundTaskQueue.cs.

namespace BackgroundJobQueue;

public interface IBackgroundTaskQueue
{
    // Adds a work item to the queue
    ValueTask EnqueueAsync(Func<CancellationToken, ValueTask> workItem);

    // Removes and returns a work item from the queue
    ValueTask<Func<CancellationToken, ValueTask>> DequeueAsync(CancellationToken cancellationToken);
}

We'll use Func<CancellationToken, ValueTask> to represent a work item. This allows us to queue any asynchronous method that accepts a CancellationToken.

Implement the Queue Service with Channels

Now, let's implement the IBackgroundTaskQueue interface using the System.Threading.Channels class. This class will manage the in memory channel.

Create a new file named BackgroundTaskQueue.cs.

using System.Threading.Channels;

namespace BackgroundJobQueue;

public class BackgroundTaskQueue : IBackgroundTaskQueue
{
    private readonly Channel<Func<CancellationToken, ValueTask>> _queue;

    public BackgroundTaskQueue(int capacity)
    {
        // BoundedChannelOptions specifies the behavior of the channel.
        var options = new BoundedChannelOptions(capacity)
        {
            // FullMode.Wait tells the writer to wait asynchronously if the queue is full.
            FullMode = BoundedChannelFullMode.Wait
        };
        _queue = Channel.CreateBounded<Func<CancellationToken, ValueTask>>(options);
    }

    public async ValueTask EnqueueAsync(Func<CancellationToken, ValueTask> workItem)
    {
        if (workItem is null)
        {
            throw new ArgumentNullException(nameof(workItem));
        }

        // Writes an item to the channel. If the channel is full,
        await _queue.Writer.WriteAsync(workItem);
    }

    public async ValueTask<Func<CancellationToken, ValueTask>> DequeueAsync(CancellationToken cancellationToken)
    {
        // Reads an item from the channel. If the channel is empty,
        var workItem = await _queue.Reader.ReadAsync(cancellationToken);

        return workItem;
    }
}

Create the Consumer Service (QueuedHostedService)

This is our consumer. It's a BackgroundService that continuously dequeues and executes jobs.

Create a new file named QueuedHostedService.cs.

namespace BackgroundJobQueue;

public class QueuedHostedService : BackgroundService
{
    private readonly IBackgroundTaskQueue _taskQueue;
    private readonly ILogger<QueuedHostedService> _logger;

    public QueuedHostedService(IBackgroundTaskQueue taskQueue, ILogger<QueuedHostedService> logger)
    {
        _taskQueue = taskQueue;
        _logger = logger;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        _logger.LogInformation("Queued Hosted Service is running.");

        while (!stoppingToken.IsCancellationRequested)
        {
            // Dequeue a work item
            var workItem = await _taskQueue.DequeueAsync(stoppingToken);

            try
            {
                // Execute the work item
                await workItem(stoppingToken);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Error occurred executing {WorkItem}.", nameof(workItem));
            }
        }

        _logger.LogInformation("Queued Hosted Service is stopping.");
    }
}

The try-catch block here is critical. It ensures that if one job fails with an exception, it won't crash the entire background service.

Register the Services in Program.cs

Next we need to register the queue and hosted service in the dependency injection container inside Program.cs.

using BackgroundJobQueue;

var builder = WebApplication.CreateBuilder(args);

//...

// Register the background task queue as a Singleton
builder.Services.AddSingleton<IBackgroundTaskQueue>(_ => 
{
    // You can configure the capacity of the queue here
    if (!int.TryParse(builder.Configuration["QueueCapacity"], out var queueCapacity))
    {
        queueCapacity = 100;
    }
    return new BackgroundTaskQueue(queueCapacity);
});

// Register the hosted service
builder.Services.AddHostedService<QueuedHostedService>();


var app = builder.Build();

//...

app.Run();

We register IBackgroundTaskQueue as a Singleton because we need a single, shared queue instance for the entire application. We register QueuedHostedService using AddHostedService() to ensure the .NET runtime manages its lifecycle.

Create a Producer (API Controller)

Finally, let's create a producer. This will be a simple API controller with an endpoint that enqueues a new background job.

Create a new controller named JobsController.cs.

using Microsoft.AspNetCore.Mvc;

namespace BackgroundJobQueue.Controllers;

[ApiController]
[Route("[controller]")]
public class JobsController : ControllerBase
{
    private readonly IBackgroundTaskQueue _queue;
    private readonly ILogger<JobsController> _logger;

    public JobsController(IBackgroundTaskQueue queue, ILogger<JobsController> logger)
    {
        _queue = queue;
        _logger = logger;
    }

    [HttpPost]
    public async Task<IActionResult> EnqueueJob()
    {
        // Enqueue a job that simulates a long running task
        await _queue.EnqueueAsync(async token =>
        {
            // Simulate a 5 second task
            var guid = Guid.NewGuid();
            _logger.LogInformation("Job {Guid} started.", guid);
            await Task.Delay(TimeSpan.FromSeconds(5), token);
            _logger.LogInformation("Job {Guid} finished.", guid);
        });

        return Ok("Job has been enqueued.");
    }
}

Now, when you run your application and send a POST request to /jobs, the API will respond instantly with "Job has been enqueued." while the 5 second task runs in the background. You'll see the log messages appear in your console after the delay.

Important Considerations and Advanced Topics

Shutdown

The CancellationToken passed to ExecuteAsync is important. The host triggers this token when you stop your application. Our while loop condition (!stoppingToken.IsCancellationRequested) and passing the token to DequeueAsync cause the service to stop listening for new items and exit.

Error Handling

Our try-catch block prevents a single failed job from crashing the consumer. For production scenarios, you can consider a more advanced error handling strategy, such as a retry mechanism. Libraries like Polly can be integrated here to automatically retry failed jobs with policies like fallback.

Limits of the In Memory Queue

The biggest drawback of this approach is that the queue is in memory. If your application process restarts or crashes for any reason, any work waiting in the queue will be lost. This solution is best for idempotent or non critical tasks.

When Should You Use External Libraries?

Built from the ground up, this solution is powerful, but it's important to know when to turn to more advanced tools.

• Hangfire: Use Hangfire when you need job continuity (saves jobs to a database), automatic retries, a management dashboard, scheduled jobs, and delayed execution. Background tasks are an ideal solution while processing.

• RabbitMQ When building a distributed system (such as a microservices architecture), you can use a custom message broker. These brokers provide scalable queues that isolate your services and guarantee message delivery.

Frequently Asked Questions

Q1: What happens to the jobs in the queue if my application restarts or crashes?

A: Because this is an in-memory queue, any unprocessed work is lost when the application closes or crashes. This solution is best suited for non-critical or idempotent tasks (i.e., they can be safely rerun without causing problems). For guaranteed business continuity, you should use a solution that stores jobs in a database or message broker, such as Hangfire or RabbitMQ.

Q2: How can I implement retry logic for jobs that fail due to an exception?

A: The try-catch block in QueuedHostedService prevents the entire background service from crashing, but it doesn't automatically retry the failed job. You can integrate a library like Polly to add robust retry capabilities. You can wrap the await workItem(stoppingToken); call in a Polly retry policy to automatically rerun the job a configured number of times with delays.

Polly Official Documentation

Q3: Will this work in a load balanced environment with multiple server instances?

A: No, this implementation is instance-specific. The queue exists only in the memory of the server instance that receives the API request. If you deploy your application across multiple servers, a job queued on Server A will be processed only by Server A. For a shared queue that can be processed by any server in a web environment, you should use a centralized, distributed message broker such as RabbitMQ, Azure Service Bus.

Q4: What happens if jobs are added to the queue faster than the background service can process them?

A: This application uses a BoundedChannel with a fixed capacity (for example, 100 in our example). When the queue is full, setting FullMode = BoundedChannelFullMode.Wait causes the producer (API controller) to asynchronously wait until space becomes available in the queue. This creates "backpressure" that prevents your application from running out of memory. However, this also means that if the background service is constantly overloaded, your API endpoint will become slower to respond as it waits to queue new jobs.

Q5: How can I monitor the number of jobs currently in the queue?

A: For basic monitoring, you can inject IBackgroundTaskQueue into a service and periodically record the queue count. A more advanced approach is to create a custom metrics endpoint (for example, for Prometheus). You can create a custom controller that accesses the Count property of the ChannelReader to report the current queue depth and set alerts if the queue grows too long.

Conclusion

We've built a performant, in memory background job queue in ASP.NET Core using only built in framework features. This is a way to increase your API's responsiveness and improve the user experience by disabling long running tasks.

Using IHostedService and System.Threading.Channels, we've created an efficient implementation of the producer, consumer model. While this in memory approach has some limitations, it's a powerful tool for many common scenarios. As your needs grow, you can consider more feature rich tools like Hangfire or RabbitMQ, knowing you've mastered the fundamentals.

References

• Background tasks with hosted services in ASP.NET Core
• An Introduction to System.Threading.Channels
• ABP Framework - Background Jobs
• Creating a queued background task service with IHostedService by Andrew Lock
• Hangfire Documentation
• RabbitMQ Tutorials