Should I manually flush HttpResponse.BodyWriter? Docs seems to contradict actual practices in MVC

[scharnyw]

I'm confused by the usages of HttpResponse.Body and HttpResponse.BodyWriter and the documentation in this aspect unfortunately does not shed much light. Any help would be greatly appreciated.

I have an application that writes large JSON responses, and I'm writing this JSON manually with STJ.Utf8JsonWriter (due to performance reasons). Previously this was written to HttpResponse.Body (a stream) and now I'm making the switch to using HttpResponse.BodyWriter (a PipeWriter). My question is: should I be flushing HttpResponse.BodyWriter periodically when writing to it?

The ASP.NET Core docs say yes, but this SO post says no. Also, both the SystemTextJsonOutputFormatter and NewtonsoftJsonOutputFormatter in MVC doesn't seem to do any flushing of the Stream/PipeWriter and leaves it entirely to the framework. So I'm completely baffled as the practices within ASP.NET Core seems to contradict its own documentation.

Also, if manual flushing is desired, how do I determine the optimum buffer size? I understand that it depends on the scenario, but still, some guidelines would be nice. My understanding is that each flushing would lead to one response chunk? Would 16 KB (HttpResponseStreamWriter.DefaultBufferSize) be a reasonable value in common situations?

[davidfowl]

Newtonsoft.Json isn’t async and doesn’t use the newer async APIs. So when it flushes buffered bytes to the underlying stream, it blocks—tying up a thread pool thread.

SystemTextJsonOutputFormatter, on the other hand, calls SerializeAsync, which is key here. System.Text.Json writes to the underlying writer as it serializes the object, and because it’s async, it doesn’t block a thread.

Both cases buffer and flush automatically based on internal heuristics—things like how StreamWriter or JsonSerializer are configured.

I have an application that writes large JSON responses manually using Utf8JsonWriter for performance. It used to write to HttpResponse.Body (a Stream), but now I’m switching to HttpResponse.BodyWriter (a PipeWriter). Do I need to flush the BodyWriter periodically?

If you’re using Utf8JsonWriter directly, you’re in manual mode. It only knows about IBufferWriter<byte>, which PipeWriter implements, but IBufferWriter doesn’t expose any flush concept. So yeah, you’ll need to explicitly flush the PipeWriter yourself. Otherwise you risk holding on to a bunch of buffered data that never makes it out to the client until the buffer fills or the response ends.

[scharnyw]

If you’re using Utf8JsonWriter directly, you’re in manual mode. It only knows about IBufferWriter<byte>, which PipeWriter implements, but IBufferWriter doesn’t expose any flush concept. So yeah, you’ll need to explicitly flush the PipeWriter yourself. Otherwise you risk holding on to a bunch of buffered data that never makes it out to the client until the buffer fills or the response ends.

Thanks for the authoritative answer! Indeed I did some testing with STJ.JsonSerializer and it will flush the PipeWriter once in a while. Based my test scenario, the average buffer size is somewhere around 14-15 KB (I understand it's a heuristic), so I guess some values around this should be OK for typical scenarios (i.e. at least not detrimental for performance?).