{"id":19100047,"url":"https://github.com/shubhamranjan/dotnet-etcd","last_synced_at":"2025-04-08T17:16:52.817Z","repository":{"id":33399007,"uuid":"135815354","full_name":"shubhamranjan/dotnet-etcd","owner":"shubhamranjan","description":"A C# .NET (dotnet) GRPC client for etcd v3 +","archived":false,"fork":false,"pushed_at":"2024-04-05T21:13:38.000Z","size":553,"stargazers_count":252,"open_issues_count":10,"forks_count":53,"subscribers_count":13,"default_branch":"main","last_synced_at":"2024-04-12T07:06:21.462Z","etag":null,"topics":["c-sharp","class-library","csharp","dotnet","dotnet-core","dotnet-framework","dotnet-standard","dotnetcore","etcd","etcd-client","etcd3","etcdv3","grpc","grpc-client","hacktoberfest","key-value","library"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shubhamranjan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2018-06-02T12:20:58.000Z","updated_at":"2024-04-07T12:58:14.000Z","dependencies_parsed_at":"2024-04-05T22:22:20.264Z","dependency_job_id":"057a5cc3-bac6-4144-a1b2-a3a52f2b4559","html_url":"https://github.com/shubhamranjan/dotnet-etcd","commit_stats":{"total_commits":245,"total_committers":17,"mean_commits":"14.411764705882353","dds":"0.24081632653061225","last_synced_commit":"c82573f242e913af1017056385d7255267975a04"},"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shubhamranjan%2Fdotnet-etcd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shubhamranjan%2Fdotnet-etcd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shubhamranjan%2Fdotnet-etcd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shubhamranjan%2Fdotnet-etcd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shubhamranjan","download_url":"https://codeload.github.com/shubhamranjan/dotnet-etcd/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245735851,"owners_count":20663804,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c-sharp","class-library","csharp","dotnet","dotnet-core","dotnet-framework","dotnet-standard","dotnetcore","etcd","etcd-client","etcd3","etcdv3","grpc","grpc-client","hacktoberfest","key-value","library"],"created_at":"2024-11-09T03:52:27.276Z","updated_at":"2025-04-08T17:16:52.794Z","avatar_url":"https://github.com/shubhamranjan.png","language":"C#","funding_links":[],"categories":["library","C\\#","csharp"],"sub_categories":[],"readme":"# dotnet-etcd\n\n![etcd logo](https://raw.githubusercontent.com/shubhamranjan/dotnet-etcd/master/docs/img/etcd-logo-rectangle.png)\n\nA C# .NET (dotnet) GRPC client for etcd v3+\n\n![Build Status](https://github.com/shubhamranjan/dotnet-etcd/actions/workflows/codeql-analysis.yml/badge.svg)\n![Nuget Version Info](https://img.shields.io/nuget/v/dotnet-etcd.svg)\n![Nuget Download Info](https://img.shields.io/nuget/dt/dotnet-etcd.svg)\n[![Code Coverage](https://img.shields.io/badge/coverage-XX%-brightgreen)](https://github.com/shubhamranjan/dotnet-etcd/actions/workflows/dotnet-tests.yml/artifacts)\n\n## Table of Contents\n\n- [Supported .NET Versions](#supported-net-versions)\n- [Installing Package](#installing-package)\n- [Documentation](#documentation)\n- [Quick Start](#quick-start)\n- [Features](#features)\n- [Contributing](#contributing)\n- [Testing and Code Coverage](#testing-and-code-coverage)\n\n## Supported .NET Versions\n\n- .NET 9\n- .NET 8\n\n### Compatibility Note\n\nFor older .NET versions:\n\n- For .NET 6/7 support, use version 7.2.0\n- For .NET versions \u003c 6, use version \u003c 5.x\n\n## Installing Package\n\nNuget package is published on [nuget.org](https://www.nuget.org/packages/dotnet-etcd/) and can be installed in the\nfollowing ways:\n\n### Nuget Package Manager\n\n```powershell\nInstall-Package dotnet-etcd\n```\n\n### .NET CLI\n\n```bash\ndotnet add package dotnet-etcd\n```\n\n### Paket CLI\n\n```bash\npaket add dotnet-etcd\n```\n\n\u003e The NuGet Team does not provide support for this client. Please contact its maintainers for support.\n\n## Documentation\n\nFor comprehensive documentation of all operations and method overloads, please see\nthe [documentation pages](docs/index.md).\n\nThe documentation is organized into the following sections:\n\n### Getting Started\n\n- [Client Initialization](docs/client-initialization/index.md) - How to initialize and configure the client\n- [Dependency Injection](docs/client-initialization/dependency-injection.md) - Using the client with DI\n- [Authentication](docs/authentication/index.md) - Authentication with etcd\n\n### Core Operations\n\n- [Key-Value Operations](docs/key-value/index.md) - Working with keys and values\n- [Watch Operations](docs/watch/index.md) - Watching for changes to keys\n- [Lease Operations](docs/lease/index.md) - Working with leases\n- [Lock Operations](docs/lock/index.md) - Distributed locking\n- [Election Operations](docs/election/index.md) - Leader election\n\n### Advanced Operations\n\n- [Cluster Operations](docs/cluster/index.md) - Managing the etcd cluster\n- [Maintenance Operations](docs/maintenance/index.md) - Maintenance tasks\n- [Transactions](docs/transactions/index.md) - Atomic operations\n\nThe documentation includes detailed API references with all method overloads, parameters, and return types, as well as\nexamples for common use cases.\n\n## Quick Start\n\nAdd using statement at the top of your class file:\n\n```csharp\nusing dotnet_etcd;\n```\n\n### Client Initialization\n\n```csharp\n// Basic initialization with a single endpoint\nEtcdClient client = new EtcdClient(\"localhost:2379\");\n\n// Multiple endpoints\nEtcdClient client = new EtcdClient(\"https://localhost:23790,https://localhost:23791,https://localhost:23792\");\n\n// Insecure connection (HTTP)\nEtcdClient client = new EtcdClient(\"http://localhost:23790\", configureChannelOptions: (options =\u003e\n{\n    options.Credentials = ChannelCredentials.Insecure;\n}));\n```\n\nFor more advanced initialization options, see\nthe [Client Initialization documentation](docs/client-initialization/index.md).\n\n### Authentication\n\n```csharp\n// Authenticate with username and password\nEtcdClient client = new EtcdClient(\"https://localhost:23790\");\nvar authRes = client.Authenticate(new Etcdserverpb.AuthenticateRequest()\n{\n    Name = \"username\",\n    Password = \"password\",\n});\n\n// Use the token for authenticated operations\nclient.Put(\"foo/bar\", \"barfoo\", new Grpc.Core.Metadata() {\n    new Grpc.Core.Metadata.Entry(\"token\", authRes.Token)\n});\n```\n\nFor more authentication options, see the [Authentication documentation](docs/authentication/index.md).\n\n## Features\n\n### Dependency Injection Support\n\nBuilt-in support for Microsoft.Extensions.DependencyInjection with extension methods for easy configuration:\n\n```csharp\nservices.AddEtcdClient(options =\u003e {\n    options.ConnectionString = \"localhost:2379\";\n    options.UseInsecureChannel = true;\n});\n```\n\n### Automatic Retry Functionality\n\ndotnet-etcd includes an automatic retry mechanism for handling transient failures when communicating with etcd clusters.\nBy default, the client is configured with a retry policy that:\n\n- Retries up to 5 times when encountering unavailable servers\n- Uses exponential backoff between retry attempts\n- Handles common transient errors automatically\n\nThis functionality is enabled by default and requires no additional configuration.\n\n### Canceling Operations\n\nOperations can be canceled using a CancellationToken. By default, the client throws OperationCanceledException when a\nrequest is canceled.\n\n```csharp\nCancellationTokenSource cts = new CancellationTokenSource();\ntry {\n    cts.Cancel();\n    var response = client.Status(new StatusRequest(), cancellationToken: cts.Token);\n} catch (OperationCanceledException) {\n    Console.WriteLine(\"Operation was canceled.\");\n}\n```\n\nFor legacy cancellation behavior with RpcException, see the [documentation](docs/index.md).\n\n### Error Handling\n\nMost errors from the etcd client are thrown as `RpcException` with specific status codes that can be handled\nappropriately:\n\n```csharp\ntry {\n    var response = client.Get(\"non-existent-key\");\n} catch (RpcException ex) {\n    switch (ex.StatusCode) {\n        case StatusCode.NotFound:\n            Console.WriteLine(\"Key not found\");\n            break;\n        case StatusCode.Unavailable:\n            Console.WriteLine(\"Server unavailable\");\n            break;\n        // Handle other status codes\n    }\n}\n```\n\n### Disposing the Client\n\nThe `EtcdClient` implements `IDisposable` and should be properly disposed when no longer needed:\n\n```csharp\nusing (var client = new EtcdClient(\"https://localhost:2379\")) {\n    var response = client.Get(\"my-key\");\n    // ...\n}\n```\n\nFor more details on proper client disposal, see the [documentation](docs/index.md#disposing-the-client).\n\n## Contributing\n\nWe welcome contributions to help improve dotnet-etcd! Please see\nthe [CONTRIBUTING.md](https://github.com/shubhamranjan/dotnet-etcd/blob/master/CONTRIBUTING.md) file for guidelines on\nhow to contribute.\n\nFor bug reports, feature requests, or questions, please create\nan [issue](https://github.com/shubhamranjan/dotnet-etcd/issues) on GitHub.\n\n### Running Tests\n\nThe project includes both unit tests and integration tests. Unit tests can be run without any external dependencies,\nwhile integration tests require a running etcd cluster.\n\n#### Setting Up etcd for Testing\n\nThe `dotnet-etcd.Tests` directory includes scripts to easily set up either a single-node or a 3-node etcd cluster using\nDocker:\n\n```bash\ncd dotnet-etcd.Tests\n\n# Start a single-node cluster\n./start-etcd.sh\n\n# Or start a 3-node cluster\n./start-etcd.sh 3nodes\n\n# Run the tests\ndotnet test\n\n# Stop the cluster when done\n./stop-etcd.sh\n```\n\nFor convenience, you can also use the script that handles the entire process:\n\n```bash\ncd dotnet-etcd.Tests\n\n# Run integration tests with a single-node cluster\n./run-integration-tests.sh\n\n# Or with a 3-node cluster\n./run-integration-tests.sh 3nodes\n```\n\nSee the [test README](dotnet-etcd.Tests/README.md) for more details on running tests.\n\n## Development\n\n### Running Tests\n\n#### Unit Tests\n\nTo run only the unit tests (which don't require a running etcd server):\n\n```bash\ndotnet test dotnet-etcd.Tests/dotnet-etcd.Tests.csproj --filter \"FullyQualifiedName~Unit\"\n```\n\n#### Integration Tests\n\nTo run integration tests, you need a running etcd server. The integration tests will connect to etcd at `localhost:2379`\nby default.\n\n```bash\ndotnet test dotnet-etcd.Tests/dotnet-etcd.Tests.csproj --filter \"FullyQualifiedName~Integration\"\n```\n\n#### All Tests\n\nTo run all tests:\n\n```bash\ndotnet test dotnet-etcd.Tests/dotnet-etcd.Tests.csproj\n```\n\n### Code Coverage\n\nTo run tests with code coverage and generate a report:\n\n1. Make sure you have the required tools:\n\n```bash\ndotnet tool install -g dotnet-reportgenerator-globaltool\n```\n\n2. Run the coverage script:\n\n```bash\n./run-unit-tests-with-coverage.sh\n```\n\n3. View the coverage report at `./dotnet-etcd.Tests/TestResults/CoverageReport/index.html`\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Testing and Code Coverage\n\nWe have comprehensive test coverage for dotnet-etcd, including both unit tests and integration tests.\n\n### Running Tests\n\nFor detailed information about running tests and generating code coverage reports, see the [TESTING.md](TESTING.md)\nfile.\n\n#### Quick Test Commands\n\n```bash\n# Run unit tests only\ndotnet test dotnet-etcd.Tests/dotnet-etcd.Tests.csproj --filter \"Category=Unit\"\n\n# Run integration tests (requires running etcd server)\ndotnet test dotnet-etcd.Tests/dotnet-etcd.Tests.csproj --filter \"Category=Integration\"\n\n# Run all tests\ndotnet test dotnet-etcd.Tests/dotnet-etcd.Tests.csproj\n```\n\n### Code Coverage\n\nWe use GitHub Actions to automatically generate code coverage reports for the main branch. You can view the latest code\ncoverage report on the [GitHub Pages site](https://shubhamranjan.github.io/dotnet-etcd/).\n\nTo generate a code coverage report locally:\n\n```bash\n# Install the required tools\ndotnet tool install --global dotnet-reportgenerator-globaltool\n\n# Run tests with coverage\ndotnet test dotnet-etcd.Tests/dotnet-etcd.Tests.csproj --collect:\"XPlat Code Coverage\"\n\n# Generate HTML report\nreportgenerator -reports:\"**/coverage.cobertura.xml\" -targetdir:\"coveragereport\" -reporttypes:Html\n\n# Open the report\nopen coveragereport/index.html  # On macOS\n# or\nstart coveragereport/index.html  # On Windows\n```\n\nFor more details, see the [TESTING.md](TESTING.md) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshubhamranjan%2Fdotnet-etcd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshubhamranjan%2Fdotnet-etcd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshubhamranjan%2Fdotnet-etcd/lists"}