Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

.NET SDK doc revamp #654

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
+2,801 −2,097
Draft

.NET SDK doc revamp #654

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c62571a
.NET SDK doc revamp
Odonno Jul 10, 2024
9b3fbe8
Merge branch 'main' into feat/dotnet-sdk-updated-docs
Ekwuno Aug 13, 2024
07f0c3f
feat(dotnet): improve documentation on Live Queries
Odonno Sep 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 128 additions & 0 deletions doc-sdk-dotnet_versioned_docs/version-1.x/connection-strings.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
---
sidebar_position: 6
sidebar_label: Connection Strings
title: .NET | SDKs | Integration
description: The SurrealDB SDK for .NET enables simple and advanced querying of a remote or embedded database.
---

# Connection Strings

Connection Strings are an easy way to configure your application to connect to a SurrealDB instance.
They are stored in the <code>appsettings.json</code> file and can be used to configure the <code>SurrealDbClient</code>.

In general, it is known as a best practice to:
- set a development Connection String in <code>appsettings.Development.json</code>,
- store your production Connection String in a Secret environment variable, or even better in a Vault.

<table>
<thead>
<tr>
<th scope="col">Keys</th>
<th colspan="2" scope="col">Description</th>
<th scope="col">Aliases</th>
</tr>
</thead>
<tbody>
<tr>
<td scope="row" data-label="Keys">
<code>Endpoint</code>
<l className='yellow'>REQUIRED</l>
</td>
<td colspan="2" scope="row" data-label="Description">
The database endpoint to connect to.
</td>
<td scope="row" data-label="Aliases">
<code>Server</code>
</td>
</tr>
<tr>
<td scope="row" data-label="Keys">
<code>Namespace</code>
<l className='grey'>OPTIONAL</l>
</td>
<td colspan="2" scope="row" data-label="Description">
Switches to a specific namespace.
</td>
<td scope="row" data-label="Aliases">
<code>NS</code>
</td>
</tr>
<tr>
<td scope="row" data-label="Keys">
<code>Database</code>
<l className='grey'>OPTIONAL</l>
</td>
<td colspan="2" scope="row" data-label="Description">
Switches to a specific database.
</td>
<td scope="row" data-label="Aliases">
<code>DB</code>
</td>
</tr>
<tr>
<td scope="row" data-label="Keys">
<code>Username</code>
<l className='grey'>OPTIONAL</l>
</td>
<td colspan="2" scope="row" data-label="Description">
Username used to have root access.
</td>
<td scope="row" data-label="Aliases">
<code>User</code>
</td>
</tr>
<tr>
<td scope="row" data-label="Keys">
<code>Password</code>
<l className='grey'>OPTIONAL</l>
</td>
<td colspan="2" scope="row" data-label="Description">
Password used to have root access.
</td>
<td scope="row" data-label="Aliases">
<code>Pass</code>
</td>
</tr>
<tr>
<td scope="row" data-label="Keys">
<code>Token</code>
<l className='grey'>OPTIONAL</l>
</td>
<td colspan="2" scope="row" data-label="Description">
Token (JWT) used to have user access.
</td>
<td scope="row" data-label="Aliases">

</td>
</tr>
<tr>
<td scope="row" data-label="Keys">
<code>NamingPolicy</code>
<l className='grey'>OPTIONAL</l>
</td>
<td colspan="2" scope="row" data-label="Description">
Naming policy used to interact with the database. <br />
Valid options are <code>CamelCase</code>, <code>SnakeCaseLower</code>, <code>SnakeCaseUpper</code>, <code>KebabCaseLower</code> and <code>KebabCaseUpper</code>.
</td>
<td scope="row" data-label="Aliases">

</td>
</tr>
</tbody>
</table>

<br /><br />

Here is a couple of examples of Connection Strings:

```sh
Server=http://127.0.0.1:8000;Namespace=test;Database=test;Username=root;Password=root
```

```sh
Endpoint=ws://127.0.0.1:8000/rpc;NS=test;DB=test;User=root;Pass=root
```

```sh
Endpoint=http://127.0.0.1:8000;NS=test;DB=test;User=root;Pass=root;NamingPolicy=SnakeCaseLower
```
4 changes: 4 additions & 0 deletions doc-sdk-dotnet_versioned_docs/version-1.x/core/_category_.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"label": "Language Starter",
"position": 4
}
245 changes: 245 additions & 0 deletions doc-sdk-dotnet_versioned_docs/version-1.x/core/authentication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,245 @@
---
sidebar_position: 2
sidebar_label: Authentication
title: .NET | SDKs | Integration
description: The SurrealDB SDK for .NET enables simple and advanced querying of a remote or embedded database.
---

# Authentication

Since SurrealDB is a database that is designed to be used in a distributed environment, it is important to secure the database and the data that is stored in it.
SurrealDB provides a number of methods for authenticating users and securing the database.

## User authentication

SurrealDB supports user authentication using a number of methods, including:


## `.SignUp()` {#signup}

Signs up to a specific authentication scope.

```csharp title="Method Syntax"
await db.SignUp(credentials)
```

### Arguments
<table>
<thead>
<tr>
<th colspan="2" scope="col">Arguments</th>
<th colspan="2" scope="col">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td colspan="2" scope="col" scope="row" data-label="Arguments">
<code>credentials</code>
<l className='yellow'>REQUIRED</l>
</td>
<td colspan="2" scope="col" scope="row" data-label="Description">
Credentials to sign up as a scoped user.
</td>
</tr>
<tr>
<td colspan="2" scope="col" scope="row" data-label="Arguments">
<code>cancellationToken</code>
<l className='yellow'>REQUIRED</l>
</td>
<td colspan="2" scope="col" scope="row" data-label="Description">
The cancellationToken enables graceful cancellation of asynchronous operations.
</td>
</tr>
</tbody>
</table>

```csharp
var authParams = new AuthParams
{
Namespace = "test",
Database = "test",
Scope = "user",
Email = "[email protected]",
Password = "123456"
};

Jwt jwt = await db.SignUp(authParams);

public class AuthParams : ScopeAuth
{
public string? Username { get; set; }
public string? Email { get; set; }
public string? Password { get; set; }
}
```

<br />

## `.SignIn()` {#signin}

Signs in to a specific authentication scope.

```csharp title="Method Syntax"
await db.SignIn(credentials)
```


### Arguments
<table>
<thead>
<tr>
<th colspan="2" scope="col">Arguments</th>
<th colspan="2" scope="col">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td colspan="2" scope="col" scope="row" data-label="Arguments">
<code>credentials</code>
<l className='yellow'>REQUIRED</l>
</td>
<td colspan="2" scope="col" scope="row" data-label="Description">
Variables used in a signin query.
</td>
</tr>
<tr>
<td colspan="2" scope="col" scope="row" data-label="Arguments">
<code>cancellationToken</code>
<l className='yellow'>REQUIRED</l>
</td>
<td colspan="2" scope="col" scope="row" data-label="Description">
The cancellationToken enables graceful cancellation of asynchronous operations.
</td>
</tr>
</tbody>
</table>

### Example usage
```csharp
// Option 1: Sign in as root user
await db.SignIn(new RootAuth { Username = "root", Password = "root" });

// Option 2: Sign in using namespace auth
await db.SignIn(
new NamespaceAuth
{
Namespace = "test",
Username = "johndoe",
Password = "password123"
}
);

// Option 3: Sign in using database auth
await db.SignIn(
new DatabaseAuth
{
Namespace = "test",
Database = "test",
Username = "johndoe",
Password = "password123"
}
);

// Option 4: Sign in as a scoped user
var authParams = new AuthParams
{
Namespace = "test",
Database = "test",
Scope = "user",
Email = "[email protected]",
Password = "123456"
};

Jwt jwt = await db.SignIn(authParams);

public class AuthParams : ScopeAuth
{
public string? Username { get; set; }
public string? Email { get; set; }
public string? Password { get; set; }
}
```

<br />

## `.Authenticate()` {#authenticate}

Authenticates the current connection with a JWT token.

```csharp title="Method Syntax"
await db.Authenticate(jwt)
```

### Arguments
<table>
<thead>
<tr>
<th colspan="2" scope="col">Arguments</th>
<th colspan="2" scope="col">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td colspan="2" scope="col" scope="row" data-label="Arguments">
<code>jwt</code>
<l className='yellow'>REQUIRED</l>
</td>
<td colspan="2" scope="col" scope="row" data-label="Description">
The JWT object holder of the authentication token.
</td>
</tr>
<tr>
<td colspan="2" scope="col" scope="row" data-label="Arguments">
<code>cancellationToken</code>
<l className='yellow'>REQUIRED</l>
</td>
<td colspan="2" scope="col" scope="row" data-label="Description">
The cancellationToken enables graceful cancellation of asynchronous operations.
</td>
</tr>
</tbody>
</table>

### Example usage
```csharp
// Sign in or sign up as a scoped user
Jwt jwt = await db.SignUp(authParams);

await db.Authenticate(jwt);
```

<br />

## `.Invalidate()` {#invalidate}

Invalidates the authentication for the current connection.

```csharp title="Method Syntax"
await db.Invalidate()
```

### Arguments
<table>
<thead>
<tr>
<th colspan="2" scope="col">Properties</th>
<th colspan="2" scope="col">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td colspan="2" scope="col" scope="row" data-label="Properties">
<code>cancellationToken</code>
<l className='grey'>OPTIONAL</l>
</td>
<td colspan="2" scope="row" data-label="Description">
The cancellationToken enables graceful cancellation of asynchronous operations.
</td>
</tr>
</tbody>
</table>

### Example usage
```csharp
await db.Invalidate();
```
Loading