Skip to content

Commit

Permalink
.NET SDK doc revamp
Browse files Browse the repository at this point in the history
  • Loading branch information
@Odonno
Odonno committed Jul 10, 2024
1 parent 248dc68 commit e9db817
Show file tree
Hide file tree
Showing 18 changed files with 2,509 additions and 2,099 deletions.
128 changes: 128 additions & 0 deletions doc-sdk-dotnet_versioned_docs/version-1.x/connection-strings.mdx
View file
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
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
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

0 comments on commit e9db817

Please sign in to comment.