Orleans Grain Persistence ETag Guidance
- 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
Assessment
This issue has not been assessed yet.