Deal with the fact that finalization of StreamWriter can close the response stream prematurely
A typical pattern is to create a StreamWriter from the Stream argument that is passed to OnWriteToStreamAsync in a media type formatter. The guidance is to *not* close this StreamWriter since doing so will also close the underlying stream (which you don't want).
But what happens if finalization of the once-out-of-scope StreamWriter occurs? Well, it will close the underlying stream!
What is the team's guidance for dealing with this? Simply suppress finalization of the StreamWriter?
The recommended pattern is to use the RegisterForDispose extension method on the request message to register all resources that you want disposed when the request is disposed.
Ok, with the help of LittleClive on the forums, I've now ascertained that finalization of StreamWriter won't necessarily close the underlying stream (I think!). But I still think there are problems... people reaching for a using statement when creating a StreamWriter, unnecessary StreamWriter object creation, forgetting to flush, etc.
The current situation is too error prone. Requiring formatters to derive a StreamWriter from your Stream just to write text runs the risk of people a) writing code to close the StreamWriter and hence the underlying stream (e.g. "using(...)"), b) unnecessary object creation (e.g. the VCard example), c) forgetting to flush, d) finalization kicking in at random to close the StreamWriter and underlying stream prematurely.
The framework should pass in a type (ideally an absract base class) that is able to write bytes and text, which doesn't require flushing, and which can't be closed by public callers. That would deal with all of the problems.