Repository files navigation

The official SurrealDB SDK for .NET.

View the SDK documentationhere.

dotnet add package SurrealDb.Net

This library supports connecting to SurrealDB over the remote HTTP and WebSocket connection protocolshttp,https,ws, andwss.

The examples below require SurrealDB to beinstalled and running on port 8000.

You can easily create a new SurrealDB client. All you have to do is define theendpoint to the SurrealDB instance.

usingvarclientHttp=newSurrealDbClient("http://127.0.0.1:8000");usingvarclientHttps=newSurrealDbClient("https://127.0.0.1:8000");usingvarclientWs=newSurrealDbClient("ws://127.0.0.1:8000/rpc");usingvarclientWss=newSurrealDbClient("wss://127.0.0.1:8000/rpc");// Now you can call other methods including Signin & Use

You can use Dependency Injection with theservices.AddSurreal() function.

varoptions=SurrealDbOptions.Create().WithEndpoint("http://127.0.0.1:8000").WithNamespace("test").WithDatabase("test").WithUsername("root").WithPassword("root").Build();services.AddSurreal(options);

Then you will be able to use theISurrealDbClient interface orSurrealDbClient class anywhere.

publicclassMyClass{privatereadonlyISurrealDbClient_client;publicMyClass(ISurrealDbClientclient){_client=client;}// ...}

Note that the default lifetime of this service isSingleton. You can override this as follows:

services.AddSurreal(options,ServiceLifetime.Scoped);

Consider the followingappsettings.json file:

{"AllowedHosts":"*","Logging": {"LogLevel": {"Default":"Information","Microsoft.AspNetCore":"Warning"    }  },"ConnectionStrings": {"SurrealDB":"Server=http://127.0.0.1:8000;Namespace=test;Database=test;Username=root;Password=root"  }}

You can use the Connection String instead of having to deal with aSurrealDbOptions.

services.AddSurreal(configuration.GetConnectionString("SurrealDB"));

It will automatically create a new SurrealDB using theServer endpoint and configure the client using the different values fornamespace,database,username andpassword. Note that these values are optional but theendpoint is still required.

Having a default instance for a project is enough most of the time, but there may be times when you'd like to target multiple SurrealDB instances, either at different addresses or at the same address but inside different NS/DBs. You can use multiple instances using Keyed service injection, as in the following example.

services.AddSurreal(configuration.GetConnectionString("SurrealDB.Main"));services.AddKeyedSurreal("backup",configuration.GetConnectionString("SurrealDB.Backup"));services.AddKeyedSurreal("monitoring",configuration.GetConnectionString("SurrealDB.Monitoring"));

Here you will have 3 instances:

• the default one, you can keep usingISurrealDbClient interface orSurrealDbClient class anywhere
• a client for backup purpose, using the[FromKeyedServices("backup")] attribute
• a client for monitoring purpose, using the[FromKeyedServices("monitoring")] attribute

[ApiController][Route("[controller]")]publicclassWeatherForecastController:ControllerBase{privateconststringTable="weatherForecast";privatereadonlyISurrealDbClient_surrealDbClient;publicWeatherForecastController(ISurrealDbClientsurrealDbClient){_surrealDbClient=surrealDbClient;}[HttpGet]publicTask<IEnumerable<WeatherForecast>>GetAll(CancellationTokencancellationToken){return_surrealDbClient.Select<WeatherForecast>(Table,cancellationToken);}[HttpGet("{id}")]publicasyncTask<IActionResult>Get(stringid,CancellationTokencancellationToken){varweatherForecast=await_surrealDbClient.Select<WeatherForecast>((Table,id),cancellationToken);if(weatherForecastisnull)returnNotFound();returnOk(weatherForecast);}[HttpPost]publicTask<WeatherForecast>Create(CreateWeatherForecastdata,CancellationTokencancellationToken){varweatherForecast=newWeatherForecast{Date=data.Date,Country=data.Country,TemperatureC=data.TemperatureC,Summary=data.Summary};return_surrealDbClient.Create(Table,weatherForecast,cancellationToken);}[HttpPut]publicTask<WeatherForecast>Update(WeatherForecastdata,CancellationTokencancellationToken){return_surrealDbClient.Upsert(data,cancellationToken);}[HttpPatch]publicTask<IEnumerable<WeatherForecast>>PatchAll(JsonPatchDocument<WeatherForecast>patches,CancellationTokencancellationToken){return_surrealDbClient.Patch(Table,patches,cancellationToken);}[HttpPatch("{id}")]publicTask<WeatherForecast>Patch(stringid,JsonPatchDocument<WeatherForecast>patches,CancellationTokencancellationToken){return_surrealDbClient.Patch((Table,id),patches,cancellationToken);}[HttpDelete]publicTaskDeleteAll(CancellationTokencancellationToken){return_surrealDbClient.Delete(Table,cancellationToken);}[HttpDelete("{id}")]publicasyncTask<IActionResult>Delete(stringid,CancellationTokencancellationToken){boolsuccess=await_surrealDbClient.Delete((Table,id),cancellationToken);if(!success)returnNotFound();returnOk();}}

Before contributing to this repository, please take note of theContributing guidelines. To contribute to this project, you will also need to install the following tools:

• The .NET SDK, preferably the latest stable version which is available fordownload here
• TheRust programming language, in order to build the embedded providers

The test and benchmark projects are dependent on the local Rust crate used by embedded providers. This crate is located in the./rust-embedded folder of this repository. To build the crate, make sure you installed the Rust toolchain on your machine and then follow these steps:

cd ./rust-embeddedcargo build

If the command line was successful, the compiled libraries are generated in the target folder and automatically copied when the .NET projects are built.

Note: you can manually disable the embedded mode by changing the value of the constantEMBEDDED_MODE located in theDirectory.Build.props file like this:

<PropertyGroupLabel="Constants"Condition="false">  <DefineConstants>EMBEDDED_MODE</DefineConstants></PropertyGroup>

The .NET release versions must follow these rules:

• Should target at least the latest LTS (Long-Term Support) version
• Should target at least the latest STS (Standard-Term Support) version

SurrealDb.Net targets .NET versions following the.NET Support Policy by Microsoft. Additionally, SurrealDb.Net targets .NET Standard 2.1 explicitly to continue support of the Mono runtime (Unity, Xamarin, etc...).

Note that the support for .NET standard 2.1 will be maintained until further notice.

This project is usingCSharpier, an opinionated code formatter.

You can install it on your machine viadotnet tool.

# Run this command at the root of the projectdotnet tool install csharpier

You can then use it as a cli:

dotnet csharpier.

The list of command-line options is available here:https://csharpier.com/docs/CLI

CSharpier supportsmultiple code editors, including Visual Studio, Jetbrains Rider, VSCode and Neovim. You will be able to run format on file save after configuring the settings in your IDE.

This project was written following testing best practices:

• TDD, leveraging:
  • clean code/architecture
  • regression testing
  • adding new features and tests easily
• a vast majority of tests are integration tests, ensuring compatibility with a concrete SurrealDB version
• each integration test is using a separate SurrealDB namespace/database

Unit/Integration tests are written usingTUnit andFluentAssertions.

You will need a local SurrealDB instance alongside the tests. Start one using the following command:

surreal start --log debug --user root --pass root memory --allow-guests

Once ready, go to the root directory of the project and run the following command:

dotnet watchtest --project SurrealDb.Net.Tests

Due to the asynchronous nature of Live Queries, they are tested against a separate project namedSurrealDb.Net.LiveQuery.Tests. Where the default test project allow full parallelization, this project completely disable test parallelization. To execute tests on Live Queries, run the following command:

dotnet watchtest --project SurrealDb.Net.LiveQuery.Tests

Note 1: Because Live Query tests are not run in parallel, it can take quite some time to run all tests.

Note 2: You can run the two test projects in parallel.

This project also containsbenchmarks in order to detect possible performance regressions.

You will need a local SurrealDB instance alongside the tests. Start one using the following command:

surreal start --user root --pass root memory --allow-guests

Once ready, go to the root directory of the project and run the following command:

dotnet run -c Release --project SurrealDb.Net.Benchmarks.Remote --filter'*'

./prepare_embedded_benchmarks.sh -sdotnet run -c Release --project SurrealDb.Net.Benchmarks.Embedded --filter'*'./prepare_embedded_benchmarks.sh -e

For Windows:

./prepare_embedded_benchmarks.ps1 -sdotnet run -c Release --project SurrealDb.Net.Benchmarks.Embedded --filter'*'./prepare_embedded_benchmarks.ps1 -e