Skip to content
Consul configuration provider for Microsoft.Extensions.Configuration
C# PowerShell Batchfile Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


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

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", "", 9999). In this case provider will make a request to instead of localhost

  2. By setting two ENV variables - CONSUL_HOST and CONSUL_PORT to Consul host and port respectively e.g. setting 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 and calling .AddConsul("ExampleConsulKey") will give base address
  • setting CONSUL_PORT=9999 and calling .AddConsul("ExampleConsulKey", "", null) will give base address
  • 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.


You can’t perform that action at this time.