### UserSecretsConfigBuilder secrets file example Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/docs/KeyValueConfigBuilders.md Example of a non-empty secrets file used by the UserSecretsConfigBuilder. The format is XML and should be considered an implementation detail. ```xml ``` -------------------------------- ### CustomConfigBuilder with virtual methods for advanced techniques Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/docs/CustomConfigBuilders.md Shows optional overrides: Initialize for immediate config reads, LazyInitialize for deferred setup (must call base.LazyInitialize), MapKey for key translation, ValidateKey for key screening, and UpdateKey for final key modification. ```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. } } ``` -------------------------------- ### Sample JSON for Sectional Mode Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/docs/KeyValueConfigBuilders.md Example JSON file used with SimpleJsonConfigBuilder in 'Sectional' mode. The top-level properties 'appSettings' and 'connectionStrings' correspond to configuration sections, and each nested dictionary is applied to the matching section. ```json { "appSettings" : { "setting1" : "value1", "setting2" : "value2", "complex" : { "setting1" : "complex:value1", "setting2" : "complex:value2", } }, "connectionStrings" : { "mySpecialConnectionString" : "Dont_check_connection_information_into_source_control" } } ``` -------------------------------- ### AzureKeyVaultConfigBuilder appSettings example with versioned key Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/docs/KeyValueConfigBuilders.md Shows how to specify a versioned key in appSettings. The key name uses the format keyName/versionId. The builder substitutes the value only if the version exists, and removes the version suffix from the resulting key. ```xml ``` -------------------------------- ### Using versioned secrets in appSettings Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/src/packages/assets/Readme-Azure.md Example of using versioned secrets by including the version in the key name. The builder replaces the value with the latest version or a specific version, and the resulting key is the part before the slash. ```xml ``` -------------------------------- ### XML configuration for ConnectionStringsSectionHandler2 Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/docs/SectionHandlers.md Example of a section using the new handler. Tagged keys map to specific attributes: ':connectionString' and ':providerName'. Untagged keys update the connectionString property. Note that the post-fix mechanism is incompatible with versioned keys in Azure Key Vault. ```xml ``` -------------------------------- ### Azure AppConfiguration ConfigBuilder XML configuration Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/src/packages/assets/Readme-AzureAppConfig.md Basic usage of the AzureAppConfigurationBuilder in a configuration file. Parameters in [] are optional, those in () are mutually exclusive, and those starting with @ allow appSettings substitution. The identity must have the 'Azure App Configuration Data Reader' or 'Data Owner' role to avoid a 403 Forbidden error. ```xml ``` -------------------------------- ### Build the project and run tests Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/CONTRIBUTING.md Run this command to restore NuGet packages, build the solution, and run tests. It should be executed after the strong-name verification skip command. ```batch build.cmd ``` -------------------------------- ### Apply custom builder to system.web/compilation section Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/docs/FAQ.md Shows how to apply a custom 'ReferenceAssemblyInjection' builder to the system.web/compilation section. Note that config builders in this repo only work out of the box with appSettings and connectionStrings; other sections require a custom ISectionHandler. ```xml ``` -------------------------------- ### Skip strong-name verification for build Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/CONTRIBUTING.md Run this command in a Visual Studio developer prompt as administrator to register the public key token for verification skip, which is required before building the project and running tests. ```powershell sn -Vr *,31bf3856ad364e35 ``` -------------------------------- ### Configure builders with appSettings parameters Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/docs/KeyValueConfigBuilders.md Shows how to configure Environment and Azure KeyVault config builders, where the KeyVault builder's vaultName parameter is filled from an appSettings value. The appSettings section uses the builders to inject additional settings. Note that the token replacement only works after base lazy initialization and has limitations when processing the appSettings section itself. ```xml ``` -------------------------------- ### Enable binding redirect updates in SampleWebApp.csproj Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/CONTRIBUTING.md Set the UpdateBindingRedirectsAfterBuild property to 'true' in the SampleWebApp.csproj file to update binding redirects in web.config. This is needed to avoid MSB3276 warnings and should be unset after updating dependencies. ```xml true ``` -------------------------------- ### Configure two EnvironmentConfigBuilders with prefixes for appSettings and connectionStrings Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/docs/KeyValueConfigBuilders.md XML configuration using two EnvironmentConfigBuilders in Greedy mode with distinct prefixes (AppSetting_ and ConnStr_) to populate appSettings and connectionStrings from the same environment variable source. The stripPrefix setting is mentioned as a related boolean option, defaulting to false. ```xml ``` -------------------------------- ### KeyPerFile ConfigBuilder XML Configuration Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/src/packages/assets/Readme-KeyPerFile.md Registers the KeyPerFileConfigBuilder in a configuration file. The @directoryPath parameter is required and specifies the source directory. Optional parameters include @ignorePrefix, keyDelimiter, and common builder parameters like @mode, @enabled, @charMap, @prefix, @stripPrefix, tokenPattern, and @escapeExpandedValues. ```xml ``` -------------------------------- ### Basic UserSecrets ConfigBuilder Configuration Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/src/packages/assets/Readme-UserSecrets.md Configures the UserSecretsConfigBuilder in an XML configuration file. Use either userSecretsId or userSecretsFile to specify the secrets file; userSecretsFile takes precedence if both are specified. The '~' character in userSecretsFile references the app root. ```xml ``` -------------------------------- ### Environment ConfigBuilder XML configuration Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/src/packages/assets/Readme-Environment.md Basic usage of the EnvironmentConfigBuilder in a configuration file. Parameters in brackets are optional, grouped parameters are mutually exclusive, and @-prefixed parameters allow appSettings substitution. The first line of parameters is common to all builders and optional. ```xml ``` -------------------------------- ### CustomConfigBuilder with required GetValue and GetAllValues Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/docs/CustomConfigBuilders.md Inherits KeyValueConfigBuilder and implements the two required methods. GetValue should be case-insensitive; GetAllValues returns a collection of key-value pairs. ```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> GetAllValues(string prefix) { // Populate the return collection a little more smartly. ;) return new Dictionary() { { "one", "1" }, { "two", "2" } }; } } ``` -------------------------------- ### Replacing default handlers with custom implementations Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/docs/SectionHandlers.md Shows how to remove the default handlers and add custom ones. The custom handler types may need a more qualified type name to locate the assembly. For ASP.NET, handlers for sections loaded before App_Code compilation must be in a separate assembly in the 'bin' directory. ```xml
``` -------------------------------- ### IIS schema file for configBuilders (configBuilders_schema.xml) Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/docs/FAQ.md Add this XML schema file to `%systemroot%\system32\inetsrv\config\schema\configBuilders_schema.xml` to allow IIS tools to recognize the `configBuilders` attribute on `appSettings` and `connectionStrings` sections. This workaround is needed because IIS config tools use XML schema validation and do not natively support the configBuilders attribute. ```xml ``` -------------------------------- ### AzureKeyVaultConfigBuilder XML configuration Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/src/packages/assets/Readme-Azure.md Basic usage of the AzureKeyVaultConfigBuilder. The first line lists common optional parameters; vaultName or uri is required. The type attribute specifies the builder class and assembly. ```xml ``` -------------------------------- ### SimpleJson ConfigBuilder XML configuration Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/src/packages/assets/Readme-Json.md Basic usage of the SimpleJsonConfigBuilder in a configuration file. Parameters in brackets are optional, grouped parameters are mutually exclusive, and @ parameters allow appSettings substitution. The jsonFile parameter is required, and jsonMode can be Flat (default) or Sectional. ```xml ``` -------------------------------- ### XML configuration for tokenPattern with default value capture Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/docs/KeyValueConfigBuilders.md Shows how to set the tokenPattern in a builder definition to capture default values. The pattern matches tokens like "${TOKEN}" and "${TOKEN:default}". This is a v3.1 feature; the out-of-box pattern does not capture defaults. ```XML ``` -------------------------------- ### Explicit declaration of default section handlers Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/docs/SectionHandlers.md Shows the explicit XML configuration for the default AppSettingsSectionHandler and ConnectionStringsSectionHandler. The section name must be 'Microsoft.Configuration.ConfigurationBuilders.SectionHandlers' for key/value config builders to find it. ```xml
``` -------------------------------- ### Implement a custom SectionHandler with required methods Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/docs/SectionHandlers.md Shows the minimal structure for a custom section handler. Must implement KeysValuesAndState() and InsertOrUpdate(). The commented GetEnumerator() method is the V2 alternative that still works in V3 but lacks value-side token support. InsertOrUpdate() is called while iterating the enumerator, so avoid modifying the underlying collection during iteration. ```CSharp public class MySpecialSectionHandler : SectionHandler { // T ConfigSection; // public override void Initialize(string name, NameValueCollection config) {} // public override string TryGetOriginalCase(string requestedKey) {} public override IEnumerable> KeysValuesAndState() { /* key, value, state */ } public override void InsertOrUpdate(string newKey, string newValue, string oldKey = null, object oldItem = null) {} // * - Version 2 used this method instead of the richer 'KeysValuesAndState()' method. // Section handlers that were created by overriding this method will still work in V3, // but without the additional sting 'value' in the enumerated tuple, builders will be unable // to properly process sections in 'Token' mode since they will only see tokens that appear // in config keys and not tokens that appear in value side of the config entry. //public override IEnumerator> GetEnumerator() { /* key, state */ } } ``` -------------------------------- ### Commit/Pull Request message format Source: https://github.com/aspnet/microsoftconfigurationbuilders/blob/main/CONTRIBUTING.md Use this format for commit and pull request messages. The summary should be less than 80 characters, followed by details and an issue reference in the specified format. ```markdown Summary of the changes (Less than 80 chars) - Detail 1 - Detail 2 Addresses #bugnumber (in this specific format) ```