Skip to main content

Get Compare-Exchange Item


Get item using a cluster-wide session

  • You can retrieve compare-exchange items using a cluster-wide session.
    The session must be opened in cluster-wide mode.

  • Use the GetCompareExchangeValue advanced session method to get a compare-exchange item by its key.
    If the specified key does not exist, the method returns null. No exception is thrown.

  • Once a compare-exchange item is retrieved using a cluster-wide session, the item is tracked by the session.
    Repeating the same GetCompareExchangeValue call with the same key does not send another request to the server,
    the value is returned from the session's internal state.
    To force a re-fetch from the server, call session.Advanced.Clear() first.

  • Examples:

    Get compare-exchange item

    // First, let's create a compare-exchange item for the example,
    // e.g. store a user's email as the key and the user document id as the value.
    using (var session = store.OpenSession(
    new SessionOptions { TransactionMode = TransactionMode.ClusterWide }))
    {
    CompareExchangeValue<string> itemToCreate =
    session.Advanced.ClusterTransaction.CreateCompareExchangeValue(
    key: "user1-name@example.com",
    value: "users/1"
    );

    // Optionally, add some metadata:
    itemToCreate.Metadata["email-type"] = "work email";

    session.SaveChanges();
    }

    using (var session = store.OpenSession(
    new SessionOptions { TransactionMode = TransactionMode.ClusterWide }))
    {
    // Get the compare-exchange item:
    // ==============================

    CompareExchangeValue<string> retrievedItem = session.Advanced.ClusterTransaction
    .GetCompareExchangeValue<string>("user1-name@example.com");

    if (retrievedItem != null)
    {
    // Access the VALUE of the retrieved item
    var userDocumentId = retrievedItem.Value; // "users/1"

    // Access the METADATA of the retrieved item
    var emailType = retrievedItem.Metadata["email-type"]; // "work email"

    // Access the VERSION number of the retrieved item
    var version = retrievedItem.Index;
    }
    else
    {
    Console.WriteLine("Compare-exchange item not found");
    }
    }

    Get compare-exchange item lazily

    // Create a compare-exchange item for the example:
    using (var session = store.OpenSession(
    new SessionOptions { TransactionMode = TransactionMode.ClusterWide }))
    {
    CompareExchangeValue<string> itemToCreate =
    session.Advanced.ClusterTransaction.CreateCompareExchangeValue(
    key: "user1-name@example.com",
    value: "users/1"
    );
    session.SaveChanges();
    }

    using (var session = store.OpenSession(
    new SessionOptions { TransactionMode = TransactionMode.ClusterWide }))
    {
    // Get the compare-exchange item lazily:
    // =====================================

    var lazyItem = session.Advanced.ClusterTransaction.Lazily
    .GetCompareExchangeValue<string>("user1-name@example.com");

    // Access the item:
    CompareExchangeValue<string> retrievedItem = lazyItem.Value;

    if (retrievedItem != null) {
    // Access the VALUE of the retrieved item
    var userDocumentId = retrievedItem.Value; // "users/1"

    // Access the VERSION number of the retrieved item
    var version = retrievedItem.Index;
    }
    else
    {
    Console.WriteLine("Compare-exchange item not found");
    }
    }

    Retrieved compare-exchange items are tracked by the session

    using (var session = store.OpenSession(
    new SessionOptions { TransactionMode = TransactionMode.ClusterWide }))
    {
    // First retrieval — server call will happen
    var item1 = session.Advanced.ClusterTransaction
    .GetCompareExchangeValue<string>("user1-name@example.com");

    // No server call - the item is returned from session
    var item2 = session.Advanced.ClusterTransaction
    .GetCompareExchangeValue<string>("user1-name@example.com");

    // Clear tracked entities and compare-exchange items
    session.Advanced.Clear();

    // Server call will happen again
    var item3 = session.Advanced.ClusterTransaction
    .GetCompareExchangeValue<string>("user1-name@example.com");
    }

Get item using a store operation

  • You can retrieve compare-exchange items using a store operation.
    Use the GetCompareExchangeValueOperation operation to get a compare-exchange item by its key.

  • If the specified key does not exist, the operation returns null. No exception is thrown.

  • Examples:

    Get compare-exchange item that has a number value and metadata

    // First, let's create a new compare-exchange item for the example,
    // e.g. store the number of sales made by an employee as the value + some metadata info:
    var putCmpXchgOp = new PutCompareExchangeValueOperation<long>("employees/1-A", 12345, 0,
    new MetadataAsDictionary
    {
    { "Department", "Sales" },
    { "Role", "Salesperson" }
    });

    CompareExchangeResult<long> putResult = store.Operations.Send(putCmpXchgOp);

    // Get the compare-exchange item:
    // ==============================

    // Define the get compare-exchange operation, pass the unique item key
    var getCmpXchgOp = new GetCompareExchangeValueOperation<long>("employees/1-A");

    // Execute the operation by passing it to Operations.Send
    CompareExchangeValue<long> retrievedItem = store.Operations.Send(getCmpXchgOp);

    if (retrievedItem != null)
    {
    // Access the VALUE of the retrieved item
    long numberOfSales = retrievedItem.Value; // 12345

    // Access the METADATA of the retrieved item
    var employeeRole = retrievedItem.Metadata["Role"]; // "Salesperson"

    // Access the VERSION number of the retrieved item
    long version = retrievedItem.Index;
    }
    else
    {
    Console.WriteLine("Compare-exchange item not found");
    }

    Get compare-exchange item that has a custom object value

    // Create a new compare-exchange item for the example:
    // Put a new compare-exchange item with an object as the value
    var employeeRole = new EmployeeRole
    {
    Role = "Salesperson",
    Department = "Sales",
    NumberOfSales = 12345
    };

    var putCmpXchgOp = new PutCompareExchangeValueOperation<EmployeeRole>(
    "employees/1-A", employeeRole, 0);

    CompareExchangeResult<EmployeeRole> putResult = store.Operations.Send(putCmpXchgOp);

    // Get the compare-exchange item:
    // ==============================

    // Define the get compare-exchange operation, pass the unique item key
    var getCmpXchgOp = new GetCompareExchangeValueOperation<EmployeeRole>("employees/1-A");

    // Execute the operation by passing it to Operations.Send
    CompareExchangeValue<EmployeeRole> retrievedItem = store.Operations.Send(getCmpXchgOp);

    if (retrievedItem != null)
    {
    // Access the VALUE of the retrieved item
    var employeeDetails = retrievedItem.Value;
    var objectType = employeeDetails.GetType(); // typeof(EmployeeRole)
    var role = employeeDetails.Role; // "Salesperson"
    var Dep = employeeDetails.Department; // "Sales"
    var Sales = employeeDetails.NumberOfSales; // 12345

    // Access the VERSION number of the retrieved item
    long version = retrievedItem.Index;
    }
    else
    {
    Console.WriteLine("Compare-exchange item not found");
    }

Syntax


GetCompareExchangeValueOperation

Get compare-exchange item using a store operation:

public GetCompareExchangeValueOperation(string key);

GetCompareExchangeValue

Get compare-exchange item using cluster-wide session:

CompareExchangeValue<T> GetCompareExchangeValue<T>(string key);
Task<CompareExchangeValue<T>> GetCompareExchangeValueAsync<T>(string key,
CancellationToken token = default);

Lazy<CompareExchangeValue<T>> GetCompareExchangeValue<T>(string key);
Lazy<Task<CompareExchangeValue<T>>> GetCompareExchangeValueAsync<T>(string key,
CancellationToken token = default);
Input parameterTypeDescription
keystringThe unique identifier of the compare-exchange item to retrieve.
The returned object:Description
CompareExchangeValue<T>The compare-exchange item is returned.
Returns null if key doesn't exist.
public class CompareExchangeValue<T>
{
// The unique identifier of the compare-exchange item.
public string Key { get; }

// The existing `value` of the returned compare-exchange item.
public T Value { get; set; }

// The compare-exchange item's version.
public long Index { get; internal set; }

// The existing `metadata` of the returned compare-exchange item.
public IMetadataDictionary Metadata;
}