# Create a new connection

The SurrealDB SDK for .NET enables simple and advanced querying of a remote or embedded database.

After [installing the SDK](/docs/reference/dotnet/installation.md), you can initialise a new instance of a SurrealDB client.
When creating a new connection to a SurrealDB instance, you can choose to connect to a local or remote endpoint.

```csharp
using SurrealDb.Net;

using var db = new SurrealDbClient("ws://127.0.0.1:8000/rpc");

await db.Connect();
await db.Use("main", "main");
```

From the code snippet above, you can see that the .NET SDK has a couple of methods that you can use to initialise a new project with SurrealDB.

## `SurrealDbClient`

Creates a new client, detecting the right protocol from the provided endpoint.

```csharp title="Method Syntax"
new SurrealDbClient(endpoint)
```

### Connection options

You can specify your connection protocol either as `http`, `https`, `ws`, or `wss`.
Since SurrealDB also supports RPC over WebSocket, by default, it is specified with a `/rpc` suffix.

**Local endpoint**

```csharp
// Creates a new client using a local endpoint
using var db = new SurrealDbClient("http://127.0.0.1:8000");
```

**Remote endpoint**

```csharp
// Creates a new client using a remote endpoint
using var db = new SurrealDbClient("wss://cloud.surrealdb.com/rpc");
```

**Namespace and database**

```csharp
var options = new SurrealDbOptions
{
    Endpoint = "wss://cloud.surrealdb.com/rpc",
    Namespace = "surrealdb",
    Database = "docs",
};

// Specify a namespace and database pair to use
using var db = new SurrealDbClient(options);
```

**Token**

```csharp
var options = new SurrealDbOptions
{
    Endpoint = "wss://cloud.surrealdb.com/rpc",
    Token = "......",
};

// Authenticate with an existing token
using var db = new SurrealDbClient(options);
```

**Credentials**

```csharp
var options = new SurrealDbOptions
{
    Endpoint = "wss://cloud.surrealdb.com/rpc",
    Username = "root",
    Password = "surrealdb",
};

// Authenticate using a pair of credentials
using var db = new SurrealDbClient(options);
```

> [!NOTE]
> Having to manually set all these options into a `SurrealDbOptions` object can be cumbersome.
> If you are familiar with the concept of Connection Strings, you can simply pass a connection string to the `SurrealDbClient` constructor.
> See the [Connection Strings](/docs/reference/dotnet/core/connection-strings.md) section for more information.

<br />

### Effect of connection protocol on token & session duration

The connection protocol you choose affects how authentication tokens and sessions work:

With websockets connections (`ws://`, `wss://`) you open a single long-lived stateful connection where after the initial authentication, the session duration applies and if not specified, defaults to `NONE` meaning that the session never expires unless otherwise specified.

When you connect with a HTTP connection (`http://`, `https://`), every request you make is short-lived and stateless, requiring you to authenticate every request individually for which the token is used, creating a short lived session. Hence, the token duration which defaults to 1 hour applies.

You can extend the session duration of a token or a session by setting the `DURATION` clause when creating a new access method with the [`DEFINE ACCESS METHOD`](/docs/reference/query-language/statements/define/access.md) statement or when defining a new user with the [`DEFINE USER`](/docs/reference/query-language/statements/define/user.md) statement.

Learn more about token and session duration in our [security best practices](/docs/learn/security/best-practices/security-best-practices.md#expiration) documentation.

<br />
## `.Connect()` {#connect}

The `.Connect()` executes a connection attempt to the underlying endpoint using the provided connection options.

> [!NOTE]
>This method is automatically called before executing any other call to the SurrealDB instance.
>It means that you do not have to explicitely call this method.
>Just note that in some contexts, calling this method before hand can improve performance by avoiding cold starts.

### Example usage

```csharp
await db.Connect();
```

<br />

## `.Use()` {#use}

Depending on the complexity of your use case, you can switch to a specific namespace and database using the `.Use()` method.
This is particularly useful if you want to switch to a different setup after connecting.

Learn more about the `.Use()` method [in the methods section](/docs/reference/dotnet/methods/use.md).

### Example usage

```csharp
await db.Use("main", "main");
```