Re-design TagHelperOutput and runtime dependencies to allow all content modes.

- Added PreContent, PostContent and ContentSet properties to TagHelperOutput.
- Added GeneratePreContent, GeneratePostContent and SupressOutput methods to TagHelperOutput.
- Added multile ExecuteChildContentAsync and GetChildContentAsync to the rendering phase, ultimately only exposing GetChildContentAsync to a TagHelper author.
- Added more knowledge of StartWritingScope and EndWritingScope to the TagHelper runtime components. This is to enable the runtime components to utilize the RazorPage's infrastructure to render a delegate to a writer and retrieve its value to ultimately expose it to the user.

#221

Author: N. Taylor Mullen

src/Microsoft.AspNet.Razor.Runtime/TagHelpers/TagHelperContext.cs

@@ -1,7 +1,9 @@
 // Copyright (c) Microsoft Open Technologies, Inc. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
+using System;
 using System.Collections.Generic;
+using System.Threading.Tasks;
 
 namespace Microsoft.AspNet.Razor.Runtime.TagHelpers
 {
@@ -14,14 +16,26 @@ public class TagHelperContext
         /// Instantiates a new <see cref="TagHelperContext"/>.
         /// </summary>
         /// <param name="allAttributes">Every attribute associated with the current HTML element.</param>
-        public TagHelperContext([NotNull] IDictionary<string, object> allAttributes)
+        /// <param name="getChildContentAsync">A delegate used to execute and retrieve the rendered child content 
+        /// asynchronously.</param>
+        public TagHelperContext([NotNull] IDictionary<string, object> allAttributes,
+                                [NotNull] Func<Task<string>> getChildContentAsync)
         {
             AllAttributes = allAttributes;
+            GetChildContentAsync = getChildContentAsync;
         }
 
         /// <summary>
         /// Every attribute associated with the current HTML element.
         /// </summary>
-        public IDictionary<string, object> AllAttributes { get; private set; }
+        public IDictionary<string, object> AllAttributes { get; }
+
+        /// <summary>
+        /// A delegate used to execute and retrieve the rendered child content asynchronously.
+        /// </summary>
+        /// <remarks>
+        /// Child content is only executed once. Successive calls to this delegate return a cached result.
+        /// </remarks>
+        public Func<Task<string>> GetChildContentAsync { get; }
     }
 }

src/Microsoft.AspNet.Razor.Runtime/TagHelpers/TagHelperExecutionContext.cs

@@ -3,6 +3,8 @@
 
 using System;
 using System.Collections.Generic;
+using System.IO;
+using System.Threading.Tasks;
 
 namespace Microsoft.AspNet.Razor.Runtime.TagHelpers
 {
@@ -12,28 +14,71 @@ namespace Microsoft.AspNet.Razor.Runtime.TagHelpers
     public class TagHelperExecutionContext
     {
         private readonly List<ITagHelper> _tagHelpers;
+        private string _childContent;
 
         /// <summary>
         /// Instantiates a new <see cref="TagHelperExecutionContext"/>.
         /// </summary>
         /// <param name="tagName">The HTML tag name in the Razor source.</param>
-        public TagHelperExecutionContext([NotNull] string tagName)
+        /// <param name="executeChildContentAsync">A delegate used to execute the child content asynchronously.</param>
+        /// <param name="startWritingScope">A delegate used to start a writing scope in a Razor page.</param>
+        /// <param name="endWritingScope">A delegate used to end a writing scope in a Razor page.</param>
+        public TagHelperExecutionContext([NotNull] string tagName,
+                                         [NotNull] Func<Task> executeChildContentAsync,
+                                         [NotNull] Action startWritingScope,
+                                         [NotNull] Func<TextWriter> endWritingScope)
         {
+            ExecuteChildContentAsync = executeChildContentAsync;
+            GetChildContentAsync = async () =>
+            {
+                if (_childContent == null)
+                {
+                    startWritingScope();
+                    await executeChildContentAsync();
+                    _childContent = endWritingScope().ToString();
+                }
+
+                return _childContent;
+            };
             AllAttributes = new Dictionary<string, object>(StringComparer.OrdinalIgnoreCase);
             HTMLAttributes = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
             _tagHelpers = new List<ITagHelper>();
             TagName = tagName;
         }
 
+        /// <summary>
+        /// A delegate used to execute the child content asynchronously.
+        /// </summary>
+        public Func<Task> ExecuteChildContentAsync { get; }
+
+        /// <summary>
+        /// A delegate used to execute and retrieve the rendered child content asynchronously.
+        /// </summary>
+        /// <remarks>
+        /// Child content is only executed once. Successive calls to this delegate return a cached result.
+        /// </remarks>
+        public Func<Task<string>> GetChildContentAsync { get; }
+
+        /// <summary>
+        /// Indicates if <see cref="GetChildContentAsync"/> has been called.
+        /// </summary>
+        public bool ChildContentRetrieved
+        {
+            get
+            {
+                return _childContent != null;
+            }
+        }
+
         /// <summary>
         /// HTML attributes.
         /// </summary>
-        public IDictionary<string, string> HTMLAttributes { get; private set; }
+        public IDictionary<string, string> HTMLAttributes { get; }
 
         /// <summary>
         /// <see cref="ITagHelper"/> bound attributes and HTML attributes.
         /// </summary>
-        public IDictionary<string, object> AllAttributes { get; private set; }
+        public IDictionary<string, object> AllAttributes { get; }
 
         /// <summary>
         /// <see cref="ITagHelper"/>s that should be run.
@@ -49,7 +94,7 @@ public IEnumerable<ITagHelper> TagHelpers
         /// <summary>
         /// The HTML tag name in the Razor source.
         /// </summary>
-        public string TagName { get; private set; }
+        public string TagName { get; }
 
         /// <summary>
         /// The <see cref="ITagHelper"/>s' output.

src/Microsoft.AspNet.Razor.Runtime/TagHelpers/TagHelperOutput.cs

@@ -15,7 +15,7 @@ namespace Microsoft.AspNet.Razor.Runtime.TagHelpers
     public class TagHelperOutput
     {
         private string _content;
-        private string _tagName;
+        private bool _contentSet;
 
         // Internal for testing
         internal TagHelperOutput(string tagName)
@@ -35,33 +35,27 @@ internal TagHelperOutput(string tagName, [NotNull] IDictionary<string, string> a
         /// </summary>
         /// <param name="tagName">The HTML element's tag name.</param>
         /// <param name="attributes">The HTML attributes.</param>
-        /// <param name="content">The HTML element's content.</param>
-        public TagHelperOutput(string tagName,
-                               [NotNull] IDictionary<string, string> attributes,
-                               string content)
+        public TagHelperOutput(string tagName, [NotNull] IDictionary<string, string> attributes)
         {
             TagName = tagName;
-            Content = content;
             Attributes = new Dictionary<string, string>(attributes, StringComparer.OrdinalIgnoreCase);
+            PreContent = string.Empty;
+            _content = string.Empty;
+            PostContent = string.Empty;
         }
 
         /// <summary>
         /// The HTML element's tag name.
         /// </summary>
         /// <remarks>
-        /// A whitespace value results in no start or end tag being rendered.
+        /// A whitespace or <c>null</c> value results in no start or end tag being rendered.
         /// </remarks>
-        public string TagName
-        {
-            get
-            {
-                return _tagName;
-            }
-            set
-            {
-                _tagName = value ?? string.Empty;
-            }
-        }
+        public string TagName { get; set; }
+
+        /// <summary>
+        /// The HTML element's pre content.
+        /// </summary>
+        public string PreContent { get; set; }
 
         /// <summary>
         /// The HTML element's content.
@@ -74,10 +68,21 @@ public string Content
             }
             set
             {
-                _content = value ?? string.Empty;
+                _contentSet = true;
+                _content = value;
             }
         }
 
+        /// <summary>
+        /// The HTML element's post content.
+        /// </summary>
+        public string PostContent { get; set; }
+
+        /// <summary>
+        /// <c>true</c> if <see cref="Content"/> has been set, <c>false</c> otherwise.
+        /// </summary>
+        public bool ContentSet { get { return _contentSet; } }
+
         /// <summary>
         /// Indicates whether or not the tag is self closing.
         /// </summary>
@@ -86,7 +91,7 @@ public string Content
         /// <summary>
         /// The HTML element's attributes.
         /// </summary>
-        public IDictionary<string, string> Attributes { get; private set; }
+        public IDictionary<string, string> Attributes { get; }
 
         /// <summary>
         /// Generates the <see cref="TagHelperOutput"/>'s start tag.
@@ -126,6 +131,21 @@ public string GenerateStartTag()
             return sb.ToString();
         }
 
+        /// <summary>
+        /// Generates the <see cref="TagHelperOutput"/>'s <see cref="PreContent"/>.
+        /// </summary>
+        /// <returns><c>string.Empty</c> if <see cref="SelfClosing"/> is <c>true</c>. <see cref="PreContent"/> otherwise.
+        /// </returns>
+        public string GeneratePreContent()
+        {
+            if (SelfClosing)
+            {
+                return string.Empty;
+            }
+
+            return PreContent;
+        }
+
         /// <summary>
         /// Generates the <see cref="TagHelperOutput"/>'s body.
         /// </summary>
@@ -141,6 +161,21 @@ public string GenerateContent()
             return Content;
         }
 
+        /// <summary>
+        /// Generates the <see cref="TagHelperOutput"/>'s <see cref="PostContent"/>.
+        /// </summary>
+        /// <returns><c>string.Empty</c> if <see cref="SelfClosing"/> is <c>true</c>. <see cref="PostContent"/> otherwise.
+        /// </returns>
+        public string GeneratePostContent()
+        {
+            if (SelfClosing)
+            {
+                return string.Empty;
+            }
+
+            return PostContent;
+        }
+
         /// <summary>
         /// Generates the <see cref="TagHelperOutput"/>'s end tag.
         /// </summary>
@@ -155,5 +190,20 @@ public string GenerateEndTag()
 
             return string.Format(CultureInfo.InvariantCulture, "</{0}>", TagName);
         }
+
+        /// <summary>
+        /// Changes the output of the <see cref="TagHelperOutput"/> to generate nothing.
+        /// </summary>
+        /// <remarks>
+        /// Sets <see cref="TagName"/>, <see cref="PreContent"/>, <see cref="Content"/> and <see cref="PostContent"/> 
+        /// to <c>null</c> to supress output.
+        /// </remarks>
+        public void SupressOutput()
+        {
+            TagName = null;
+            PreContent = null;
+            Content = null;
+            PostContent = null;
+        }
     }
 }

src/Microsoft.AspNet.Razor.Runtime/TagHelpers/TagHelperRunner.cs

@@ -19,28 +19,13 @@ public class TagHelperRunner
         /// <paramref name="context"/>'s <see cref="ITagHelper"/>s.</returns>
         public async Task<TagHelperOutput> RunAsync([NotNull] TagHelperExecutionContext context)
         {
-            return await RunAsyncCore(context, string.Empty);
+            return await RunAsyncCore(context);
         }
 
-        /// <summary>
-        /// Calls the <see cref="ITagHelper.ProcessAsync"/> method on <see cref="ITagHelper"/>s.
-        /// </summary>
-        /// <param name="context">Contains information associated with running <see cref="ITagHelper"/>s.</param>
-        /// <param name="bufferedBody">Contains the buffered content of the current HTML tag.</param>
-        /// <returns>Resulting <see cref="TagHelperOutput"/> from processing all of the
-        /// <paramref name="context"/>'s <see cref="ITagHelper"/>s.</returns>
-        public async Task<TagHelperOutput> RunAsync([NotNull] TagHelperExecutionContext context,
-                                                    [NotNull] TextWriter bufferedBody)
-        {
-            return await RunAsyncCore(context, bufferedBody.ToString());
-        }
-
-        private async Task<TagHelperOutput> RunAsyncCore(TagHelperExecutionContext executionContext, string outputContent)
+        private async Task<TagHelperOutput> RunAsyncCore(TagHelperExecutionContext executionContext)
         {
-            var tagHelperContext = new TagHelperContext(executionContext.AllAttributes);
-            var tagHelperOutput = new TagHelperOutput(executionContext.TagName,
-                                                      executionContext.HTMLAttributes,
-                                                      outputContent);
+            var tagHelperContext = new TagHelperContext(executionContext.AllAttributes, executionContext.GetChildContentAsync);
+            var tagHelperOutput = new TagHelperOutput(executionContext.TagName, executionContext.HTMLAttributes);
 
             foreach (var tagHelper in executionContext.TagHelpers)
             {

src/Microsoft.AspNet.Razor.Runtime/TagHelpers/TagHelperScopeManager.cs

@@ -3,6 +3,8 @@
 
 using System;
 using System.Collections.Generic;
+using System.IO;
+using System.Threading.Tasks;
 
 namespace Microsoft.AspNet.Razor.Runtime.TagHelpers
 {
@@ -25,10 +27,17 @@ public TagHelperScopeManager()
         /// Starts a <see cref="TagHelperExecutionContext"/> scope.
         /// </summary>
         /// <param name="tagName">The HTML tag name that the scope is associated with.</param>
+        /// <param name="executeChildContentAsync">A delegate used to execute the child content asynchronously.</param>
+        /// <param name="startWritingScope">A delegate used to start a writing scope in a Razor page.</param>
+        /// <param name="endWritingScope">A delegate used to end a writing scope in a Razor page.</param>
         /// <returns>A <see cref="TagHelperExecutionContext"/> to use.</returns>
-        public TagHelperExecutionContext Begin(string tagName)
+        public TagHelperExecutionContext Begin([NotNull] string tagName,
+                                               [NotNull] Func<Task> executeChildContentAsync,
+                                               [NotNull] Action startWritingScope,
+                                               [NotNull] Func<TextWriter> endWritingScope)
         {
-            var executionContext = new TagHelperExecutionContext(tagName);
+            var executionContext = 
+                new TagHelperExecutionContext(tagName, executeChildContentAsync, startWritingScope, endWritingScope);
 
             _executionScopes.Push(executionContext);