The way back: serialisation, HTML and hydration

From a C# object to JSON, from JSON to HTML, from HTML to an interactive page.

UnderstandStudy an examplePractise

Understand the concept

When a controller returns an object, ASP.NET Core serialises it to JSON with System.Text.Json. The default naming is camelCase; dates are written in ISO 8601, and storing and sending them in UTC avoids time-zone confusion. Serialising entities with circular references causes errors and leaks needless data, so responses are shaped with DTOs.

When Next.js receives the JSON it renders Server Components to HTML and streams it to the browser. Ready parts are sent first; if a slow piece of data is wrapped in Suspense, the rest of the page does not wait for it. Alongside the HTML come the JavaScript needed to bring client components to life and a compact description of server components (the RSC payload).

The browser shows the HTML immediately; React then hydrates: it matches the server-produced HTML with the tree built on the client and attaches event listeners. If server and client produce different content (for example formatting a date in a different time zone) a hydration mismatch occurs. Time-dependent or browser-dependent values are therefore handled carefully.

WHEN TO USE IT

The response’s final leg decides when users see the page and when they can use it.

COMMON PITFALL

Formatting a date with different time zones on server and client, causing a hydration mismatch.

01 / PRACTICE

One topic. Three levels of depth.

Illustrative example

public sealed record PostDto(string Title, DateTime PublishedAtUtc);
// → {"title":"İlk yazı","publishedAtUtc":"2026-10-01T09:00:00Z"}

Default camelCase naming and an ISO 8601 UTC date.

This page connects to no real server or database. Code samples are illustrative for .NET 8, Next.js and SQL Server; timings are example values in the simulation, not measurements. Try samples only in your own development environment; never share real connection strings, tokens or passwords.

02 / YOUR TURN

Try it yourself first.

The console warns ‘Text content does not match server-rendered HTML’ and it happens only near midnight. What is the most likely cause?

Show the solution and explanation

Worked solution

Tarih/saat sunucuda ve istemcide farklı saat dilimiyle biçimleniyor.
Gece yarısına yakın 'bugün/dün' veya gün sayısı iki tarafta farklı çıkıyor.
Çözüm: saat dilimini sabitlemek veya bu değeri yalnız istemcide hesaplamak.

Time-dependent values are a hydration risk unless server and client are guaranteed to produce the same result.

RasimAtaberkŞahin

Understand the concept

One topic. Three levels of depth.

Try it yourself first.