Guides on Drasi .NET Docs

Use the generic host

Mon, 01 Jan 0001 00:00:00 +0000

Use AddDrasi when your app already has a generic host (ASP.NET Core, a worker service, or Host.CreateApplicationBuilder). The core API does not require DI. This guide is only for hosted apps.

Register the engine

using System.Text.Json.Nodes;
using Drasi;
using Drasi.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddDrasi("orders-app", drasi =>
{
 drasi.AddSource("orders");
 drasi.AddQuery(
 "open",
 "MATCH (o:Order) WHERE o.status = 'open' RETURN o.id AS id, o.total AS total",
 ["orders"]);
 drasi.AddReaction("watch", ["open"], evt =>
 {
 foreach (var diff in evt.Results)
 {
 Console.WriteLine($"{diff.Type} {diff.Data}");
 }
 });
});
await builder.Build().RunAsync();

AddDrasi registers Engine as a singleton and a DrasiHostedService. On start, the host:

Push changes and handle diffs

Mon, 01 Jan 0001 00:00:00 +0000

Use an in-process source when the data already lives in your application. Use an in-process reaction when you want to handle result diffs in C# instead of a plugin.

Add a source you can push into

await drasi.AddSourceAsync("orders");

The one-argument overload registers a C# source. There is no plugin kind. Emit graph changes with PushChangeAsync:

await drasi.PushChangeAsync("orders", new SourceChange
{
 Op = ChangeOp.Insert,
 Id = "o1",
 Labels = ["Order"],
 Properties = new JsonObject
 {
 ["id"] = "o1",
 ["status"] = "open",
 ["total"] = 42,
 },
});

Id is the graph key. Put the same value in Properties["id"] when a query selects o.id.

Work with plugins

Mon, 01 Jan 0001 00:00:00 +0000

Plugins are self-contained native libraries (.so, .dylib, or .dll) loaded through drasi-host-sdk, the same host path drasi-server uses. Install them from ghcr.io/drasi-project or load files you already have on disk.

This guide needs network access to ghcr.io.

Inspect the host

var info = Engine.GetHostInfo();
Console.WriteLine(
 $"{info.TargetTriple} core {info.CoreVersion} lib {info.LibVersion} "
 + $"plugin {info.SdkVersion} ffi {info.FfiSdkVersion}");

GetHostInfo reports the platform triple and the drasi-core, drasi-lib, and plugin package SDK versions this binary was built against. It also reports the cdylib FFI ABI that the loader validates against plugin metadata. Plugins must match all of those values. Current packages support the PostgreSQL plugin set used by Sentinel: drasi-core 0.5.10, drasi-lib 0.9.3, the host/plugin SDK 0.11.3, and FFI ABI 0.14.0. Use PostgreSQL source and bootstrap artifacts built for this exact set.

Stream results with IAsyncEnumerable

Mon, 01 Jan 0001 00:00:00 +0000

Every streaming method on Engine returns IAsyncEnumerable<T>. Consume with await foreach. Disposing the enumerator (or the engine) completes the sequence.

Query result diffs

await foreach (var evt in drasi.QueryResultsAsync("open-orders"))
{
 foreach (var diff in evt.Results)
 {
 Console.WriteLine($"{diff.Type} {diff.Data}");
 }
}

QueryResultsAsync registers a hidden C# reaction named __stream_{queryId}_{guid} and removes it when the enumerator is disposed. Pass reactionId if you need a stable name.

This is the same payload a callback reaction receives (QueryResultEvent). Prefer a reaction when the handler should outlive a single loop. Prefer QueryResultsAsync when the consumer is a loop, a channel, or ASP.NET endpoint code.

Load a topology from configuration

Mon, 01 Jan 0001 00:00:00 +0000

Engine.FromConfigAsync builds an engine from a document of sources, queries, and reactions, then starts it. Missing id defaults to drasi.

This matches Python and Node fromConfig. Use CreateAsync when you want to add components in code after construction.

JSON document

var config = JsonNode.Parse("""
{
 "id": "demo",
 "sources": [{ "id": "orders", "autoStart": true }],
 "queries": [{
 "id": "open",
 "query": "MATCH (o:Order) WHERE o.status = 'open' RETURN o.id AS id, o.total AS total",
 "sources": ["orders"],
 "language": "cypher"
 }]
}
""")!;

await using var drasi = await Engine.FromConfigAsync(config);

Document keys:

Key	Meaning
`id`	Engine id (default `drasi`)
`secrets`, `stateStore`, `indexStore`, `walProvider`, `identity`	Same as `EngineOptions`. Merged from the `options` argument when the document omits them.
`pluginsDir`	Directory passed to `LoadPluginsAsync` before start
`sources`	In-process (`id` only) or plugin (`kind`, `id`, `config`, `autoStart`, `bootstrap`)
`queries`	`id`, `query`, `sources`, optional `language`, `joins`
`reactions`	Plugin reactions (`kind`, `id`, `queries`, `config`)

C# callback reactions cannot be expressed in JSON. Add them after FromConfigAsync, or use AddDrasi with a DrasiBuilder callback.

Handle errors

Mon, 01 Jan 0001 00:00:00 +0000

Engine and plugin failures are a DrasiException (or a more specific subclass). Branch on Code, not on message text. Codes live in DrasiErrorCodes. Bad arguments still throw ArgumentException. After Dispose or DisposeAsync, further calls throw ObjectDisposedException. After ShutdownAsync without dispose, native calls may throw DrasiException with ENGINE_CLOSED.

Catch by type or by code

try
{
 await drasi.AddSourceAsync("postgres", "orders", config);
}
catch (UnknownKindException ex) when (ex.Code == DrasiErrorCodes.UnknownSourceKind)
{
 Console.WriteLine($"plugin kind not loaded: {ex.Message}");
}
catch (DrasiException ex)
{
 Console.WriteLine($"{ex.Code}: {ex.Message}");
}

Exception types

DrasiException
├── ConfigException
│ └── UnknownKindException
├── SourceException
├── StreamLaggedException
└── PluginException
 ├── PluginNotFoundException
 ├── PluginCompatibilityException
 └── PluginSignatureException

Type	When
`UnknownKindException`	Unknown source, reaction, bootstrap, store, identity, query language, or change op
`ConfigException`	Missing required config (paths, identity, durable store, JSON shape)
`SourceException`	Bad `SourceChange` (missing id, relation without both ends)
`StreamLaggedException`	An `IAsyncEnumerable` consumer overflowed its 256-item buffer
`PluginNotFoundException`	Registry or disk lookup failed
`PluginCompatibilityException`	Plugin SDK or core version does not match this host
`PluginSignatureException`	`requireSigned: true` and the artifact was not `verified`

Codes

DrasiErrorCodes.All lists every code the native host may report. Common ones: