Add ConnectionStringSectionHandler2 (#211)

Author: StephenMolloy

README.md

@@ -39,6 +39,11 @@ linked here:
   * Character Mapping - Some config builders have had an internal mapping of characters that might exist in keys in the config file but are illegal in keys at the
         source. As more scenarios come to light and individual prefrences are not always unanimous, V3 instead adds the [`charMap`](docs/KeyValueConfigBuilders.md#charmap) attribute to allow this character
         mapping to work with all **KeyValueConfigBuilders** and to be handled in an easily configurable manner.
+  * `ConnectionStringsSectionHandler2` - A new section handler for the `<connectionStrings>` section has been included in the base package. This new handler will
+        allow updating of both the 'connectionString' attribute as well as the 'providerName' attribute. It does require the builders and source of config data to be
+        aware of this new ability though. The default section handler for the `<connectionStrings>` section has not been updated and remains as it was in previous
+        versions, so apps wishing to take advantage of the new handler will have to wire it up in their config. More details can be found in the
+        [SectionHandlers documentation](docs/SetionHandlers.md#ConnectionStringsSectionHandler2).
 
 ### V2 Updates:
   * Azure App Configuration Support - There is a [new builder](docs/KeyValueConfigBuilders.md#azureappconfigurationbuilder) for drawing values from the new Azure App Configuration service.

docs/SectionHandlers.md

@@ -86,3 +86,36 @@ compiled in a separate assembly in the 'bin' directory. For example:
   </handlers>
 </Microsoft.Configuration.ConfigurationBuilders.SectionHandlers>
 ```
+
+## ConnectionStringsSectionHandler2
+Version 3 of this package suite includes a new section handler for the `<connectionStrings>` section. For maximum compatibility, the
+old section handler is still used by default. Here we will explain how to use this new section handler and how to replace the old one.
+
+The new `ConnectionStringsSectionHandler2` works pretty much like it's non-numbered predecessor. The main difference is, when it
+enumerates through the list of connection strings in the section, it will ask builders to look for values that match
+"&lt;name&gt;:connectionString" and "&lt;name&gt;:providerName" in addition to just "&lt;name&gt;". When updating or inserting
+new `ConnectionStringSettings` items into the configuration collection, values that come from tagged keys will go to the
+appropriate attribute. Values that are found without a tagged key update the 'connectionString' property as they did before.
+
+```xml
+    <connectionStrings configBuilders="StrictBuilder">
+        <add name="strict-cs" connectionString="Will get the value of 'strict-cs' or 'strict-cs:connectionString'"
+                              providerName="Will only get the value of 'strict-cs:providerName'" />
+
+        <!-- Easy to imagine pulling these from a structured json file. -->
+        <add name="token-cs1" connectionString="${tokenCS:connectionString}"
+                              providerName="${tokenCS:providerName}" />
+        <!-- But token mode can be messy. -->
+        <add name="token-cs2" connectionString="${token-names-not-important}"
+                              providerName="${they-can-even-be-tagged-wrong:connectionString}" />
+    </connectionStrings>
+```
+
+One thing to note is that the mechanism for associating a key/value lookup with a specific attribute of connection string entries
+is a simple post-fix to the key. This makes this feature incompatible with versioned keys in Azure Key Vault. Most other cases should
+just work as they did before, with a little extra magic cleanliness when you start using this feature.
+
+An example of this new behavior from `ConnectionStringsSectionHandler2` can be seen in the [SampleConsoleApp](samples/SampleConsoleApp/App.config#L37-L46).
+Or in the [test project](https://github.com/aspnet/MicrosoftConfigurationBuilders/blob/main/test/Microsoft.Configuration.ConfigurationBuilders.Test/ConnectionStringsSectionHandler2Tests.cs).
+The [SampleWebApp](samples/SampleWebApp/Web.config#L38-L41) does not use the new section handler, but it does include some notes about how
+it's resulting connection string collection would look different if it did.

samples/SampleConsoleApp/App.config

@@ -16,12 +16,15 @@
       <add name="Env" type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder, Microsoft.Configuration.ConfigurationBuilders.Environment" />
       <add name="KeyPerFile" mode="Greedy" directoryPath="${SampleItems}/KeyPerFileRoot" type="Microsoft.Configuration.ConfigurationBuilders.KeyPerFileConfigBuilder, Microsoft.Configuration.ConfigurationBuilders.KeyPerFile" />
       <add name="Json" mode="Greedy" jsonMode="Flat" jsonFile="${jsonFile}" type="Microsoft.Configuration.ConfigurationBuilders.SimpleJsonConfigBuilder, Microsoft.Configuration.ConfigurationBuilders.Json" />
+      <add name="JsonCS" mode="Strict" jsonMode="Sectional" jsonFile="${jsonFile}"  type="Microsoft.Configuration.ConfigurationBuilders.SimpleJsonConfigBuilder, Microsoft.Configuration.ConfigurationBuilders.Json" />
       <add name="JsonExpand" mode="Token" jsonMode="Sectional" jsonFile="${jsonFile}"  type="SamplesLib.ExpandWrapper`1[[Microsoft.Configuration.ConfigurationBuilders.SimpleJsonConfigBuilder, Microsoft.Configuration.ConfigurationBuilders.Json]], SamplesLib" />
     </builders>
   </configBuilders>
 
   <Microsoft.Configuration.ConfigurationBuilders.SectionHandlers>
     <handlers>
+      <remove name="DefaultConnectionStringsHandler" />
+      <add name="NewConnectionStringsHandler" type="Microsoft.Configuration.ConfigurationBuilders.ConnectionStringsSectionHandler2, Microsoft.Configuration.ConfigurationBuilders.Base" />
       <add name="ClientSettingsHandler" type="SamplesLib.ClientSettingsSectionHandler, SamplesLib" />
     </handlers>
   </Microsoft.Configuration.ConfigurationBuilders.SectionHandlers>
@@ -31,6 +34,17 @@
     <add key="jsonFile" value="~/../../../SampleWebApp/App_Data/settings.json" />
   </appSettings>
 
+  <connectionStrings configBuilders="JsonCS">
+    <add name="simpleCS" connectionString="A Simple Connection String" providerName="A Simple Provider Name" />
+    <add name="noProvider" connectionString="A Connection String with no providerName" />
+    <add name="jsonConnectionString1" connectionString="" />
+    <!-- In Strict/Greedy mode, this advanced example updates both attributes as expected. -->
+    <!-- In Token mode however, note that only the 'tagged' token works (and it is applied to the wrong attribute here for clear demonstration)
+          because there is no 'jsonAdvConnStr' config value. If there was, the 'connectionString' attribute would be updated in addition
+          to 'providerName.'-->
+    <add name="jsonAdvConnStr" connectionString="${jsonAdvConnStr}" providerName="${jsonAdvConnStr:connectionString}"/>
+  </connectionStrings>
+
   <customSettings configBuilders="Json" />
 
   <expandedSettings configBuilders="JsonExpand">

samples/SampleConsoleApp/Program.cs

@@ -17,6 +17,17 @@ static void Main(string[] args)
             Console.WriteLine("");
             Console.WriteLine("");
 
+            Console.WriteLine("---------- Connection Strings (Advanced Sample) ----------");
+            Console.WriteLine("Name                     ConnectionString                                  ProviderName");
+            Console.WriteLine("------------------------+-------------------------------------------------+--------------------------------------------------");
+            foreach (ConnectionStringSettings cs in ConfigurationManager.ConnectionStrings)
+            {
+                Console.WriteLine($"{cs.Name.PadRight(25)}{cs.ConnectionString.PadRight(50)}{cs.ProviderName}");
+            }
+
+            Console.WriteLine("");
+            Console.WriteLine("");
+
             Console.WriteLine("---------- Custom Settings ----------");
             var customSettings = ConfigurationManager.GetSection("customSettings") as NameValueCollection;
             foreach (string setting in customSettings.Keys)

samples/SampleWebApp/App_Data/settings.json

@@ -14,6 +14,10 @@
     "jsonConnectionString1": "CS1 From ConnectionStrings Json object",
     "specialFeature": {
       "connStr": "Special feature CS From ConnectionStrings Json object"
+    },
+    "jsonAdvConnStr": {
+      "connectionString": "Advanced ConnectionString",
+      "providerName": "Advanced ProviderName"
     }
   },
 

samples/SampleWebApp/Web.config

@@ -17,6 +17,7 @@
       <add name="Secrets" mode="Token" userSecretsFile="${SampleItems}/secrets.xml" type="Microsoft.Configuration.ConfigurationBuilders.UserSecretsConfigBuilder, Microsoft.Configuration.ConfigurationBuilders.UserSecrets" />
       <add name="KeyVault" mode="Greedy" prefix="AppSettings_" stripPrefix="true" vaultName="${KeyVaultTestName}" enabled="${AzureBuildersEnabled}" type="Microsoft.Configuration.ConfigurationBuilders.AzureKeyVaultConfigBuilder, Microsoft.Configuration.ConfigurationBuilders.Azure" />
       <add name="AzConfig" mode="Token" tokenPattern="\[(\w+)\]" endpoint="[AzConfigTestEndpoint]" enabled="[AzureBuildersEnabled]" type="Microsoft.Configuration.ConfigurationBuilders.AzureAppConfigurationBuilder, Microsoft.Configuration.ConfigurationBuilders.AzureAppConfiguration" />
+      <add name="Json2" mode="Token" jsonMode="Sectional" jsonFile="${jsonFile}" type="Microsoft.Configuration.ConfigurationBuilders.SimpleJsonConfigBuilder, Microsoft.Configuration.ConfigurationBuilders.Json" />
     </builders>
   </configBuilders>
 
@@ -31,9 +32,13 @@
     <add key="AzConfigTestEndpoint" value="This comes from an environment variable." />
   </appSettings>
 
-  <connectionStrings configBuilders="Secrets,Json">
+  <connectionStrings configBuilders="Secrets,Json,Json2">
     <add name="connStrFromSecrets" connectionString="${ConnectionString1}" providerName="MyDataProvider" />
     <add name="connectionString1" connectionString="Does not come from secrets in 'Token' mode." />
+    <!-- 'Json2' will replace the connectionString on this in 'Token' mode, or both the CS and providerName in the old 'Expand' mode. -->
+    <!-- Note that both of the jsonAdvConnStr:* values also show up as their own connection strings as a result of the 'Greedy' 'Json' builder.
+          With the new ConnectionStringsSectionHandler2, they would be consolodated into one coherent 'jsonAdvConnStr' entry. -->
+    <add name="jsonTricks-for-Token-or-Expand" connectionString="${jsonAdvConnStr:connectionString}" providerName="${jsonAdvConnStr:providerName}"/>
   </connectionStrings>
 
   <customSettings configBuilders="KeyPerFile,AzConfig" />

samples/SampleWebApp/default.aspx

@@ -14,9 +14,9 @@
         }
         Response.Write("</table><br/><br/>");
 
-        Response.Write("<table border=1><tr><th colspan=2><h2>Connection Strings</h2></th></tr>");
+        Response.Write("<table border=1><tr><th colspan=3><h2>Connection Strings</h2></th></tr>");
         foreach (ConnectionStringSettings cs in WebConfigurationManager.ConnectionStrings) {
-            Response.Write("<tr><td>" + HttpUtility.HtmlEncode(cs.Name) + "</td><td>" + HttpUtility.HtmlEncode(cs.ConnectionString) + "</td></tr>");
+            Response.Write("<tr><td>" + HttpUtility.HtmlEncode(cs.Name) + "</td><td>" + HttpUtility.HtmlEncode(cs.ConnectionString) + "</td><td>" + HttpUtility.HtmlEncode(cs.ProviderName) + "</td></tr>");
         }
         Response.Write("</table><br/><br/>");
 

src/Base/SectionHandler.cs

@@ -212,4 +212,120 @@ public override string TryGetOriginalCase(string requestedKey)
             return base.TryGetOriginalCase(requestedKey);
         }
     }
+
+    /// <summary>
+    /// A class that can be used by <see cref="KeyValueConfigBuilder"/>s to apply key/value config pairs to <see cref="ConnectionStringsSection"/>
+    /// with special 'tagging' to allow updating both the 'connectionString' attribute as well as the 'providerName' attribute.
+    /// </summary>
+    public class ConnectionStringsSectionHandler2 : SectionHandler<ConnectionStringsSection>
+    {
+        private const string connStrNameTag = ":connectionString";
+        private const string providerNameTag = ":providerName";
+
+        private class CSSH2State { public bool UpdateName; public ConnectionStringSettings CS; }
+
+        /// <summary>
+        /// Updates an existing connection string attribute in the assigned <see cref="SectionHandler{T}.ConfigSection"/> with a new name and a new value. The old
+        /// connection string setting can be located using the <paramref name="oldItem"/> parameter. If an old connection string is not found, a new connection
+        /// string should be inserted.
+        /// </summary>
+        /// <param name="newKey">The updated key name for the connection string. May be post-fixed with attribute tag.</param>
+        /// <param name="newValue">The updated value for the connection string.</param>
+        /// <param name="oldKey">The old key name for the connection string, or null. May be post-fixed with attribute tag.</param>
+        /// <param name="oldItem">A reference to the old <see cref="ConnectionStringSettings"/> object obtained by <see cref="KeysValuesAndState"/>, or null.</param>
+        public override void InsertOrUpdate(string newKey, string newValue, string oldKey = null, object oldItem = null)
+        {
+            string tag;
+            (oldKey, tag) = SplitTag(oldKey);
+            (newKey, _) = SplitTag(newKey);
+
+            CSSH2State state = oldItem as CSSH2State;
+            ConnectionStringSettings cs = state?.CS ?? ConfigSection.ConnectionStrings[oldKey] ?? new ConnectionStringSettings();
+
+            // Make sure there are no entries using the old or new name other than this one
+            ConfigSection.ConnectionStrings.Remove(oldKey);
+            ConfigSection.ConnectionStrings.Remove(newKey);
+
+            // Update values and re-add to the collection (no state means 'Greedy' mode where we do want to update)
+            if (state == null || state.UpdateName)
+                cs.Name = newKey;
+            if (tag == providerNameTag)
+                cs.ProviderName = newValue;
+            else
+                cs.ConnectionString = newValue;
+            ConfigSection.ConnectionStrings.Add(cs);
+        }
+
+        /// <summary>
+        /// Gets an <see cref="IEnumerable{T}"/> for iterating over the key/value pairs contained in the assigned <see cref="SectionHandler{T}.ConfigSection"/>. />
+        /// </summary>
+        /// <returns>An enumerator over tuples where the values of the tuple are the existing name for each connection string, the value of 
+        /// the connection string or the value of the provider name, and a reference to the <see cref="ConnectionStringSettings"/> object itself
+        /// which will be returned to us as a reference state object when updating the config record.</returns>
+        public override IEnumerable<Tuple<string, string, object>> KeysValuesAndState()
+        {
+            // The ConnectionStrings collection may change on us while we enumerate. :/
+            ConnectionStringSettings[] connStrs = new ConnectionStringSettings[ConfigSection.ConnectionStrings.Count];
+            ConfigSection.ConnectionStrings.CopyTo(connStrs, 0);
+
+            foreach (ConnectionStringSettings cs in connStrs)
+            {
+                // Greedy mode doesn't enumerate here. It just goes direct to 'InsertOrUpdate', which preserves non-tagged
+                //  behavior via null-tag awareness.
+                // Strict mode will need us to lookup a non-tagged value in addition to tagged values in order to
+                //  remain as compatible as possible with the simple old model.
+                // Token mode is trickier. See step-by-step notes.
+
+                string originalName = cs.Name;
+                string originalCS = cs.ConnectionString;
+
+                // In 'Token' mode, this will replace tokens in 'name' and 'connectionString'.
+                yield return Tuple.Create(originalName, originalCS, (object)new CSSH2State() { UpdateName = true, CS = cs }) ;
+
+                // In 'Token' mode, this will re-replace tokens in 'connectionString' only. Conceptually a no-op, except we
+                //  don't know which mode we're in so we can't technically skip this re-replacement. We also can't skip this step because
+                //  it is required for 'Strict' mode. (It will also re-lookup tokens in 'name', but we are able to skip replacing those
+                //  here, since using _this_ tagged 'name' string might not be faithful to the original non-tagged 'name'.)
+                // Also, re-lookups for tokens should be cached and free, since the tokens inside the 'name' didn't change when tagged.
+                yield return Tuple.Create(originalName + connStrNameTag, originalCS, (object)new CSSH2State() { UpdateName = false, CS = cs });
+
+                // In 'Token' mode, this will replace tokens in 'providerName' only. Same deal with 'name' as the previous step. However,
+                //  the tag on the original name is important, as that is the only way we will know to work on 'providerName' instead of 'name'
+                //  in 'InsertOrUpdate'.
+                yield return Tuple.Create(originalName + providerNameTag, cs.ProviderName, (object)new CSSH2State() { UpdateName = false, CS = cs });
+            }
+        }
+
+        /// <summary>
+        /// Attempt to lookup the original key casing so it can be preserved during greedy updates which would otherwise lose
+        /// the original casing in favor of the casing used in the config source.
+        /// </summary>
+        /// <param name="requestedKey">The key to find original casing for.</param>
+        /// <returns>A string containing the key with original casing from the config section, or the key as passed in if no match
+        /// can be found.</returns>
+        public override string TryGetOriginalCase(string requestedKey)
+        {
+            if (!String.IsNullOrWhiteSpace(requestedKey))
+            {
+                var connStr = ConfigSection.ConnectionStrings[requestedKey];
+                if (connStr != null)
+                    return connStr.Name;
+            }
+
+            return base.TryGetOriginalCase(requestedKey);
+        }
+
+        private (string, string) SplitTag(string key)
+        {
+            if (key != null)
+            {
+                if (key.EndsWith(connStrNameTag))
+                    return (key.Remove(key.Length - connStrNameTag.Length), connStrNameTag);
+                else if (key.EndsWith(providerNameTag))
+                    return (key.Remove(key.Length - providerNameTag.Length), providerNameTag);
+            }
+
+            return (key, null);
+        }
+    }
 }