3.1 preview1 (#276)

* Rev to 3.1

* Semver update - Allow differing minor versions between packages.

* pipeline update

* Do a preview release first.

* Show pipeline as a solution file.

Author: StephenMolloy

MicrosoftConfigurationBuilders.sln

@@ -37,6 +37,7 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Test", "test\Microsoft.Conf
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{91E7BC05-1980-48F2-B3F4-CE56EB3D114F}"
 	ProjectSection(SolutionItems) = preProject
+		azure-pipeline\azure-pipeline.yml = azure-pipeline\azure-pipeline.yml
 		tools\MicrosoftConfigurationBuilders.settings.targets = tools\MicrosoftConfigurationBuilders.settings.targets
 		README.md = README.md
 	EndProjectSection

README.md

@@ -14,6 +14,14 @@ For more information about Configuration Builders and the features and builders
 
 
 <a name="updates"></a>
+### V3.1 Updates:
+  * Added Snapshot capabilities to the [`AzureAppConfigurationBuilder`](docs/KeyValueConfigBuilders.md#azureappconfigurationbuilder).
+  * Added ability to provide "[default values](docs/KeyValueConfigBuilders.md#tokenPattern)" in `Token` mode.
+  * Fixed bug with rooted-paths and `Utils.MapPath` in ASP.Net scenarios.
+  * Fixed `GetCredential()` and related option-overload issues in [`AzureAppConfigurationBuilder`](docs/KeyValueConfigBuilders.md#azureappconfigurationbuilder).
+  * Auth failures are "optional" for [Azure Config Builders](docs/KeyValueConfigBuilders.md#azure-config-builders).
+  * Fixed [`AzureAppConfigurationBuilder`](docs/KeyValueConfigBuilders.md#azureappconfigurationbuilder) bug with key filters in `Strict` mode.
+
 ### V3 Updates:
   * :warning: ***Breaking Change*** - `Expand` mode is gone. It has been [replaced by `Token` mode](docs/KeyValueConfigBuilders.md#mode).
   * `Utils.MapPath` - This was somewhat broken in ASP.Net scenarios previously. It should now reliably go against `Server.MapPath()` in ASP.Net scenarios. It has also been updated to fall back against the directory of the config file being processed when resolving the app root in the case of a `Configuration` object being created by `ConfigurationManager.OpenConfiguration*` API's rather than being part of a fully-initialized runtime configuration stack.

azure-pipeline/azure-pipeline.yml

@@ -157,15 +157,15 @@ extends:
           displayName: Verify Signed Packages
           inputs:
             TargetFolder: $(Build.SourcesDirectory)\.binaries\verify\packages
-            WhiteListPathForCerts: tools/.verif.whitelist
+            WhiteListPathForCerts: $(Build.SourcesDirectory)\tools\.verif.whitelist
             ExcludeFolders: .git MicroBuild decomp *.xml
         # Following article on https://dev.azure.com/devdiv/DevDiv/_wiki/wikis/DevDiv.wiki/25351/APIScan-step-by-step-guide-to-setting-up-a-Pipeline
         # No longer need the old format, and following guideline to use (ApiScanClientId)
         - task: APIScan@2
           displayName: Run APIScan
           inputs:
             softwareFolder: '$(Build.SourcesDirectory)\.binaries\verify\dlls'
-            softwareName: 'Microsoft.Configuration.ConfigurationBuilders.*'
+            softwareName: 'Microsoft.Configuration.ConfigurationBuilders'
             softwareVersionNum: '*'
             softwareBuildNum: '$(Build.BuildId)'
             symbolsFolder: '$(Build.SourcesDirectory)\.binaries\bin\Release;SRV*http://symweb'

docs/KeyValueConfigBuilders.md

@@ -152,10 +152,12 @@ In a similar vein to `GetCredential()`, builders who need finer control over the
 <add name="AzureAppConfig"
     [@mode|@enabled="enabled"|@charMap|@prefix|@stripPrefix|tokenPattern|@escapeExpandedValues]
     (@endpoint="https://your-appconfig-store.azconfig.io" | <del>@connectionString="Endpoint=https://your-appconfig-store.azconfig.io;Id=XXXXXXXXXX;Secret=XXXXXXXXXX"</del>)
+    [@snapshot="string"]
     [@keyFilter="string"]
     [@labelFilter="label"]
     [@acceptDateTime="DateTimeOffset"]
     [@useAzureKeyVault="bool"]
+    [@preloadValues="bool"]
     type="Microsoft.Configuration.ConfigurationBuilders.AzureAppConfigurationBuilder, Microsoft.Configuration.ConfigurationBuilders.AzureAppConfiguration" />
 ```
 > :information_source: **NOTE:**
@@ -164,12 +166,14 @@ In a similar vein to `GetCredential()`, builders who need finer control over the
 [AppConfiguration](https://docs.microsoft.com/en-us/azure/azure-app-configuration/overview) is a new offering from Azure. If you wish to use this new service for managing your configuration, then use this AzureAppConfigurationBuilder. Either `endpoint` or `connectionString` are required, but all other attributes are optional. If both `endpoint` and `connectionString` are used, then preference is given to the connection string.
   * `endpoint` - This specifies the AppConfiguration store to connect to.
   * ~~`connectionString`~~ - The recommendation is to use `endpoint` in conjunction with [DefaultAzureCredential](#azure-config-builders). ~~This specifies the AppConfiguration store to connect to, along with the Id and Secret necessary to access the service. Be careful not to expose any secrets in your code, repos, or App Configuration stores if you use this method for connecting.~~
+  * `snapshot` - Use this attribute to draw configuration values from the specific AppConfig snapshot named by the value of this attribute. **Setting this attribute will cause `keyFilter`, `labelFilter`, and `acceptDateTime` to be silently ignored.**
   * `keyFilter` - Use this to select a set of configuration values matching a certain key pattern.
       > :information_source: NOTE:
       > This filter is conceptually similar to the `prefix` attribute, but this filter is handled by the AppConfiguration service on the server side, whereas `prefix` filtering is done directly by the config builder in the application. They achieve the same goal through different mechanisms which have tradeoffs and merits according to the situation.
   * `labelFilter` - Only retrieve configuration values that match a certain label.
   * `acceptDateTime` - Instead of versioning ala Azure Key Vault, AppConfiguration uses timestamps. Use this attribute to go back in time to retrieve configuration values from a past state.
   * `useAzureKeyVault` - Enable this feature to allow AzureAppConfigurationBuilder to connect to and retrieve secrets from Azure Key Vault for config values that are stored in Key Vault. The same managed service identity that is used for connecting to the AppConfiguration service will be used to connect to Key Vault. The Key Vault uri is retrieved as part of the data from AppConfiguration and does not need to be specified here. Default is `false`.
+  * `preloadValues` - Enable this feature to have the builder pre-load all values from the AppConfiguration store into memory. Essentially the same as a 'Greedy' mode fetch of config values from the AppConfig store - but without dumping them all into the working config section.If you have a large cache of config values, or you have some values (that match key and label filters) that you don't want to pull into application memory - even if they don't get applied to existing config entries - then disable this. Otherwise, it is `true` by default because fetching as many config values as possible in one request is a much more scalable design and will help applications avoid throttling on the service end.
 
 #### AzureKeyVaultConfigBuilder
 ```xml

src/packages/assets/Readme-Azure.md

@@ -26,6 +26,9 @@ __Tip:__ To use versioned secrets, it is _not_ recommended to use the `version`
 </appSettings>
 ```
 
+### V3.1 Updates:
+  * Auth failures are "optional" for [Azure Config Builders](https://github.com/aspnet/MicrosoftConfigurationBuilders/blob/main/docs/KeyValueConfigBuilders.md#azure-config-builders).
+
 ### V3 Updates:
 A more complete list of updates [lives here](https://github.com/aspnet/MicrosoftConfigurationBuilders/blob/main/README.md#v3-updates). These are the ones most relevant to this builder:
   * :warning: ***Breaking Change*** - `Expand` mode is gone. It has been [replaced by `Token` mode](https://github.com/aspnet/MicrosoftConfigurationBuilders/blob/main/docs/KeyValueConfigBuilders.md#mode).

src/packages/assets/Readme-AzureAppConfig.md

@@ -8,10 +8,12 @@ The basic usage of this builder is given below. Parameters inside `[]`s are opti
 <add name="AzureAppConfig"
     [@mode|@enabled="enabled"|@charMap|@prefix|@stripPrefix|tokenPattern|@escapeExpandedValues]
     (@endpoint="https://your-appconfig-store.azconfig.io" | @connectionString="Endpoint=https://your-appconfig-store.azconfig.io;Id=XXXXXXXXXX;Secret=XXXXXXXXXX")
+    [@snapshot="string"]
     [@keyFilter="string"]
     [@labelFilter="label"]
     [@acceptDateTime="DateTimeOffset"]
     [@useAzureKeyVault="bool"]
+    [@preloadValues="bool"]
     type="Microsoft.Configuration.ConfigurationBuilders.AzureAppConfigurationBuilder, Microsoft.Configuration.ConfigurationBuilders.AzureAppConfiguration" />
 ```
 >:information_source: [NOTE]
@@ -20,10 +22,19 @@ The basic usage of this builder is given below. Parameters inside `[]`s are opti
 
   * `endpoint` - This specifies the AppConfiguration store to connect to.
   * `connectionString` - The recommendation is to use `endpoint`. ~~This specifies the AppConfiguration store to connect to, along with the Id and Secret necessary to access the service. Be carefulnot to expose any secrets in your code, repos, or App Configuration stores if you use this method for connecting.~~
+  * `snapshot` - Use this attribute to draw configuration values from the specific AppConfig snapshot named by the value of this attribute. **Setting this attribute will cause `keyFilter`, `labelFilter`, and `acceptDateTime` to be silently ignored.**
   * `keyFilter` - Use this to select a set of configuration values matching a certain key pattern.
   * `labelFilter` - Only retrieve configuration values that match a certain label.
   * `acceptDateTime` - Instead of versioning ala Azure Key Vault, AppConfiguration uses timestamps. Use this attribute to go back in time to retrieve configuration values from a past state.
   * `useAzureKeyVault` - Enable this feature to allow AzureAppConfigurationBuilder to connect to and retrieve secrets from Azure Key Vault for config values that are stored in Key Vault. The same managed service identity that is used for connecting to the AppConfiguration service will be used to connect to Key Vault. The Key Vault uri is retrieved as part of the data from AppConfiguration and does not need to be specific here. Default is `false`.
+  * `preloadValues` - Enable this feature to have the builder pre-load all values from the AppConfiguration store into memory. Essentially the same as a 'Greedy' mode fetch of config values from the AppConfig store - but without dumping them all into the working config section.If you have a large cache of config values, or you have some values (that match key and label filters) that you don't want to pull into application memory - even if they don't get applied to existing config entries - then disable this. Otherwise, it is `true` by default because fetching as many config values as possible in one request is a much more scalable design and will help applications avoid throttling on the service end.
+
+### V3.1 Updates:
+  * Added Snapshot capabilities.
+  * Added preloading all values - on by default.
+  * Fixed `GetCredential()` and related option-overload issues.
+  * Auth failures are "optional" for [Azure Config Builders](https://github.com/aspnet/MicrosoftConfigurationBuilders/blob/main/docs/KeyValueConfigBuilders.md#azure-config-builders).
+  * Fixed bug with key filters in `Strict` mode.
 
 ### V3 Updates:
 A more complete list of updates [lives here](https://github.com/aspnet/MicrosoftConfigurationBuilders/blob/main/README.md#v3-updates). These are the ones most relevant to this builder:

src/packages/assets/Readme.md

@@ -9,6 +9,14 @@ The set of builders produced here are styled as "Key/Value Config Builders." The
 For more information about the builders featured in this project, to report bugs, or submit contributions, please refer to the github project page for [MicrosoftConfigurationBuilders](https://github.com/aspnet/MicrosoftConfigurationBuilders/).
 
 
+### V3.1 Updates:
+  * Added Snapshot capabilities to the [`AzureAppConfigurationBuilder`](https://github.com/aspnet/MicrosoftConfigurationBuilders/blob/main/docs/KeyValueConfigBuilders.md#azureappconfigurationbuilder).
+  * Added ability to provide "[default values](https://github.com/aspnet/MicrosoftConfigurationBuilders/blob/main/docs/KeyValueConfigBuilders.md#tokenPattern)" in `Token` mode.
+  * Fixed bug with rooted-paths and `Utils.MapPath` in ASP.Net scenarios.
+  * Fixed `GetCredential()` and related option-overload issues in [`AzureAppConfigurationBuilder`](https://github.com/aspnet/MicrosoftConfigurationBuilders/blob/main/docs/KeyValueConfigBuilders.md#azureappconfigurationbuilder).
+  * Auth failures are "optional" for [Azure Config Builders](https://github.com/aspnet/MicrosoftConfigurationBuilders/blob/main/docs/KeyValueConfigBuilders.md#azure-config-builders).
+  * Fixed [`AzureAppConfigurationBuilder`](https://github.com/aspnet/MicrosoftConfigurationBuilders/blob/main/docs/KeyValueConfigBuilders.md#azureappconfigurationbuilder) bug with key filters in `Strict` mode.
+
 ### V3 Updates:
   * :warning: ***Breaking Change*** - `Expand` mode is gone. It has been [replaced by `Token` mode](https://github.com/aspnet/MicrosoftConfigurationBuilders/blob/main/docs/KeyValueConfigBuilders.md#mode).
   * `Utils.MapPath` - This was somewhat broken in ASP.Net scenarios previously. It should now reliably go against `Server.MapPath()` in ASP.Net scenarios. It has also been updated to fall back against the directory of the config file being processed when resolving the app root in the case of a `Configuration` object being created by `ConfigurationManager.OpenConfiguration*` API's rather than being part of a fully-initialized runtime configuration stack.

tools/MicrosoftConfigurationBuilders.settings.targets

@@ -23,23 +23,28 @@
             Release:	Third for Info and Package.
          Update package and file without touching assembly, except for major releases.
     -->
-    <BuildQuality Condition="'$(BuildQuality)' == ''">rtm</BuildQuality>
-    <VersionStartYear>2022</VersionStartYear>
+    <BuildQuality Condition="'$(BuildQuality)' == ''">preview1</BuildQuality>
+    <VersionStartYear>2025</VersionStartYear>
     <!-- Update version in config.xdt's for major/minor changes. (Don't update for 'release' changes.) -->
     <VersionMajor>3</VersionMajor>
-    <VersionMinor>0</VersionMinor>
+    <!-- Minor versions can differ within a major release according to semver. Use 'Contains' here to catch the main project and the package project. -->
+    <VersionMinor Condition="'$(VersionMinor)' == '' AND $(MSBuildProjectName.Contains('AzureAppConfig'))">1</VersionMinor>
+    <VersionMinor Condition="'$(VersionMinor)' == '' AND $(MSBuildProjectName.Contains('Azure'))">1</VersionMinor>
+    <VersionMinor Condition="'$(VersionMinor)' == '' AND $(MSBuildProjectName.Contains('Base'))">1</VersionMinor>
+    <VersionMinor Condition="'$(VersionMinor)' == '' AND $(MSBuildProjectName.Contains('Json'))">1</VersionMinor>
+    <VersionMinor Condition="'$(VersionMinor)' == ''">0</VersionMinor>
     <VersionRevision>0</VersionRevision>
     <VersionRelease>0</VersionRelease>
     <VersionBuild Condition="'$(VersionBuild)' == '' OR '$(VersionBuild)' == '0'">$([MSBuild]::Add(1, $([MSBuild]::Subtract($([System.DateTime]::Now.Year), $(VersionStartYear)))))$([System.DateTime]::Now.ToString("MMdd"))</VersionBuild>
     <NuGetPackageVersion>$(VersionMajor).$(VersionMinor).$(VersionRelease)</NuGetPackageVersion>
-    <NuGetPackageBaseDependencyVersion>$(VersionMajor).$(VersionMinor).$(VersionRelease)</NuGetPackageBaseDependencyVersion>
+    <NuGetPackageBaseDependencyVersion>"$(VersionMajor).0.0"</NuGetPackageBaseDependencyVersion> <!-- SemVer proposes that non-major updates should be backward compatible. -->
   </PropertyGroup>
 
   <!-- Add release type for non-RTM releases. -->
   <PropertyGroup Label="Prerelease version adjustments" Condition="'$(BuildQuality)' != 'rtm'">
     <VersionRelease>$(VersionRelease)-$(BuildQuality)</VersionRelease>
     <NuGetPackageVersion>$(NuGetPackageVersion)-$(BuildQuality)</NuGetPackageVersion>
-    <NuGetPackageBaseDependencyVersion>$(NuGetPackageBaseDependencyVersion)-$(BuildQuality)</NuGetPackageBaseDependencyVersion>
+    <NuGetPackageBaseDependencyVersion>$(VersionMajor).$(VersionMinor).$(VersionRelease)-$(BuildQuality)</NuGetPackageBaseDependencyVersion> <!-- Bend SemVer guidelines for preview releases. -->
   </PropertyGroup>
 
   <!-- Additionaly, add date stamp to 'preview' releases. -->