Skip to content
.NET API for Consul (
C# Smalltalk
Branch: master
Clone or download
Latest commit d6d1cd6 Dec 4, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
Consul Add GRPC Healthcheck sample Nov 27, 2019
GRPC Add AspNetCore Adapter Nov 27, 2019
NConsul.AspNetCore Update to .NET Core 3.1 Dec 4, 2019
assets Add strong name signing for Consul assembly Jul 20, 2015
.gitattributes Initial commit May 15, 2015
.gitignore Add debugtype=portable for vscode Apr 19, 2017 Update changelog and versions Jan 18, 2017
LICENSE Initial commit May 15, 2015
NConsul.sln Add AspNetCore Adapter Nov 27, 2019
NuGet.config Add nuget config Jun 26, 2016 Update README Nov 27, 2019
appveyor.yml Fix version (#118) Jun 27, 2018


Fork from and Support GRPC.

  • Consul API: v0.7.2
  • .NET Core: >= 2.0

Consul.NET is a .NET port of the Go Consul API, but reworked to use .NET idioms such as Tasks/CancellationTokens instead of Goroutines/Channels. The majority of the calls directly track the HTTP API, but this API does have additional functionality that is provided in the Go API, like Locks and Semaphores.

GRPC Check Example

var consulClient = new ConsulClient(x => x.Address = new Uri($"http://localhost:8500"));
var grpCheck = new AgentServiceCheck()
    DeregisterCriticalServiceAfter = TimeSpan.FromSeconds(5),
    Interval = TimeSpan.FromSeconds(10),
    GRPC = "",
    GRPCUseTLS = false,
    Timeout = TimeSpan.FromSeconds(10)
var registration = new AgentServiceRegistration()
    Checks = new[] { grpCheck },
    ID = Guid.NewGuid().ToString(),
    Name = "grpctest",
    Address = "localhost",
    Port = 5000,
    Tags = new[] { $"xc/grpc/test" }

await consulClient.Agent.ServiceRegister(registration);


    .RegisterService("grpctest","localhost",5000,new []{"xc/grpc/test"});


You'll need a running Consul Server on your local machine, or a Consul Agent connected to a Consul Server cluster. To run a local server:

  1. Download a copy of the latest Windows version and unzip it into the Consul.Test folder.
  2. Open a command prompt and cd to the Consul.Test folder.
  3. Run .\consul.exe agent -dev -config-file test_config.json

This creates a 1-server cluster that operates in "dev" mode (does not write data to disk) and listens on

Once Consul is running (you'll see something like consul: cluster leadership acquired) in your command prompt, then do the following steps in your project.

Add a reference to the Consul library and add a using statement:

using Consul;

Write a function to talk to the KV store:

public static async Task<string> HelloConsul()
    using (var client = new ConsulClient())
        var putPair = new KVPair("hello")
            Value = Encoding.UTF8.GetBytes("Hello Consul")

        var putAttempt = await client.KV.Put(putPair);

        if (putAttempt.Response)
            var getPair = await client.KV.Get("hello");
            return Encoding.UTF8.GetString(getPair.Response.Value, 0,
        return "";

And call it:


You should see Hello Consul in the output of your program. You should also see the following lines in your command prompt, if you're running a local Consul server:

[DEBUG] http: Request /v1/kv/hello (6.0039ms)
[DEBUG] http: Request /v1/kv/hello (0)

The API just went out to Consul, wrote "Hello Consul" under the key "hello", then fetched the data back out and wrote it to your prompt.


All operations are done using a ConsulClient object. First, instantiate a ConsulClient object, which connects to localhost:8500, the default Consul HTTP API port. Once you've got a ConsulClient object, various functionality is exposed as properties under the ConsulClient.

All responses are wrapped in QueryResponse and WriteResponse classes, which provide metadata about the request, like how long it took and the monotonic Consul index when the operation occured.

This API also assumes some knowledge of Consul, including things like blocking queries and consistency modes


The ACL endpoints are used to create, update, destroy, and query ACL tokens.


The Agent endpoints are used to interact with the local Consul agent. Usually, services and checks are registered with an agent which then takes on the burden of keeping that data synchronized with the cluster. For example, the agent registers services and checks with the Catalog and performs anti-entropy to recover from outages.


The Catalog is the endpoint used to register and deregister nodes, services, and checks. It also provides query endpoints.


The Event endpoints are used to fire new events and to query the available events.


The Health endpoints are used to query health-related information. They are provided separately from the Catalog since users may prefer not to use the optional health checking mechanisms. Additionally, some of the query results from the Health endpoints are filtered while the Catalog endpoints provide the raw entries.


The KV endpoint is used to access Consul's simple key/value store, useful for storing service configuration or other metadata.


The Prepared Query endpoints are used to create, update, destroy, and execute prepared queries. Prepared queries allow you to register a complex service query and then execute it later via its ID or name to get a set of healthy nodes that provide a given service.


The Session endpoints are used to create, destroy, and query sessions.


The Status endpoints are used to get information about the status of the Consul cluster. This information is generally very low level and not often useful for clients.

Additional Functions

Functionality based on the Consul guides using the available primitives has been implemented as well, just like the Go API.


Lock is used to implement client-side leader election for a distributed lock. It is an implementation of the Consul Leader Election guide.


Semaphore is used to implement a distributed semaphore using the Consul KV primitives. It is an implementation of the Consul Semaphore guide.

Using with .NET Core and Mono

Both .NET 4.5+ and .NET Core 1.0+ are fully supported. Mono is supported on a best-effort basis. It should compile and run happily on Mono but this is not as heavily tested as Microsoft .NET stacks. If you have any issues using the Nuget package or compiling this code with .NET, .NET Core, or Mono, please file a Github issue with details of the problem.

You can’t perform that action at this time.