.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.
Project setup options
Section titled “Project setup options”- 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.
- 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.
Install
Section titled “Install”From NuGet
Section titled “From NuGet”dotnet add package SourceOrrery --version 0.3.1or, 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.
From the GitHub release
Section titled “From the GitHub release”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:
New-Item -ItemType Directory -Force packages | Out-NullInvoke-WebRequest https://github.com/Netizine/sourceorrery/releases/download/v0.3.1/SourceOrrery.0.3.1.nupkg -OutFile packages\SourceOrrery.0.3.1.nupkgdotnet new nugetconfig # once per repository, if it has no nuget.config yetdotnet nuget add source .\packages --name sourceorrery-release --configfile nuget.configdotnet add package SourceOrrery --version 0.3.1mkdir -p packagescurl -L -o packages/SourceOrrery.0.3.1.nupkg https://github.com/Netizine/sourceorrery/releases/download/v0.3.1/SourceOrrery.0.3.1.nupkgdotnet new nugetconfig # once per repository, if it has no nuget.config yetdotnet nuget add source ./packages --name sourceorrery-release --configfile nuget.configdotnet add package SourceOrrery --version 0.3.1mkdir -p packagescurl -L -o packages/SourceOrrery.0.3.1.nupkg https://github.com/Netizine/sourceorrery/releases/download/v0.3.1/SourceOrrery.0.3.1.nupkgdotnet new nugetconfig # once per repository, if it has no nuget.config yetdotnet nuget add source ./packages --name sourceorrery-release --configfile nuget.configdotnet add package SourceOrrery --version 0.3.1From source
Section titled “From source”See Building from source below.
Get a secret
Section titled “Get a secret”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 vaultWith 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 copyvalue.Expose(); // byte[] (a copy)value.ExposeText(); // stringvalue.Length;value.Dispose(); // zeroise; Expose() throws ObjectDisposedException afterwardsvalue.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
Section titled “Errors”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.
Load a project
Section titled “Load a project”using var project = Project.Load("sourceorrery.toml"); // or Project.Load() to discover itforeach (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
Section titled “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
Section titled “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 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:
git clone https://github.com/Netizine/sourceorrerycd sourceorrerygit checkout v0.3.1 # or stay on main for the newest changescargo build --release -p sourceorrery-ffidotnet pack bindings/dotnet/SourceOrrery/SourceOrrery.csproj -c Release -o dist/nugetdist/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:
cargo build --release -p sourceorrery-cli -p sourceorrery-ffieval "$(bash scripts/ci/fixture-vault.sh)" # a throwaway vault, the variables the tests read, SOURCEORRERY_NATIVE_DIRdotnet test bindings/dotnet/SourceOrrery.slndotnet run --project bindings/dotnet/examples/GetSecret -- "$SOURCEORRERY_TEST_VAULT" database-passworddotnet build bindings/dotnet/conformance -c Releasepython tests/conformance/sdk/harness.py --runner dotnetWhat the fixture script creates: The SDK test vault.
Source: bindings/dotnet (opens in a new tab).