dotnet / dotnet/docs

Orleans Grain Persistence ETag Guidance

Open
#51,314 0 comments 0 reactions 0 assignees View on GitHub
:watch: Not Triaged dotnet-orleans/svc
Dominant language
No language data
Stars
4.8k
Forks
6.1k
Avg merge
15h 21m
Merged PRs (30d)
370

Description

### Describe the issue or suggestion

Page: [Grain persistence](https://learn.microsoft.com/en-us/dotnet/orleans/grains/grain-persistence/)

Add a new section titled "ETag and Optimistic Concurrency" after the "Write state" section, with a warning and do's/don'ts table:

Understanding ETag behavior is essential when working with grain persistence, especially in reentrant grains or when state may be modified externally. Mishandling ETags can lead to data loss or InconsistentStateException errors. Some providers leave this as null if they don't use Etags. This is why thorough testing of providers is required.

The ETag property provides optimistic concurrency control. When you call WriteStateAsync() or ClearStateAsync(), the storage provider compares the grain's current ETag with the value in storage. If they don't match (indicating another write occurred), the operation fails with an InconsistentStateException.

Behaviors:
ReadStateAsync(): Updates both State and ETag from storage
WriteStateAsync(): Fails if ETag doesn't match storage; updates ETag on success
ClearStateAsync(): Fails if ETag doesn't match storage; resets ETag to null on success
Setting ETag = null before write/clear operations bypasses version checking

---
#### Document Details

⚠ *Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.*

* ID: 4a124b90-917f-0167-176b-f123193300d2
* Version Independent ID: 8b9bcb0f-4a4a-8beb-eef3-9992f63c2f23
* Platform ID: af443b67-9a4f-e58c-e82f-055d30008b23
* Content: [Grain persistence - .NET](https://learn.microsoft.com/en-us/dotnet/orleans/grains/grain-persistence/?tabs=managed-identity&pivots=orleans-10-0)
* Content Source: [docs/orleans/grains/grain-persistence/index.md](https://github.com/dotnet/docs/blob/main/docs/orleans/grains/grain-persistence/index.md)
* Service: **dotnet-orleans**
* GitHub Login: @meaghanlewis
* Microsoft Alias: **mosagie**

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.