{"id":18436079,"url":"https://github.com/codenotary/immudb4net","last_synced_at":"2025-04-07T20:32:35.606Z","repository":{"id":58855680,"uuid":"508200407","full_name":"codenotary/immudb4net","owner":"codenotary","description":null,"archived":false,"fork":false,"pushed_at":"2023-07-12T16:43:34.000Z","size":555,"stargazers_count":3,"open_issues_count":4,"forks_count":2,"subscribers_count":12,"default_branch":"main","last_synced_at":"2023-07-12T17:40:46.731Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codenotary.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-06-28T07:34:54.000Z","updated_at":"2022-09-23T13:58:15.000Z","dependencies_parsed_at":"2023-01-29T15:31:21.036Z","dependency_job_id":null,"html_url":"https://github.com/codenotary/immudb4net","commit_stats":null,"previous_names":[],"tags_count":1,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenotary%2Fimmudb4net","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenotary%2Fimmudb4net/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenotary%2Fimmudb4net/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenotary%2Fimmudb4net/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codenotary","download_url":"https://codeload.github.com/codenotary/immudb4net/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223291629,"owners_count":17120965,"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":[],"created_at":"2024-11-06T06:10:14.708Z","updated_at":"2024-11-06T06:10:15.485Z","avatar_url":"https://github.com/codenotary.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ImmuDB4Net - The Official [immudb] Client for .NET [![License](https://img.shields.io/github/license/codenotary/immudb4j)](LICENSE)\n\n[immudb]: https://immudb.io/\n\n## Contents\n\n- [1. Introduction](#1-introduction)\n- [2. Prerequisites](#2-prerequisites)\n- [3. Installation](#3-installation)\n- [4. Build locally from sources](#4-build-locally-from-sources)\n- [5. Supported Versions](#5-supported-versions)\n- [6. Quickstart](#6-quickstart)\n- [7. Step-by-step Guide](#7-step-by-step-guide)\n  - [7.1. Creating a Client](#71-creating-a-client)\n  - [7.2. User Sessions](#72-user-sessions)\n  - [7.3. Creating a Database](#73-creating-a-database)\n  - [7.4. Setting the Active Database](#74-setting-the-active-database)\n  - [7.5. Standard Read and Write](#75-standard-read-and-write)\n  - [7.6. Verified or Safe Read and Write](#76-verified-or-safe-read-and-write)\n  - [7.7. Multi-key Read and Write](#77-multi-key-read-and-write)\n  - [7.8. Executing SQL statements and queries](#78-executing-sql-statements-and-queries)\n  - [7.9. Closing the client](#79-closing-the-client)\n- [8. Building from source](#8-building-from-source)\n- [9. Contributing](#9-contributing)\n\n## 1. Introduction\n\nImmuDB4Net implements a [gRPC] immudb client, based on [immudb's official protobuf definition].\nIt exposes a minimal and simple to use API for applications, while the cryptographic verifications and state update protocol implementation\nare fully implemented internally by this client.\n\nThe latest validated immudb state may be kept in the local file system using default `FileImmuStateHolder`.\nPlease read [immudb Research Paper] for details of how immutability is ensured by [immudb].\n\n[gRPC]: https://grpc.io/\n[immudb Research Paper]: https://immudb.io/\n[immudb's official protobuf definition](https://github.com/codenotary/immudb/blob/master/pkg/api/schema/schema.proto)\n\n## 2. Prerequisites\n\nImmuDB4Net assumes you have access to a running immudb server.\nRunning `immudb` on your system is very simple, please refer to this [immudb QuickStart](https://docs.immudb.io/master/quickstart.html) page.\n\n## 3. Installation\n\nInclude ImmuDB4Net as a dependency in your project via Nuget package. `ImmuDB4Net` is currently hosted on [NuGet.Org]\n\n[NuGet.Org]: https://nuget.org\n\n## 4. Build locally from sources\n\nUse ```dotnet build``` to build locally the ImmuDB client assembly.\n\n## 5. Supported Versions\n\nImmuDB4Net supports the [latest immudb server] release, that is 1.4.0 at the time of updating this document.\n\n[latest immudb server]: https://github.com/codenotary/immudb/releases/tag/v1.4.0\n\n## 6. Quickstart\n\n[Hello Immutable World!] example can be found in `immudb-client-examples` repo:\n\n[Hello Immutable World!]: https://github.com/codenotary/immudb-client-examples/blob/feat/dotnet-example/dotnet/simple-app\n\n## 7. Step-by-step Guide\n\n### 7.1. Creating a Client\n\nThe following code snippets show how to create a client.\n\nUsing default configuration:\n\n``` C#\n    ImmuClient immuClient = ImmuClient.NewBuilder().Build();\n\n    // or\n\n    Immuclient immuClient = new ImmuClient();\n    Immuclient immuClient = new ImmuClient(\"localhost\", 3322);\n    Immuclient immuClient = new ImmuClient(\"localhost\", 3322, \"defaultdb\");\n\n\n```\n\nSetting `immudb` url and port:\n\n``` C#\n    ImmuClient immuClient = ImmuClient.NewBuilder()\n                                .WithServerUrl(\"localhost\")\n                                .WithServerPort(3322)\n                                .Build();\n\n    ImmuClient immuClient = ImmuClient.NewBuilder()\n                                .WithServerUrl(\"localhost\")\n                                .WithServerPort(3322)\n                                .Build();\n\n```\n\nCustomizing the `State Holder`:\n\n``` C#\n    FileImmuStateHolder stateHolder = FileImmuStateHolder.NewBuilder()\n                                        .WithStatesFolder(\"./my_immuapp_states\")\n                                        .Build();\n\n    ImmuClient immuClient = ImmuClient.NewBuilder()\n                                      .WithStateHolder(stateHolder)\n                                      .Build();\n```\n\n### 7.2. User Sessions\n\nUse `Open` and `Close` methods to initiate and terminate user sessions:\n\n``` C#\n    await immuClient.Open(\"usr1\", \"pwd1\", \"defaultdb\");\n\n    // Interact with immudb using logged-in user.\n    //...\n\n    await immuClient.Close();\n\n    // or one liner open the session right \n    client = await ImmuClient.NewBuilder().Open();\n\n    //then close it\n    await immuClient.Close();\n\n```\n\n### 7.3. Creating a Database\n\nCreating a new database is quite simple:\n\n``` C#\n    await immuClient.CreateDatabase(\"db1\");\n```\n\n### 7.4. Setting the Active Database\n\nSpecify the active database with:\n\n``` C#\n    await immuClient.UseDatabase(\"db1\");\n```\n\n### 7.5. Standard Read and Write\n\nimmudb provides standard read and write operations that behave as in a standard\nkey-value store i.e. no cryptographic verification is involved. Such operations\nmay be used when validations can be postponed.\n\n``` C#\n    await client.Set(\"k123\", \"v123\");\n    string v = await client.Get(\"k123\").ToString();\nor\n    await client.Set(\"k123\", new byte[]{1, 2, 3});\n    byte[] v = await client.Get(\"k123\").Value;\n```\n\n### 7.6. Verified or Safe Read and Write\n\nimmudb provides built-in cryptographic verification for any entry. The client\nimplements the mathematical validations while the application uses as a standard\nread or write operation:\n\n``` C#\n    try \n    {\n        await Client.VerifiedSet(\"k123\", new byte[]{1, 2, 3});\n        byte[] v = await client.VerifiedGet(\"k123\").Value;\nor\n        await client.VerifiedSet(\"k123\", \"v123\");\n        string v = await client.VerifiedGet(\"k123\").ToString();\n\n    } catch(VerificationException e) {\n\n        // Check if it is a data tampering detected case!\n\n    }\n```\n\n### 7.7. Multi-key Read and Write\n\nTransactional multi-key read and write operations are supported by immudb and ImmuDB4Net.\n\nAtomic multi-key write (all entries are persisted or none):\n\n``` C#\n        List\u003cKVPair\u003e kvs = new List\u003cKVPair\u003e() \n        {\n            new KVPair(\"sga-key1\", new byte[] {1, 2}),\n            new KVPair(\"sga-key2\", new byte[] {3, 4})\n        }\n\n        try \n        {\n            await immuClient.SetAll(kvs);\n        } catch (CorruptedDataException e) \n        {\n            // ...\n        }\n```\n\nAtomic multi-key read (all entries are retrieved or none):\n\n``` C#\n    List\u003cstring\u003e keys = new List\u003cstring\u003e() {key1, key2, key3};\n    List\u003cEntry\u003e result = await immuClient.GetAll(keys);\n\n    foreach(Entry entry in result) {\n        byte[] key = entry.Key;\n        byte[] value = entry.Value;\n        // ...\n    }\n```\n\n### 7.8. Executing SQL statements and queries\n\nImmuDB4Net provides `SQLExec` and `SQLQuery` commands and an example of usage is below:\n\n``` C#\n        var client = new ImmuClient();\n        await client.Open(\"immudb\", \"immudb\", \"defaultdb\");\n\n        await client.SQLExec(\"CREATE TABLE IF NOT EXISTS logs(id INTEGER AUTO_INCREMENT, created TIMESTAMP, entry VARCHAR, PRIMARY KEY id)\");\n        await client.SQLExec(\"CREATE INDEX IF NOT EXISTS ON logs(created)\");\n        var rspInsert = await client.SQLExec(\"INSERT INTO logs(created, entry) VALUES($1, $2)\",\n                SQLParameter.Create(DateTime.UtcNow),\n                SQLParameter.Create(\"hello immutable world\"));\n        var queryResult = await client.SQLQuery(\"SELECT created, entry FROM LOGS order by created DESC\");\n        var sqlVal = queryResult.Rows[0][\"entry\"];\n        \n        Console.WriteLine($\"The log entry is: {sqlVal.Value}\");\n\n```\n\n### 7.9. Closing the client\n\nUse `Close`, for closing the connection with immudb server . When terminating the process, use the `ImmuClient.ReleaseSdkResources` function :\n\n``` C#\n    await client.Close();\n    await ImmuClient.ReleaseSdkResources();\n```\n\nNote: After the shutdown, a new client needs to be created to establish a new connection.\n\n## 8. Building from source\n\nTo build from source you need as prerequisites to clone a local copy of the git repo: \u003chttps://github.com/codenotary/immudb4net\u003e\nand then to have installed on the build machine the dotnet 6.0 SDK. Then, from the terminal just run ```dotnet build``` .\n\nIn order to successfully execute the integration tests with the command```dotnet test``` you have to install as prerequisites ```docker``` and also to start locally an ImmuDB instance on port 3322. For example, you can run ImmuDB in docker as below:\n\n``` bash\ndocker run -d --name immudb -p 3322:3322 codenotary/immudb:latest\n```\n\n## 9. Contributing\n\nWe welcome contributions. Feel free to join the team!\n\nTo report bugs or get help, use [GitHub's issues].\n\n[GitHub's issues]: https://github.com/codenotary/immudb4net/issues\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodenotary%2Fimmudb4net","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodenotary%2Fimmudb4net","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodenotary%2Fimmudb4net/lists"}