One of the common discussions to have around network APIs is whether streams should be push or pull. That is, do you push content to the network, or does the infrastructure pull it from you and copy it to the network? In general there is no “right” way of determining this, it is a matter of taste and what fits more naturally in the object model in question.
HttpContent is the common abstraction for any kind of content in HttpClient regardless of whether it be as part of an HttpRequestMessage or an HttpResponseMessage. Luckily it supports both patterns.
The pull pattern is supported by StreamContent which is one of the default implementations of HttpContent. Here the input stream is read (pulled) by the infrastructure and copied to the network. This works great in many cases such as file streams and the like where the content easily can be read.
To support a push model we similarly use a special HttpContent implementation. There isn’t one in the current bits but we can easily create one to support push. The trick is that it doesn’t take an input stream but rather an Action<Stream> as input. When it is time the Action delegate is called so that it can write whatever it wants to the output stream and so there you have a push model.
Once we have the ActionOfStream content then we can use it to write content that requires a push model such as XDocument.Save which writes content directly to an output stream with no support for a pull model: