dotnet-etcd

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

Table of Contents

• Supported .NET Versions
• Installing Package
• Documentation
• Quick Start
• Features
• Contributing
• Testing and Code Coverage

Supported .NET Versions

• .NET 9
• .NET 8

Compatibility Note

For older .NET versions:

• For .NET 6/7 support, use version 7.2.0
• For .NET versions < 6, use 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.

Documentation

For comprehensive documentation of all operations and method overloads, please see the documentation pages.

The documentation is organized into the following sections:

Getting Started

• Client Initialization - How to initialize and configure the client
• Dependency Injection - Using the client with DI
• Authentication - Authentication with etcd

Core Operations

• Key-Value Operations - Working with keys and values
• Watch Operations - Watching for changes to keys
• Lease Operations - Working with leases
• Lock Operations - Distributed locking
• Election Operations - Leader election

Advanced Operations

• Cluster Operations - Managing the etcd cluster
• Maintenance Operations - Maintenance tasks
• Transactions - Atomic operations

The documentation includes detailed API references with all method overloads, parameters, and return types, as well as examples for common use cases.

Quick Start

Add using statement at the top of your class file:

using dotnet_etcd;

Client Initialization

// Basic initialization with a single endpoint
EtcdClient client = new EtcdClient("localhost:2379");

// Multiple endpoints
EtcdClient client = new EtcdClient("https://localhost:23790,https://localhost:23791,https://localhost:23792");

// Insecure connection (HTTP)
EtcdClient client = new EtcdClient("http://localhost:23790", configureChannelOptions: (options =>
{
    options.Credentials = ChannelCredentials.Insecure;
}));

For more advanced initialization options, see the Client Initialization documentation.

Authentication

// Authenticate with username and password
EtcdClient client = new EtcdClient("https://localhost:23790");
var authRes = client.Authenticate(new Etcdserverpb.AuthenticateRequest()
{
    Name = "username",
    Password = "password",
});

// Use the token for authenticated operations
client.Put("foo/bar", "barfoo", new Grpc.Core.Metadata() {
    new Grpc.Core.Metadata.Entry("token", authRes.Token)
});

For more authentication options, see the Authentication documentation.

Features

Dependency Injection Support

Built-in support for Microsoft.Extensions.DependencyInjection with extension methods for easy configuration:

services.AddEtcdClient(options => {
    options.ConnectionString = "localhost:2379";
    options.UseInsecureChannel = true;
});

Automatic Retry Functionality

dotnet-etcd includes an automatic retry mechanism for handling transient failures when communicating with etcd clusters. By default, the client is configured with a retry policy that:

• Retries up to 5 times when encountering unavailable servers
• Uses exponential backoff between retry attempts
• Handles common transient errors automatically

This functionality is enabled by default and requires no additional configuration.

Canceling Operations

Operations can be canceled using a CancellationToken. By default, the client throws OperationCanceledException when a request is canceled.

CancellationTokenSource cts = new CancellationTokenSource();
try {
    cts.Cancel();
    var response = client.Status(new StatusRequest(), cancellationToken: cts.Token);
} catch (OperationCanceledException) {
    Console.WriteLine("Operation was canceled.");
}

For legacy cancellation behavior with RpcException, see the documentation.

Error Handling

Most errors from the etcd client are thrown as RpcException with specific status codes that can be handled appropriately:

try {
    var response = client.Get("non-existent-key");
} catch (RpcException ex) {
    switch (ex.StatusCode) {
        case StatusCode.NotFound:
            Console.WriteLine("Key not found");
            break;
        case StatusCode.Unavailable:
            Console.WriteLine("Server unavailable");
            break;
        // Handle other status codes
    }
}

Disposing the Client

The EtcdClient implements IDisposable and should be properly disposed when no longer needed:

using (var client = new EtcdClient("https://localhost:2379")) {
    var response = client.Get("my-key");
    // ...
}

For more details on proper client disposal, see the documentation.

Contributing

We welcome contributions to help improve dotnet-etcd! Please see the CONTRIBUTING.md file for guidelines on how to contribute.

For bug reports, feature requests, or questions, please create an issue on GitHub.

Running Tests

The project includes both unit tests and integration tests. Unit tests can be run without any external dependencies, while integration tests require a running etcd cluster.

Setting Up etcd for Testing

The dotnet-etcd.Tests directory includes scripts to easily set up either a single-node or a 3-node etcd cluster using Docker:

cd dotnet-etcd.Tests

# Start a single-node cluster
./start-etcd.sh

# Or start a 3-node cluster
./start-etcd.sh 3nodes

# Run the tests
dotnet test

# Stop the cluster when done
./stop-etcd.sh

For convenience, you can also use the script that handles the entire process:

cd dotnet-etcd.Tests

# Run integration tests with a single-node cluster
./run-integration-tests.sh

# Or with a 3-node cluster
./run-integration-tests.sh 3nodes

See the test README for more details on running tests.

Development

Running Tests

Unit Tests

To run only the unit tests (which don't require a running etcd server):

dotnet test dotnet-etcd.Tests/dotnet-etcd.Tests.csproj --filter "FullyQualifiedName~Unit"

Integration Tests

To run integration tests, you need a running etcd server. The integration tests will connect to etcd at localhost:2379 by default.

dotnet test dotnet-etcd.Tests/dotnet-etcd.Tests.csproj --filter "FullyQualifiedName~Integration"

All Tests

To run all tests:

dotnet test dotnet-etcd.Tests/dotnet-etcd.Tests.csproj

Code Coverage

To run tests with code coverage and generate a report:

1. Make sure you have the required tools:

dotnet tool install -g dotnet-reportgenerator-globaltool

2. Run the coverage script:

./run-unit-tests-with-coverage.sh

3. View the coverage report at ./dotnet-etcd.Tests/TestResults/CoverageReport/index.html

License

This project is licensed under the MIT License - see the LICENSE file for details.

Testing and Code Coverage

We have comprehensive test coverage for dotnet-etcd, including both unit tests and integration tests.

Running Tests

For detailed information about running tests and generating code coverage reports, see the TESTING.md file.

Quick Test Commands

# Run unit tests only
dotnet test dotnet-etcd.Tests/dotnet-etcd.Tests.csproj --filter "Category=Unit"

# Run integration tests (requires running etcd server)
dotnet test dotnet-etcd.Tests/dotnet-etcd.Tests.csproj --filter "Category=Integration"

# Run all tests
dotnet test dotnet-etcd.Tests/dotnet-etcd.Tests.csproj

Code Coverage

We use GitHub Actions to automatically generate code coverage reports for the main branch. You can view the latest code coverage report on the GitHub Pages site.

To generate a code coverage report locally:

# Install the required tools
dotnet tool install --global dotnet-reportgenerator-globaltool

# Run tests with coverage
dotnet test dotnet-etcd.Tests/dotnet-etcd.Tests.csproj --collect:"XPlat Code Coverage"

# Generate HTML report
reportgenerator -reports:"**/coverage.cobertura.xml" -targetdir:"coveragereport" -reporttypes:Html

# Open the report
open coveragereport/index.html  # On macOS
# or
start coveragereport/index.html  # On Windows

For more details, see the TESTING.md file.