dotnet-etcd-core 8.0.2

.NET 5.0 This package targets .NET 5.0. The package is compatible with this framework or higher. .NET Core 3.1 This package targets .NET Core 3.1. The package is compatible with this framework or higher. .NET Standard 2.0 This package targets .NET Standard 2.0. The package is compatible with this framework or higher. 
dotnet add package dotnet-etcd-core --version 8.0.2
                    


                    

                
NuGet\Install-Package dotnet-etcd-core -Version 8.0.2
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="dotnet-etcd-core" Version="8.0.2" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="dotnet-etcd-core" Version="8.0.2" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="dotnet-etcd-core" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add dotnet-etcd-core --version 8.0.2
                    


                    

                
#r "nuget: dotnet-etcd-core, 8.0.2"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#addin nuget:?package=dotnet-etcd-core&version=8.0.2
                    


                            Install dotnet-etcd-core as a Cake Addin
                        

                    

                
#tool nuget:?package=dotnet-etcd-core&version=8.0.2
                    


                            Install dotnet-etcd-core as a Cake Tool

dotnet-etcd

etcd logo

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

Build Status Nuget Version Info Nuget Download Info Code Coverage

Table of Contents

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

Core Operations

Advanced 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
  1. Run the coverage script:
./run-unit-tests-with-coverage.sh
  1. 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.

Product Compatible and additional computed target framework versions.
.NET net5.0 is compatible.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 is compatible. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
8.0.2 99 4/26/2025
6.2.1.1 415 3/9/2023
6.2.1 274 3/8/2023

* Package updates
     * Minor enhancements and cleanups