# .NET

Documentation version: 0.3.1.

> [!NOTE]
> SDKs are read-only. The CLI creates vaults and sets secret values;
> applications do not need a CLI process running alongside them.

## Project setup options

1. **Option 1: Set up with the CLI.** Follow the [CLI installation guide](https://sourceorrery.ai/getting-started/#install),
   then create the vault and set its secret values in your own terminal.
2. **Option 2: Set up with an AI coding agent.** Run
   `sourceorrery init --integration all`, then ask your agent to set up
   SourceOrrery for the project without showing values. You keep vault
   keys and new values private. [The agent setup guide](https://sourceorrery.ai/guides/ai-agents/)
   works with an existing CLI installation.

## Install




### From NuGet

```bash
dotnet add package SourceOrrery --version 0.3.1
```

or, in the project file:

```xml
<PackageReference Include="SourceOrrery" Version="0.3.1" />
```

[`SourceOrrery` on NuGet](https://www.nuget.org/packages/SourceOrrery)
carries the native library for `win-x64`, `win-arm64`, `osx-x64`,
`osx-arm64`, `linux-x64` and `linux-arm64` under `runtimes/<rid>/native`,
so one package serves every platform. It is published by trusted
publishing and carries nuget.org's repository signature
([Supply chain](https://sourceorrery.ai/security/supply-chain/#nuget)).

Targets .NET 8 and later. P/Invoke is source-generated with
`LibraryImport`, so the package is trimming- and AOT-compatible. Set
`SOURCEORRERY_NATIVE_DIR` to use a native library from elsewhere.

### From the GitHub release

The same package, `SourceOrrery.0.3.1.nupkg`, is attached to the
[v0.3.1 release](https://github.com/Netizine/sourceorrery/releases/tag/v0.3.1).
Put it in a folder, register that folder as a package source in the
repository's `nuget.config`, and add the package:



#### Windows

```powershell
New-Item -ItemType Directory -Force packages | Out-Null
Invoke-WebRequest https://github.com/Netizine/sourceorrery/releases/download/v0.3.1/SourceOrrery.0.3.1.nupkg -OutFile packages\SourceOrrery.0.3.1.nupkg
dotnet new nugetconfig                        # once per repository, if it has no nuget.config yet
dotnet nuget add source .\packages --name sourceorrery-release --configfile nuget.config
dotnet add package SourceOrrery --version 0.3.1
```

#### macOS

```bash
mkdir -p packages
curl -L -o packages/SourceOrrery.0.3.1.nupkg https://github.com/Netizine/sourceorrery/releases/download/v0.3.1/SourceOrrery.0.3.1.nupkg
dotnet new nugetconfig                        # once per repository, if it has no nuget.config yet
dotnet nuget add source ./packages --name sourceorrery-release --configfile nuget.config
dotnet add package SourceOrrery --version 0.3.1
```

#### Linux

```bash
mkdir -p packages
curl -L -o packages/SourceOrrery.0.3.1.nupkg https://github.com/Netizine/sourceorrery/releases/download/v0.3.1/SourceOrrery.0.3.1.nupkg
dotnet new nugetconfig                        # once per repository, if it has no nuget.config yet
dotnet nuget add source ./packages --name sourceorrery-release --configfile nuget.config
dotnet add package SourceOrrery --version 0.3.1
```



### From source

See [Building from source](https://sourceorrery.ai/sdks/dotnet/#building-from-source) below.

## Get a secret

```csharp
using SourceOrrery;

using var reader = SecretReader.Open("development");
using var secret = reader.Get("database-password");
Connect(password: secret.Value.ExposeText());
// disposing zeroises the value and releases the vault
```

With the default options, `SOURCEORRERY_HOME` locates the vault;
this machine's key in the OS credential store opens it, else the
recovery key: an explicit one, `SOURCEORRERY_RECOVERY_KEY`, then a file
or `SOURCEORRERY_RECOVERY_KEY_FILE`. `SecretReader.Open(vault, new
OpenOptions { Home = .., RecoveryKey = .., RecoveryKeyFile = .., Environment = false })`
overrides any of that. The SDK never prompts and never asks the vault's
view check.

A secret the vault keeps at a provider
([HashiCorp Vault](https://sourceorrery.ai/providers/hashicorp-vault/),
[AWS Secrets Manager](https://sourceorrery.ai/providers/aws-secrets-manager/),
[Azure Key Vault](https://sourceorrery.ai/providers/azure-key-vault/)) is read there through
the vault's connection, with the same calls: the connection signs in with
the credentials it stores, or with the provider's own sign-in on the
machine. No provider is contacted until a secret it keeps is read.

| Call | Returns |
|------|---------|
| `reader.Get(name)` | `Secret` for the newest accessible version |
| `reader.Get(name, version)` | `Secret` for exactly that version |
| `reader.GetProperties(name, version?)` | `SecretProperties` record (policy not applied) |
| `reader.Resolve("sourceorrery://development/database-password")` | `Secret` |
| `reader.GetDescriptor()` | `VaultDescriptor` record (no values) |

`Secret.Properties` (`Vault`, `Name`, `Version`, `Enabled`, `ContentType`,
`Tags`, `NotBefore`, `ExpiresOn`, `CreatedOn`, `UpdatedOn` as
`DateTimeOffset`, `RecoveryLevel`, `Reference`) and `Secret.Value`, a
`SecretValue`:

```csharp
value.Use((span, _) => Connect(span));   // ReadOnlySpan<byte>, no copy
value.Expose();                          // byte[] (a copy)
value.ExposeText();                      // string
value.Length;
value.Dispose();                         // zeroise; Expose() throws ObjectDisposedException afterwards
value.ToString();                        // "[REDACTED]"
```

Disposing a value, from another thread or from inside its own `Use`
callback (directly, or by disposing the `Secret` or `Project` that owns
it), refuses every later use at once, but the native bytes are zeroised
and freed only when the callbacks already running have returned: a span is
never left pointing at freed memory. `Dispose` never waits.

## Errors

Every failure is a `SourceOrreryException` or a subclass, with `Code`,
`Detail`, `Hint` and `Message` (detail plus hint):

```csharp
try
{
    using var reader = SecretReader.Open("development");
    using var secret = reader.Get("database-password");
}
catch (VaultLockedException e) { Console.Error.WriteLine(e.Hint); }
catch (SecretNotFoundException e) { Console.Error.WriteLine(e.Hint); }
catch (SourceOrreryException e) { Console.Error.WriteLine($"{e.Code}: {e.Message}"); }
```

Classes: `VaultNotFoundException`, `VaultLockedException`,
`MigrationRequiredException`, `VaultMismatchException`,
`SecretNotFoundException`, `VersionNotFoundException`,
`SecretDeletedException`, `PolicyException` with
`SecretDisabledException`, `SecretNotYetValidException` (`IsTransient`),
`SecretExpiredException`, `IntegrityException`, `UnsupportedException`,
`InvalidArgumentException`, `InvalidNameException`, `ManifestException`,
`PermissionDeniedException`, `StorageException`,
`UnauthenticatedException` (the provider that stores the secret refused the
credentials), `ProviderUnavailableException` (the provider could not be
reached; `IsTransient`). See [the SDK overview](https://sourceorrery.ai/sdks/#errors).

## Load a project

```csharp
using var project = Project.Load("sourceorrery.toml");   // or Project.Load() to discover it
foreach (var secret in project.Secrets)
{
    Environment.SetEnvironmentVariable(secret.Env, secret.Value.ExposeText());
}
```

`Project.Load` resolves every `[secrets.*]` entry the way `sourceorrery run`
does and throws the first required secret's exception if one cannot be read.

## Threads

A `SecretReader` may be shared between threads; `Dispose` waits for the
calls already running. A `SecretValue` may be used from several threads,
and disposed while a callback runs (above).

## Building from source

You need Git, Rust 1.91.1 or newer installed with rustup, and a C compiler
(on Linux also `pkg-config` and `libdbus-1-dev`);
[Building from source](https://sourceorrery.ai/guides/building-from-source/#what-you-need) has the commands for
each platform. For this SDK, also the .NET SDK: 8 or newer builds the
library, and the tests and the example need .NET 10, which they target.

Get the code, build the native library, and pack the library into a
NuGet package:

```bash
git clone https://github.com/Netizine/sourceorrery
cd sourceorrery
git checkout v0.3.1              # or stay on main for the newest changes
cargo build --release -p sourceorrery-ffi
dotnet pack bindings/dotnet/SourceOrrery/SourceOrrery.csproj -c Release -o dist/nuget
```

`dist/nuget/SourceOrrery.<version>.nupkg` installs like the release's
package (register `dist/nuget` as a package source, as above). The version
is the one committed in the repository, not the release's;
[Get the code](https://sourceorrery.ai/guides/building-from-source/#get-the-code) shows how to stamp the release
version first. A package built this way carries no native library (the
release workflow adds one per platform under `runtimes/`), so give your
application the one you built: copy `sourceorrery_ffi.dll`,
`libsourceorrery_ffi.so` or `libsourceorrery_ffi.dylib` from
`target/release` next to it, or name that directory in
`SOURCEORRERY_NATIVE_DIR`.

To run the tests, the example and the conformance harness, build the CLI
too, which creates the test vault, and run the rest in Bash (Git Bash on
Windows) from the repository root:

```bash
cargo build --release -p sourceorrery-cli -p sourceorrery-ffi
eval "$(bash scripts/ci/fixture-vault.sh)"       # a throwaway vault, the variables the tests read, SOURCEORRERY_NATIVE_DIR
dotnet test bindings/dotnet/SourceOrrery.sln
dotnet run --project bindings/dotnet/examples/GetSecret -- "$SOURCEORRERY_TEST_VAULT" database-password
dotnet build bindings/dotnet/conformance -c Release
python tests/conformance/sdk/harness.py --runner dotnet
```

What the fixture script creates: [The SDK test vault](https://sourceorrery.ai/guides/building-from-source/#the-sdk-test-vault).
Source: [`bindings/dotnet`](https://github.com/Netizine/sourceorrery/blob/main/bindings/dotnet/README.md).
