Skip to main content

Developer guide overview

This guide shows you how to build .NET applications on Clustron Zaris: how to get a client, store and retrieve data, run bulk and batch operations, clear data, control write behavior with options, and manage serialization. It also covers the coordination primitives (leases, locks, counters, watch, transactions) that make Zaris safe to use from many processes at once.

Every task in this guide uses the same client interface, IZarisClient, and the same code works whether the store runs in-process or across a distributed cluster.

What you will learn​

The guide is task-focused. By the end you can:

  • Resolve a client from dependency injection and reuse it correctly.
  • Store, read, and delete single keys, and interpret the KvResult you get back.
  • Move many keys at once with bulk operations, and mix operation types with batches.
  • Clear a prefix, a key range, or the whole store.
  • Attach TTL, labels, leases, and concurrency checks to a write through PutOptions.
  • Control how your objects are serialized and deserialized.
  • Design keys and labels so scans, queries, and watches stay efficient.
  • Make operations resilient with the client's built-in retries and safe-to-retry patterns.
  • Observe a store through the metrics it emits, and test your code against an in-process store.
  • Apply best practices, avoid common pitfalls, and use Zaris as an ASP.NET Core cache.

The typical workflow​

Most applications follow the same shape. You resolve a client once at startup, then reuse it for every operation.

// 1. Resolve a client for a named store.
var client = await provider.GetAsync("default");

// 2. Write and read data.
await client.PutAsync("key", "value");
var result = await client.GetAsync<string>("key");

// 3. Inspect the result.
if (result.IsSuccess)
{
    Console.WriteLine(result.Value);
}

Every operation returns a result object rather than throwing on a missing key or a rejected write. You check IsSuccess (or the more specific Status) instead of catching exceptions for expected outcomes. Basic operations covers this pattern in detail.

Coordination primitives​

Single-key reads and writes are enough for a cache. When several processes share the same store, you also need to coordinate them. Zaris exposes these primitives through the same client:

  • Leases grant time-bound ownership of a key. When the lease expires, keys attached to it are removed.
  • Locks give one caller exclusive access to a key while it makes a change.
  • Counters provide atomic increment and decrement for shared numeric state.
  • Watch delivers change notifications so your code reacts to updates instead of polling.
  • Transactions group several operations into one all-or-nothing unit.

Each primitive has its own page later in this guide.

The same API everywhere​

The client API does not change between deployment modes. A store configured as InProc runs inside your process; a store configured as Remote talks to a cluster over the network. Your application code is identical in both cases, so you can develop against an in-process store and deploy against a cluster without rewriting calls. See Getting a client for how to select a mode through configuration.

Next steps​