Remove the HtmlAbstractions git submodule and merge Html.Abstractions into this repo

.gitmodules

@@ -42,10 +42,6 @@
 	path = modules/Hosting
 	url = https://github.com/aspnet/Hosting.git
 	branch = release/2.1
-[submodule "modules/HtmlAbstractions"]
-	path = modules/HtmlAbstractions
-	url = https://github.com/aspnet/HtmlAbstractions.git
-	branch = release/2.1
 [submodule "modules/HttpAbstractions"]
 	path = modules/HttpAbstractions
 	url = https://github.com/aspnet/HttpAbstractions.git

build/artifacts.props

@@ -192,7 +192,6 @@
     <PackageArtifact Include="Microsoft.Extensions.Identity.Stores" AllMetapackage="true" AppMetapackage="true" Category="ship" />
     <PackageArtifact Include="Microsoft.Extensions.Localization.Abstractions" AllMetapackage="true" AppMetapackage="true" Category="ship" />
     <PackageArtifact Include="Microsoft.Extensions.Localization" AllMetapackage="true" AppMetapackage="true" Category="ship" />
-    <PackageArtifact Include="Microsoft.Extensions.WebEncoders" AllMetapackage="true" AppMetapackage="true" Category="ship" />
     <PackageArtifact Include="Microsoft.Net.Http.Headers" AllMetapackage="true" AppMetapackage="true" Category="ship" />
     <PackageArtifact Include="Microsoft.NET.Sdk.Razor" Category="ship" />
     <PackageArtifact Include="Microsoft.Owin.Security.Interop" Category="ship" />

build/buildorder.props

@@ -8,7 +8,6 @@
 
   <ItemGroup>
     <RepositoryBuildOrder Include="DotNetTools" Order="1" />
-    <RepositoryBuildOrder Include="HtmlAbstractions" Order="1" />
     <RepositoryBuildOrder Include="Razor" Order="6" />
     <RepositoryBuildOrder Include="HttpAbstractions" Order="6" />
     <RepositoryBuildOrder Include="HttpClientFactory" Order="6" />

build/dependencies.props

@@ -21,16 +21,16 @@
   <!-- These are package versions that should not be overridden or updated by automation. -->
   <PropertyGroup Label="Package Versions: Pinned">
     <!-- Packages that came from aspnet/Extensions. -->
-    <MicrosoftAspNetCoreBenchmarkRunnerSourcesPackageVersion>2.1.6</MicrosoftAspNetCoreBenchmarkRunnerSourcesPackageVersion>
+    <MicrosoftAspNetCoreBenchmarkRunnerSourcesPackageVersion>2.1.1</MicrosoftAspNetCoreBenchmarkRunnerSourcesPackageVersion>
-    <MicrosoftAspNetCoreCertificatesGenerationSourcesPackageVersion>2.1.6</MicrosoftAspNetCoreCertificatesGenerationSourcesPackageVersion>
+    <MicrosoftAspNetCoreCertificatesGenerationSourcesPackageVersion>2.1.1</MicrosoftAspNetCoreCertificatesGenerationSourcesPackageVersion>
     <MicrosoftAspNetCoreTestingPackageVersion>2.1.0</MicrosoftAspNetCoreTestingPackageVersion>
     <MicrosoftExtensionsActivatorUtilitiesSourcesPackageVersion>2.1.1</MicrosoftExtensionsActivatorUtilitiesSourcesPackageVersion>
     <MicrosoftExtensionsCachingAbstractionsPackageVersion>2.1.2</MicrosoftExtensionsCachingAbstractionsPackageVersion>
     <MicrosoftExtensionsCachingMemoryPackageVersion>2.1.2</MicrosoftExtensionsCachingMemoryPackageVersion>
     <MicrosoftExtensionsCachingRedisPackageVersion>2.1.2</MicrosoftExtensionsCachingRedisPackageVersion>
     <MicrosoftExtensionsCachingSqlServerPackageVersion>2.1.2</MicrosoftExtensionsCachingSqlServerPackageVersion>
-    <MicrosoftExtensionsClosedGenericMatcherSourcesPackageVersion>2.1.6</MicrosoftExtensionsClosedGenericMatcherSourcesPackageVersion>
+    <MicrosoftExtensionsClosedGenericMatcherSourcesPackageVersion>2.1.1</MicrosoftExtensionsClosedGenericMatcherSourcesPackageVersion>
-    <MicrosoftExtensionsCommandLineUtilsSourcesPackageVersion>2.1.6</MicrosoftExtensionsCommandLineUtilsSourcesPackageVersion>
+    <MicrosoftExtensionsCommandLineUtilsSourcesPackageVersion>2.1.1</MicrosoftExtensionsCommandLineUtilsSourcesPackageVersion>
     <MicrosoftExtensionsConfigurationAbstractionsPackageVersion>2.1.1</MicrosoftExtensionsConfigurationAbstractionsPackageVersion>
     <MicrosoftExtensionsConfigurationAzureKeyVaultPackageVersion>2.1.1</MicrosoftExtensionsConfigurationAzureKeyVaultPackageVersion>
     <MicrosoftExtensionsConfigurationBinderPackageVersion>2.1.1</MicrosoftExtensionsConfigurationBinderPackageVersion>
@@ -43,7 +43,7 @@
     <MicrosoftExtensionsConfigurationUserSecretsPackageVersion>2.1.1</MicrosoftExtensionsConfigurationUserSecretsPackageVersion>
     <MicrosoftExtensionsConfigurationXmlPackageVersion>2.1.1</MicrosoftExtensionsConfigurationXmlPackageVersion>
     <MicrosoftExtensionsConfigurationPackageVersion>2.1.1</MicrosoftExtensionsConfigurationPackageVersion>
-    <MicrosoftExtensionsCopyOnWriteDictionarySourcesPackageVersion>2.1.6</MicrosoftExtensionsCopyOnWriteDictionarySourcesPackageVersion>
+    <MicrosoftExtensionsCopyOnWriteDictionarySourcesPackageVersion>2.1.1</MicrosoftExtensionsCopyOnWriteDictionarySourcesPackageVersion>
     <MicrosoftExtensionsDependencyInjectionAbstractionsPackageVersion>2.1.1</MicrosoftExtensionsDependencyInjectionAbstractionsPackageVersion>
     <MicrosoftExtensionsDependencyInjectionSpecificationTestsPackageVersion>2.1.1</MicrosoftExtensionsDependencyInjectionSpecificationTestsPackageVersion>
     <MicrosoftExtensionsDependencyInjectionPackageVersion>2.1.1</MicrosoftExtensionsDependencyInjectionPackageVersion>
@@ -53,7 +53,7 @@
     <MicrosoftExtensionsFileProvidersEmbeddedPackageVersion>2.1.1</MicrosoftExtensionsFileProvidersEmbeddedPackageVersion>
     <MicrosoftExtensionsFileProvidersPhysicalPackageVersion>2.1.1</MicrosoftExtensionsFileProvidersPhysicalPackageVersion>
     <MicrosoftExtensionsFileSystemGlobbingPackageVersion>2.1.1</MicrosoftExtensionsFileSystemGlobbingPackageVersion>
-    <MicrosoftExtensionsHashCodeCombinerSourcesPackageVersion>2.1.6</MicrosoftExtensionsHashCodeCombinerSourcesPackageVersion>
+    <MicrosoftExtensionsHashCodeCombinerSourcesPackageVersion>2.1.1</MicrosoftExtensionsHashCodeCombinerSourcesPackageVersion>
     <MicrosoftExtensionsLoggingAbstractionsPackageVersion>2.1.1</MicrosoftExtensionsLoggingAbstractionsPackageVersion>
     <MicrosoftExtensionsLoggingAzureAppServicesPackageVersion>2.1.1</MicrosoftExtensionsLoggingAzureAppServicesPackageVersion>
     <MicrosoftExtensionsLoggingConfigurationPackageVersion>2.1.1</MicrosoftExtensionsLoggingConfigurationPackageVersion>
@@ -64,21 +64,22 @@
     <MicrosoftExtensionsLoggingTestingPackageVersion>2.1.1</MicrosoftExtensionsLoggingTestingPackageVersion>
     <MicrosoftExtensionsLoggingTraceSourcePackageVersion>2.1.1</MicrosoftExtensionsLoggingTraceSourcePackageVersion>
     <MicrosoftExtensionsLoggingPackageVersion>2.1.1</MicrosoftExtensionsLoggingPackageVersion>
-    <MicrosoftExtensionsObjectMethodExecutorSourcesPackageVersion>2.1.6</MicrosoftExtensionsObjectMethodExecutorSourcesPackageVersion>
+    <MicrosoftExtensionsObjectMethodExecutorSourcesPackageVersion>2.1.1</MicrosoftExtensionsObjectMethodExecutorSourcesPackageVersion>
     <MicrosoftExtensionsObjectPoolPackageVersion>2.1.6</MicrosoftExtensionsObjectPoolPackageVersion>
     <MicrosoftExtensionsOptionsConfigurationExtensionsPackageVersion>2.1.1</MicrosoftExtensionsOptionsConfigurationExtensionsPackageVersion>
     <MicrosoftExtensionsOptionsPackageVersion>2.1.1</MicrosoftExtensionsOptionsPackageVersion>
     <MicrosoftExtensionsParameterDefaultValueSourcesPackageVersion>2.1.1</MicrosoftExtensionsParameterDefaultValueSourcesPackageVersion>
     <MicrosoftExtensionsPrimitivesPackageVersion>2.1.6</MicrosoftExtensionsPrimitivesPackageVersion>
-    <MicrosoftExtensionsProcessSourcesPackageVersion>2.1.6</MicrosoftExtensionsProcessSourcesPackageVersion>
+    <MicrosoftExtensionsProcessSourcesPackageVersion>2.1.1</MicrosoftExtensionsProcessSourcesPackageVersion>
-    <MicrosoftExtensionsPropertyActivatorSourcesPackageVersion>2.1.6</MicrosoftExtensionsPropertyActivatorSourcesPackageVersion>
+    <MicrosoftExtensionsPropertyActivatorSourcesPackageVersion>2.1.1</MicrosoftExtensionsPropertyActivatorSourcesPackageVersion>
-    <MicrosoftExtensionsPropertyHelperSourcesPackageVersion>2.1.6</MicrosoftExtensionsPropertyHelperSourcesPackageVersion>
+    <MicrosoftExtensionsPropertyHelperSourcesPackageVersion>2.1.1</MicrosoftExtensionsPropertyHelperSourcesPackageVersion>
-    <MicrosoftExtensionsRazorViewsSourcesPackageVersion>2.1.6</MicrosoftExtensionsRazorViewsSourcesPackageVersion>
+    <MicrosoftExtensionsRazorViewsSourcesPackageVersion>2.1.1</MicrosoftExtensionsRazorViewsSourcesPackageVersion>
-    <MicrosoftExtensionsSecurityHelperSourcesPackageVersion>2.1.6</MicrosoftExtensionsSecurityHelperSourcesPackageVersion>
+    <MicrosoftExtensionsSecurityHelperSourcesPackageVersion>2.1.1</MicrosoftExtensionsSecurityHelperSourcesPackageVersion>
-    <MicrosoftExtensionsStackTraceSourcesPackageVersion>2.1.6</MicrosoftExtensionsStackTraceSourcesPackageVersion>
+    <MicrosoftExtensionsStackTraceSourcesPackageVersion>2.1.1</MicrosoftExtensionsStackTraceSourcesPackageVersion>
-    <MicrosoftExtensionsTypeNameHelperSourcesPackageVersion>2.1.6</MicrosoftExtensionsTypeNameHelperSourcesPackageVersion>
+    <MicrosoftExtensionsTypeNameHelperSourcesPackageVersion>2.1.1</MicrosoftExtensionsTypeNameHelperSourcesPackageVersion>
-    <MicrosoftExtensionsValueStopwatchSourcesPackageVersion>2.1.6</MicrosoftExtensionsValueStopwatchSourcesPackageVersion>
+    <MicrosoftExtensionsValueStopwatchSourcesPackageVersion>2.1.1</MicrosoftExtensionsValueStopwatchSourcesPackageVersion>
-    <MicrosoftExtensionsWebEncodersSourcesPackageVersion>2.1.6</MicrosoftExtensionsWebEncodersSourcesPackageVersion>
+    <MicrosoftExtensionsWebEncodersSourcesPackageVersion>2.1.1</MicrosoftExtensionsWebEncodersSourcesPackageVersion>
+    <MicrosoftExtensionsWebEncodersPackageVersion>2.1.1</MicrosoftExtensionsWebEncodersPackageVersion>
 
     <!-- External and partner dependencies -->
     <AngleSharpPackageVersion>0.9.9</AngleSharpPackageVersion>

build/external-dependencies.props

@@ -83,6 +83,7 @@
     <ExtensionsDependency Include="Microsoft.Extensions.TypeNameHelper.Sources" Version="$(MicrosoftExtensionsTypeNameHelperSourcesPackageVersion)" />
     <ExtensionsDependency Include="Microsoft.Extensions.ValueStopwatch.Sources" Version="$(MicrosoftExtensionsValueStopwatchSourcesPackageVersion)" />
     <ExtensionsDependency Include="Microsoft.Extensions.WebEncoders.Sources" Version="$(MicrosoftExtensionsWebEncodersSourcesPackageVersion)" />
+    <ExtensionsDependency Include="Microsoft.Extensions.WebEncoders" Version="$(MicrosoftExtensionsWebEncodersPackageVersion)" AllMetapackage="true" AppMetapackage="true" />
   </ItemGroup>
 
    <ItemGroup>

build/repo.props

@@ -46,6 +46,7 @@
 
     <ProjectToBuild Include="
                       $(RepositoryRoot)src\Features\JsonPatch\**\*.*proj;
+                      $(RepositoryRoot)src\Html\**\*.*proj;
                       $(RepositoryRoot)src\Middleware\**\*.*proj;
                       "
                     Exclude="@(ProjectToExclude)" />

build/submodules.props

@@ -59,7 +59,6 @@
     <ShippedRepository Include="DotNetTools" />
     <ShippedRepository Include="EntityFrameworkCore" />
     <ShippedRepository Include="Hosting" />
-    <ShippedRepository Include="HtmlAbstractions" />
     <ShippedRepository Include="HttpAbstractions" />
     <ShippedRepository Include="HttpClientFactory" />
     <ShippedRepository Include="HttpSysServer" />

eng/Baseline.props

@@ -80,6 +80,13 @@
     <BaselinePackageReference Include="Microsoft.AspNetCore.DataProtection" Version="[2.1.1, )" />
     <BaselinePackageReference Include="Microsoft.Extensions.DependencyInjection" Version="[2.1.1, )" />
   </ItemGroup>
+  <!-- Package: Microsoft.AspNetCore.Html.Abstractions-->
+  <PropertyGroup Condition=" '$(PackageId)' == 'Microsoft.AspNetCore.Html.Abstractions' ">
+    <BaselinePackageVersion>2.1.1</BaselinePackageVersion>
+  </PropertyGroup>
+  <ItemGroup Condition=" '$(PackageId)' == 'Microsoft.AspNetCore.Html.Abstractions' AND '$(TargetFramework)' == 'netstandard2.0' ">
+    <BaselinePackageReference Include="System.Text.Encodings.Web" Version="[4.5.0, )" />
+  </ItemGroup>
   <!-- Package: Microsoft.AspNetCore.JsonPatch-->
   <PropertyGroup Condition=" '$(PackageId)' == 'Microsoft.AspNetCore.JsonPatch' ">
     <BaselinePackageVersion>2.1.1</BaselinePackageVersion>

eng/Dependencies.props

@@ -13,9 +13,11 @@
     <LatestPackageReference Include="Microsoft.Extensions.Configuration.CommandLine" Version="$(MicrosoftExtensionsConfigurationCommandLinePackageVersion)" />
     <LatestPackageReference Include="Microsoft.Extensions.Options" Version="$(MicrosoftExtensionsOptionsPackageVersion)" />
     <LatestPackageReference Include="Microsoft.Extensions.Logging" Version="$(MicrosoftExtensionsLoggingPackageVersion)" />
+    <LatestPackageReference Include="Microsoft.Extensions.WebEncoders" Version="$(MicrosoftExtensionsWebEncodersPackageVersion)" />
     <LatestPackageReference Include="Microsoft.Extensions.Logging.Console" Version="$(MicrosoftExtensionsLoggingConsolePackageVersion)" />
     <LatestPackageReference Include="Microsoft.Extensions.Logging.Testing" Version="$(MicrosoftExtensionsLoggingTestingPackageVersion)" />
     <LatestPackageReference Include="System.Net.WebSockets.WebSocketProtocol" Version="$(SystemNetWebSocketsWebSocketProtocolPackageVersion)" />
+    <LatestPackageReference Include="System.Text.Encodings.Web" Version="$(SystemTextEncodingsWebPackageVersion)" />
   </ItemGroup>
 
   <ItemGroup Label="External dependencies">

eng/ProjectReferences.props

@@ -2,6 +2,7 @@
 <Project>
   <ItemGroup>
     <ProjectReferenceProvider Include="Microsoft.AspNetCore.JsonPatch" ProjectPath="$(RepositoryRoot)src\Features\JsonPatch\src\Microsoft.AspNetCore.JsonPatch.csproj" />
+    <ProjectReferenceProvider Include="Microsoft.AspNetCore.Html.Abstractions" ProjectPath="$(RepositoryRoot)src\Html\Abstractions\src\Microsoft.AspNetCore.Html.Abstractions.csproj" />
     <ProjectReferenceProvider Include="Microsoft.AspNetCore.WebSockets" ProjectPath="$(RepositoryRoot)src\Middleware\WebSockets\src\Microsoft.AspNetCore.WebSockets.csproj" />
   </ItemGroup>
 </Project>

eng/tools/BaselineGenerator/baseline.xml

@@ -8,6 +8,7 @@
   <Package Id="Microsoft.AspNetCore.DataProtection.Extensions" Version="2.1.1" />
   <Package Id="Microsoft.AspNetCore.DataProtection.Redis" Version="0.4.1" />
   <Package Id="Microsoft.AspNetCore.DataProtection.SystemWeb" Version="2.1.1" />
+  <Package Id="Microsoft.AspNetCore.Html.Abstractions" Version="2.1.1" />
   <Package Id="Microsoft.AspNetCore.JsonPatch" Version="2.1.1" />
   <Package Id="Microsoft.AspNetCore.WebSockets" Version="2.1.1" />
 </Baseline>

modules/HtmlAbstractions

@@ -1 +0,0 @@
-Subproject commit 252ae0c434d93f5bfaf949c35edb9ef59730d0a3

src/Html/Abstractions/src/HtmlContentBuilder.cs

@@ -0,0 +1,207 @@
+// Copyright (c) .NET Foundation. 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.IO;
+using System.Text.Encodings.Web;
+
+namespace Microsoft.AspNetCore.Html
+{
+    /// <summary>
+    /// An <see cref="IHtmlContentBuilder"/> implementation using an in memory list.
+    /// </summary>
+    public class HtmlContentBuilder : IHtmlContentBuilder
+    {
+        /// <summary>
+        /// Creates a new <see cref="HtmlContentBuilder"/>.
+        /// </summary>
+        public HtmlContentBuilder()
+            : this(new List<object>())
+        {
+        }
+
+        /// <summary>
+        /// Creates a new <see cref="HtmlContentBuilder"/> with the given initial capacity.
+        /// </summary>
+        /// <param name="capacity">The initial capacity of the backing store.</param>
+        public HtmlContentBuilder(int capacity)
+            : this(new List<object>(capacity))
+        {
+        }
+
+        /// <summary>
+        /// Gets the number of elements in the <see cref="HtmlContentBuilder"/>.
+        /// </summary>
+        public int Count => Entries.Count;
+
+        /// <summary>
+        /// Creates a new <see cref="HtmlContentBuilder"/> with the given list of entries.
+        /// </summary>
+        /// <param name="entries">
+        /// The list of entries. The <see cref="HtmlContentBuilder"/> will use this list without making a copy.
+        /// </param>
+        public HtmlContentBuilder(IList<object> entries)
+        {
+            if (entries == null)
+            {
+                throw new ArgumentNullException(nameof(entries));
+            }
+
+            Entries = entries;
+        }
+
+        // This is not List<IHtmlContent> because that would lead to wrapping all strings to IHtmlContent
+        // which is not space performant.
+        //
+        // In general unencoded strings are added here. We're optimizing for that case, and allocating
+        // a wrapper when encoded strings are used.
+        //
+        // internal for testing.
+        internal IList<object> Entries { get; }
+
+        /// <inheritdoc />
+        public IHtmlContentBuilder Append(string unencoded)
+        {
+            if (!string.IsNullOrEmpty(unencoded))
+            {
+                Entries.Add(unencoded);
+            }
+
+            return this;
+        }
+
+        /// <inheritdoc />
+        public IHtmlContentBuilder AppendHtml(IHtmlContent htmlContent)
+        {
+            if (htmlContent == null)
+            {
+                return this;
+            }
+
+            Entries.Add(htmlContent);
+            return this;
+        }
+
+        /// <inheritdoc />
+        public IHtmlContentBuilder AppendHtml(string encoded)
+        {
+            if (!string.IsNullOrEmpty(encoded))
+            {
+                Entries.Add(new HtmlString(encoded));
+            }
+
+            return this;
+        }
+
+        /// <inheritdoc />
+        public IHtmlContentBuilder Clear()
+        {
+            Entries.Clear();
+            return this;
+        }
+
+        /// <inheritdoc />
+        public void CopyTo(IHtmlContentBuilder destination)
+        {
+            if (destination == null)
+            {
+                throw new ArgumentNullException(nameof(destination));
+            }
+
+            for (var i = 0; i < Entries.Count; i++)
+            {
+                var entry = Entries[i];
+
+                string entryAsString;
+                IHtmlContentContainer entryAsContainer;
+                if ((entryAsString = entry as string)  != null)
+                {
+                    destination.Append(entryAsString);
+                }
+                else if ((entryAsContainer = entry as IHtmlContentContainer) != null)
+                {
+                    // Since we're copying, do a deep flatten.
+                    entryAsContainer.CopyTo(destination);
+                }
+                else
+                {
+                    // Only string, IHtmlContent values can be added to the buffer.
+                    destination.AppendHtml((IHtmlContent)entry);
+                }
+            }
+        }
+
+        /// <inheritdoc />
+        public void MoveTo(IHtmlContentBuilder destination)
+        {
+            if (destination == null)
+            {
+                throw new ArgumentNullException(nameof(destination));
+            }
+
+            for (var i = 0; i < Entries.Count; i++)
+            {
+                var entry = Entries[i];
+
+                string entryAsString;
+                IHtmlContentContainer entryAsContainer;
+                if ((entryAsString = entry as string) != null)
+                {
+                    destination.Append(entryAsString);
+                }
+                else if ((entryAsContainer = entry as IHtmlContentContainer) != null)
+                {
+                    // Since we're moving, do a deep flatten.
+                    entryAsContainer.MoveTo(destination);
+                }
+                else
+                {
+                    // Only string, IHtmlContent values can be added to the buffer.
+                    destination.AppendHtml((IHtmlContent)entry);
+                }
+            }
+
+            Entries.Clear();
+        }
+
+        /// <inheritdoc />
+        public void WriteTo(TextWriter writer, HtmlEncoder encoder)
+        {
+            if (writer == null)
+            {
+                throw new ArgumentNullException(nameof(writer));
+            }
+
+            if (encoder == null)
+            {
+                throw new ArgumentNullException(nameof(encoder));
+            }
+
+            for (var i = 0; i < Entries.Count; i++)
+            {
+                var entry = Entries[i];
+
+                var entryAsString = entry as string;
+                if (entryAsString != null)
+                {
+                    encoder.Encode(writer, entryAsString);
+                }
+                else
+                {
+                    // Only string, IHtmlContent values can be added to the buffer.
+                    ((IHtmlContent)entry).WriteTo(writer, encoder);
+                }
+            }
+        }
+
+        private string DebuggerToString()
+        {
+            using (var writer = new StringWriter())
+            {
+                WriteTo(writer, HtmlEncoder.Default);
+                return writer.ToString();
+            }
+        }
+    }
+}

src/Html/Abstractions/src/HtmlContentBuilderExtensions.cs

@@ -0,0 +1,223 @@
+// Copyright (c) .NET Foundation. 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.Diagnostics;
+using System.Globalization;
+using System.IO;
+using System.Text.Encodings.Web;
+
+namespace Microsoft.AspNetCore.Html
+{
+    /// <summary>
+    /// Extension methods for <see cref="IHtmlContentBuilder"/>.
+    /// </summary>
+    public static class HtmlContentBuilderExtensions
+    {
+        /// <summary>
+        /// Appends the specified <paramref name="format"/> to the existing content after replacing each format
+        /// item with the HTML encoded <see cref="string"/> representation of the corresponding item in the
+        /// <paramref name="args"/> array.
+        /// </summary>
+        /// <param name="builder">The <see cref="IHtmlContentBuilder"/>.</param>
+        /// <param name="format">
+        /// The composite format <see cref="string"/> (see http://msdn.microsoft.com/en-us/library/txafckwd.aspx).
+        /// The format string is assumed to be HTML encoded as-provided, and no further encoding will be performed.
+        /// </param>
+        /// <param name="args">
+        /// The object array to format. Each element in the array will be formatted and then HTML encoded.
+        /// </param>
+        /// <returns>A reference to this instance after the append operation has completed.</returns>
+        public static IHtmlContentBuilder AppendFormat(
+            this IHtmlContentBuilder builder,
+            string format,
+            params object[] args)
+        {
+            if (builder == null)
+            {
+                throw new ArgumentNullException(nameof(builder));
+            }
+
+            if (format == null)
+            {
+                throw new ArgumentNullException(nameof(format));
+            }
+
+            if (args == null)
+            {
+                throw new ArgumentNullException(nameof(args));
+            }
+
+            builder.AppendHtml(new HtmlFormattableString(format, args));
+            return builder;
+        }
+
+        /// <summary>
+        /// Appends the specified <paramref name="format"/> to the existing content with information from the
+        /// <paramref name="formatProvider"/> after replacing each format item with the HTML encoded
+        /// <see cref="string"/> representation of the corresponding item in the <paramref name="args"/> array.
+        /// </summary>
+        /// <param name="builder">The <see cref="IHtmlContentBuilder"/>.</param>
+        /// <param name="formatProvider">An object that supplies culture-specific formatting information.</param>
+        /// <param name="format">
+        /// The composite format <see cref="string"/> (see http://msdn.microsoft.com/en-us/library/txafckwd.aspx).
+        /// The format string is assumed to be HTML encoded as-provided, and no further encoding will be performed.
+        /// </param>
+        /// <param name="args">
+        /// The object array to format. Each element in the array will be formatted and then HTML encoded.
+        /// </param>
+        /// <returns>A reference to this instance after the append operation has completed.</returns>
+        public static IHtmlContentBuilder AppendFormat(
+            this IHtmlContentBuilder builder,
+            IFormatProvider formatProvider,
+            string format,
+            params object[] args)
+        {
+            if (builder == null)
+            {
+                throw new ArgumentNullException(nameof(builder));
+            }
+
+            if (format == null)
+            {
+                throw new ArgumentNullException(nameof(format));
+            }
+
+            if (args == null)
+            {
+                throw new ArgumentNullException(nameof(args));
+            }
+
+            builder.AppendHtml(new HtmlFormattableString(formatProvider, format, args));
+            return builder;
+        }
+
+        /// <summary>
+        /// Appends an <see cref="Environment.NewLine"/>.
+        /// </summary>
+        /// <param name="builder">The <see cref="IHtmlContentBuilder"/>.</param>
+        /// <returns>The <see cref="IHtmlContentBuilder"/>.</returns>
+        public static IHtmlContentBuilder AppendLine(this IHtmlContentBuilder builder)
+        {
+            if (builder == null)
+            {
+                throw new ArgumentNullException(nameof(builder));
+            }
+
+            builder.AppendHtml(HtmlString.NewLine);
+            return builder;
+        }
+
+        /// <summary>
+        /// Appends an <see cref="Environment.NewLine"/> after appending the <see cref="string"/> value.
+        /// The value is treated as unencoded as-provided, and will be HTML encoded before writing to output.
+        /// </summary>
+        /// <param name="builder">The <see cref="IHtmlContentBuilder"/>.</param>
+        /// <param name="unencoded">The <see cref="string"/> to append.</param>
+        /// <returns>The <see cref="IHtmlContentBuilder"/>.</returns>
+        public static IHtmlContentBuilder AppendLine(this IHtmlContentBuilder builder, string unencoded)
+        {
+            if (builder == null)
+            {
+                throw new ArgumentNullException(nameof(builder));
+            }
+
+            builder.Append(unencoded);
+            builder.AppendHtml(HtmlString.NewLine);
+            return builder;
+        }
+
+        /// <summary>
+        /// Appends an <see cref="Environment.NewLine"/> after appending the <see cref="IHtmlContent"/> value.
+        /// </summary>
+        /// <param name="builder">The <see cref="IHtmlContentBuilder"/>.</param>
+        /// <param name="content">The <see cref="IHtmlContent"/> to append.</param>
+        /// <returns>The <see cref="IHtmlContentBuilder"/>.</returns>
+        public static IHtmlContentBuilder AppendLine(this IHtmlContentBuilder builder, IHtmlContent content)
+        {
+            if (builder == null)
+            {
+                throw new ArgumentNullException(nameof(builder));
+            }
+
+            builder.AppendHtml(content);
+            builder.AppendHtml(HtmlString.NewLine);
+            return builder;
+        }
+
+        /// <summary>
+        /// Appends an <see cref="Environment.NewLine"/> after appending the <see cref="string"/> value.
+        /// The value is treated as HTML encoded as-provided, and no further encoding will be performed.
+        /// </summary>
+        /// <param name="builder">The <see cref="IHtmlContentBuilder"/>.</param>
+        /// <param name="encoded">The HTML encoded <see cref="string"/> to append.</param>
+        /// <returns>The <see cref="IHtmlContentBuilder"/>.</returns>
+        public static IHtmlContentBuilder AppendHtmlLine(this IHtmlContentBuilder builder, string encoded)
+        {
+            if (builder == null)
+            {
+                throw new ArgumentNullException(nameof(builder));
+            }
+
+            builder.AppendHtml(encoded);
+            builder.AppendHtml(HtmlString.NewLine);
+            return builder;
+        }
+
+        /// <summary>
+        /// Sets the content to the <see cref="string"/> value. The value is treated as unencoded as-provided,
+        /// and will be HTML encoded before writing to output.
+        /// </summary>
+        /// <param name="builder">The <see cref="IHtmlContentBuilder"/>.</param>
+        /// <param name="unencoded">The <see cref="string"/> value that replaces the content.</param>
+        /// <returns>The <see cref="IHtmlContentBuilder"/>.</returns>
+        public static IHtmlContentBuilder SetContent(this IHtmlContentBuilder builder, string unencoded)
+        {
+            if (builder == null)
+            {
+                throw new ArgumentNullException(nameof(builder));
+            }
+
+            builder.Clear();
+            builder.Append(unencoded);
+            return builder;
+        }
+
+        /// <summary>
+        /// Sets the content to the <see cref="IHtmlContent"/> value.
+        /// </summary>
+        /// <param name="builder">The <see cref="IHtmlContentBuilder"/>.</param>
+        /// <param name="content">The <see cref="IHtmlContent"/> value that replaces the content.</param>
+        /// <returns>The <see cref="IHtmlContentBuilder"/>.</returns>
+        public static IHtmlContentBuilder SetHtmlContent(this IHtmlContentBuilder builder, IHtmlContent content)
+        {
+            if (builder == null)
+            {
+                throw new ArgumentNullException(nameof(builder));
+            }
+
+            builder.Clear();
+            builder.AppendHtml(content);
+            return builder;
+        }
+
+        /// <summary>
+        /// Sets the content to the <see cref="string"/> value. The value is treated as HTML encoded as-provided, and
+        /// no further encoding will be performed.
+        /// </summary>
+        /// <param name="builder">The <see cref="IHtmlContentBuilder"/>.</param>
+        /// <param name="encoded">The HTML encoded <see cref="string"/> that replaces the content.</param>
+        /// <returns>The <see cref="IHtmlContentBuilder"/>.</returns>
+        public static IHtmlContentBuilder SetHtmlContent(this IHtmlContentBuilder builder, string encoded)
+        {
+            if (builder == null)
+            {
+                throw new ArgumentNullException(nameof(builder));
+            }
+
+            builder.Clear();
+            builder.AppendHtml(encoded);
+            return builder;
+        }
+    }
+}

src/Html/Abstractions/src/HtmlFormattableString.cs

@@ -0,0 +1,184 @@
+// Copyright (c) .NET Foundation. 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.Diagnostics;
+using System.Globalization;
+using System.IO;
+using System.Text.Encodings.Web;
+
+namespace Microsoft.AspNetCore.Html
+{
+    /// <summary>
+    /// An <see cref="IHtmlContent"/> implementation of composite string formatting
+    /// (see https://msdn.microsoft.com/en-us/library/txafckwd(v=vs.110).aspx) which HTML encodes
+    /// formatted arguments.
+    /// </summary>
+    [DebuggerDisplay("{DebuggerToString()}")]
+    public class HtmlFormattableString : IHtmlContent
+    {
+        private readonly IFormatProvider _formatProvider;
+        private readonly string _format;
+        private readonly object[] _args;
+
+        /// <summary>
+        /// Creates a new <see cref="HtmlFormattableString"/> with the given <paramref name="format"/> and
+        /// <paramref name="args"/>.
+        /// </summary>
+        /// <param name="format">A composite format string.</param>
+        /// <param name="args">An array that contains objects to format.</param>
+        public HtmlFormattableString(string format, params object[] args)
+            : this(formatProvider: null, format: format, args: args)
+        {
+        }
+
+        /// <summary>
+        /// Creates a new <see cref="HtmlFormattableString"/> with the given <paramref name="formatProvider"/>,
+        /// <paramref name="format"/> and <paramref name="args"/>.
+        /// </summary>
+        /// <param name="formatProvider">An object that provides culture-specific formatting information.</param>
+        /// <param name="format">A composite format string.</param>
+        /// <param name="args">An array that contains objects to format.</param>
+        public HtmlFormattableString(IFormatProvider formatProvider, string format, params object[] args)
+        {
+            if (format == null)
+            {
+                throw new ArgumentNullException(nameof(format));
+            }
+
+            if (args == null)
+            {
+                throw new ArgumentNullException(nameof(args));
+            }
+
+            _formatProvider = formatProvider ?? CultureInfo.CurrentCulture;
+            _format = format;
+            _args = args;
+        }
+
+        /// <inheritdoc />
+        public void WriteTo(TextWriter writer, HtmlEncoder encoder)
+        {
+            if (writer == null)
+            {
+                throw new ArgumentNullException(nameof(writer));
+            }
+
+            if (encoder == null)
+            {
+                throw new ArgumentNullException(nameof(encoder));
+            }
+
+            var formatProvider = new EncodingFormatProvider(_formatProvider, encoder);
+            writer.Write(string.Format(formatProvider, _format, _args));
+        }
+
+        private string DebuggerToString()
+        {
+            using (var writer = new StringWriter())
+            {
+                WriteTo(writer, HtmlEncoder.Default);
+                return writer.ToString();
+            }
+        }
+
+        // This class implements Html encoding via an ICustomFormatter. Passing an instance of this
+        // class into a string.Format method or anything similar will evaluate arguments implementing
+        // IHtmlContent without HTML encoding them, and will give other arguments the standard
+        // composite format string treatment, and then HTML encode the result.
+        //
+        // Plenty of examples of ICustomFormatter and the interactions with string.Format here:
+        // https://msdn.microsoft.com/en-us/library/system.string.format(v=vs.110).aspx#Format6_Example
+        private class EncodingFormatProvider : IFormatProvider, ICustomFormatter
+        {
+            private readonly HtmlEncoder _encoder;
+            private readonly IFormatProvider _formatProvider;
+
+            private StringWriter _writer;
+
+            public EncodingFormatProvider(IFormatProvider formatProvider, HtmlEncoder encoder)
+            {
+                Debug.Assert(formatProvider != null);
+                Debug.Assert(encoder != null);
+
+                _formatProvider = formatProvider;
+                _encoder = encoder;
+            }
+
+            public string Format(string format, object arg, IFormatProvider formatProvider)
+            {
+                // These are the cases we need to special case. We trust the HtmlString or IHtmlContent instance
+                // to do the right thing with encoding.
+                var htmlString = arg as HtmlString;
+                if (htmlString != null)
+                {
+                    return htmlString.ToString();
+                }
+
+                var htmlContent = arg as IHtmlContent;
+                if (htmlContent != null)
+                {
+                    _writer = _writer ?? new StringWriter();
+
+                    htmlContent.WriteTo(_writer, _encoder);
+
+                    var result = _writer.ToString();
+                    _writer.GetStringBuilder().Clear();
+
+                    return result;
+                }
+
+                // If we get here then 'arg' is not an IHtmlContent, and we want to handle it the way a normal
+                // string.Format would work, but then HTML encode the result.
+                //
+                // First check for an ICustomFormatter - if the IFormatProvider is a CultureInfo, then it's likely
+                // that ICustomFormatter will be null.
+                var customFormatter = (ICustomFormatter)_formatProvider.GetFormat(typeof(ICustomFormatter));
+                if (customFormatter != null)
+                {
+                    var result = customFormatter.Format(format, arg, _formatProvider);
+                    if (result != null)
+                    {
+                        return _encoder.Encode(result);
+                    }
+                }
+
+                // Next check if 'arg' is an IFormattable (DateTime is an example).
+                //
+                // An IFormattable will likely call back into the IFormatterProvider and ask for more information
+                // about how to format itself. This is the typical case when IFormatterProvider is a CultureInfo.
+                var formattable = arg as IFormattable;
+                if (formattable != null)
+                {
+                    var result = formattable.ToString(format, _formatProvider);
+                    if (result != null)
+                    {
+                        return _encoder.Encode(result);
+                    }
+                }
+
+                // If we get here then there's nothing really smart left to try.
+                if (arg != null)
+                {
+                    var result = arg.ToString();
+                    if (result != null)
+                    {
+                        return _encoder.Encode(result);
+                    }
+                }
+
+                return string.Empty;
+            }
+
+            public object GetFormat(Type formatType)
+            {
+                if (formatType == typeof(ICustomFormatter))
+                {
+                    return this;
+                }
+
+                return null;
+            }
+        }
+    }
+}

src/Html/Abstractions/src/HtmlString.cs

@@ -0,0 +1,61 @@
+// Copyright (c) .NET Foundation. 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.IO;
+using System.Text.Encodings.Web;
+
+namespace Microsoft.AspNetCore.Html
+{
+    /// <summary>
+    /// An <see cref="IHtmlContent"/> implementation that wraps an HTML encoded <see cref="string"/>.
+    /// </summary>
+    public class HtmlString : IHtmlContent
+    {
+        /// <summary>
+        /// An <see cref="HtmlString"/> instance for <see cref="Environment.NewLine"/>.
+        /// </summary>
+        public static readonly HtmlString NewLine = new HtmlString(Environment.NewLine);
+
+        /// <summary>
+        /// An <see cref="HtmlString"/> instance for <see cref="string.Empty"/>.
+        /// </summary>
+        public static readonly HtmlString Empty = new HtmlString(string.Empty);
+
+        /// <summary>
+        /// Creates a new <see cref="HtmlString"/>.
+        /// </summary>
+        /// <param name="value">The HTML encoded value.</param>
+        public HtmlString(string value)
+        {
+            Value = value;
+        }
+
+        /// <summary>
+        /// Gets the HTML encoded value.
+        /// </summary>
+        public string Value { get; }
+
+        /// <inheritdoc />
+        public void WriteTo(TextWriter writer, HtmlEncoder encoder)
+        {
+            if (writer == null)
+            {
+                throw new ArgumentNullException(nameof(writer));
+            }
+
+            if (encoder == null)
+            {
+                throw new ArgumentNullException(nameof(encoder));
+            }
+
+            writer.Write(Value);
+        }
+
+        /// <inheritdoc />
+        public override string ToString()
+        {
+            return Value ?? string.Empty;
+        }
+    }
+}

src/Html/Abstractions/src/IHtmlContent.cs

@@ -0,0 +1,22 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+
+using System.IO;
+using System.Text.Encodings.Web;
+
+namespace Microsoft.AspNetCore.Html
+{
+    /// <summary>
+    /// HTML content which can be written to a TextWriter.
+    /// </summary>
+    public interface IHtmlContent
+    {
+        /// <summary>
+        /// Writes the content by encoding it with the specified <paramref name="encoder"/>
+        /// to the specified <paramref name="writer"/>.
+        /// </summary>
+        /// <param name="writer">The <see cref="TextWriter"/> to which the content is written.</param>
+        /// <param name="encoder">The <see cref="HtmlEncoder"/> which encodes the content to be written.</param>
+        void WriteTo(TextWriter writer, HtmlEncoder encoder);
+    }
+}

src/Html/Abstractions/src/IHtmlContentBuilder.cs

@@ -0,0 +1,40 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+
+namespace Microsoft.AspNetCore.Html
+{
+    /// <summary>
+    /// A builder for HTML content.
+    /// </summary>
+    public interface IHtmlContentBuilder : IHtmlContentContainer
+    {
+        /// <summary>
+        /// Appends an <see cref="IHtmlContent"/> instance.
+        /// </summary>
+        /// <param name="content">The <see cref="IHtmlContent"/> to append.</param>
+        /// <returns>The <see cref="IHtmlContentBuilder"/>.</returns>
+        IHtmlContentBuilder AppendHtml(IHtmlContent content);
+
+        /// <summary>
+        /// Appends a <see cref="string"/> value. The value is treated as unencoded as-provided, and will be HTML
+        /// encoded before writing to output.
+        /// </summary>
+        /// <param name="unencoded">The <see cref="string"/> to append.</param>
+        /// <returns>The <see cref="IHtmlContentBuilder"/>.</returns>
+        IHtmlContentBuilder Append(string unencoded);
+
+        /// <summary>
+        /// Appends an HTML encoded <see cref="string"/> value. The value is treated as HTML encoded as-provided, and
+        /// no further encoding will be performed.
+        /// </summary>
+        /// <param name="encoded">The HTML encoded <see cref="string"/> to append.</param>
+        /// <returns>The <see cref="IHtmlContentBuilder"/>.</returns>
+        IHtmlContentBuilder AppendHtml(string encoded);
+
+        /// <summary>
+        /// Clears the content.
+        /// </summary>
+        /// <returns>The <see cref="IHtmlContentBuilder"/>.</returns>
+        IHtmlContentBuilder Clear();
+    }
+}

src/Html/Abstractions/src/IHtmlContentContainer.cs

@@ -0,0 +1,30 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+
+namespace Microsoft.AspNetCore.Html
+{
+    /// <summary>
+    /// Defines a contract for <see cref="IHtmlContent"/> instances made up of several components which
+    /// can be copied into an <see cref="IHtmlContentBuilder"/>.
+    /// </summary>
+    public interface IHtmlContentContainer : IHtmlContent
+    {
+        /// <summary>
+        /// Copies the contained content of this <see cref="IHtmlContentContainer"/> into <paramref name="builder"/>.
+        /// </summary>
+        /// <param name="builder">The <see cref="IHtmlContentBuilder"/>.</param>
+        void CopyTo(IHtmlContentBuilder builder);
+
+        /// <summary>
+        /// <para>
+        /// Moves the contained content of this <see cref="IHtmlContentContainer"/> into <paramref name="builder"/>.
+        /// </para>
+        /// <para>
+        /// After <see cref="MoveTo"/> is called, this <see cref="IHtmlContentContainer"/> instance should be left
+        /// in an empty state.
+        /// </para>
+        /// </summary>
+        /// <param name="builder">The <see cref="IHtmlContentBuilder"/>.</param>
+        void MoveTo(IHtmlContentBuilder builder);
+    }
+}

src/Html/Abstractions/src/Microsoft.AspNetCore.Html.Abstractions.csproj

@@ -0,0 +1,18 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <Description>ASP.NET Core HTML abstractions used for building HTML content.
+    
+Commonly used types:
+Microsoft.AspNetCore.Html.HtmlString
+Microsoft.AspNetCore.Html.IHtmlContent</Description>
+    <TargetFramework>netstandard2.0</TargetFramework>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <PackageTags>aspnetcore</PackageTags>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <Reference Include="System.Text.Encodings.Web" />
+  </ItemGroup>
+
+</Project>

src/Html/Abstractions/src/Properties/AssemblyInfo.cs

@@ -0,0 +1,8 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+
+using System.Reflection;
+using System.Resources;
+using System.Runtime.CompilerServices;
+
+[assembly: InternalsVisibleTo("Microsoft.AspNetCore.Html.Abstractions.Tests, PublicKey=0024000004800000940000000602000000240000525341310004000001000100f33a29044fa9d740c9b3213a93e57c84b472c84e0b8a0e1ae48e67a9f8f6de9d5f7f3d52ac23e48ac51801f1dc950abe901da34d2a9e3baadb141a17c77ef3c565dd5ee5054b91cf63bb3c6ab83f72ab3aafe93d0fc3c2348b764fafb0b1c0733de51459aeab46580384bf9d74c4e28164b7cde247f891ba07891c9d872ad2bb")]

src/Html/Abstractions/src/baseline.netcore.json

@@ -0,0 +1,626 @@
+{
+  "AssemblyIdentity": "Microsoft.AspNetCore.Html.Abstractions, Version=2.1.1.0, Culture=neutral, PublicKeyToken=adb9793829ddae60",
+  "Types": [
+    {
+      "Name": "Microsoft.AspNetCore.Html.HtmlContentBuilder",
+      "Visibility": "Public",
+      "Kind": "Class",
+      "ImplementedInterfaces": [
+        "Microsoft.AspNetCore.Html.IHtmlContentBuilder"
+      ],
+      "Members": [
+        {
+          "Kind": "Method",
+          "Name": "CopyTo",
+          "Parameters": [
+            {
+              "Name": "destination",
+              "Type": "Microsoft.AspNetCore.Html.IHtmlContentBuilder"
+            }
+          ],
+          "ReturnType": "System.Void",
+          "Sealed": true,
+          "Virtual": true,
+          "ImplementedInterface": "Microsoft.AspNetCore.Html.IHtmlContentContainer",
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Method",
+          "Name": "MoveTo",
+          "Parameters": [
+            {
+              "Name": "destination",
+              "Type": "Microsoft.AspNetCore.Html.IHtmlContentBuilder"
+            }
+          ],
+          "ReturnType": "System.Void",
+          "Sealed": true,
+          "Virtual": true,
+          "ImplementedInterface": "Microsoft.AspNetCore.Html.IHtmlContentContainer",
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Method",
+          "Name": "WriteTo",
+          "Parameters": [
+            {
+              "Name": "writer",
+              "Type": "System.IO.TextWriter"
+            },
+            {
+              "Name": "encoder",
+              "Type": "System.Text.Encodings.Web.HtmlEncoder"
+            }
+          ],
+          "ReturnType": "System.Void",
+          "Sealed": true,
+          "Virtual": true,
+          "ImplementedInterface": "Microsoft.AspNetCore.Html.IHtmlContent",
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Method",
+          "Name": "get_Count",
+          "Parameters": [],
+          "ReturnType": "System.Int32",
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Method",
+          "Name": "Append",
+          "Parameters": [
+            {
+              "Name": "unencoded",
+              "Type": "System.String"
+            }
+          ],
+          "ReturnType": "Microsoft.AspNetCore.Html.IHtmlContentBuilder",
+          "Sealed": true,
+          "Virtual": true,
+          "ImplementedInterface": "Microsoft.AspNetCore.Html.IHtmlContentBuilder",
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Method",
+          "Name": "AppendHtml",
+          "Parameters": [
+            {
+              "Name": "htmlContent",
+              "Type": "Microsoft.AspNetCore.Html.IHtmlContent"
+            }
+          ],
+          "ReturnType": "Microsoft.AspNetCore.Html.IHtmlContentBuilder",
+          "Sealed": true,
+          "Virtual": true,
+          "ImplementedInterface": "Microsoft.AspNetCore.Html.IHtmlContentBuilder",
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Method",
+          "Name": "AppendHtml",
+          "Parameters": [
+            {
+              "Name": "encoded",
+              "Type": "System.String"
+            }
+          ],
+          "ReturnType": "Microsoft.AspNetCore.Html.IHtmlContentBuilder",
+          "Sealed": true,
+          "Virtual": true,
+          "ImplementedInterface": "Microsoft.AspNetCore.Html.IHtmlContentBuilder",
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Method",
+          "Name": "Clear",
+          "Parameters": [],
+          "ReturnType": "Microsoft.AspNetCore.Html.IHtmlContentBuilder",
+          "Sealed": true,
+          "Virtual": true,
+          "ImplementedInterface": "Microsoft.AspNetCore.Html.IHtmlContentBuilder",
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Constructor",
+          "Name": ".ctor",
+          "Parameters": [],
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Constructor",
+          "Name": ".ctor",
+          "Parameters": [
+            {
+              "Name": "capacity",
+              "Type": "System.Int32"
+            }
+          ],
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Constructor",
+          "Name": ".ctor",
+          "Parameters": [
+            {
+              "Name": "entries",
+              "Type": "System.Collections.Generic.IList<System.Object>"
+            }
+          ],
+          "Visibility": "Public",
+          "GenericParameter": []
+        }
+      ],
+      "GenericParameters": []
+    },
+    {
+      "Name": "Microsoft.AspNetCore.Html.HtmlContentBuilderExtensions",
+      "Visibility": "Public",
+      "Kind": "Class",
+      "Abstract": true,
+      "Static": true,
+      "Sealed": true,
+      "ImplementedInterfaces": [],
+      "Members": [
+        {
+          "Kind": "Method",
+          "Name": "AppendFormat",
+          "Parameters": [
+            {
+              "Name": "builder",
+              "Type": "Microsoft.AspNetCore.Html.IHtmlContentBuilder"
+            },
+            {
+              "Name": "format",
+              "Type": "System.String"
+            },
+            {
+              "Name": "args",
+              "Type": "System.Object[]",
+              "IsParams": true
+            }
+          ],
+          "ReturnType": "Microsoft.AspNetCore.Html.IHtmlContentBuilder",
+          "Static": true,
+          "Extension": true,
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Method",
+          "Name": "AppendFormat",
+          "Parameters": [
+            {
+              "Name": "builder",
+              "Type": "Microsoft.AspNetCore.Html.IHtmlContentBuilder"
+            },
+            {
+              "Name": "formatProvider",
+              "Type": "System.IFormatProvider"
+            },
+            {
+              "Name": "format",
+              "Type": "System.String"
+            },
+            {
+              "Name": "args",
+              "Type": "System.Object[]",
+              "IsParams": true
+            }
+          ],
+          "ReturnType": "Microsoft.AspNetCore.Html.IHtmlContentBuilder",
+          "Static": true,
+          "Extension": true,
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Method",
+          "Name": "AppendLine",
+          "Parameters": [
+            {
+              "Name": "builder",
+              "Type": "Microsoft.AspNetCore.Html.IHtmlContentBuilder"
+            }
+          ],
+          "ReturnType": "Microsoft.AspNetCore.Html.IHtmlContentBuilder",
+          "Static": true,
+          "Extension": true,
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Method",
+          "Name": "AppendLine",
+          "Parameters": [
+            {
+              "Name": "builder",
+              "Type": "Microsoft.AspNetCore.Html.IHtmlContentBuilder"
+            },
+            {
+              "Name": "unencoded",
+              "Type": "System.String"
+            }
+          ],
+          "ReturnType": "Microsoft.AspNetCore.Html.IHtmlContentBuilder",
+          "Static": true,
+          "Extension": true,
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Method",
+          "Name": "AppendLine",
+          "Parameters": [
+            {
+              "Name": "builder",
+              "Type": "Microsoft.AspNetCore.Html.IHtmlContentBuilder"
+            },
+            {
+              "Name": "content",
+              "Type": "Microsoft.AspNetCore.Html.IHtmlContent"
+            }
+          ],
+          "ReturnType": "Microsoft.AspNetCore.Html.IHtmlContentBuilder",
+          "Static": true,
+          "Extension": true,
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Method",
+          "Name": "AppendHtmlLine",
+          "Parameters": [
+            {
+              "Name": "builder",
+              "Type": "Microsoft.AspNetCore.Html.IHtmlContentBuilder"
+            },
+            {
+              "Name": "encoded",
+              "Type": "System.String"
+            }
+          ],
+          "ReturnType": "Microsoft.AspNetCore.Html.IHtmlContentBuilder",
+          "Static": true,
+          "Extension": true,
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Method",
+          "Name": "SetContent",
+          "Parameters": [
+            {
+              "Name": "builder",
+              "Type": "Microsoft.AspNetCore.Html.IHtmlContentBuilder"
+            },
+            {
+              "Name": "unencoded",
+              "Type": "System.String"
+            }
+          ],
+          "ReturnType": "Microsoft.AspNetCore.Html.IHtmlContentBuilder",
+          "Static": true,
+          "Extension": true,
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Method",
+          "Name": "SetHtmlContent",
+          "Parameters": [
+            {
+              "Name": "builder",
+              "Type": "Microsoft.AspNetCore.Html.IHtmlContentBuilder"
+            },
+            {
+              "Name": "content",
+              "Type": "Microsoft.AspNetCore.Html.IHtmlContent"
+            }
+          ],
+          "ReturnType": "Microsoft.AspNetCore.Html.IHtmlContentBuilder",
+          "Static": true,
+          "Extension": true,
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Method",
+          "Name": "SetHtmlContent",
+          "Parameters": [
+            {
+              "Name": "builder",
+              "Type": "Microsoft.AspNetCore.Html.IHtmlContentBuilder"
+            },
+            {
+              "Name": "encoded",
+              "Type": "System.String"
+            }
+          ],
+          "ReturnType": "Microsoft.AspNetCore.Html.IHtmlContentBuilder",
+          "Static": true,
+          "Extension": true,
+          "Visibility": "Public",
+          "GenericParameter": []
+        }
+      ],
+      "GenericParameters": []
+    },
+    {
+      "Name": "Microsoft.AspNetCore.Html.HtmlFormattableString",
+      "Visibility": "Public",
+      "Kind": "Class",
+      "ImplementedInterfaces": [
+        "Microsoft.AspNetCore.Html.IHtmlContent"
+      ],
+      "Members": [
+        {
+          "Kind": "Method",
+          "Name": "WriteTo",
+          "Parameters": [
+            {
+              "Name": "writer",
+              "Type": "System.IO.TextWriter"
+            },
+            {
+              "Name": "encoder",
+              "Type": "System.Text.Encodings.Web.HtmlEncoder"
+            }
+          ],
+          "ReturnType": "System.Void",
+          "Sealed": true,
+          "Virtual": true,
+          "ImplementedInterface": "Microsoft.AspNetCore.Html.IHtmlContent",
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Constructor",
+          "Name": ".ctor",
+          "Parameters": [
+            {
+              "Name": "format",
+              "Type": "System.String"
+            },
+            {
+              "Name": "args",
+              "Type": "System.Object[]",
+              "IsParams": true
+            }
+          ],
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Constructor",
+          "Name": ".ctor",
+          "Parameters": [
+            {
+              "Name": "formatProvider",
+              "Type": "System.IFormatProvider"
+            },
+            {
+              "Name": "format",
+              "Type": "System.String"
+            },
+            {
+              "Name": "args",
+              "Type": "System.Object[]",
+              "IsParams": true
+            }
+          ],
+          "Visibility": "Public",
+          "GenericParameter": []
+        }
+      ],
+      "GenericParameters": []
+    },
+    {
+      "Name": "Microsoft.AspNetCore.Html.HtmlString",
+      "Visibility": "Public",
+      "Kind": "Class",
+      "ImplementedInterfaces": [
+        "Microsoft.AspNetCore.Html.IHtmlContent"
+      ],
+      "Members": [
+        {
+          "Kind": "Method",
+          "Name": "get_Value",
+          "Parameters": [],
+          "ReturnType": "System.String",
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Method",
+          "Name": "WriteTo",
+          "Parameters": [
+            {
+              "Name": "writer",
+              "Type": "System.IO.TextWriter"
+            },
+            {
+              "Name": "encoder",
+              "Type": "System.Text.Encodings.Web.HtmlEncoder"
+            }
+          ],
+          "ReturnType": "System.Void",
+          "Sealed": true,
+          "Virtual": true,
+          "ImplementedInterface": "Microsoft.AspNetCore.Html.IHtmlContent",
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Method",
+          "Name": "ToString",
+          "Parameters": [],
+          "ReturnType": "System.String",
+          "Virtual": true,
+          "Override": true,
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Constructor",
+          "Name": ".ctor",
+          "Parameters": [
+            {
+              "Name": "value",
+              "Type": "System.String"
+            }
+          ],
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Field",
+          "Name": "NewLine",
+          "Parameters": [],
+          "ReturnType": "Microsoft.AspNetCore.Html.HtmlString",
+          "Static": true,
+          "ReadOnly": true,
+          "Visibility": "Public",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Field",
+          "Name": "Empty",
+          "Parameters": [],
+          "ReturnType": "Microsoft.AspNetCore.Html.HtmlString",
+          "Static": true,
+          "ReadOnly": true,
+          "Visibility": "Public",
+          "GenericParameter": []
+        }
+      ],
+      "GenericParameters": []
+    },
+    {
+      "Name": "Microsoft.AspNetCore.Html.IHtmlContent",
+      "Visibility": "Public",
+      "Kind": "Interface",
+      "Abstract": true,
+      "ImplementedInterfaces": [],
+      "Members": [
+        {
+          "Kind": "Method",
+          "Name": "WriteTo",
+          "Parameters": [
+            {
+              "Name": "writer",
+              "Type": "System.IO.TextWriter"
+            },
+            {
+              "Name": "encoder",
+              "Type": "System.Text.Encodings.Web.HtmlEncoder"
+            }
+          ],
+          "ReturnType": "System.Void",
+          "GenericParameter": []
+        }
+      ],
+      "GenericParameters": []
+    },
+    {
+      "Name": "Microsoft.AspNetCore.Html.IHtmlContentBuilder",
+      "Visibility": "Public",
+      "Kind": "Interface",
+      "Abstract": true,
+      "ImplementedInterfaces": [
+        "Microsoft.AspNetCore.Html.IHtmlContentContainer"
+      ],
+      "Members": [
+        {
+          "Kind": "Method",
+          "Name": "AppendHtml",
+          "Parameters": [
+            {
+              "Name": "content",
+              "Type": "Microsoft.AspNetCore.Html.IHtmlContent"
+            }
+          ],
+          "ReturnType": "Microsoft.AspNetCore.Html.IHtmlContentBuilder",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Method",
+          "Name": "Append",
+          "Parameters": [
+            {
+              "Name": "unencoded",
+              "Type": "System.String"
+            }
+          ],
+          "ReturnType": "Microsoft.AspNetCore.Html.IHtmlContentBuilder",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Method",
+          "Name": "AppendHtml",
+          "Parameters": [
+            {
+              "Name": "encoded",
+              "Type": "System.String"
+            }
+          ],
+          "ReturnType": "Microsoft.AspNetCore.Html.IHtmlContentBuilder",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Method",
+          "Name": "Clear",
+          "Parameters": [],
+          "ReturnType": "Microsoft.AspNetCore.Html.IHtmlContentBuilder",
+          "GenericParameter": []
+        }
+      ],
+      "GenericParameters": []
+    },
+    {
+      "Name": "Microsoft.AspNetCore.Html.IHtmlContentContainer",
+      "Visibility": "Public",
+      "Kind": "Interface",
+      "Abstract": true,
+      "ImplementedInterfaces": [
+        "Microsoft.AspNetCore.Html.IHtmlContent"
+      ],
+      "Members": [
+        {
+          "Kind": "Method",
+          "Name": "CopyTo",
+          "Parameters": [
+            {
+              "Name": "builder",
+              "Type": "Microsoft.AspNetCore.Html.IHtmlContentBuilder"
+            }
+          ],
+          "ReturnType": "System.Void",
+          "GenericParameter": []
+        },
+        {
+          "Kind": "Method",
+          "Name": "MoveTo",
+          "Parameters": [
+            {
+              "Name": "builder",
+              "Type": "Microsoft.AspNetCore.Html.IHtmlContentBuilder"
+            }
+          ],
+          "ReturnType": "System.Void",
+          "GenericParameter": []
+        }
+      ],
+      "GenericParameters": []
+    }
+  ]
+}

src/Html/Abstractions/test/HtmlContentBuilderExtensionsTest.cs

@@ -0,0 +1,463 @@
+// Copyright (c) .NET Foundation. 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.Globalization;
+using System.IO;
+using System.Text.Encodings.Web;
+using Microsoft.AspNetCore.Testing;
+using Microsoft.Extensions.WebEncoders.Testing;
+using Xunit;
+
+namespace Microsoft.AspNetCore.Html.Test
+{
+    public class HtmlContentBuilderExtensionsTest
+    {
+        [Fact]
+        public void Builder_AppendLine_Empty()
+        {
+            // Arrange
+            var builder = new TestHtmlContentBuilder();
+
+            // Act
+            builder.AppendLine();
+
+            // Assert
+            Assert.Collection(
+                builder.Entries,
+                entry => Assert.Equal(Environment.NewLine, HtmlContentToString(entry)));
+        }
+
+        [Fact]
+        public void Builder_AppendLine_String()
+        {
+            // Arrange
+            var builder = new TestHtmlContentBuilder();
+
+            // Act
+            builder.AppendLine("Hi");
+
+            // Assert
+            Assert.Collection(
+                builder.Entries,
+                entry => Assert.Equal("Hi", Assert.IsType<UnencodedString>(entry).Value),
+                entry => Assert.Equal(Environment.NewLine, HtmlContentToString(entry)));
+        }
+
+        [Fact]
+        public void Builder_AppendLine_IHtmlContent()
+        {
+            // Arrange
+            var builder = new TestHtmlContentBuilder();
+            var content = new OtherHtmlContent("Hi");
+
+            // Act
+            builder.AppendLine(content);
+
+            // Assert
+            Assert.Collection(
+                builder.Entries,
+                entry => Assert.Same(content, entry),
+                entry => Assert.Equal(Environment.NewLine, HtmlContentToString(entry)));
+        }
+
+        [Fact]
+        public void Builder_AppendHtmlLine_String()
+        {
+            // Arrange
+            var builder = new TestHtmlContentBuilder();
+
+            // Act
+            builder.AppendHtmlLine("Hi");
+
+            // Assert
+            Assert.Collection(
+                builder.Entries,
+                entry => Assert.Equal("Hi", Assert.IsType<EncodedString>(entry).Value),
+                entry => Assert.Equal(Environment.NewLine, HtmlContentToString(entry)));
+        }
+
+        [Fact]
+        public void Builder_SetContent_String()
+        {
+            // Arrange
+            var builder = new TestHtmlContentBuilder();
+            builder.Append("Existing Content. Will be Cleared.");
+
+            // Act
+            builder.SetContent("Hi");
+
+            // Assert
+            Assert.Collection(
+                builder.Entries,
+                entry => Assert.Equal("Hi", Assert.IsType<UnencodedString>(entry).Value));
+        }
+
+        [Fact]
+        public void Builder_SetContent_IHtmlContent()
+        {
+            // Arrange
+            var builder = new TestHtmlContentBuilder();
+            builder.Append("Existing Content. Will be Cleared.");
+
+            var content = new OtherHtmlContent("Hi");
+
+            // Act
+            builder.SetHtmlContent(content);
+
+            // Assert
+            Assert.Collection(
+                builder.Entries,
+                entry => Assert.Same(content, entry));
+        }
+
+        [Fact]
+        public void Builder_SetHtmlContent_String()
+        {
+            // Arrange
+            var builder = new TestHtmlContentBuilder();
+            builder.Append("Existing Content. Will be Cleared.");
+
+            // Act
+            builder.SetHtmlContent("Hi");
+
+            // Assert
+            Assert.Collection(
+                builder.Entries,
+                entry => Assert.Equal("Hi", Assert.IsType<EncodedString>(entry).Value));
+        }
+
+        [Fact]
+        public void Builder_AppendFormat()
+        {
+            // Arrange
+            var builder = new TestHtmlContentBuilder();
+
+            // Act
+            builder.AppendFormat("{0} {1} {2} {3}!", "First", "Second", "Third", "Fourth");
+
+            // Assert
+            Assert.Equal(
+                "HtmlEncode[[First]] HtmlEncode[[Second]] HtmlEncode[[Third]] HtmlEncode[[Fourth]]!",
+                HtmlContentToString(builder));
+        }
+
+        [Fact]
+        public void Builder_AppendFormat_HtmlContent()
+        {
+            // Arrange
+            var builder = new TestHtmlContentBuilder();
+
+            // Act
+            builder.AppendFormat("{0}!", new EncodedString("First"));
+
+            // Assert
+            Assert.Equal(
+                "First!",
+                HtmlContentToString(builder));
+        }
+
+        [Fact]
+        public void Builder_AppendFormat_HtmlString()
+        {
+            // Arrange
+            var builder = new TestHtmlContentBuilder();
+
+            // Act
+            builder.AppendFormat("{0}!", new HtmlString("First"));
+
+            // Assert
+            Assert.Equal("First!", HtmlContentToString(builder));
+        }
+
+        [Fact]
+        public void Builder_AppendFormatContent_With1Argument()
+        {
+            // Arrange
+            var builder = new TestHtmlContentBuilder();
+
+            // Act
+            builder.AppendFormat("0x{0:X} - hex equivalent for 50.", 50);
+
+            // Assert
+            Assert.Equal(
+                "0xHtmlEncode[[32]] - hex equivalent for 50.",
+                HtmlContentToString(builder));
+        }
+
+        [Fact]
+        public void Builder_AppendFormatContent_With2Arguments()
+        {
+            // Arrange
+            var builder = new TestHtmlContentBuilder();
+
+            // Act
+            builder.AppendFormat("0x{0:X} - hex equivalent for {1}.", 50, 50);
+
+            // Assert
+            Assert.Equal(
+                "0xHtmlEncode[[32]] - hex equivalent for HtmlEncode[[50]].",
+                HtmlContentToString(builder));
+        }
+
+        [Fact]
+        public void Builder_AppendFormatContent_With3Arguments()
+        {
+            // Arrange
+            var builder = new TestHtmlContentBuilder();
+
+            // Act
+            builder.AppendFormat("0x{0:X} - {1} equivalent for {2}.", 50, "hex", 50);
+
+            // Assert
+            Assert.Equal(
+                "0xHtmlEncode[[32]] - HtmlEncode[[hex]] equivalent for HtmlEncode[[50]].",
+                HtmlContentToString(builder));
+        }
+
+        [Fact]
+        public void Builder_AppendFormat_WithAlignmentComponent()
+        {
+            // Arrange
+            var builder = new TestHtmlContentBuilder();
+
+            // Act
+            builder.AppendFormat("{0, -25} World!", "Hello");
+
+            // Assert
+            Assert.Equal(
+                "HtmlEncode[[Hello]]       World!",
+                HtmlContentToString(builder));
+        }
+
+        [Fact]
+        public void Builder_AppendFormat_WithFormatStringComponent()
+        {
+            // Arrange
+            var builder = new TestHtmlContentBuilder();
+
+            // Act
+            builder.AppendFormat("0x{0:X}", 50);
+
+            // Assert
+            Assert.Equal("0xHtmlEncode[[32]]", HtmlContentToString(builder));
+        }
+
+        [Fact]
+        public void Builder_AppendFormat_WithCulture()
+        {
+            // Arrange
+            var builder = new TestHtmlContentBuilder();
+
+            // Act
+            builder.AppendFormat(
+                CultureInfo.InvariantCulture,
+                "Numbers in InvariantCulture - {0, -5:N} {1} {2} {3}!",
+                1.1,
+                2.98,
+                145.82,
+                32.86);
+
+            // Assert
+            Assert.Equal(
+                "Numbers in InvariantCulture - HtmlEncode[[1.10]] HtmlEncode[[2.98]] " +
+                    "HtmlEncode[[145.82]] HtmlEncode[[32.86]]!",
+                HtmlContentToString(builder));
+        }
+
+        [Fact]
+        public void Builder_AppendFormat_WithCulture_1Argument()
+        {
+            // Arrange
+            var builder = new TestHtmlContentBuilder();
+
+            // Act
+            builder.AppendFormat(
+                CultureInfo.InvariantCulture,
+                "Numbers in InvariantCulture - {0:N}!",
+                1.1);
+
+            // Assert
+            Assert.Equal(
+                "Numbers in InvariantCulture - HtmlEncode[[1.10]]!",
+                HtmlContentToString(builder));
+        }
+
+        [Fact]
+        public void Builder_AppendFormat_WithCulture_2Arguments()
+        {
+            // Arrange
+            var builder = new TestHtmlContentBuilder();
+
+            // Act
+            builder.AppendFormat(
+                CultureInfo.InvariantCulture,
+                "Numbers in InvariantCulture - {0:N} {1}!",
+                1.1,
+                2.98);
+
+            // Assert
+            Assert.Equal(
+                "Numbers in InvariantCulture - HtmlEncode[[1.10]] HtmlEncode[[2.98]]!",
+                HtmlContentToString(builder));
+        }
+
+        [Fact]
+        public void Builder_AppendFormat_WithCulture_3Arguments()
+        {
+            // Arrange
+            var builder = new TestHtmlContentBuilder();
+
+            // Act
+            builder.AppendFormat(
+                CultureInfo.InvariantCulture,
+                "Numbers in InvariantCulture - {0:N} {1} {2}!",
+                1.1,
+                2.98,
+                3.12);
+
+            // Assert
+            Assert.Equal(
+                "Numbers in InvariantCulture - HtmlEncode[[1.10]] HtmlEncode[[2.98]] HtmlEncode[[3.12]]!",
+                HtmlContentToString(builder));
+        }
+
+        [Fact]
+        public void Builder_AppendFormat_WithDifferentCulture()
+        {
+            // Arrange
+            var builder = new TestHtmlContentBuilder();
+            var culture = new CultureInfo("fr-FR");
+
+            // Act
+            builder.AppendFormat(culture, "{0} in french!", 1.21);
+
+            // Assert
+            Assert.Equal(
+                "HtmlEncode[[1,21]] in french!",
+                HtmlContentToString(builder));
+        }
+
+        [Fact]
+        [ReplaceCulture("de-DE", "de-DE")]
+        public void Builder_AppendFormat_WithDifferentCurrentCulture()
+        {
+            // Arrange
+            var builder = new TestHtmlContentBuilder();
+
+            // Act
+            builder.AppendFormat(CultureInfo.CurrentCulture, "{0:D}", DateTime.Parse("01/02/2015"));
+
+            // Assert
+            Assert.Equal(
+                "HtmlEncode[[Sonntag, 1. Februar 2015]]",
+                HtmlContentToString(builder));
+        }
+
+        private static string HtmlContentToString(IHtmlContent content)
+        {
+            using (var writer = new StringWriter())
+            {
+                content.WriteTo(writer, new HtmlTestEncoder());
+                return writer.ToString();
+            }
+        }
+
+        private class TestHtmlContentBuilder : IHtmlContentBuilder
+        {
+            public List<IHtmlContent> Entries { get; } = new List<IHtmlContent>();
+
+            public IHtmlContentBuilder Append(string unencoded)
+            {
+                Entries.Add(new UnencodedString(unencoded));
+                return this;
+            }
+
+            public IHtmlContentBuilder AppendHtml(IHtmlContent content)
+            {
+                Entries.Add(content);
+                return this;
+            }
+
+            public IHtmlContentBuilder AppendHtml(string encoded)
+            {
+                Entries.Add(new EncodedString(encoded));
+                return this;
+            }
+
+            public IHtmlContentBuilder Clear()
+            {
+                Entries.Clear();
+                return this;
+            }
+
+            public void CopyTo(IHtmlContentBuilder destination)
+            {
+                foreach (var entry in Entries)
+                {
+                    destination.AppendHtml(entry);
+                }
+            }
+
+            public void MoveTo(IHtmlContentBuilder destination)
+            {
+                CopyTo(destination);
+                Clear();
+            }
+
+            public void WriteTo(TextWriter writer, HtmlEncoder encoder)
+            {
+                foreach (var entry in Entries)
+                {
+                    entry.WriteTo(writer, encoder);
+                }
+            }
+        }
+
+        private class EncodedString : IHtmlContent
+        {
+            public EncodedString(string value)
+            {
+                Value = value;
+            }
+
+            public string Value { get; }
+
+            public void WriteTo(TextWriter writer, HtmlEncoder encoder)
+            {
+                writer.Write(Value);
+            }
+        }
+
+        private class UnencodedString : IHtmlContent
+        {
+            public UnencodedString(string value)
+            {
+                Value = value;
+            }
+
+            public string Value { get; }
+
+            public void WriteTo(TextWriter writer, HtmlEncoder encoder)
+            {
+                encoder.Encode(writer, Value);
+            }
+        }
+
+        private class OtherHtmlContent : IHtmlContent
+        {
+            public OtherHtmlContent(string value)
+            {
+                Value = value;
+            }
+
+            public string Value { get; }
+
+            public void WriteTo(TextWriter writer, HtmlEncoder encoder)
+            {
+                throw new NotImplementedException();
+            }
+        }
+    }
+}

src/Html/Abstractions/test/HtmlContentBuilderTest.cs

@@ -0,0 +1,276 @@
+// Copyright (c) .NET Foundation. 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.IO;
+using System.Text.Encodings.Web;
+using Microsoft.AspNetCore.Html;
+using Microsoft.Extensions.WebEncoders.Testing;
+using Xunit;
+
+namespace Microsoft.Extensions.Internal
+{
+    public class HtmlContentBuilderTest
+    {
+        [Fact]
+        public void AppendString_AppendsAString()
+        {
+            // Arrange
+            var content = new HtmlContentBuilder();
+
+            // Act
+            content.Append("Hello");
+
+            // Assert
+            Assert.Equal(1, content.Count);
+            var result = Assert.Single(content.Entries);
+            Assert.IsType<string>(result);
+        }
+
+        [Fact]
+        public void AppendString_WrittenAsEncoded()
+        {
+            // Arrange
+            var content = new HtmlContentBuilder();
+            content.Append("Hello");
+
+            var writer = new StringWriter();
+
+            // Act
+            content.WriteTo(writer, new HtmlTestEncoder());
+
+            // Assert
+            Assert.Equal("HtmlEncode[[Hello]]", writer.ToString());
+        }
+
+        [Fact]
+        public void AppendHtml_DoesNotGetWrittenAsEncoded()
+        {
+            // Arrange
+            var content = new HtmlContentBuilder();
+            content.AppendHtml("Hello");
+
+            var writer = new StringWriter();
+
+            // Act
+            content.WriteTo(writer, new HtmlTestEncoder());
+
+            // Assert
+            Assert.Equal("Hello", writer.ToString());
+        }
+
+        [Fact]
+        public void AppendIHtmlContent_AppendsAsIs()
+        {
+            // Arrange
+            var content = new HtmlContentBuilder();
+            var writer = new StringWriter();
+
+            // Act
+            content.AppendHtml(new TestHtmlContent("Hello"));
+
+            // Assert
+            Assert.Equal(1, content.Count);
+            var result = Assert.Single(content.Entries);
+            var testHtmlContent = Assert.IsType<TestHtmlContent>(result);
+            testHtmlContent.WriteTo(writer, new HtmlTestEncoder());
+            Assert.Equal("Written from TestHtmlContent: Hello", writer.ToString());
+        }
+
+        [Fact]
+        public void CanAppendMultipleItems()
+        {
+            // Arrange
+            var content = new HtmlContentBuilder();
+
+            // Act
+            content.AppendHtml(new TestHtmlContent("hello"));
+            content.Append("Test");
+
+            // Assert
+            Assert.Equal(2, content.Count);
+            Assert.Collection(
+                content.Entries,
+                entry => Assert.Equal("Written from TestHtmlContent: hello", entry.ToString()),
+                entry => Assert.Equal("Test", entry));
+        }
+
+        [Fact]
+        public void Clear_DeletesAllItems()
+        {
+            // Arrange
+            var content = new HtmlContentBuilder();
+            content.AppendHtml(new TestHtmlContent("hello"));
+            content.Append("Test");
+
+            // Act
+            content.Clear();
+
+            // Assert
+            Assert.Equal(0, content.Count);
+            Assert.Empty(content.Entries);
+        }
+
+        [Fact]
+        public void CopyTo_CopiesAllItems()
+        {
+            // Arrange
+            var source = new HtmlContentBuilder();
+            source.AppendHtml(new TestHtmlContent("hello"));
+            source.Append("Test");
+
+            var destination = new HtmlContentBuilder();
+            destination.Append("some-content");
+
+            // Act
+            source.CopyTo(destination);
+
+            // Assert
+            Assert.Equal(2, source.Count);
+            Assert.Equal(3, destination.Count);
+            Assert.Collection(
+                destination.Entries,
+                entry => Assert.Equal("some-content", Assert.IsType<string>(entry)),
+                entry => Assert.Equal(new TestHtmlContent("hello"), Assert.IsType<TestHtmlContent>(entry)),
+                entry => Assert.Equal("Test", Assert.IsType<string>(entry)));
+        }
+
+        [Fact]
+        public void CopyTo_DoesDeepCopy()
+        {
+            // Arrange
+            var source = new HtmlContentBuilder();
+
+            var nested = new HtmlContentBuilder();
+            source.AppendHtml(nested);
+            nested.AppendHtml(new TestHtmlContent("hello"));
+            source.Append("Test");
+
+            var destination = new HtmlContentBuilder();
+            destination.Append("some-content");
+
+            // Act
+            source.CopyTo(destination);
+
+            // Assert
+            Assert.Equal(2, source.Count);
+            Assert.Equal(1, nested.Count);
+            Assert.Equal(3, destination.Count);
+            Assert.Collection(
+                destination.Entries,
+                entry => Assert.Equal("some-content", Assert.IsType<string>(entry)),
+                entry => Assert.Equal(new TestHtmlContent("hello"), Assert.IsType<TestHtmlContent>(entry)),
+                entry => Assert.Equal("Test", Assert.IsType<string>(entry)));
+        }
+
+        [Fact]
+        public void MoveTo_CopiesAllItems_AndClears()
+        {
+            // Arrange
+            var source = new HtmlContentBuilder();
+            source.AppendHtml(new TestHtmlContent("hello"));
+            source.Append("Test");
+
+            var destination = new HtmlContentBuilder();
+            destination.Append("some-content");
+
+            // Act
+            source.MoveTo(destination);
+
+            // Assert
+            Assert.Equal(0, source.Count);
+            Assert.Equal(3, destination.Count);
+            Assert.Collection(
+                destination.Entries,
+                entry => Assert.Equal("some-content", Assert.IsType<string>(entry)),
+                entry => Assert.Equal(new TestHtmlContent("hello"), Assert.IsType<TestHtmlContent>(entry)),
+                entry => Assert.Equal("Test", Assert.IsType<string>(entry)));
+        }
+
+        [Fact]
+        public void MoveTo_DoesDeepMove()
+        {
+            // Arrange
+            var source = new HtmlContentBuilder();
+
+            var nested = new HtmlContentBuilder();
+            source.AppendHtml(nested);
+            nested.AppendHtml(new TestHtmlContent("hello"));
+            source.Append("Test");
+
+            var destination = new HtmlContentBuilder();
+            destination.Append("some-content");
+
+            // Act
+            source.MoveTo(destination);
+
+            // Assert
+            Assert.Equal(0, source.Count);
+            Assert.Equal(0, nested.Count);
+            Assert.Equal(3, destination.Count);
+            Assert.Collection(
+                destination.Entries,
+                entry => Assert.Equal("some-content", Assert.IsType<string>(entry)),
+                entry => Assert.Equal(new TestHtmlContent("hello"), Assert.IsType<TestHtmlContent>(entry)),
+                entry => Assert.Equal("Test", Assert.IsType<string>(entry)));
+        }
+
+        [Fact]
+        public void WriteTo_WritesAllItems()
+        {
+            // Arrange
+            var content = new HtmlContentBuilder();
+            var writer = new StringWriter();
+            content.AppendHtml(new TestHtmlContent("Hello"));
+            content.Append("Test");
+
+            // Act
+            content.WriteTo(writer, new HtmlTestEncoder());
+
+            // Assert
+            Assert.Equal(2, content.Count);
+            Assert.Equal("Written from TestHtmlContent: HelloHtmlEncode[[Test]]", writer.ToString());
+        }
+
+        private class TestHtmlContent : IHtmlContent, IEquatable<TestHtmlContent>
+        {
+            private string _content;
+
+            public TestHtmlContent(string content)
+            {
+                _content = content;
+            }
+
+            public void WriteTo(TextWriter writer, HtmlEncoder encoder)
+            {
+                writer.Write(ToString());
+            }
+
+            public override string ToString()
+            {
+                return "Written from TestHtmlContent: " + _content;
+            }
+
+            public override int GetHashCode()
+            {
+                return _content.GetHashCode();
+            }
+
+            public override bool Equals(object obj)
+            {
+                var other = obj as TestHtmlContent;
+                if (other != null)
+                {
+                    return Equals(other);
+                }
+
+                return base.Equals(obj);
+            }
+
+            public bool Equals(TestHtmlContent other)
+            {
+                return string.Equals(_content, other._content);
+            }
+        }
+    }
+}

src/Html/Abstractions/test/HtmlFormattableStringTest.cs

@@ -0,0 +1,217 @@
+// Copyright (c) .NET Foundation. 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.Globalization;
+using System.IO;
+using Microsoft.AspNetCore.Testing;
+using Microsoft.Extensions.WebEncoders.Testing;
+using Xunit;
+
+namespace Microsoft.AspNetCore.Html
+{
+    public class HtmlFormattableStringTest
+    {
+        [Fact]
+        public void HtmlFormattableString_EmptyArgs()
+        {
+            // Arrange
+            var formattableString = new HtmlFormattableString("Hello, World!");
+
+            // Act
+            var result = HtmlContentToString(formattableString);
+
+            // Assert
+            Assert.Equal("Hello, World!", result);
+        }
+
+        [Fact]
+        public void HtmlFormattableString_EmptyArgsAndCulture()
+        {
+            // Arrange
+            var formattableString = new HtmlFormattableString(CultureInfo.CurrentCulture, "Hello, World!");
+
+            // Act
+            var result = HtmlContentToString(formattableString);
+
+            // Assert
+            Assert.Equal("Hello, World!", result);
+        }
+
+        [Fact]
+        public void HtmlFormattableString_MultipleArguments()
+        {
+            // Arrange
+            var formattableString = new HtmlFormattableString("{0} {1} {2} {3}!", "First", "Second", "Third", "Fourth");
+
+            // Act
+            var result = HtmlContentToString(formattableString);
+
+            // Assert
+            Assert.Equal(
+                "HtmlEncode[[First]] HtmlEncode[[Second]] HtmlEncode[[Third]] HtmlEncode[[Fourth]]!",
+                result);
+        }
+
+        [Fact]
+        public void HtmlFormattableString_WithHtmlString()
+        {
+            // Arrange
+            var formattableString = new HtmlFormattableString("{0}!", new HtmlString("First"));
+
+            // Act
+            var result = HtmlContentToString(formattableString);
+
+            // Assert
+            Assert.Equal("First!", result);
+        }
+
+        [Fact]
+        public void HtmlFormattableString_WithOtherIHtmlContent()
+        {
+            // Arrange
+            var builder = new HtmlContentBuilder();
+            builder.Append("First");
+
+            var formattableString = new HtmlFormattableString("{0}!", builder);
+
+            // Act
+            var result = HtmlContentToString(formattableString);
+
+            // Assert
+            Assert.Equal("HtmlEncode[[First]]!", result);
+        }
+
+        // This test is needed to ensure the shared StringWriter gets cleared.
+        [Fact]
+        public void HtmlFormattableString_WithMultipleHtmlContentArguments()
+        {
+            // Arrange
+            var formattableString = new HtmlFormattableString(
+                "Happy {0}, {1}!",
+                new HtmlString("Birthday"),
+                new HtmlContentBuilder().Append("Billy"));
+
+            // Act
+            var result = HtmlContentToString(formattableString);
+
+            // Assert
+            Assert.Equal("Happy Birthday, HtmlEncode[[Billy]]!", result);
+        }
+
+        [Fact]
+        public void HtmlFormattableString_WithHtmlString_AndOffset()
+        {
+            // Arrange
+            var formattableString = new HtmlFormattableString("{0, 20}!", new HtmlString("First"));
+
+            // Act
+            var result = HtmlContentToString(formattableString);
+
+            // Assert
+            Assert.Equal("               First!", result);
+        }
+
+        [Fact]
+        public void HtmlFormattableString_With3Arguments()
+        {
+            // Arrange
+            var formattableString = new HtmlFormattableString("0x{0:X} - {1} equivalent for {2}.", 50, "hex", 50);
+
+            // Act
+            var result = HtmlContentToString(formattableString);
+
+            // Assert
+            Assert.Equal(
+                "0xHtmlEncode[[32]] - HtmlEncode[[hex]] equivalent for HtmlEncode[[50]].",
+                result);
+        }
+
+        [Fact]
+        public void HtmlFormattableString_WithAlignmentComponent()
+        {
+            // Arrange
+            var formattableString = new HtmlFormattableString("{0, -25} World!", "Hello");
+
+            // Act
+            var result = HtmlContentToString(formattableString);
+
+            // Assert
+            Assert.Equal(
+                "HtmlEncode[[Hello]]       World!", result);
+        }
+
+        [Fact]
+        public void HtmlFormattableString_WithFormatStringComponent()
+        {
+            // Arrange
+            var formattableString = new HtmlFormattableString("0x{0:X}", 50);
+
+            // Act
+            var result = HtmlContentToString(formattableString);
+
+            // Assert
+            Assert.Equal("0xHtmlEncode[[32]]", result);
+        }
+
+        [Fact]
+        public void HtmlFormattableString_WithCulture()
+        {
+            // Arrange
+            var formattableString = new HtmlFormattableString(
+                CultureInfo.InvariantCulture,
+                "Numbers in InvariantCulture - {0, -5:N} {1} {2} {3}!",
+                1.1,
+                2.98,
+                145.82,
+                32.86);
+
+            // Act
+            var result = HtmlContentToString(formattableString);
+
+            // Assert
+            Assert.Equal(
+                "Numbers in InvariantCulture - HtmlEncode[[1.10]] HtmlEncode[[2.98]] " +
+                    "HtmlEncode[[145.82]] HtmlEncode[[32.86]]!",
+                result);
+        }
+
+        [Fact]
+        [ReplaceCulture("en-US", "en-US")]
+        public void HtmlFormattableString_UsesPassedInCulture()
+        {
+            // Arrange
+            var culture = new CultureInfo("fr-FR");
+            var formattableString = new HtmlFormattableString(culture, "{0} in french!", 1.21);
+
+            // Act
+            var result = HtmlContentToString(formattableString);
+
+            // Assert
+            Assert.Equal("HtmlEncode[[1,21]] in french!", result);
+        }
+
+        [Fact]
+        [ReplaceCulture("de-DE", "de-DE")]
+        public void HtmlFormattableString_UsesCurrentCulture()
+        {
+            // Arrange
+            var formattableString = new HtmlFormattableString("{0:D}", DateTime.Parse("01/02/2015"));
+
+            // Act
+            var result = HtmlContentToString(formattableString);
+
+            // Assert
+            Assert.Equal("HtmlEncode[[Sonntag, 1. Februar 2015]]", result);
+        }
+
+        private static string HtmlContentToString(IHtmlContent content)
+        {
+            using (var writer = new StringWriter())
+            {
+                content.WriteTo(writer, new HtmlTestEncoder());
+                return writer.ToString();
+            }
+        }
+    }
+}

src/Html/Abstractions/test/Microsoft.AspNetCore.Html.Abstractions.Tests.csproj

@@ -0,0 +1,12 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFrameworks>$(StandardTestTfms)</TargetFrameworks>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <Reference Include="Microsoft.AspNetCore.Html.Abstractions" />
+    <Reference Include="Microsoft.Extensions.WebEncoders" />
+  </ItemGroup>
+
+</Project>