Add documentation about FlushAsync

README.md

@@ -196,6 +196,25 @@ The `RazorTemplate` base class provides `Render` and `RenderAsync` methods to ex
 
 Templates are stateful and not thread-safe, so it is advised to always create new instances of the templates to render.
 
+### Flushing partial output
+
+By default, the output of a template is buffered while it is executing, then copied to the provided writer when finished. This is necessary for features such as layouts to be supported, but may not always be desired.
+
+The `RazorTemplate` class provides a `FlushAsync` method which will copy the buffered output to the provided `TextWriter` and then flush the writer:
+
+<!-- snippet: TemplateWithFlush.Usage -->
+<a id='snippet-templatewithflush.usage'></a>
+```cshtml
+<div>Lightweight content goes here.</div>
+@await FlushAsync()
+<div>Slower to render content goes here.</div>
+```
+<sup><a href='/src/RazorBlade.IntegrationTest/Examples/TemplateWithFlush.cshtml#L2-L6' title='Snippet source file'>snippet source</a> | <a href='#snippet-templatewithflush.usage' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
+> [!IMPORTANT]  
+> Flushing is not compatible with layout usage.
+
 ### MSBuild
 
 The source generator will process `RazorBlade` MSBuild items which have the `.cshtml` file extension.

src/RazorBlade.IntegrationTest/Examples/TemplateWithFlush.cshtml

@@ -0,0 +1,6 @@
+@inherits RazorBlade.HtmlTemplate
+@* begin-snippet: TemplateWithFlush.Usage *@
+<div>Lightweight content goes here.</div>
+@await FlushAsync()
+<div>Slower to render content goes here.</div>
+@* end-snippet *@

src/RazorBlade.IntegrationTest/PageWithFlush.cshtml

@@ -0,0 +1,7 @@
+@inherits RazorBlade.HtmlTemplate
+<h2>Hello, world!</h2>
+This is the body contents before flushing.
+@await FlushAsync()
+This is the body contents after flushing.
+@await FlushAsync()
+This is the body contents after a second flushing.

src/RazorBlade.IntegrationTest/Program.cs

@@ -10,6 +10,7 @@ public static void Main()
         WriteTemplate(new TestTemplate { Name = "World" });
         WriteTemplate(new TestTemplateWithModel(new FooBarModelClass { Foo = "Foo", Bar = "Bar" }));
         WriteTemplate(new PageWithLayout());
+        WriteTemplate(new PageWithFlush());
     }
 
     private static void WriteTemplate(RazorTemplate template)

src/RazorBlade.Library/RazorTemplate.cs

@@ -164,11 +164,20 @@ private protected virtual async Task<IRazorExecutionResult> ExecuteAsyncCore(Tex
     /// <summary>
     /// Writes the buffered output to the target output then flushes the output stream.
     /// </summary>
+    /// <returns>
+    /// An empty <see cref="IEncodedContent"/>, which allows using a direct expression: <c>@await FlushAsync()</c>
+    /// </returns>
     /// <remarks>
     /// This feature is not compatible with layouts.
     /// </remarks>
-    protected internal Task FlushAsync()
-        => _executionScope?.FlushAsync() ?? Task.CompletedTask;
+    protected internal async Task<IEncodedContent> FlushAsync()
+    {
+        if (_executionScope is not { } executionScope)
+            throw new InvalidOperationException("The template is not executing.");
+
+        await executionScope.FlushAsync().ConfigureAwait(false);
+        return HtmlString.Empty;
+    }
 
     /// <summary>
     /// Executes the template and appends the result to <see cref="Output"/>.