Merge pull request #64 from aspnet/55_Xml-Escape-Values

Add xml escaping for Expand mode.

Author: StephenMolloy

README.md

@@ -69,6 +69,13 @@ key name before being inserted into AppSettings. `stripPrefix` is a boolean valu
 This setting is a boolean that specified whether to avoid throwing exceptions when the backing configuration source cannot be found or connected.
 The default default value is `true`, though some config builders (such as the Azure-based builders) will use a different default.
 
+#### escapeExpandedValues
+.Net configuration is XML-based in it's raw form. While these config builders work on `ConfigurationSection` objects in `Strict` and `Greedy` modes,
+when operating in `Expand` mode, tokens in the raw XML input are directly replaced with values. Applications that use `Expand` mode may do so because
+they need to inject additional XML rather than just a string value. But for the cases when a simple string replacement is the goal, unescaped XML
+characters in replacement values may result in invalid XML. In these cases, simply set the `escapeExpandedValues` attribute to `true` and the
+config builder will escape special XML characters before replacing tokens in `Expand` mode. The default value is `false`.
+
 #### tokenPattern
 This is a setting that is shared between all KeyValueConfigBuilder-derived builders is `tokenPattern`. When describing the `Expand` behavior of these builders
 above, it was mentioned that the raw xml is searched for tokens that look like __`${token}`__. This is done with a regular expression. `@"\$\{(\w+)\}"` to be exact.
@@ -119,7 +126,7 @@ preceded with an '@' symbol.
 ### EnvironmentConfigBuilder
 ```xml
 <add name="Environment"
-    [mode|@prefix|@stripPrefix|tokenPattern|@optional=true]
+    [mode|@prefix|@stripPrefix|tokenPattern|@escapeExpandedValues|@optional=true]
     type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder, Microsoft.Configuration.ConfigurationBuilders.Environment" />
 ```
 This is the most basic of the config builders. It draws its values from Environment, and it does not have any additional configuration options.
@@ -132,7 +139,7 @@ This is the most basic of the config builders. It draws its values from Environm
 ### UserSecretsConfigBuilder
 ```xml
 <add name="UserSecrets"
-    [mode|@prefix|@stripPrefix|tokenPattern|@optional=true]
+    [mode|@prefix|@stripPrefix|tokenPattern|@escapeExpandedValues|@optional=true]
     (@userSecretsId="12345678-90AB-CDEF-1234-567890" | @userSecretsFile="~\secrets.file")
     type="Microsoft.Configuration.ConfigurationBuilders.UserSecretsConfigBuilder, Microsoft.Configuration.ConfigurationBuilders.UserSecrets" />
 ```
@@ -168,7 +175,7 @@ and currently exposes the format of the file which, as mentioned above, should b
 ### AzureAppConfigurationBuilder
 ```xml
 <add name="AzureAppConfig"
-    [mode|@prefix|@stripPrefix|tokenPattern|@optional=false]
+    [mode|@prefix|@stripPrefix|tokenPattern|@escapeExpandedValues|@optional=false]
     (@vaultName="MyVaultName" | @uri="https://MyVaultName.vault.azure.net")
     [@connectionString="connection string"]
     [@version="secrets version"]
@@ -211,7 +218,7 @@ entries: `item1` and `item2`.
 ### AzureKeyVaultConfigBuilder
 ```xml
 <add name="AzureKeyVault"
-    [mode|@prefix|@stripPrefix|tokenPattern|@optional=false]
+    [mode|@prefix|@stripPrefix|tokenPattern|@escapeExpandedValues|@optional=false]
     (@vaultName="MyVaultName" | @uri="https://MyVaultName.vault.azure.net")
     [@connectionString="connection string"]
     [@version="secrets version"]
@@ -249,7 +256,7 @@ entries: `item1` and `item2`.
 ### KeyPerFileConfigBuilder
 ```xml
 <add name="KeyPerFile"
-    [mode|@prefix|@stripPrefix|tokenPattern|@optional=false]
+    [mode|@prefix|@stripPrefix|tokenPattern|@escapeExpandedValues|@optional=false]
 	(@directoryPath="PathToSourceDirectory")
     [@ignorePrefix="ignore."]
     [keyDelimiter=":"]
@@ -267,7 +274,7 @@ their orchestrated windows containers in this key-per-file manner.
 ### SimpleJsonConfigBuilder
 ```xml
 <add name="SimpleJson"
-    [mode|@prefix|@stripPrefix|tokenPattern|@optional=true]
+    [mode|@prefix|@stripPrefix|tokenPattern|@escapeExpandedValues|@optional=true]
     @jsonFile="~\config.json"
     [@jsonMode="(Flat|Sectional)"]
     type="Microsoft.Configuration.ConfigurationBuilders.SimpleJsonConfigBuilder, Microsoft.Configuration.ConfigurationBuilders.Json" />

samples/SampleWebApp/App_Data/expandTest.json

@@ -0,0 +1,3 @@
+{
+  "expandTestCS": "A & really ' bad \" unescaped < connection > string."
+}

samples/SampleWebApp/App_Data/settings.json

@@ -21,7 +21,7 @@
     "jsonComplex": {
       "setting1": "Complex Setting 1",
       "setting2": "Complex Setting 2",
-      "jsonArrayOfSettings": [ "one", "two", "three"]
+      "jsonArrayOfSettings": [ "one", "two", "three" ]
     }
   }
 }

samples/SampleWebApp/SampleWebApp.csproj

@@ -91,6 +91,7 @@
   </ItemGroup>
   <ItemGroup>
     <Content Include="App_Data\settings.json" />
+    <Content Include="App_Data\expandTest.json" />
     <None Include="packages.config" />
     <None Include="Web.Debug.config">
       <DependentUpon>Web.config</DependentUpon>

samples/SampleWebApp/Web.config

@@ -33,7 +33,8 @@
       <add name="KV4" vaultName="${ConfigBuilderTestKeyVaultName}" mode="Greedy" version="0de51928e49144ce86eb1de9056ac937" type="Microsoft.Configuration.ConfigurationBuilders.AzureKeyVaultConfigBuilder, Microsoft.Configuration.ConfigurationBuilders.Azure, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
 
       <add name="AS_Sub_Test" optional="${Boolean}" type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder, Microsoft.Configuration.ConfigurationBuilders.Environment, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
-  </builders>
+      <add name="ExpTest" mode="Expand" escapeExpandedValues="true" jsonFile="~/App_Data/expandTest.json" jsonMode="Flat" type="Microsoft.Configuration.ConfigurationBuilders.SimpleJsonConfigBuilder, Microsoft.Configuration.ConfigurationBuilders.Json, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
+    </builders>
   </configBuilders>
 
   <appSettings configBuilders="Environment,Secrets,Json,KeyPerFile">
@@ -62,7 +63,9 @@
     <!-- key="Secret3" value="Will be added by KV3:Latest3. IFF already added, will be "updated" by KV1 to Latest3. KV2 and KV4 don't have versions matching this secret." -->
   </appSettings>
 
-  <connectionStrings configBuilders="Json">
+  <connectionStrings configBuilders="Json,ExpTest">
+    <add name="expansionTest" connectionString="${expandTestCS}" />
+    <add name="expandTestCS" connectionString="Only replaced in Strict/Greedy modes. Not Expand."/>
     <add name="jsonConnectionString1" connectionString="Will be replaced by 'Json' in 'Flat' AND 'Sectional' jsonModes, but with different values." />
     <add name="connectionStrings:jsonConnectionString1" connectionString="Will only be replaced by 'Json' in 'Flat' jsonMode." />
     <add name="jsonConnectionString2" connectionString="Will only be replaced by 'Json' in 'Sectional' jsonMode." />

src/Base/KeyValueConfigBuilder.cs

@@ -7,6 +7,7 @@
 using System.Collections.Specialized;
 using System.Text.RegularExpressions;
 using System.Xml;
+using System.Security;
 
 namespace Microsoft.Configuration.ConfigurationBuilders
 {
@@ -23,7 +24,8 @@ public abstract class KeyValueConfigBuilder : ConfigurationBuilder
         public const string stripPrefixTag = "stripPrefix";
         public const string tokenPatternTag = "tokenPattern";
         public const string optionalTag = "optional";
-        #pragma warning restore CS1591 // No xml comments for tag literals.
+        public const string escapeTag = "escapeExpandedValues";
+#pragma warning restore CS1591 // No xml comments for tag literals.
 
         private NameValueCollection _config = null;
         private IDictionary<string, string> _cachedValues;
@@ -50,6 +52,11 @@ public abstract class KeyValueConfigBuilder : ConfigurationBuilder
         public bool Optional { get { EnsureInitialized(); return _optional; } protected set { _optional = value; } }
         private bool _optional = true;
         /// <summary>
+        /// Specifies whether the config builder should cause errors if the backing source cannot be found.
+        /// </summary>
+        public bool EscapeValues { get { EnsureInitialized(); return _escapeValues; } protected set { _escapeValues = value; } }
+        private bool _escapeValues = false;
+        /// <summary>
         /// Gets or sets a regular expression used for matching tokens in raw xml during Greedy substitution.
         /// </summary>
         public string TokenPattern { get { EnsureInitialized(); return _tokenPattern; } protected set { _tokenPattern = value; } }
@@ -113,6 +120,7 @@ protected virtual void LazyInitialize(string name, NameValueCollection config)
             _keyPrefix = UpdateConfigSettingWithAppSettings(prefixTag) ?? _keyPrefix;
             _stripPrefix = (UpdateConfigSettingWithAppSettings(stripPrefixTag) != null) ? Boolean.Parse(config[stripPrefixTag]) : _stripPrefix;
             _optional = (UpdateConfigSettingWithAppSettings(optionalTag) != null) ? Boolean.Parse(config[optionalTag]) : _optional;
+            _escapeValues = (UpdateConfigSettingWithAppSettings(escapeTag) != null) ? Boolean.Parse(config[escapeTag]) : _escapeValues;
 
             _cachedValues = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
             _lazyInitialized = true;
@@ -278,7 +286,7 @@ private XmlNode ExpandTokens(XmlNode rawXml)
 
                     // Same prefix-handling rules apply in expand mode as in strict mode.
                     // Since the key is being completely replaced by the value, we don't need to call UpdateKey().
-                    return GetValueInternal(key) ?? m.Groups[0].Value;
+                    return EscapeValue(GetValueInternal(key)) ?? m.Groups[0].Value;
                 });
 
             XmlDocument doc = new XmlDocument();
@@ -321,6 +329,12 @@ private string TrimPrefix(string fullString)
             return fullString.Substring(KeyPrefix.Length);
         }
 
+        // Maybe this could be virtual? Simple xml escaping should be enough for most folks.
+        private string EscapeValue(string original)
+        {
+            return (_escapeValues && original != null) ? SecurityElement.Escape(original) : original;
+        }
+
         #endregion
         //=========================================================================================================================
     }