> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/sdks/net.md).

# .NET

Write and read records from C# and .NET with the Norbix .NET SDK.

The .NET SDK comes as two NuGet packages (source: [github.com/norbix-code/sdk-net](https://github.com/norbix-code/sdk-net)):

| Package                                                   | What it talks to                                         |
| --------------------------------------------------------- | -------------------------------------------------------- |
| [`Norbix.Api`](https://www.nuget.org/packages/Norbix.Api) | your app's data: records, files, users                   |
| [`Norbix.Hub`](https://www.nuget.org/packages/Norbix.Hub) | configuration: schemas, integrations, templates, account |

Both target .NET 10 and give you a `Norbix.Sdk.NorbixClient`. Add **one** of them to a project: with both, the compiler stops with *The type 'NorbixClient' exists in both 'Norbix.Api' and 'Norbix.Hub'* — put Hub work in its own project.

This page was run on 2026-10-06 with `Norbix.Api` **3.11.0** and .NET SDK 10.0. All the code below is one file, `Program.cs` of a console app: put the blocks one after the other.

## Before you start

* A project with a `books` collection — `title` (text, required), `pages` (number, required), `in_stock` (yes / no), `genre`. Create it in Cloud as in step 3 of the [Quickstart](/codemash/get-started/managed-service/quickstart.md).
* A key and your project id in `NORBIX_API_KEY` and `NORBIX_PROJECT_ID` — see [Install a Norbix SDK](/codemash/sdks/install.md). The key needs a role that may write records, for example **Data Editor**.

## Install

```sh
dotnet new console -n Quickstart
cd Quickstart
dotnet add package Norbix.Api
```

## Create the client

```csharp
using System.Text.Json;
using Norbix.Sdk;
using Norbix.Sdk.Types.Api;

// Reads NORBIX_API_KEY and NORBIX_PROJECT_ID from the environment.
using var client = new NorbixClient();
```

To pass the values in code instead, use `new NorbixClient(new NorbixClientOptions { ApiKey = "nbsu_…", ProjectId = "pr_…" })`.

## Write a record

A record goes in as a JSON string in `Document`. The answer has the new record's `Id`.

```csharp
// Write: add one book to the `books` collection.
var created = await client.Database.InsertOneAsync(new InsertOneRequest
{
    CollectionName = "books",
    Document = JsonSerializer.Serialize(new { title = "Dune", pages = 412, genre = "fiction" }),
});
Console.WriteLine($"Inserted {created.Id}");
```

## Read records

`FindAsync` returns one page of records in `List.Items`. Each item is a `JsonElement`. Set `Filter`, `Sort` or `Projection` on the request as in [Search parameters](/codemash/cloud/concepts/search-parameters.md).

```csharp
// Read: find the books.
var found = await client.Database.FindAsync(new FindRequest { CollectionName = "books", PageSize = 10 });
foreach (JsonElement book in found.List.Items)
{
    Console.WriteLine($"{book.GetProperty("title")} — {book.GetProperty("pages")} pages");
}
```

## Handle errors

A failed call throws `NorbixException` with the gateway's `ErrorCode` and `Message`, the `HttpStatus`, and every error in `Errors`. Here the schema says `pages` is required:

```csharp
// Error handling: the schema requires `pages`, so this insert fails.
try
{
    await client.Database.InsertOneAsync(new InsertOneRequest
    {
        CollectionName = "books",
        Document = JsonSerializer.Serialize(new { title = "Untitled draft" }),
    });
}
catch (NorbixException ex)
{
    Console.WriteLine($"Failed: {ex.ErrorCode} — {ex.Message}");
}
```

## Run it

```sh
dotnet run
```

The output (the collection already had *The Hobbit*):

```
Inserted 6ac54bbd212c29912eaddd95
Dune — 412 pages
The Hobbit — 310 pages
Failed: CM-ERRORS-DATABASE-030 — Field 'pages' is invalid: a value is required
```

{% hint style="info" %}
`Norbix.Sdk` (1.0.0) on NuGet is an older package that is no longer updated. Use `Norbix.Api` and `Norbix.Hub`.
{% endhint %}

## Next steps

* Every operation, with a tab per language: [SDK reference](/codemash/sdks/database.md).
* The same calls from the terminal: [CLI](/codemash/cli/cli.md).