Skip to content

.NET

The read-only .NET SDK: install it from NuGet, the release or source, open a vault, get a secret, handle typed exceptions, load a project.

6 min read
  1. Option 1: Set up with the CLI. Follow the CLI installation guide, 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 works with an existing CLI installation.
Terminal window
dotnet add package SourceOrrery --version 0.3.1

or, in the project file:

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

SourceOrrery on NuGet (opens in a new tab) 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).

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.

The same package, SourceOrrery.0.3.1.nupkg, is attached to the v0.3.1 release (opens in a new tab). Put it in a folder, register that folder as a package source in the repository’s nuget.config, and add the package:

Terminal window
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

See Building from source below.

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, AWS Secrets Manager, 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:

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.

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

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.

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.

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).

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 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:

Terminal window
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 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:

Terminal window
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. Source: bindings/dotnet (opens in a new tab).