{"id":19454612,"url":"https://github.com/fauna/faunadb-csharp","last_synced_at":"2025-04-07T09:19:55.086Z","repository":{"id":10316915,"uuid":"42745704","full_name":"fauna/faunadb-csharp","owner":"fauna","description":"C# driver for FaunaDB v4","archived":false,"fork":false,"pushed_at":"2024-08-28T19:36:53.000Z","size":3707,"stargazers_count":61,"open_issues_count":8,"forks_count":15,"subscribers_count":31,"default_branch":"v4","last_synced_at":"2025-03-31T07:05:28.103Z","etag":null,"topics":["client","clients","csharp","database","driver","drivers","fauna","faunadb"],"latest_commit_sha":null,"homepage":"https://fauna.com","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fauna.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-09-18T20:31:11.000Z","updated_at":"2024-11-04T23:48:50.000Z","dependencies_parsed_at":"2022-09-04T14:13:14.857Z","dependency_job_id":"efb8b494-3417-4c82-9496-92c8dd6df7fa","html_url":"https://github.com/fauna/faunadb-csharp","commit_stats":null,"previous_names":["faunadb/faunadb-csharp"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fauna%2Ffaunadb-csharp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fauna%2Ffaunadb-csharp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fauna%2Ffaunadb-csharp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fauna%2Ffaunadb-csharp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fauna","download_url":"https://codeload.github.com/fauna/faunadb-csharp/tar.gz/refs/heads/v4","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247622983,"owners_count":20968575,"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":["client","clients","csharp","database","driver","drivers","fauna","faunadb"],"created_at":"2024-11-10T17:10:27.465Z","updated_at":"2025-04-07T09:19:55.052Z","avatar_url":"https://github.com/fauna.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# C# driver for Fauna v4 (deprecated)\n\n[![NuGet](https://img.shields.io/nuget/v/FaunaDB.Client.svg?maxAge=21600)](https://www.nuget.org/packages/FaunaDB.Client/)\n[![License](https://img.shields.io/badge/license-MPL_2.0-blue.svg?maxAge=2592000)](https://raw.githubusercontent.com/fauna/faunadb-csharp/main/LICENSE)\n\n\u003e [!WARNING]\n\u003e  Fauna is decommissioning FQL v4 on June 30, 2025.\n\u003e\n\u003e This driver is not compatible with FQL v10, the latest version. Fauna accounts\n\u003e created after August 21, 2024 must use FQL v10. Ensure you migrate existing\n\u003e projects to the official v10 driver by the v4 EOL date:\n\u003e https://github.com/fauna/fauna-dotnet.\n\u003e\n\u003e For more information, see the [v4 end of life (EOL)\n\u003e announcement](https://docs.fauna.com/fauna/v4/#fql-v4-end-of-life) and\n\u003e [related FAQ](https://docs.fauna.com/fauna/v4/migration/faq).\n\nThe official C# driver for [Fauna v4](https://docs.fauna.com/fauna/v4/).\n\nSee the [Fauna v4 documentation](https://docs.fauna.com/fauna/v4) and\n[tutorials](https://docs.fauna.com/fauna/v4/learn/tutorials/fql/crud?lang=javascript) for\nguides and a complete database [API\nreference](https://docs.fauna.com/fauna/v4/api/fql/).\n\n## Documentation\n\nC# doc are hosted on GitHub:\n\n* [faunadb-csharp](https://fauna.github.io/faunadb-csharp/4.2.0/)\n\n## How to Build\n\n### Requirements\n\n* [.NET SDK](https://www.microsoft.com/net/download/all)\n* Mono if you're using macOS or Linux\n\n### Build\n\nRunning the following command will build the driver for all supported .NET frameworks:\n\n```bash\ndotnet build FaunaDB.Client\n```\n\nIf you're using MacOS or Linux you may need to override `FrameworkPathOverride` to point to the Mono specific api:\n\n```bash\nFrameworkPathOverride=/Library/Frameworks/Mono.framework/Versions/Current/lib/mono/4.5-api dotnet build FaunaDB.Client/ --framework net45\n```\n\n### Running Tests\n\nRunning the following command will run the tests for all supported .NET frameworks\n\n```bash\ndotnet test FaunaDB.Client.Test\n```\n\nIf you're using macOS or Linux you may need to override `FrameworkPathOverride`:\n\n```bash\nFrameworkPathOverride=/Library/Frameworks/Mono.framework/Versions/Current/lib/mono/4.5-api dotnet test FaunaDB.Client.Test/ --framework net45\n```\n\nspecific tests:\n\n```bash\nFrameworkPathOverride=/Library/Frameworks/Mono.framework/Versions/Current/lib/mono/4.5-api dotnet test FaunaDB.Client.Test/ --framework net45 --filter Name~EncoderTest\n```\n\nIf you're using .net core (which is cross-platform for Windows, Mac or Linux), use the following examples for running tests:\n```bash\n# runs all the tests for all target frameworks from csproj file\ndotnet test FaunaDB.Client.Test\n\n# runs tests for a specific target framework\ndotnet test FaunaDB.Client.Test --framework net45\ndotnet test FaunaDB.Client.Test --framework netcoreapp3.1\ndotnet test FaunaDB.Client.Test --framework net5.0\n\n# runs all the tests in a specified test class (format: namespace.class)\ndotnet test FaunaDB.Client.Test --filter FullyQualifiedName~Test.EnvironmentHeaderTest --framework netcoreapp3.1\n\n# runs a single test\ndotnet test FaunaDB.Client.Test --filter Name=TestNetlifyEnvironment --framework netcoreapp3.1\n\n# runs all the tests starting with TestUnknownEnvironment\ndotnet test FaunaDB.Client.Test --filter FullyQualifiedName~Test.EnvironmentHeaderTest.TestUnknownEnvironment --framework netcoreapp3.1\n```\n\n## Referencing FaunaDB Assembly\n\nFirst install the Nuget package by adding the package reference to your MSBuild project:\n\n```xml\n\u003cPackageReference Include=\"FaunaDB.Client\" Version=\"4.2.0\" /\u003e\n```\n\nor by using your IDE and searching for `FaunaDB.Client`.\n\n## Quickstart\n\nHere is an example on how to execute a simple query on FaunaDB:\n\n```csharp\nusing System;\nusing System.Collections.Generic;\nusing System.Threading.Tasks;\nusing FaunaDB.Client;\nusing FaunaDB.Types;\n\nusing static FaunaDB.Query.Language;\n\nnamespace FaunaDBProject\n{\n    class FaunaDBHelloWorld\n    {\n        static readonly string ENDPOINT = \"https://db.fauna.com:443\";\n        static readonly string SECRET = \"\u003c\u003cYOUR-SECRET-HERE\u003e\u003e\";\n\n        static void ProcessData(Value[] values)\n        {\n            foreach (Value value in values)\n            {\n                //do something\n            }\n        }\n        static async Task DoQuery(FaunaClient client)\n        {\n            Value result = await client.Query(Paginate(Match(Index(\"spells\"))));\n            IResult\u003cValue[]\u003e data = result.At(\"data\").To\u003cValue[]\u003e();\n\n            data.Match(\n                Success: value =\u003e ProcessData(value),\n                Failure: reason =\u003e Console.WriteLine($\"Something went wrong: {reason}\")\n            );\n        }\n\n        public static void Main(string[] args)\n        {\n            var client = new FaunaClient(endpoint: ENDPOINT, secret: SECRET);\n\n            DoQuery(client).Wait();\n        }\n    }\n}\n```\n\nThis small example shows how to use pretty much every aspect of the library.\n\n#### How to instantiate a FaunaDB `FaunaClient`\n\n```csharp\nvar client = new FaunaClient(endpoint: ENDPOINT, secret: SECRET, httpClient: HTTP_CLIENT, timeout: TIMEOUT);\n```\n\nExcept `secret` all other arguments are optional.\n\nYou can also pass a custom HttpClient when creating a new FaunaClient:\n\n```csharp\n// using System.Net.Http;\nvar http = new HttpClient();\n\n// The default request headers can be any string values, but should be specific to your application.\nhttp.DefaultRequestHeaders.Add(\"X-Custom-Header\", \"42\");\n\nhttp.Timeout = TimeSpan.FromSeconds(15);\n\nvar client = new FaunaClient(\"secret\", \"http://localhost:9090/\", httpClient: http);\n```\n\n#### HTTP 2.0 support\nStarting from version 4.0.0 of this driver (faunadb-csharp), HTTP/2 support is enabled by default for .NET standards 2.1 and above.\nThis means that if you use .NET core 3.1 and above (which support that standard), you'll be sending requests to Fauna on HTTP/2.\n.NET standards lower than 2.1 and .NET frameworks 4.5-4.8 have HTTP/1.1 enabled as the default protocol version, since they lack of support for HTTP/2.\nWe've also added an optional parameter if you want to specify the version of the protocol directly:\n```csharp\nvar adminClient = new FaunaClient(\n    endpoint: endpoint,\n    secret: secret,\n    httpVersion: HttpVersion.Version11\n);\n```\n\n#### How to execute a query\n\n```csharp\nValue result = await client.Query(Paginate(Match(Index(\"spells\"))));\n```\n\n`Query` methods receives an `Expr` object. `Expr` objects can be composed with others `Expr` to create complex query objects. `FaunaDB.Query.Language` is a helper class where you can find all available expressions in the library.\n\nYou can also pass a `TimeSpan queryTimeout` argument to that specific query as well:\n\n```csharp\nValue result = await client.Query(Paginate(Match(Index(\"spells\"))), TimeSpan.FromSeconds(42));\n```\n\n#### How to access objects fields and convert to primitive values\n\nObjects fields are accessed through `At` methods of `Value` class. It's possible to access fields by names if the value represents an object or by index if it represents an array. Also it's possible to convert `Value` class to its primitive correspondent using `To` methods specifying a type.\n\n```csharp\nIResult\u003cValue[]\u003e data = result.At(\"data\").To\u003cValue[]\u003e();\n```\n\n#### How work with `IResult\u003cT\u003e` objects\n\nThis object represents the result of an operation and it might be success or a failure. All convertion operations returns an object like this. This way it's possible to avoid check for nullability everywhere in the code.\n\n```csharp\ndata.Match(\n    Success: value =\u003e ProcessData(value),\n    Failure: reason =\u003e Console.WriteLine($\"Something went wrong: {reason}\")\n);\n```\n\nOptionally it's possible transform one `IResult\u003cT\u003e` into another `IResult\u003cU\u003e` of different type using `Map` and `FlatMap`.\n\n```csharp\nIResult\u003cint\u003e result = \u003c\u003c...\u003e\u003e;\nIResult\u003cstring\u003e result.Map(value =\u003e value.toString());\n```\n\nIf `result` represents an failure all calls to `Map` and `FlatMap` are ignored. See `FaunaDB.Types.Result`.\n\n### How to work with user defined classes\n\nInstead of manually creating your objects via the DSL (e.g. the Obj() method), you may use the `Encoder` class to convert a user-defined type into the equivalent `Value` type.\n\nFor example:\n\n```csharp\nclass Product\n{\n    [FaunaField(\"description\")]\n    public string Description { get; set; }\n\n    [FaunaField(\"price\")]\n    public double Price { get; set; }\n\n    [FaunaConstructor]\n    public Product(string description, double price)\n    {\n        Description = description;\n        Price = price;\n    }\n}\n```\n\nTo persist an instance of `Product` in FaunaDB:\n\n```csharp\nProduct product = new Product(\"Smartphone\", 649.90);\n\nawait client.Query(\n    Create(\n        Collection(\"product\"),\n        Obj(\"data\", Encoder.Encode(product))\n    )\n);\n```\n\nTo convert from a `Value` type back to the `Product` type, you can use a `Decoder`:\n\n```csharp\nValue value = await client.Query(Get(Ref(Collection(\"product\"), \"123456789\")));\n\nProduct product = Decoder.Decode\u003cProduct\u003e(value.At(\"data\"));\n```\n\nor via the `To\u003cT\u003e()` helper method:\n\n```csharp\nValue value = await client.Query(Get(Ref(Collection(\"product\"), \"123456789\")));\n\nIResult\u003cProduct\u003e product = value.At(\"data\").To\u003cProduct\u003e();\nproduct.Match(\n    Success: p =\u003e Console.WriteLine(\"Product loaded: {0}\", p.Description),\n    Failure: reason =\u003e Console.WriteLine($\"Something went wrong: {reason}\")\n);\n\n// or even:\n\nProduct productLoaded = value.At(\"data\").To\u003cProduct\u003e().Value;\nConsole.WriteLine(\"Product loaded: {0}\", prod.Description);\n```\n\nNote that in this case the return type is `IResult\u003cT\u003e`.\n\nThere are three attributes that can be used to change the behavior of the `Encoder` and `Decoder`:\n\n- `FaunaField`: Used to override a custom field name and/or provide a default value for that field. If this attribute is not specified, the member name will be used instead. Can be used on fields, properties and constructor arguments.\n- `FaunaConstructor`: Used to mark a constructor or a public static method as the method used to instantiate the specified type. This attribute can be used only once per class.\n- `FaunaIgnore`: Used to ignore a specific member. Can be used on fields, properties and constructors arguments. If used on a constructor argument, that argument must have a default value.\n\n`Encoder` and `Decoder` can currently convert:\n\n- Primitive scalar types (`int`, `long`, `string`, etc.)\n- Primitive arrays, generic collections such as `List\u003cT\u003e`, and their respective interfaces such as `IList\u003cT\u003e`.\n- Dictionaries with string keys, such as `Dictionary\u003cstring, T\u003e` and its respective interface `IDictionary\u003cstring, T\u003e`.\n\n### Document streaming\n\nFauna supports document streaming, where changes to a streamed document are pushed to all clients subscribing to that document.\n\nThe streaming API is built using the Observer pattern which enables a subscriber to register with and receive notifications from a provider.\nProvider is implemented within `StreamingEventHandler` class, and subscriber within `StreamingEventMonitor` class.\n\nThe following example assumes that you have already created a `FaunaClient`.\n\nIn the example below, we are capturing the 4 first messages by manually binding a subscriber.\n\n```csharp\n// docRef is a reference to the document for which we want to stream updates.\n// You can acquire a document reference with a query like the following, but it\n// needs to work with the documents that you have.\n// var docRef = Get(Ref(Collection(\"scoreboards\"), \"123\"));\n\n// create a data provider\nvar provider = await adminClient.Stream(docRef);\n\n// we use this object to signalize a completion of\n// asynchronous operation for the current example\nvar done = new TaskCompletionSource\u003cobject\u003e();\n\n// a collection for storage of incoming events from the provider\nList\u003cValue\u003e events = new List\u003cValue\u003e();\n\n// creating a subscriber\n// it takes 3 lambdas that describe the following:\n// - next event processing\n// - error processing\n// - completion processing\nvar monitor = new StreamingEventMonitor(\n    value =\u003e\n    {\n        events.Add(value);\n        if (events.Count == 4)\n        {\n            provider.Complete();\n        }\n        else\n        {\n            provider.RequestData();\n        }\n    },\n    ex =\u003e { done.SetException(ex); },\n    () =\u003e { done.SetResult(null); }\n);\n\n// subscribe to data provider\nmonitor.Subscribe(provider);\n\n// blocking until we receive all the events\nawait done.Task;\n\n// clear the subscription\nmonitor.Unsubscribe();\n```\n\nYou can also extend a base class instead of passing lambdas:\n```csharp\nprivate class MyStreamingMonitor : StreamingEventMonitor\n{\n    // optionally override OnNext event\n    public override void OnNext(Value value)\n    {\n        // process your event\n        RequestData();\n    }\n\n    // optionally override OnError event\n    public override void OnError(Exception error)\n    {\n        // process an error\n    }\n\n    // optionally override OnCompleted event\n    public override void OnCompleted()\n    {\n        // process completion event\n    }\n}\n\n// creating a subscriber\nvar monitor = new MyStreamingMonitor();\n\n// subscribe to data provider\nmonitor.Subscribe(provider);\n\n// clear the subscription\nmonitor.Unsubscribe();\n```\n\n## License\n\nCopyright 2021 [Fauna, Inc.](https://fauna.com/)\n\nLicensed under the Mozilla Public License, Version 2.0 (the \"License\"); you may\nnot use this software except in compliance with the License. You may obtain a\ncopy of the License at\n\n[http://mozilla.org/MPL/2.0/](http://mozilla.org/MPL/2.0/)\n\nUnless required by applicable law or agreed to in writing, software distributed\nunder the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR\nCONDITIONS OF ANY KIND, either express or implied. See the License for the\nspecific language governing permissions and limitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffauna%2Ffaunadb-csharp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffauna%2Ffaunadb-csharp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffauna%2Ffaunadb-csharp/lists"}