Merge pull request #44 from aspnet/Doc-Updates

Doc updates and nupkg packing refinement.

Author: StephenMolloy

README.md

@@ -45,7 +45,7 @@ public class AzureKeyVaultConfigBuilder : KeyValueConfigBuilder
         /// <param name="config">A collection of the name/value pairs representing builder-specific attributes specified in the configuration for this provider.</param>
         protected override void LazyInitialize(string name, NameValueCollection config)
         {
-            // Default 'Optional' to false. base.Initialize() will override if specified in config.
+            // Default 'Optional' to false. base.LazyInitialize() will override if specified in config.
             Optional = false;
 
             base.LazyInitialize(name, config);
@@ -133,12 +133,22 @@ public override ICollection<KeyValuePair<string, string>> GetAllValues(string pr
             return d;
         }
 
+        /// <summary>
+        /// Makes a determination about whether the input key is valid for this builder and backing store.
+        /// </summary>
+        /// <param name="key">The string to be validated. May be partial.</param>
+        /// <returns>True if the string is valid. False if the string is not a valid key.</returns>
         public override bool ValidateKey(string key)
         {
             // Key Vault only allows alphanumerics and '-'. This builder also allows for one '/'.
             return Regex.IsMatch(key, "^[a-zA-Z0-9-]+(/?[a-zA-Z0-9-]+)?$");
         }
 
+        /// <summary>
+        /// Transforms the raw key to a new string just before updating items in Strict and Greedy modes.
+        /// </summary>
+        /// <param name="rawKey">The key as read from the incoming config section.</param>
+        /// <returns>The key string that will be left in the processed config section.</returns>
         public override string UpdateKey(string rawKey)
         {
             // Remove the version segment if it's there.

src/Azure/AzureKeyVaultConfigBuilder.cs

@@ -27,6 +27,7 @@ public abstract class KeyValueConfigBuilder : ConfigurationBuilder
 
         private NameValueCollection _config = null;
         private IDictionary<string, string> _cachedValues;
+        private bool _lazyInitializeStarted = false;
         private bool _lazyInitialized = false;
         private bool _greedyInitialized = false;
         private bool _inAppSettings = false;
@@ -74,9 +75,9 @@ public abstract class KeyValueConfigBuilder : ConfigurationBuilder
         /// <returns>True if the string is valid. False if the string is not a valid key.</returns>
         public virtual bool ValidateKey(string key) { return true; }
         /// <summary>
-        /// Transforms the raw key read from the config file to a new string when updating items in Strict and Greedy modes.
+        /// Transforms the raw key to a new string just before updating items in Strict and Greedy modes.
         /// </summary>
-        /// <param name="rawKey">The key as read from the incomming config section.</param>
+        /// <param name="rawKey">The key as read from the incoming config section.</param>
         /// <returns>The key string that will be left in the processed config section.</returns>
         public virtual string UpdateKey(string rawKey) { return rawKey; }
 
@@ -107,6 +108,7 @@ public override void Initialize(string name, NameValueCollection config)
         protected virtual void LazyInitialize(string name, NameValueCollection config)
         {
             // Use pre-assigned defaults if not specified. Non-freeform options should throw on unrecognized values.
+            _lazyInitializeStarted = true;
             _tokenPattern = config[tokenPatternTag] ?? _tokenPattern;
             _keyPrefix = UpdateConfigSettingWithAppSettings(prefixTag) ?? _keyPrefix;
             _stripPrefix = (UpdateConfigSettingWithAppSettings(stripPrefixTag) != null) ? Boolean.Parse(config[stripPrefixTag]) : _stripPrefix;
@@ -116,11 +118,16 @@ protected virtual void LazyInitialize(string name, NameValueCollection config)
             _lazyInitialized = true;
         }
 
+        /// <summary>
+        /// Perform token substitution on a config parameter passed through builder initialization using token values from appSettings.
+        /// </summary>
+        /// <param name="configName">The name of the parameter to be retrieved.</param>
+        /// <returns>The updated parameter value if it exists. Null otherwise.</returns>
         protected string UpdateConfigSettingWithAppSettings(string configName)
         {
             string configValue = _config[configName];
 
-            if (String.IsNullOrWhiteSpace(configValue))
+            if (!_lazyInitializeStarted || String.IsNullOrWhiteSpace(configValue))
                 return configValue;
 
             // If we are processing appSettings in ProcessConfigurationSection(), then we can use that. Other config builders in

src/Base/KeyValueConfigBuilder.cs

@@ -13,15 +13,49 @@ internal interface ISectionHandler
         IEnumerator<KeyValuePair<string, object>> GetEnumerator();
     }
 
+    /// <summary>
+    /// A class to be used by <see cref="KeyValueConfigBuilder"/>s to apply key/value config pairs to .Net configuration sections.
+    /// </summary>
+    /// <typeparam name="T">The type of <see cref="ConfigurationSection"/> that the implementing class can process.</typeparam>
     public abstract class SectionHandler<T> : ISectionHandler where T : ConfigurationSection
     {
+        /// <summary>
+        /// The <see cref="ConfigurationSection"/> instance being processed by this <see cref="SectionHandler{T}"/>.
+        /// </summary>
         public T ConfigSection { get; private set; }
-        public abstract void InsertOrUpdate(string newKey, string newValue, string oldKey = null, object oldItem = null);
+
+        /// <summary>
+        /// Gets an <see cref="IEnumerator{T}"/> that iterates over the key/value pairs contained in the assigned <see cref="ConfigSection"/>. />
+        /// </summary>
+        /// <returns>An enumerator over pairs consisting of the existing key for a config value in the config section, and an object reference
+        /// for the key/value pair to be passed in to <see cref="InsertOrUpdate(string, string, string, object)"/> while processing the config section.</returns>
         public abstract IEnumerator<KeyValuePair<string, object>> GetEnumerator();
+
+        /// <summary>
+        /// Updates an existing config value in the assigned <see cref="ConfigSection"/> with a new key and a new value. The old config value
+        /// can be located using the <paramref name="oldKey"/> or <paramref name="oldItem"/> parameters. If an old config value is not
+        /// found, a new config value should be inserted.
+        /// </summary>
+        /// <param name="newKey">The updated key name for the config item.</param>
+        /// <param name="newValue">The updated value for the config item.</param>
+        /// <param name="oldKey">The old key name for the config item, or null.</param>
+        /// <param name="oldItem">A reference to the old key/value pair obtained by <see cref="GetEnumerator"/>, or null.</param>
+        public abstract void InsertOrUpdate(string newKey, string newValue, string oldKey = null, object oldItem = null);
     }
 
+    /// <summary>
+    /// A class that can be used by <see cref="KeyValueConfigBuilder"/>s to apply key/value config pairs to <see cref="AppSettingsSection"/>.
+    /// </summary>
     public class AppSettingsSectionHandler : SectionHandler<AppSettingsSection>
     {
+        /// <summary>
+        /// Updates an existing app setting in the assigned <see cref="SectionHandler{T}.ConfigSection"/> with a new key and a new value. The old setting
+        /// can be located using the <paramref name="oldKey"/> parameter. If an old setting is not found, a new setting should be inserted.
+        /// </summary>
+        /// <param name="newKey">The updated key name for the app setting.</param>
+        /// <param name="newValue">The updated value for the app setting.</param>
+        /// <param name="oldKey">The old key name for the app setting, or null.</param>
+        /// <param name="oldItem">The old key name for the app setting, or null., or null.</param>
         public override void InsertOrUpdate(string newKey, string newValue, string oldKey = null, object oldItem = null)
         {
             if (newValue != null)
@@ -34,6 +68,10 @@ public override void InsertOrUpdate(string newKey, string newValue, string oldKe
             }
         }
 
+        /// <summary>
+        /// Gets an <see cref="IEnumerator{T}"/> that iterates over the key/value pairs contained in the assigned <see cref="SectionHandler{T}.ConfigSection"/>. />
+        /// </summary>
+        /// <returns>An enumerator over pairs where both values of the pair are the existing key for each setting in the appSettings section.</returns>
         public override IEnumerator<KeyValuePair<string, object>> GetEnumerator()
         {
             // Grab a copy of the keys array since we are using 'yield' and the Settings collection may change on us.
@@ -43,14 +81,26 @@ public override IEnumerator<KeyValuePair<string, object>> GetEnumerator()
         }
     }
 
+    /// <summary>
+    /// A class that can be used by <see cref="KeyValueConfigBuilder"/>s to apply key/value config pairs to <see cref="ConnectionStringsSection"/>.
+    /// </summary>
     public class ConnectionStringsSectionHandler : SectionHandler<ConnectionStringsSection>
     {
-        public override void InsertOrUpdate(string newKey, string newValue, string oldKey = null, object oldValue = null)
+        /// <summary>
+        /// Updates an existing connection string in the assigned <see cref="SectionHandler{T}.ConfigSection"/> with a new name and a new value. The old
+        /// connection string 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.</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.</param>
+        /// <param name="oldItem">A reference to the old <see cref="ConnectionStringSettings"/> object obtained by <see cref="GetEnumerator"/>, or null.</param>
+        public override void InsertOrUpdate(string newKey, string newValue, string oldKey = null, object oldItem = null)
         {
             if (newValue != null)
             {
                 // Preserve the old entry if it exists, as it might have more than just name/connectionString attributes.
-                ConnectionStringSettings cs = (oldValue as ConnectionStringSettings) ?? new ConnectionStringSettings();
+                ConnectionStringSettings cs = (oldItem as ConnectionStringSettings) ?? new ConnectionStringSettings();
 
                 // Make sure there are no entries using the old or new name other than this one
                 ConfigSection.ConnectionStrings.Remove(oldKey);
@@ -63,6 +113,11 @@ public override void InsertOrUpdate(string newKey, string newValue, string oldKe
             }
         }
 
+        /// <summary>
+        /// Gets an <see cref="IEnumerator{T}"/> that iterates over the key/value pairs contained in the assigned <see cref="SectionHandler{T}.ConfigSection"/>. />
+        /// </summary>
+        /// <returns>An enumerator over pairs where the key is the existing name for each setting in the connectionStrings section, and the value
+        /// is a reference to the <see cref="ConnectionStringSettings"/> object referred to by that name.</returns>
         public override IEnumerator<KeyValuePair<string, object>> GetEnumerator()
         {
             // The ConnectionStrings collection may change on us while we enumerate. :/

src/Base/SectionHandler.cs

@@ -6,16 +6,25 @@
 
 namespace Microsoft.Configuration.ConfigurationBuilders
 {
-    public class SectionHandlersSection : ConfigurationSection
+    /// <summary>
+    /// Provides programmatic access to the 'sectionHandlers' config section. This class can't be inherited.
+    /// </summary>
+    public sealed class SectionHandlersSection : ConfigurationSection
     {
         static readonly string handlerSectionName = "Microsoft.Configuration.ConfigurationBuilders.SectionHandlers";
 
+        /// <summary>
+        /// Gets the collection of <see cref="SectionHandler{T}" />s defined for processing config sections with <see cref="KeyValueConfigBuilder"/>s./>
+        /// </summary>
         [ConfigurationProperty("handlers", IsDefaultCollection = true, Options = ConfigurationPropertyOptions.IsDefaultCollection)]
-        protected ProviderSettingsCollection Handlers
+        public ProviderSettingsCollection Handlers
         {
             get { return (ProviderSettingsCollection)base["handlers"]; }
         }
 
+        /// <summary>
+        /// Used to initialize a default set of section handlers. (For the appSettings and connectionStrings sections.)
+        /// </summary>
         protected override void InitializeDefault()
         {
             // This only runs once at the top "parent" level of the config stack. If there is already an

src/Base/SectionHandlerSection.cs

@@ -32,7 +32,8 @@ $keyValueCommonParameters = @(
 		[ParameterDescription]@{ Name="mode"; IsRequired=$false },
 		[ParameterDescription]@{ Name="prefix"; IsRequired=$false },
 		[ParameterDescription]@{ Name="stripPrefix"; IsRequired=$false },
-		[ParameterDescription]@{ Name="tokenPattern"; IsRequired=$false });
+		[ParameterDescription]@{ Name="tokenPattern"; IsRequired=$false },
+		[ParameterDescription]@{ Name="optional"; IsRequired=$false });
 
 
 function CommonInstall($builderDescription) {

src/packages/ConfigurationBuilders.Base.nupkg/shared/tools/Net471/KeyValueConfigBuildersCommon.ps1

@@ -13,8 +13,7 @@ $jsonConfigBuilder = [BuilderDescription]@{
 	DefaultName="SimpleJson";
 	AllowedParameters=@( $keyValueCommonParameters +
 		[ParameterDescription]@{ Name="jsonFile"; IsRequired=$true; DefaultValue="~/App_Data/settings.json" },
-		[ParameterDescription]@{ Name="jsonMode"; IsRequired=$false },
-		[ParameterDescription]@{ Name="optional"; IsRequired=$false });
+		[ParameterDescription]@{ Name="jsonMode"; IsRequired=$false });
 }
 
 CommonInstall $jsonConfigBuilder

src/packages/ConfigurationBuilders.Json.nupkg/tools/Net471/Install.ps1

@@ -14,8 +14,7 @@ $keyPerFileConfigBuilder = [BuilderDescription]@{
 	AllowedParameters=@( $keyValueCommonParameters +
 		[ParameterDescription]@{ Name="directoryPath"; IsRequired=$true; DefaultValue="[PathToSourceDirectory]" },
 		[ParameterDescription]@{ Name="keyDelimiter"; IsRequired=$false },
-		[ParameterDescription]@{ Name="ignorePrefix"; IsRequired=$false },
-		[ParameterDescription]@{ Name="optional"; IsRequired=$false });
+		[ParameterDescription]@{ Name="ignorePrefix"; IsRequired=$false });
 }
 
 CommonInstall $keyPerFileConfigBuilder

src/packages/ConfigurationBuilders.KeyPerFile.nupkg/tools/Net471/Install.ps1

@@ -14,8 +14,7 @@ $secretsConfigBuilder = [BuilderDescription]@{
 	DefaultName="Secrets";
 	AllowedParameters=@( $keyValueCommonParameters +
 		[ParameterDescription]@{ Name="userSecretsId"; IsRequired=$false; DefaultValue=$userSecretsId },
-		[ParameterDescription]@{ Name="userSecretsFile"; IsRequired=$false },
-		[ParameterDescription]@{ Name="optional"; IsRequired=$false });
+		[ParameterDescription]@{ Name="userSecretsFile"; IsRequired=$false });
 }
 
 CommonInstall $secretsConfigBuilder

src/packages/ConfigurationBuilders.UserSecrets.nupkg/tools/Net471/Install.ps1

@@ -24,21 +24,23 @@
          Update package and file without touching assembly, except for major releases.
     -->
     <BuildQuality Condition="'$(BuildQuality)' == ''">preview</BuildQuality>
+    <VersionStartYear Condition="'$(VersionStartYear)' == ''">2019</VersionStartYear>
     <VersionMajor>2</VersionMajor>
     <VersionMinor>0</VersionMinor>
     <VersionRevision>0</VersionRevision>
     <VersionRelease>0</VersionRelease>
-    <VersionRelease Condition="'$(BuildQuality)' != 'rtm'">$(VersionRelease)-$(BuildQuality)</VersionRelease>
-    <VersionStartYear Condition="'$(VersionStartYear)' == ''">2019</VersionStartYear>
+    <VersionBuild Condition="'$(VersionBuild)' == '' OR '$(VersionBuild)' == '0'">$([MSBuild]::Add(1, $([MSBuild]::Subtract($([System.DateTime]::Now.Year), $(VersionStartYear)))))$([System.DateTime]::Now.ToString("MMdd"))</VersionBuild>
   </PropertyGroup>
 
   <PropertyGroup Label="NuGet package dependencies">
     <NuGetPackageVersion>$(VersionMajor).$(VersionMinor).$(VersionRelease)</NuGetPackageVersion>
     <NuGetPackageBaseDependencyVersion>$(VersionMajor).$(VersionMinor).$(VersionRelease)</NuGetPackageBaseDependencyVersion>
   </PropertyGroup>
 
-  <PropertyGroup Condition="'$(MSBuildProjectExtension)' == '.nuproj'">
-    <NuGetPackageVersion Condition="'$(UpdateNightlyPackages)' == 'true'">$(NuGetPackageVersion)-b$(VersionBuild)</NuGetPackageVersion>
+  <PropertyGroup Label="Prerelease version adjustments" Condition="'$(BuildQuality)' != 'rtm'">
+    <VersionRelease>$(VersionRelease)-$(BuildQuality)</VersionRelease>
+    <NuGetPackageVersion>$(VersionMajor).$(VersionMinor).$(VersionRelease)$(VersionBuild)</NuGetPackageVersion>
+    <NuGetPackageBaseDependencyVersion>$(VersionMajor).$(VersionMinor).$(VersionRelease)$(VersionBuild)</NuGetPackageBaseDependencyVersion>
   </PropertyGroup>
 
   <!-- Default properties -->