Refresh docs for V3 update. (#192)

Author: StephenMolloy

MicrosoftConfigurationBuilders.sln

@@ -93,6 +93,15 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SampleConsoleApp", "samples
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SampleSectionHandlers", "samples\SampleSectionHandlers\SampleSectionHandlers.csproj", "{B3F1C0AD-957B-4453-A830-F104FE368BC4}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{905D083F-6414-4DEA-9779-76C8A2518F8D}"
+	ProjectSection(SolutionItems) = preProject
+		docs\CustomConfigBuilders.md = docs\CustomConfigBuilders.md
+		docs\FAQ.md = docs\FAQ.md
+		docs\Intro.md = docs\Intro.md
+		docs\KeyValueConfigBuilders.md = docs\KeyValueConfigBuilders.md
+		docs\SectionHandlers.md = docs\SectionHandlers.md
+	EndProjectSection
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU

README.md

@@ -0,0 +1,80 @@
+# Implementing More Key/Value Config Builders
+
+If you don't see a config builder here that suits your needs, you can write your own. Referencing the `Basic` nuget package for this project will get you the base upon which
+all of these builders inherit. Most of the heavy-ish lifting and consistent behavior across key/value config builders comes from this base. Take a look at the code for more
+detail, but in many cases implementing a custom key/value config builder in this same vein is as easy as inheriting the base, and implementing two basic methods.
+```CSharp
+using Microsoft.Configuration.ConfigurationBuilders;
+
+public class CustomConfigBuilder : KeyValueConfigBuilder
+{
+    public override string GetValue(string key)
+    {
+        // Key lookup should be case-insensitive, because most key/value collections in .Net config sections are as well.
+        return "Value for given key, or null.";
+    }
+
+    public override ICollection<KeyValuePair<string, string>> GetAllValues(string prefix)
+    {
+        // Populate the return collection a little more smartly. ;)
+        return new Dictionary<string, string>() { { "one", "1" }, { "two", "2" } };
+    }
+}
+```
+
+Additionally, there are a few virtual methods that you can take advantage of for more advanced techniques.
+```CSharp
+public class CustomConfigBuilder : KeyValueConfigBuilder
+{
+        public override void Initialize(string name, NameValueCollection config)
+        {
+            // Use this initializer only for things that absolutely must be read from
+            // the 'config' collection immediately upon creation.
+            // AppSettings parameter substitution is not available at this point.
+            // Use LazyInitialize(string, NameValueCollection) instead whenever possible.
+        }
+
+        protected override void LazyInitialize(string name, NameValueCollection config)
+        {
+            // Use this for things that don't need to be initialized until just before
+            //   config values are retrieved.
+            //
+            // *First, set the default values for 'Enabled' and 'CharacterMap' if
+            //   different from the base.
+            //
+            // *Second, be sure to call 'base.LazyInitialize(name, config)'. AppSettings
+            //   parameter substitution via 'UpdateConfigSettingWithAppSettings(parameterName)'
+            //   will be available after that call.
+            //
+            // *Third, check the value of 'Enabled' to see if there is any need to continue.
+            //
+            // *Lastly, read any additional parameters and do any other tasks needed
+            //   in preparation for retrieving config values.
+        }
+
+        public override bool MapKey(string key)
+        {
+            // If you know the format of the key pulled from *.config files is going to be invalid, but you
+            // are able to translate the bad format to a known good format to get a value from your
+            // config source, use this method.
+            // Ex) AppSettings are commonly named things like "area:feature", but the ':' is not a legal
+            //    character for key names in Azure Key Vault. MapKey() can help translate the ':' to a
+            //    '-' in this case, which will allow the ability to look up a config value for this appSetting
+            //    in Key Vault, even though it's original key name is not valid in Key Vault.
+        }
+
+        public override bool ValidateKey(string key)
+        {
+            // A no-op by default. If your backing storage cannot handle certain characters, this is a one-stop
+            // place for screening key names. It is particularly helpful in `Strict` and `Token` modes where
+            // key names for lookup are taken from *.config files and could potentially contain invalid
+            // characters that cause exceptions in the backing config store.
+        }
+
+        public override string UpdateKey(string rawKey)
+        {
+            // Just before replacing retrieved values in a config section, this method gets called.
+            // 'AzureKeyVaultConfigBuilder' uses this override to strip version tags from keys.
+        }
+}
+```

docs/CustomConfigBuilders.md

@@ -0,0 +1,156 @@
+# MicrosoftConfigurationBuilders FAQ
+
+TODO - search for 'expand'
+We get a lot of questions about `KeyValueConfigBuilders` - and Configuration Builders in general. Here are
+some of the most frequent along with answers that are hopefully helpful.
+
+
+<details>
+  <summary><a name="expand"><b>Why did you get rid of 'Expand' mode?</b></a></summary>
+  
+  Because 'Expand' mode operated in the 'ProcessRawXml' phase of configuration building, while the other
+  modes all operate in 'ProcessConfigurationSection.' It was a bit of a balancing act trying to develop
+  features that work across both phases - a challenge which is sometimes quite difficult given the lack of
+  information we have about the section we are processing in 'ProcessRawXml.'
+  
+  For example, V3 of these builders tries to accomodate 'ConfigurationManager.OpenConfiguration()'
+  scenarios where apps want to read a config file that is not their own. In these cases, we need to
+  know information about the file and section we are processing that we just can't know in the
+  'ProcessRawXml' phase. Another example is the [parameters from appSettings](KeyValueConfigBuilders.md#appsettings-parameters)
+  feature which was disabled in 'Expand' mode while processing the appSettings section, but can
+  still be used somewhat functionally when executing any of the modes that operate in 'ProcessConfigurationSection.'
+
+  To make things simpler across the board, 'Expand' mode was replaced with 'Token' mode which should
+  operate in a fairly similar manner with the added benefit of being less prone to producing invalid
+  XML to muck things up. :smiley:
+</details>
+
+<details>
+  <summary><a name="newhandler"><b>Can you add a `SectionHandler` for section `XYZ?`</b></a></summary>
+  
+  We have included default `SectionHandlers` for `<appSettings>` and `<connectionStrings>` because they
+  are by far the most commonly used "key/value" config sections. But we introduced the `SectionHandler<T>`
+  API to allow for more sections to be processed.
+
+  We don't currently feel that there are any other sections out there that have enough demand to
+  warrant including a default section handler in the base package that everybody is required to use.
+  That does not mean that section handlers for other sections is not ever a valid scenario, and you
+  are of course welcome and encouraged to leverage the section handler feature if it suits your needs.
+  That is why we introduced the feature afterall.
+</details>
+
+<details>
+  <summary><a name="applicationsettings"><b>Can you add a `SectionHandler` for the client `ApplicationSettings` section?</b></a></summary>
+  
+  See [above](#newhandler). `ApplicationSettings` is less commonly used. But more problematically, it
+  isn't really a standard .Net configuration section like it appears to be on first glance. The classes
+  that support ApplicationSettings provide a strict and strongly typed window into what looks like a
+  standard configuration section in your app.config file. While we can easily write a section handler
+  for the `ClientSettingsSection` ([example](../samples/SampleSectionHandlers/ClientSettingsSectionHandler.cs))
+  it won't integrate into the ApplicationSettings framework seamlessly like one might expect. The
+  ApplicationSetting framework has already determined the number and names (including casing, which
+  is problematic in 'Greedy' mode) of all the settings it will present before the base configuration
+  system even gets a crack at reading from the config file. So you can't *add* new values with 'Greedy'
+  mode, and you can't override existing values in 'Greedy' mode if you don't properly match
+  casing - despite the fact that ApplicationSettings is supposed to be case-insensitive.
+
+  If you wish, you can use the [sample section handler](../samples/SampleSectionHandlers/ClientSettingsSectionHandler.cs)
+  to process ApplicationSettings in your application, but know that the use case is rather limited.
+  It will work in 'Strict' mode... and maybe require some prodding to force the ApplicationSettings
+  framework to forget the settings it's seen before and decide to look back into the config file to
+  get new values.
+
+  You can read more about the architecture of the AppliationSettings framework [here](https://docs.microsoft.com/en-us/dotnet/desktop/winforms/advanced/application-settings-architecture?view=netframeworkdesktop-4.8)
+  to see how it builds layers on top of the standard config system that often obscure any changes or
+  additional settings that appear in the `ClientSettingsSection` but won't be seen in
+  `MyApp.Properties.Settings`. That set of articles is also a good starting point for learning
+  about `SettingsProvider` and how that might be leveraged to accomplish configuration injection
+  through a different mechanism in the case when applications must use ApplicationSettings.
+</details>
+
+<details>
+  <summary><a name="azureappservices"><b>Do ConfigBuilders break the 'Application Settings' feature of Azure AppServices?</b></a></summary>
+  
+  Maybe a little? It does appear that adding a 'configBuilders' tag to your 'appSettings' or 'connectionStrings'
+  sections confuses the injection logic for the Azure AppServices "Application Settings" feature. I do not
+  have any insight as to why that is other than to say that the two features "grew up" contemporaneously, so
+  they were probably not aware that configBuilders could exist.
+
+  But all is not lost. The "Application Settings" feature injects all it's values into the environment of
+  the service. So while using ConfigBuilders might interfere with the automatic injection of those values,
+  you can also use ConfigBuilders to pull those values back in. See [this issue comment](#133#issuecomment-1049520479)
+  for more details.
+</details>
+
+<details>
+  <summary><a name="iisschema"><b>Why does IIS/inetmgr complain about configBuilders?</b></a></summary>
+  
+  Because IIS config tools are old and cranky, just like the old .Net config system wanted them to be. :smiling_imp:
+
+  The old .Net config system is supposed to be quite rigid and super-strongly typed. So when IIS developed
+  tools to work with config, they took steps to ensure they didn't break folks by creating invalid configuration.
+  In particular, they decided to use XML schema's to ensure the XML they save is on the up-and-up. (Just
+  like Visual Studio does. But Visual Studio gets updated quite a bit more frequently than IIS tools and
+  has a lower bar for fixing nagging bugs that have a workaround - and was therefore better equipped to
+  change with the times when .Net config added new features and sections. Also, failing schema validation
+  in Visual Studio simply resulted in red squiggles instead of error dialogs. :frowning:)
+
+  The workaround is really quite simple, but it isn't something we can do in these packages. As suggested
+  in #126, simply add a schema file for IIS to help it understand that configBuilders are ok on some
+  sections.
+
+  `%systemroot%\system32\inetsrv\config\schema\configBuilders_schema.xml`
+  ```xml
+<configSchema>
+  <sectionSchema name="appSettings">
+      <attribute name="configBuilders" type="string"/>
+  </sectionSchema>
+  <sectionSchema name="connectionStrings">
+      <attribute name="configBuilders" type="string"/>
+  </sectionSchema>
+</configSchema>
+  ```
+
+</details>
+
+<details>
+  <summary><a name="windowscontainers"><b>My config builder isn't working in my Windows container.</b></a></summary>
+  
+  That's a statement, not a question. But here's a likely explanation.
+
+  Windows containers only modify the environment block of the EntryPoint process. So if your application
+  is running as a service (like IIS/ASP.Net apps) or some other process not directly created by the
+  EntryPoint, any environment variables set when starting the container will not be visible to your
+  app.
+
+  To work around this issue, [ASP.Net](https://github.com/microsoft/dotnet-framework-docker/tree/main/src/aspnet)
+  and [IIS](https://github.com/microsoft/iis-docker) container images rely on a `ServiceMonitor.exe`
+  utility to be the entry point for the container, and this utility proactively modifies the environment
+  of the worker process with any additional environment variables passed to docker run.
+
+  For IIS/ASP.Net workloads, do try to use an IIS/ASP.Net derived container that uses `ServiceMonitor.exe.`
+  For other workloads, try making your app the EntryPoint, or try a similar approach to how IIS/ASP.Net
+  handle this... possibly even leveraging [ServiceMonitor.exe](https://github.com/Microsoft/IIS.ServiceMonitor)
+  itself.
+</details>
+
+<details>
+  <summary><a name="vstyperes"><b>Why do I get an error in Visual Studio when I switch my web app to use IIS instead of IISExpress?</b></a></summary>
+  
+  Many reasons. The gist of the situation is this... When you switch your web application to run in IIS
+  instead of IISExpress, Visual Studio tries to read your config file to parse connection strings. I
+  believe it's looking for 'LocalDB', but that's not really important. Your web app's config file is
+  obviously not part of the process configuration for devenv.exe, so VS opens it via
+  `ConfigurationManager.OpenConfiguration()` or something similar. Prior to V3, this was likely to
+  result in failures in many of these key/value config builders if they were applied to the
+  `<connectionStrings>` section.
+
+  In V3, we handle the `ConfigurationManager.OpenConfiguration()` scenario better, but we can still
+  get tripped up by the insanely complicated way Visual Studio manages reference binding. As a result,
+  there may be version mis-matches when trying to load some builders. The Azure builders seem particularly
+  vulnerable to this. I haven't found a good way to deal with this.
+
+  **However,** even though the error appears in a scary dialog box, it does not affect the behavior of
+  your application. When running/debugging your app on local IIS, the config builders are still able to
+  execute as expected.
+</details>