# .NET

Connect to SurrealDB and run your first queries with the .NET SDK.

The .NET SDK for SurrealDB lets you connect to a database and query it from your application. This guide covers connecting, authenticating, and running your first queries.

## 1. Install the SDK

Follow the [installation guide](/docs/reference/dotnet/installation.md) to add the SDK to your project. From the .NET CLI, add the `SurrealDb.Net` package:

```bash
dotnet add package SurrealDb.Net
```

Once installed, import the SDK and its models namespaces.

```csharp
using SurrealDb.Net;
using SurrealDb.Net.Models;
using SurrealDb.Net.Models.Auth;
```

The `SurrealDb.Net` namespace contains the `SurrealDbClient`, while `SurrealDb.Net.Models` and `SurrealDb.Net.Models.Auth` provide the record base types and authentication types like [`RootAuth`](/docs/reference/dotnet/core/authentication.md).

## 2. Connect to SurrealDB

Create a new [`SurrealDbClient`](/docs/reference/dotnet/core/create-a-new-connection.md) with a connection string. The URL scheme determines the connection type.

Supported connection protocols include:
- **WebSocket** (`ws://`, `wss://`) for long-lived stateful connections, required for live queries, sessions, and transactions
- **HTTP** (`http://`, `https://`) for short-lived stateless connections
- **Memory** (`mem://`) for [embedded instances](/docs/reference/dotnet/embedding.md)

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

After connecting, use [`.SignIn()`](/docs/reference/dotnet/methods/signin.md) to authenticate and [`.Use()`](/docs/reference/dotnet/methods/use.md) to select the namespace and database you want to work with. Most operations require both.

```csharp
await db.SignIn(new RootAuth { Username = "root", Password = "secret" });
await db.Use("main", "main");
```

## 3. Inserting data into SurrealDB

Once connected, you can use the [`Create`](/docs/reference/dotnet/methods/create.md) method to create records. Define a class that derives from `Record` to map to your table, then pass an instance to `Create`.

```csharp
const string TABLE = "person";

var person = new Person
{
    Title = "Founder & CEO",
    Name = new() { FirstName = "Tobie", LastName = "Morgan Hitchcock" },
    Marketing = true
};
var created = await db.Create(TABLE, person);
Console.WriteLine(created);
```

The `Person` and `Name` classes describe the shape of your data. `Person` derives from `Record`, which provides the record `Id`.

```csharp
public class Person : Record
{
    public string? Title { get; set; }
    public Name? Name { get; set; }
    public bool Marketing { get; set; }
}
public class Name
{
    public string? FirstName { get; set; }
    public string? LastName { get; set; }
}
```

## 4. Retrieving data from SurrealDB

### Selecting records

The [`Select`](/docs/reference/dotnet/methods/select.md) method retrieves all records from a table. Provide the type parameter to tell the SDK what type to deserialise the response into.

```csharp
var people = await db.Select<Person>(TABLE);
Console.WriteLine(people);
```

### Running SurrealQL queries

For more advanced use cases, you can use the [`Query`](/docs/reference/dotnet/methods/query.md) method to run [SurrealQL](/docs/reference/query-language.md) statements directly. Use [`GetValue<>`](/docs/reference/dotnet/core/writing-surrealql.md) to extract a typed result from the response.

```csharp
var queryResponse = await db.Query(
  $"SELECT Marketing, count() AS Count FROM type::table({TABLE}) GROUP BY Marketing"
);
var groups = queryResponse.GetValue<List<Group>>(0);
Console.WriteLine(groups);

public class Group
{
    public bool Marketing { get; set; }
    public int Count { get; set; }
}
```

## 5. Closing the connection

When you create the client with `using var db = ...`, the client is disposed automatically when it goes out of scope, releasing the connection and its resources. If you need to close it explicitly, call `Dispose()`.

```csharp
db.Dispose();
```

## Next steps

You have learned how to install the SDK, connect to SurrealDB, create records, and retrieve data. There is a lot more you can do with the SDK, including updating and deleting records, authentication, live queries, and transactions.

- [Connection management](/docs/reference/dotnet/core/create-a-new-connection.md) - Learn how to create and configure a SurrealDbClient connection.

- [Authentication](/docs/reference/dotnet/core/authentication.md) - Read more about authentication levels and how to integrate them into your application.

- [Data manipulation](/docs/reference/dotnet/core/data-manipulation.md) - Learn how to create, read, update, and delete records using the SDK.

- [API Reference](/docs/reference/dotnet/methods.md) - Complete reference for all methods, types, and errors.

> [!NOTE]
> This getting-started guide covers the essentials. For the complete methods, API, and concept reference, see the [.NET SDK reference](/docs/reference/dotnet.md).