How to get the Etag for an Item?

[WestDiscGolf]

Is your feature request related to a problem? Please describe.
When updating an item there is the functionality to use the associated etag of the resource through the IItemWithEtag construct however the Get* functionality does not return the etag to use. How does this value get surfaced to the consumer of the repository?

Very briefly I tried updating the GetAsync method to set the ETag if the TItem implements the interface however as it's read only this can't be set.

Describe the solution you'd like
A way to surface meta data from Get / Query requests.

[mumby0168]

Is this how do you as a consumer read the etag value?

[WestDiscGolf]

With the Cosmos SDK I would access the Etag from the returned result from the container read call ...

ItemResponse<TItem> response =
                await container.ReadItemAsync<TItem>(id, partitionKey, cancellationToken: cancellationToken)
                    .ConfigureAwait(false);

var eTag = response.Etag; // <- here

I wonder if there is an option for overrides of the Get* versions of the methods which expose the ItemResponse<T>.Headers?

[mumby0168]

We aim to have dedicated documentation for this soon.

There is a bit of explanation in the README see below.

Optimistic Concurrency Control with Etags

The default repository now supports etags and will pass them when IItemWithEtag is implemented correctly or the base classes EtagItem or FullItem are used. The etag check is enforced on all updates when TItem is of the correct type. It can however be bypassed by setting the ignoreEtag optional parameter in the relevant async methods. The InMemory repository also supports OCC with Etags. The OptimisticCurrencyControl sample shows these features.

Getting the new etag

When creating a new object, if storing in memory, it is important to store the result from the create call to ensure you have the correct etag for future updated.

For example your code should look something like this:

TItem currentItem = new TItem(...);
currentItem = _repository.CreateAsync(currentItem);

Sequential updates

When doing sequential updates to the same item it is important to use the result from the update method (when OptimizeBandwith is false) or refetch the updated data each time (when OptimizeBandwith is true) otherwise the etag value will not be updated. The following code shows what to do in each case:

Optimize Bandwith Off

TItem currentItem = _repository.CreateAsync(itemConfig);
currentItem = _repository.UpdateAsync(currentItem);
currentItem = _repository.UpdateAsync(currentItem);

Optimize Bandwith On

TItem currentItem = _repository.CreateAsync(itemConfig);
_repository.UpdateAsync(currentItem);
currentItem = _repository.GetAsync(currentItem.Id);
_repository.UpdateAsync(currentItem);
currentItem = _repository.GetAsync(currentItem);
currentItem = _repository.UpdateAsync(currentItem);

Catching mismatched etag errors

The following code shows how to catch the error when the etags do not match.

  try
  {
      currentBankAccount = await repository.UpdateAsync(currentBankAccount);
      Console.WriteLine($"Updated bank account: {currentBankAccount}.");
  }
  catch (CosmosException exception) when (exception.StatusCode == HttpStatusCode.PreconditionFailed)
  {
      Console.WriteLine("Failed to update balance as the etags did not match.");
  }

Ignoring the etag

The following code shows how to ignore the etag when doing an update.

await repository.UpdateAsync(currentBankAccount, ignoreEtag: true);

Passing the etag to a patch update

The following code shows how to pass the etag when doing a update to specific properties.

await repository.UpdateAsync(currentBankAccount.Id,
  builder => builder.Replace(account => account.Balance, currentBankAccount.Balance - 250), etag: currentBankAccount.Etag);

[mumby0168]

Hi, @WestDiscGolf converted this to a discussion. Hope this is okay 😄

[WestDiscGolf]

@mumby0168 No worries 😄

Thanks for the update on the use of the etag when you create or update. If you read out a record and return it to a consuming UI, for example, in request #1 and then in request #2 the user posts the updated data back with the original etag ready for updating. If you read it out by id and then used it when you push an update you may lose data if it's been changed since you got the data and did the UI round trip. This wouldn't be good 😟 Would I still have to use the SDK manually to get the current etag?

Sorry if I'm not explaining it clearly

[mumby0168]

Okay, so you read a user out of Cosmos DB? You have the etag if this point? (if your User model derives from ETagItem, FullItem or implements the IItemWithEtag interface) then you return it to a UI via a DTO? Have I got this right so far?

[WestDiscGolf]

Ahhh, this is what I was missing! I don't think I'd come across EtagItem before. This has solved the problem. Thank you!

[mumby0168]

Great stuff!