Infinispan Hot Rod .NET Client Guide

dotnet add package Infinispan.Hotrod

<PackageReference Include="Infinispan.Hotrod" Version="10.0.0-beta.2" />

using Infinispan.Hotrod;

// Connect with a URI (simplest approach)
var client = InfinispanClient.FromUri("hotrod://admin:password@localhost:11222");

// Create a typed cache using the builder
var cache = client.NewCache<string>("default")
    .WithEncoding(MediaType.PlainText)
    .Build();

await cache.Put("greeting", "hello world");

var value = await cache.Get("greeting");
Console.WriteLine(value); // hello world

client.Dispose();

var client = new InfinispanClient();
client.AddHost("localhost", 11222);
client.User = "admin";
client.Password = "password";

var client = InfinispanClient.FromUri("hotrod://localhost:11222");

// With authentication
var client = InfinispanClient.FromUri("hotrod://admin:password@localhost:11222");

// Multiple servers
var client = InfinispanClient.FromUri("hotrod://server1:11222,server2:11222,server3:11222");

// TLS (use hotrods:// scheme)
var client = InfinispanClient.FromUri("hotrods://admin:password@localhost:11222");

// With query parameters
var client = InfinispanClient.FromUri(
    "hotrod://admin:pass@localhost:11222?sasl_mechanism=SCRAM-SHA-256");

var client = new InfinispanClient();
client.AddHost("server1", 11222);
client.AddHost("server2", 11222);

var client = new InfinispanClient();
client.AddHost("PRIMARY", "dc1-server1", 11222);
client.AddHost("PRIMARY", "dc1-server2", 11222);
client.AddHost("BACKUP", "dc2-server1", 11222);
client.AddHost("BACKUP", "dc2-server2", 11222);

client.SwitchCluster("BACKUP");

client.ClientIntelligence = ClientIntelligence.HashDistributionAware;

var client = InfinispanClient.FromUri(
    "hotrod://admin:password@localhost:11222?sasl_mechanism=SCRAM-SHA-256");

var client = new InfinispanClient();
client.AddHost("localhost", 11222);
client.User = "admin";
client.Password = "password";
client.AuthMech = "SCRAM-SHA-256";
client.Domain = "infinispan";

var client = new InfinispanClient();
client.AddHost("server.example.com", 11222);
client.User = "user@EXAMPLE.COM";
client.Password = "password";
client.AuthMech = "GSSAPI";
client.Domain = "server.example.com";

var client = new InfinispanClient();
client.AddHost("server.example.com", 11222);
client.AuthMech = "GSSAPI";
client.Domain = "server.example.com";

using System.Security.Cryptography.X509Certificates;

var client = new InfinispanClient();
client.AddHost("server.example.com", 11222);
client.AuthMech = "EXTERNAL";
client.UseTLS = true;
client.CACert = chain; // server CA chain

client.UseTLS = true;

using System.Security.Cryptography.X509Certificates;

var chain = new X509Chain();
chain.ChainPolicy.CustomTrustStore.Add(
    new X509Certificate2("/path/to/ca.pem"));
chain.ChainPolicy.TrustMode = X509ChainTrustMode.CustomRootTrust;

client.UseTLS = true;
client.CACert = chain;

var cache = client.NewCache<string>("my-cache")
    .WithEncoding(MediaType.PlainText)
    .Build();

// Store an entry.
await cache.Put("key", "value");

// Retrieve an entry.
var value = await cache.Get("key");

// Delete an entry.
await cache.Remove("key");

var cache = client.NewCache(
    new StringMarshaller(), new StringMarshaller(), "my-cache");

var vwv = await cache.GetWithVersion("key");
if (vwv != null)
{
    Console.WriteLine($"value={vwv.Value} version={vwv.Version}");
}

var vwm = await cache.GetWithMetadata("key");
if (vwm != null)
{
    Console.WriteLine($"value={vwm.Value} version={vwm.Version}");
    Console.WriteLine($"created={vwm.Created} lifespan={vwm.Lifespan}");
    Console.WriteLine($"lastUsed={vwm.LastUsed} maxIdle={vwm.MaxIdle}");
}

bool replaced = await cache.ReplaceWithVersion("key", "new-value", vwv.Version);

var (prev, removed) = await cache.RemoveWithVersion("key", vwv.Version);

var entries = new Dictionary<string, string>
{
    { "key1", "val1" },
    { "key2", "val2" },
    { "key3", "val3" }
};
await cache.PutAll(entries);

var keys = new HashSet<string> { "key1", "key2" };
var result = await cache.GetAll(keys);

var keys = await cache.KeySet();

await cache.Put("key", "value",
    lifespan: new ExpirationTime { Unit = TimeUnit.SECONDS, Value = 30 },
    maxidle: new ExpirationTime { Unit = TimeUnit.SECONDS, Value = 10 });

cache.ForceReturnValue = true;
var previous = await cache.Put("key", "new-value");

public class JsonMarshaller<T> : Marshaller<T>
{
    public override byte[] Marshall(T t)
    {
        var json = JsonSerializer.Serialize(t);
        return Encoding.UTF8.GetBytes(json);
    }

    public override T Unmarshall(byte[] buff)
    {
        var json = Encoding.UTF8.GetString(buff);
        return JsonSerializer.Deserialize<T>(json);
    }
}

var cache = client.NewCache(
    new StringMarshaller(),
    new JsonMarshaller<Person>(),
    "people");

await cache.Put("john", new Person { Name = "John", Age = 30 });
var person = await cache.Get("john");

var cache = client.NewCache<Person>("people")
    .WithEncoding(MediaType.Protobuf)
    .Build();

var cache = client.NewCache(
    new StringMarshaller(),
    new ProtobufMarshaller<Person>(),
    "people");

var cache = client.NewCache<string>("my-cache")
    .WithEncoding(MediaType.PlainText)
    .Build();

await cache.EnableNearCache(maxEntries: 5000);

var stats = cache.NearCacheStats;
if (stats != null)
{
    Console.WriteLine($"hits={stats.Hits} misses={stats.Misses}");
    Console.WriteLine($"invalidations={stats.Invalidations} size={stats.Size}");
}

public class MyListener : AbstractClientListener
{
    private string _id = Guid.NewGuid().ToString();
    public override string ListenerID { get => _id; set => _id = value; }

    public override void OnEvent(Event e)
    {
        Console.WriteLine($"type={e.Type} key={Encoding.ASCII.GetString(e.Key)}");
    }

    public override void OnError(Exception ex)
    {
        Console.WriteLine($"Listener error: {ex?.Message}");
    }
}

var listener = new MyListener();
await cache.AddListener(listener);

// Wait for events...
listener.Wait();

await cache.RemoveListener(listener);

await cache.AddListener(listener, includeState: true);

using Infinispan.Hotrod;
using Infinispan.Hotrod.Linq;

var cache = client.NewCache<Person>("people")
    .WithEncoding(MediaType.Protobuf)
    .Build();

await using var cq = cache.ContinuousQuery(
    "FROM example.Person WHERE age >= 18");

await using var cq = cache.ContinuousQuery(
    "FROM example.Person WHERE age >= 18");

await foreach (var ev in cq.Events.ReadAllAsync(cancellationToken))
{
    Console.WriteLine($"Type={ev.Type}, Key={ev.Key}");
    if (ev.Type == CQResultType.Joining)
    {
        // Entry now matches the query
    }
    else if (ev.Type == CQResultType.Leaving)
    {
        // Entry no longer matches the query
    }
}

var cq = cache.ContinuousQuery("FROM example.Person WHERE age >= 18");
// ... process events ...
await cq.DisposeAsync();

await foreach (var entry in cache.RetrieveEntriesWithMetadata(batchSize: 500))
{
    Console.WriteLine($"key={entry.Key} value={entry.Value.Value}");
    Console.WriteLine($"version={entry.Value.Version} created={entry.Value.Created}");
    Console.WriteLine($"lifespan={entry.Value.Lifespan} maxIdle={entry.Value.MaxIdle}");
}

await foreach (var value in cache.Values())
{
    Console.WriteLine(value);
}

var tx = cache.BeginTransaction(timeoutMs: 30000);

var value = await tx.Get("key");
await tx.Put("key", "new-value");
await tx.Remove("other-key");

await tx.CommitAsync();

var tx = cache.BeginTransaction();
await tx.Put("key", "value",
    lifespan: new ExpirationTime { Unit = TimeUnit.MINUTES, Value = 5 });
await tx.CommitAsync();

var client = InfinispanClient.FromUri("hotrod://admin:password@127.0.0.1:11222");

// Get the counter manager
var counters = client.Counters();

// Define a strong counter
await counters.Define("my-counter", new CounterConfiguration
{
    Type = CounterType.Strong,
    Storage = CounterStorage.Persistent,
    InitialValue = 0
});

// Define a bounded strong counter
await counters.Define("bounded-counter", new CounterConfiguration
{
    Type = CounterType.Strong,
    Storage = CounterStorage.Volatile,
    Bounded = true,
    LowerBound = 0,
    UpperBound = 100,
    InitialValue = 50
});

// Define a weak counter
await counters.Define("weak-counter", new CounterConfiguration
{
    Type = CounterType.Weak,
    Storage = CounterStorage.Volatile,
    ConcurrencyLevel = 4,
    InitialValue = 0
});

// Get a counter handle
var counter = counters.Counter("my-counter");

// Get the current value
long value = await counter.Get();

// Add a delta and get the result
long newValue = await counter.AddAndGet(5);

// Set a value and get the previous one
long previous = await counter.GetAndSet(42);

// Compare and swap
var (oldValue, success) = await counter.CompareAndSwap(42, 100);
if (success)
{
    Console.WriteLine("Swapped successfully");
}

// Reset to initial value
await counter.Reset();

// Check if a counter is defined
bool exists = await counters.IsDefined("my-counter");

// Get counter configuration
CounterConfiguration config = await counters.GetConfiguration("my-counter");

// List all counter names
IList<string> names = await counters.Names();

// Remove a counter
await counters.Remove("my-counter");

var client = InfinispanClient.FromUri("hotrod://admin:password@127.0.0.1:11222");

var multimap = client.NewMultimap(
    new StringMarshaller(), new StringMarshaller(), "my-multimap");

var multimap = client.NewMultimap(
    new StringMarshaller(), new StringMarshaller(), "my-multimap",
    supportsDuplicates: true);

await multimap.Put("colors", "red");
await multimap.Put("colors", "blue");
await multimap.Put("colors", "green");

IList<string> colors = await multimap.Get("colors");
// colors = ["red", "blue", "green"]

IList<string> empty = await multimap.Get("nonexistent");
// empty = []

bool removed = await multimap.RemoveKey("colors");

await multimap.Put("colors", "red");
await multimap.Put("colors", "blue");

bool removed = await multimap.RemoveEntry("colors", "red");
// Only "blue" remains

bool hasKey = await multimap.ContainsKey("colors");

bool hasValue = await multimap.ContainsValue("red");

bool hasEntry = await multimap.ContainsEntry("colors", "red");

await multimap.Put("k1", "v1");
await multimap.Put("k1", "v2");
await multimap.Put("k2", "v3");

long size = await multimap.Size();
// size = 3

var client = InfinispanClient.FromUri("hotrod://admin:password@127.0.0.1:11222");
var admin = client.Administration();

await admin.CreateCache("my-cache", "<distributed-cache/>");

await admin.CreateCacheWithTemplate("my-cache", "my-template");

await admin.GetOrCreateCache("my-cache");
await admin.GetOrCreateCacheWithTemplate("my-cache", "my-template");

await admin.RemoveCache("my-cache");

ISet<string> names = await admin.GetCacheNames();

await admin.UpdateConfigurationAttribute(
    "my-cache", "memory.max-count", "5000");

await admin.AssignAlias("my-cache", "cache-alias");

await admin.ReindexCache("my-indexed-cache");

await admin.UpdateIndexSchema("my-indexed-cache");

await admin.CreateTemplate("my-template", "<local-cache/>");

await admin.RemoveTemplate("my-template");

await admin.CreateCache("volatile-cache", flags: AdminFlag.Volatile);

var schemas = admin.Schemas();

using Infinispan.Hotrod;

builder.Services.AddInfinispanCache(options =>
{
    options.CacheName = "sessions";
    options.ConfigureClient = client =>
    {
        client.AddHost("infinispan-server", 11222);
        client.User = "admin";
        client.Password = "password";
        client.AuthMech = "SCRAM-SHA-256";
    };
});

using var client = InfinispanClient.FromUri("hotrod://admin:password@localhost:11222");

using var cache = new InfinispanDistributedCache(client, "my-cache");

await cache.SetAsync("key", Encoding.UTF8.GetBytes("value"),
    new DistributedCacheEntryOptions
    {
        AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(30),
        SlidingExpiration = TimeSpan.FromMinutes(5)
    });

var data = await cache.GetAsync("key");

await cache.RefreshAsync("session-key");

builder.Services.AddInfinispanHybridCache(
    infinispan =>
    {
        infinispan.CacheName = "hybrid";
        infinispan.ConfigureClient = client =>
        {
            client.AddHost("infinispan-server", 11222);
            client.User = "admin";
            client.Password = "password";
        };
    },
    hybrid =>
    {
        hybrid.MaximumPayloadBytes = 1024 * 1024;
        hybrid.DefaultEntryOptions = new HybridCacheEntryOptions
        {
            Expiration = TimeSpan.FromMinutes(10),
            LocalCacheExpiration = TimeSpan.FromMinutes(2)
        };
    });

public class MyService(HybridCache cache)
{
    public async Task<Product> GetProductAsync(string id)
    {
        return await cache.GetOrCreateAsync(
            $"product:{id}",
            async cancel => await LoadProductFromDatabase(id, cancel));
    }
}

dotnet build

dotnet test