skip to content

In a Blazor Web App, why does a static page that passes ChildContent to a child with @rendermode InteractiveServer throw, and what other render-mode boundary rules apply?

level: seniorimportance: should knowfreq 38%

answer

  1. a render mode starts a boundary
  2. parameters must be serializable
  3. delegates such as RenderFragment cannot cross
  4. no different interactive mode under an interactive parent
  5. a null render mode means inherit

basics

~20 s

A render mode on a child starts a new boundary whose parameters are serialized into the page for the interactive runtime. A RenderFragment is a delegate, arbitrary code, so it cannot be serialized and Blazor throws an InvalidOperationException.

solid answer

~40 s

When a static parent renders `<Child @rendermode="InteractiveServer" />`, Blazor wraps the child in a **render mode boundary**: it prerenders the child, then writes a descriptor with the component type and its parameters into the HTML so the circuit or the WebAssembly runtime can recreate it. Parameters therefore have to survive serialization; a delegate such as `ChildContent` (a `RenderFragment`), a `RenderFragment<T>` or a lambda cannot, so the boundary throws an `InvalidOperationException` naming the parameter. The other rules: children inherit the parent's mode; a different interactive mode inside an interactive parent throws a `NotSupportedException`; a `null` render mode means inherit, not static; and a layout cannot be made interactive per page because it receives `Body` as a render fragment. The workaround is a wrapper component that owns the child content and carries the render mode itself.

code

razor · 7 lines
razor
@* Fails: ChildContent is a RenderFragment crossing the boundary *@
<Card @rendermode="InteractiveServer">
    <LeaveRequestForm />
</Card>

@* Works: the wrapper builds the fragment inside the circuit *@
<LeaveRequestCard @rendermode="InteractiveServer" EmployeeId="@employeeId" />

go deeper

for a junior

Remember that a component with a different render mode from its parent cannot receive child content, and that children inherit their parent's mode.

for a middle

Explain that a boundary serializes parameters for the interactive runtime, why delegates fail, and the wrapper-component workaround.

for a senior

Design component trees around boundaries: keep fragments inside one runtime, pass small serializable data, avoid secrets in WebAssembly parameters, and know why interactive layouts need global interactivity.

for a principal

Decide where boundaries belong in a large app so shared UI components stay mode-agnostic and teams are not forced into global interactivity by one layout requirement.

## What a render mode boundary is In a **Blazor Web App**, the place where a component gets a render mode that differs from its parent's is a **render mode boundary**. Everything above it ran on the server's static renderer; everything below it must later be recreated in another runtime - a server circuit for Interactive Server, the browser's .NET WebAssembly runtime for Interactive WebAssembly. To make that possible, the server does two things at the boundary: 1. It **prerenders** the child (unless prerendering is off) so the HTML is in the response. 2. It writes a **component descriptor** into the page: the component type plus its **parameter values**, serialized. For WebAssembly the parameters are Base64-encoded JSON readable by anyone viewing the page; for Server the descriptor is protected with ASP.NET Core Data Protection and expires after five minutes. The interactive runtime reads the descriptor and creates a fresh instance with those parameters. ## Why ChildContent throws `ChildContent` is a `RenderFragment`, which is a **delegate** - compiled code with a closure over the parent's state. Code cannot be serialized into JSON and rebuilt in another process or in the browser. The boundary checks every parameter before rendering and throws an `InvalidOperationException` when one is a delegate: - a plain `RenderFragment`, such as `ChildContent`, gets a message saying the parameter is of a delegate type, "which is arbitrary code and cannot be serialized"; - a `RenderFragment<T>` gets a message saying templated content cannot be passed across a render mode boundary. The same applies to any lambda passed as a parameter. Other parameters must be serializable by `System.Text.Json` and should be small, because they travel inside the page. ## The rules, in one place | Situation | Result | |---|---| | Child with no mode under a static parent | static SSR | | Child with no mode under an interactive parent | inherits the parent's mode | | Static parent, children with different interactive modes side by side | allowed; each child is its own boundary | | Interactive parent, child with a **different** interactive mode | `NotSupportedException`: the render mode is not supported by the parent's renderer | | Child given a `null` render mode | same as no mode: it **inherits**, it does not force static | | Delegate parameter crossing a boundary | `InvalidOperationException` | Two consequences surprise people: - **Layouts.** In per-page interactivity, `MainLayout` is rendered by the static parent and receives the page as `Body`, a `RenderFragment`. Making the layout interactive would push that fragment across a boundary, so it fails. Interactive layouts need global interactivity, set on `<Routes>` in `App.razor`. - **`null` is not static.** Code that computes `@rendermode="@(isStatic ? null : InteractiveServer)"` only gets static SSR when the parent is static. The template uses this trick on `Routes`, under the always-static `App` component. ## Workarounds - **Wrap it.** Create a small component that renders the child together with its content, and put the render mode on the wrapper. The fragment is now built inside the interactive runtime and never crosses the boundary. The template's `Routes` component exists for exactly this reason: it wraps the `Router` so the router's templates stay on one side. - **Pass data, not markup.** Replace a `RenderFragment` parameter with a serializable parameter - a string, an id, a small record - and let the interactive component render it. - **Move the boundary up.** Make the parent interactive instead, so both live in one runtime. ## Applying it to a portal page An employee self-service page that is static apart from a leave-request widget might want `<Card @rendermode="InteractiveServer"><LeaveRequestForm /></Card>`. That fails, because the card's `ChildContent` crosses the boundary. A `LeaveRequestCard` component that renders `<Card><LeaveRequestForm /></Card>` inside itself, used as `<LeaveRequestCard @rendermode="InteractiveServer" />`, works, and keeps the rest of the page static.

  • What is the difference between the parameters a WebAssembly boundary and a Server boundary write into the page?
    For an Interactive WebAssembly child, the type and parameter values are Base64-encoded JSON in the HTML, so anyone can read them and they must not carry secrets. For an Interactive Server child, the descriptor is protected with ASP.NET Core Data Protection and expires after five minutes, so the browser cannot read or forge it. In both cases the values must be serializable.
  • Why can't a page with @rendermode InteractiveServer contain a child marked InteractiveWebAssembly?
    Below an interactive parent, every child is created by that parent's renderer - here the server circuit's renderer, which can only create server components. Asked to create a WebAssembly one, it throws a `NotSupportedException` saying the component's render mode is not supported by interactive server-side rendering. Different interactive modes can only sit side by side under a static parent.

  • Any parameter can cross a render mode boundary because Blazor passes the object reference.
  • Setting a child's render mode to null always forces static server-side rendering.
  • An InteractiveServer page can host an InteractiveWebAssembly child for heavy client work.
  • Making MainLayout interactive per page is the normal way to get an interactive navigation menu.
  • Server boundary parameters sit in the page as plain JSON that users can read.