Azure Cosmos DB SDK Patterns

// Create once, register as a singleton, and reuse it for the life of the app.
CosmosClient client = new CosmosClient(
    accountEndpoint,
    new DefaultAzureCredential(),
    new CosmosClientOptions
    {
        ApplicationPreferredRegions = new List<string> { Regions.EastUS2, Regions.WestUS2 },
        ConnectionMode = ConnectionMode.Direct // the default in .NET v3
    });

Container container = client.GetContainer("retail", "products");

// Point read: id + partition key. A 1 KB item costs 1 RU.
ItemResponse<Product> read = await container.ReadItemAsync<Product>(
    id: "bike-042",
    partitionKey: new PartitionKey("road-bikes"));
Console.WriteLine($"Point read: {read.RequestCharge} RU");

// Query: parameterized and scoped to one partition key.
QueryDefinition query = new QueryDefinition(
        "SELECT * FROM products p WHERE p.category = @category AND p.price < @max")
    .WithParameter("@category", "road-bikes")
    .WithParameter("@max", 500);

using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    query,
    requestOptions: new QueryRequestOptions { PartitionKey = new PartitionKey("road-bikes") });

while (feed.HasMoreResults)
{
    FeedResponse<Product> page = await feed.ReadNextAsync();
    Console.WriteLine($"Page: {page.Count} items, {page.RequestCharge} RU");
}

ItemResponse<Product> read = await container.ReadItemAsync<Product>(
    "bike-042", new PartitionKey("road-bikes"));

Product product = read.Resource;
product.price = 399.99m;

try
{
    await container.ReplaceItemAsync(
        product,
        product.id,
        new PartitionKey(product.category),
        new ItemRequestOptions { IfMatchEtag = read.ETag });
}
catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.PreconditionFailed)
{
    // 412: another writer changed the item. Read it again, reapply the change, retry.
}

List<PatchOperation> operations = new()
{
    PatchOperation.Set("/status", "shipped"),
    PatchOperation.Increment("/revision", 1),
    PatchOperation.Add("/tags/-", "priority"), // "-" appends to the array
    PatchOperation.Remove("/draftNotes")
};

// Optional: apply the patch only when the item still matches this filter.
PatchItemRequestOptions options = new()
{
    FilterPredicate = "FROM orders o WHERE o.status = 'packed'"
};

ItemResponse<Order> patched = await container.PatchItemAsync<Order>(
    id: "order-1001",
    partitionKey: new PartitionKey("customer-77"),
    patchOperations: operations,
    requestOptions: options);

PartitionKey customer = new PartitionKey("customer-77");

TransactionalBatch batch = container.CreateTransactionalBatch(customer)
    .CreateItem(order)
    .CreateItem(lineOne)
    .PatchItem("customer-77-profile", new[] { PatchOperation.Increment("/orderCount", 1) });

using TransactionalBatchResponse response = await batch.ExecuteAsync();

if (response.IsSuccessStatusCode)
{
    Order created = response.GetOperationResultAtIndex<Order>(0).Resource;
}
else
{
    // Nothing was committed. The failing operation carries its own status code,
    // such as 409 when a create meets an existing id; the rest report 424.
    Console.WriteLine($"Batch rolled back: {response.StatusCode}");
}