Consul configuration provider implementation for Microsoft.Extensions.Configuration. Allows reading Asp.Net.Core app configuration from Consul Key-Value store

Programming language: C#
License: MIT License
Tags: Extensions     NetCore     Configuration     Netstandard     AspNetCore     Config     Consul     Provider    
Latest version: v1.0.1

DarkXaHTeP.Extensions.Configuration.Consul alternatives and similar packages

Based on the "Extensions" category.
Alternatively, view DarkXaHTeP.Extensions.Configuration.Consul alternatives based on common mentions on social networks and blogs.

Do you think we are missing an alternative of DarkXaHTeP.Extensions.Configuration.Consul or a related project?

Add another 'Extensions' Package



Consul configuration provider implementation for Microsoft.Extensions.Configuration. Allows reading Asp.Net.Core app configuration from Consul Key-Value store


NuGet Version NuGet Downloads


Travis build Coverage report


Install package into your project from NuGet and use AddConsul extension method on IConfigurationBuilder as shown in examples below:

Creating ConfigurationBuilder manually
IConfigurationBuilder builder = new ConfigurationBuilder()

IConfiguration configuration = builder.Build()
Building Asp.Net Core 2.0 Host
IWebHost webHost = new WebHostBuilder()
    .ConfigureAppConfiguration((hostingContext, config) =>
            .AddJsonFile("appsettings.json", true, true)
What happens internally

In both cases Consul configuration provider will make a GET HTTP request to Consul using URL http://localhost:8500/v1/kv/ExampleConsulKey?recurse=true to list all sub-keys of ExampleConsulKey and add them to configuration dictionary

Release notes

For release notes please see CHANGELOG.md

Advanced Usage

Providing custom Consul address

In case your Consul agent doesn't run on http://localhost:8500 it is possible to provide custom Consul address:

  1. By specifying additional arguments to "AddConsul" method e.g. .AddConsul("ExampleConsulKey", "example.com", 9999). In this case provider will make a request to http://example.com:9999/v1/kv/ExampleConsulKey?recurse=true instead of localhost

  2. By setting two ENV variables - CONSUL_HOST and CONSUL_PORT to Consul host and port respectively e.g. setting CONSUL_HOST=example.com and CONSUL_PORT=9999 and calling .AddConsul("ExampleConsulKey") will give same result as the first case.

Please note that each of host and port values can be set using different approach. Default value will be used if not set. For example:

  • setting just CONSUL_HOST=example.com and calling .AddConsul("ExampleConsulKey") will give base address example.com:8500.
  • setting CONSUL_PORT=9999 and calling .AddConsul("ExampleConsulKey", "example.com", null) will give base address example.com:9999
  • setting CONSUL_PORT=9999 and calling .AddConsul("ExampleConsulKey") will give address localhost:9999
Parsing sub-keys

Let's assume that Consul provider is added like this .AddConsul("ExampleConsulKey")and Consul KV Store contains keys listed in the left table column. Corresponding configuration keys, that will be created by provider, are listed on the right:

Consul KV Store Key Configuration Key
ExampleConsulKey/key1 key1
ExampleConsulKey/key2 key2
ExampleConsulKey/key3/subkey1 key3:subkey1
ExampleConsulKey/key4/subkey1/subsubkey1 key4:subkey1:subsubkey1

OtherKey will not be included because it is not under ExampleConsulKey key.

Parsing arrays

Consul provider allows defining arrays by adding item index in square brackets to the Consul KV Store key

Consul KV StoreKey Configuration Key
ExampleConsulKey/keys[0] keys:0
ExampleConsulKey/keys[1] keys:1
ExampleConsulKey/keys2[0]/subkey1 keys2:0:subkey1
ExampleConsulKey/keys2[0]/subkey2 keys2:0:subkey2
ExampleConsulKey/keys2[1]/subkey1 keys2:1:subkey1
ExampleConsulKey/keys2[1]/subkey2 keys2:1:subkey2
Creating strongly typed configuration

Consul provider defines settings in a well-known format (colon as delimiter for sub-keys and array indexes) that allows binding to types using Configuration Binder and Options.

For examples of this functionality you may take a look at tests here.


Feel free to ask questions and post bugs/ideas in the issues, as well as send pull requests.


*Note that all licence references and agreements mentioned in the DarkXaHTeP.Extensions.Configuration.Consul README section above are relevant to that project's source code only.