dotnet-etcd 5.0.2

A C# .NET (dotnet) GRPC client for etcd v3+.

etcd is a distributed key value store that provides a reliable way to store data across a cluster of machines. It’s open-source and available on GitHub. etcd gracefully handles leader elections during network partitions and will tolerate machine failure, including the leader.

Your applications can read and write data into etcd. A simple use-case is to store database connection details or feature flags in etcd as key value pairs. These values can be watched, allowing your app to reconfigure itself when they change.

Advanced uses take advantage of the consistency guarantees to implement database leader elections or do distributed locking across a cluster of workers.

Install-Package dotnet-etcd -Version 5.0.2
dotnet add package dotnet-etcd --version 5.0.2
<PackageReference Include="dotnet-etcd" Version="5.0.2" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add dotnet-etcd --version 5.0.2
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: dotnet-etcd, 5.0.2"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install dotnet-etcd as a Cake Addin
#addin nuget:?package=dotnet-etcd&version=5.0.2

// Install dotnet-etcd as a Cake Tool
#tool nuget:?package=dotnet-etcd&version=5.0.2
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

dotnet-etcd

A C# .NET (dotnet) GRPC client for etcd v3+

Build Status Nuget Version Info Nuget Download Info

Supported .NET Versions

  • .NET 5
  • .NETCoreApp 3.1
  • .NETStandard 2.1

For older dotnet versions, use lib version < 5.x

Installing Package

Nuget package is published on nuget.org and can be installed in the following ways :

Nuget Package Manager

Install-Package dotnet-etcd

.NET CLI

dotnet add package dotnet-etcd

Paket CLI

paket add dotnet-etcd

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Usage :

Add using statement at the top of your class file

    using dotnet_etcd;

Client Initialization

    EtcdClient client = new EtcdClient("host1:port1:,...., hostN:portN");
    // E.g.
    EtcdClient etcdClient = new EtcdClient("https://localhost:23790,https://localhost:23791,https://localhost:23792");

Client With user and password

    EtcdClient client = new EtcdClient("https://localhost:23790");
    var authRes = client.Authenticate(new Etcdserverpb.AuthenticateRequest()
    {
        Name = "name",
        Password = "password",
    });
    //  Put key "foo/bar" with value "foobar" with authenticated token
    client.Put("foo/bar", "barfoo", new Grpc.Core.Metadata() {
        new Grpc.Core.Metadata.Entry("token",authRes.Token)
    });
Available Constructor Parameters
  • handler - Http Handler that can be used by the underlying grpc client. This can be used for variouse use cases, for e.g. configuring client certifcates . Default : null
  • ssl - Bool depicting whether to configure a secure or unsecure connection. Default : false.

Operations

A lot of methods have been implemented using etcd's default input/output parameters. I am simplifying a lot of methods by including more overloads as I come across use cases. If you have some, please feel free to raise and issue or a PR 😃

Key-Value Operations
Put a key
    client.Put(<KEY_STRING>,<VALUE_STRING>);
    // E.g Put key "foo/bar" with value "foobar"
    client.Put("foo/bar","barfoo");

    await client.PutAsync(<KEY_STRING>,<VALUE_STRING>);
    // E.g Put key "foo/bar" with value "foobar" in async
    await client.PutAsync("foo/bar","barfoo");
Get a key
    client.GetVal(<KEY_STRING>);
    // E.g Get key "foo/bar"
    client.GetVal("foo/bar");
    // To get full etcd response
    client.Get("foo/bar");

    await client.GetValAsync(<KEY_STRING>);
    // E.g. Get key "foo/bar" in async
    await client.GetValAsync("foo/bar");
    // To get full etcd response
    await client.GetAsync("foo/bar");
Get multiple keys with a common prefix
    client.GetRange(<PREFIX_STRING>);
    // E.g. Get all keys with pattern "foo/*"
    client.GetRange("foo/"); 

    await client.GetRangeAsync(<PREFIX_STRING>);
    // E.g. Get all keys with pattern "foo/*" in async
    await client.GetRangeAsync("foo/");

    // E.g. Get all keys
    await client.GetRangeAsync("");
Delete a key
    client.Delete(<KEY_STRING>);
    // E.g. Delete key "foo/bar"
    client.Delete("foo/bar");

    await client.DeleteAsync(<KEY_STRING>);
    // E.g. Delete key "foo/bar" in async
    await client.DeleteAsync("foo/bar");
Delete multiple keys with a common prefix
    client.DeleteRange(<PREFIX_STRING>);
    // E.g. Delete all keys with pattern "foo/*"
    client.DeleteRange("foo/"); 

    await client.DeleteRangeAsync(<PREFIX_STRING>);
    // E.g. Delete all keys with pattern "foo/*" in async
    await client.DeleteRangeAsync("foo/");

Watch Operations

Watch a key
    WatchRequest request = new WatchRequest()
    {
        CreateRequest = new WatchCreateRequest()
        {
            Key = ByteString.CopyFromUtf8("foo")
        }
    };
    etcdClient.Watch(request, print);

    // -------------------------------
    // Print function that prints key and value from the watch response
    private static void print(WatchResponse response)
    {   
        if (response.Events.Count == 0)
        {
            Console.WriteLine(response);
        }
        else
        {
            Console.WriteLine($"{response.Events[0].Kv.Key.ToStringUtf8()}:{response.Events .Kv.Value.ToStringUtf8()}");
        }
    }

    // ----------------------------------
    // Print function that prints key and value from the minimal watch
    // response data 
    private static void print(WatchEvent[] response)
    {
        foreach(WatchEvent e1 in response)
        {
            Console.WriteLine($"{e1.Key}:{e1.Value}:{e1.Type}");
        }
    }

Watch also has a simple overload as follows

    etcdClient.Watch("foo", print);

More overloads are also available. You can check them using IntelliSense (Ctrl+Shift+Space). Detailed documentation coming soon.

Cluster Operations

Add a member into the cluster
     MemberAddRequest request = new MemberAddRequest();
     request.PeerURLs.Add("http://example.com:2380");
     request.PeerURLs.Add("http://10.0.0.1:2380");
     MemberAddResponse res = etcdClient.MemberAdd(request);

     // Async
     MemberAddResponse res = await etcdClient.MemberAddAsync(request);

     // Do something with response
Remove an existing member from the cluster
    MemberRemoveRequest request = new MemberRemoveRequest
    {
        // ID of member to be removed
        ID = 651748107021
    };
    MemberRemoveResponse res = etcdClient.MemberRemove(request);

    // Async
    MemberRemoveResponse res = await etcdClient.MemberRemoveAsync(request);

    // Do something with response

Update the member configuration

    MemberUpdateRequest request = new MemberUpdateRequest
    {
        // ID of member to be updated
        ID = 651748107021
    };
    request.PeerURLs.Add("http://10.0.0.1:2380");
    MemberUpdateResponse res = etcdClient.MemberUpdate(request);

    // Async
    MemberUpdateResponse res = await etcdClient.MemberUpdateAsync(request);

    // Do something with response

List all the members in the cluster

    MemberListRequest request = new MemberListRequest();
    etcdClient.MemberList(request);
    MemberListResponse res = etcdClient.MemberList(request);

    // Async
    MemberListResponse res = await etcdClient.MemberListAsync(request);

    // Do something with response
    foreach(var member in res.Members)
    {
        Console.WriteLine($"{member.ID} - {member.Name} - {member.PeerURLs}");
    }

Modify data with transaction https://etcd.io/docs/v3.4.0/learning/api/#transaction

    var txr = new Etcdserverpb.TxnRequest();
    txr.Success.Add(new Etcdserverpb.RequestOp()
    {
        RequestPut = new Etcdserverpb.PutRequest()
        {
            Key = Google.Protobuf.ByteString.CopyFrom("transaction-key", System.Text.Encoding.UTF8),
            Value = Google.Protobuf.ByteString.CopyFrom("tv", System.Text.Encoding.UTF8),
        }
    });
    client.Transaction(txr);

dotnet-etcd

A C# .NET (dotnet) GRPC client for etcd v3+

Build Status Nuget Version Info Nuget Download Info

Supported .NET Versions

  • .NET 5
  • .NETCoreApp 3.1
  • .NETStandard 2.1

For older dotnet versions, use lib version < 5.x

Installing Package

Nuget package is published on nuget.org and can be installed in the following ways :

Nuget Package Manager

Install-Package dotnet-etcd

.NET CLI

dotnet add package dotnet-etcd

Paket CLI

paket add dotnet-etcd

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Usage :

Add using statement at the top of your class file

    using dotnet_etcd;

Client Initialization

    EtcdClient client = new EtcdClient("host1:port1:,...., hostN:portN");
    // E.g.
    EtcdClient etcdClient = new EtcdClient("https://localhost:23790,https://localhost:23791,https://localhost:23792");

Client With user and password

    EtcdClient client = new EtcdClient("https://localhost:23790");
    var authRes = client.Authenticate(new Etcdserverpb.AuthenticateRequest()
    {
        Name = "name",
        Password = "password",
    });
    //  Put key "foo/bar" with value "foobar" with authenticated token
    client.Put("foo/bar", "barfoo", new Grpc.Core.Metadata() {
        new Grpc.Core.Metadata.Entry("token",authRes.Token)
    });
Available Constructor Parameters
  • handler - Http Handler that can be used by the underlying grpc client. This can be used for variouse use cases, for e.g. configuring client certifcates . Default : null
  • ssl - Bool depicting whether to configure a secure or unsecure connection. Default : false.

Operations

A lot of methods have been implemented using etcd's default input/output parameters. I am simplifying a lot of methods by including more overloads as I come across use cases. If you have some, please feel free to raise and issue or a PR 😃

Key-Value Operations
Put a key
    client.Put(<KEY_STRING>,<VALUE_STRING>);
    // E.g Put key "foo/bar" with value "foobar"
    client.Put("foo/bar","barfoo");

    await client.PutAsync(<KEY_STRING>,<VALUE_STRING>);
    // E.g Put key "foo/bar" with value "foobar" in async
    await client.PutAsync("foo/bar","barfoo");
Get a key
    client.GetVal(<KEY_STRING>);
    // E.g Get key "foo/bar"
    client.GetVal("foo/bar");
    // To get full etcd response
    client.Get("foo/bar");

    await client.GetValAsync(<KEY_STRING>);
    // E.g. Get key "foo/bar" in async
    await client.GetValAsync("foo/bar");
    // To get full etcd response
    await client.GetAsync("foo/bar");
Get multiple keys with a common prefix
    client.GetRange(<PREFIX_STRING>);
    // E.g. Get all keys with pattern "foo/*"
    client.GetRange("foo/"); 

    await client.GetRangeAsync(<PREFIX_STRING>);
    // E.g. Get all keys with pattern "foo/*" in async
    await client.GetRangeAsync("foo/");

    // E.g. Get all keys
    await client.GetRangeAsync("");
Delete a key
    client.Delete(<KEY_STRING>);
    // E.g. Delete key "foo/bar"
    client.Delete("foo/bar");

    await client.DeleteAsync(<KEY_STRING>);
    // E.g. Delete key "foo/bar" in async
    await client.DeleteAsync("foo/bar");
Delete multiple keys with a common prefix
    client.DeleteRange(<PREFIX_STRING>);
    // E.g. Delete all keys with pattern "foo/*"
    client.DeleteRange("foo/"); 

    await client.DeleteRangeAsync(<PREFIX_STRING>);
    // E.g. Delete all keys with pattern "foo/*" in async
    await client.DeleteRangeAsync("foo/");

Watch Operations

Watch a key
    WatchRequest request = new WatchRequest()
    {
        CreateRequest = new WatchCreateRequest()
        {
            Key = ByteString.CopyFromUtf8("foo")
        }
    };
    etcdClient.Watch(request, print);

    // -------------------------------
    // Print function that prints key and value from the watch response
    private static void print(WatchResponse response)
    {   
        if (response.Events.Count == 0)
        {
            Console.WriteLine(response);
        }
        else
        {
            Console.WriteLine($"{response.Events[0].Kv.Key.ToStringUtf8()}:{response.Events .Kv.Value.ToStringUtf8()}");
        }
    }

    // ----------------------------------
    // Print function that prints key and value from the minimal watch
    // response data 
    private static void print(WatchEvent[] response)
    {
        foreach(WatchEvent e1 in response)
        {
            Console.WriteLine($"{e1.Key}:{e1.Value}:{e1.Type}");
        }
    }

Watch also has a simple overload as follows

    etcdClient.Watch("foo", print);

More overloads are also available. You can check them using IntelliSense (Ctrl+Shift+Space). Detailed documentation coming soon.

Cluster Operations

Add a member into the cluster
     MemberAddRequest request = new MemberAddRequest();
     request.PeerURLs.Add("http://example.com:2380");
     request.PeerURLs.Add("http://10.0.0.1:2380");
     MemberAddResponse res = etcdClient.MemberAdd(request);

     // Async
     MemberAddResponse res = await etcdClient.MemberAddAsync(request);

     // Do something with response
Remove an existing member from the cluster
    MemberRemoveRequest request = new MemberRemoveRequest
    {
        // ID of member to be removed
        ID = 651748107021
    };
    MemberRemoveResponse res = etcdClient.MemberRemove(request);

    // Async
    MemberRemoveResponse res = await etcdClient.MemberRemoveAsync(request);

    // Do something with response

Update the member configuration

    MemberUpdateRequest request = new MemberUpdateRequest
    {
        // ID of member to be updated
        ID = 651748107021
    };
    request.PeerURLs.Add("http://10.0.0.1:2380");
    MemberUpdateResponse res = etcdClient.MemberUpdate(request);

    // Async
    MemberUpdateResponse res = await etcdClient.MemberUpdateAsync(request);

    // Do something with response

List all the members in the cluster

    MemberListRequest request = new MemberListRequest();
    etcdClient.MemberList(request);
    MemberListResponse res = etcdClient.MemberList(request);

    // Async
    MemberListResponse res = await etcdClient.MemberListAsync(request);

    // Do something with response
    foreach(var member in res.Members)
    {
        Console.WriteLine($"{member.ID} - {member.Name} - {member.PeerURLs}");
    }

Modify data with transaction https://etcd.io/docs/v3.4.0/learning/api/#transaction

    var txr = new Etcdserverpb.TxnRequest();
    txr.Success.Add(new Etcdserverpb.RequestOp()
    {
        RequestPut = new Etcdserverpb.PutRequest()
        {
            Key = Google.Protobuf.ByteString.CopyFrom("transaction-key", System.Text.Encoding.UTF8),
            Value = Google.Protobuf.ByteString.CopyFrom("tv", System.Text.Encoding.UTF8),
        }
    });
    client.Transaction(txr);

Release Notes

Breaking Change:
- Clients using certs with ssl will break. The lib now accepts a http handler as an argument which users can utilize to manage various aspects of the grpc client like ssl.

NuGet packages (10)

Showing the top 5 NuGet packages that depend on dotnet-etcd:

Package Downloads
Etcd.Configuration
Get configuration from etcd configuration center.
etcd.Provider.Cluster.Extensions
etcd扩展,定时刷新集群节点地址
Ocelot.Provider.Etcd
Provides Ocelot extensions to use Etcd
Ocelot.Provider.Etcd.Cluster
发布
etcd.Provider.Service
etcd注册服务,方法扩展;个人提供任意使用,保留注释

GitHub repositories

This package is not used by any popular GitHub repositories.

Version History

Version Downloads Last updated
5.0.2 127 9/6/2021
5.0.2-alpha 88 8/22/2021
5.0.0-alpha 57 8/9/2021
4.2.0 69,590 12/8/2020
4.1.1 53,439 7/12/2020
4.1.0-beta 348 5/31/2020
4.0.0-beta 185 5/10/2020
3.2.0 23,521 4/6/2020
3.1.1 3,455 3/21/2020
3.1.0 1,545 2/23/2020
3.0.0.1-beta 564 9/6/2019
3.0.0 44,799 9/24/2019
3.0.0-beta 2,495 9/6/2019
3.0.0-alpha 303 8/11/2019
2.3.1 60,557 3/18/2019
2.3.0 833 3/9/2019
2.2.0 519 2/17/2019
2.1.1 493 2/12/2019
2.1.0 946 1/27/2019
2.0.1 6,815 12/9/2018
2.0.0 799 11/18/2018