Docs: fix WaitForExternalEvent references and add FIFO queue sample#1368
Open
cgillum wants to merge 6 commits into
Open
Docs: fix WaitForExternalEvent references and add FIFO queue sample#1368cgillum wants to merge 6 commits into
cgillum wants to merge 6 commits into
Conversation
DTFx has no WaitForExternalEvent helper. Update the docs samples and API references to use the real OnEvent + TaskCompletionSource pattern, and add a FIFO job queue sample to the eternal orchestrations guide.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates Durable Task Framework (DTFx) documentation to remove references to a non-existent WaitForExternalEvent API and replace those examples with the supported OnEvent + TaskCompletionSource external event pattern. It also adds a new FIFO-per-key job queue sample to the eternal orchestrations guide.
Changes:
- Removed
WaitForExternalEventmentions from quickstart/determinism docs. - Rewrote multiple timer/orchestration samples to use
OnEvent+TaskCompletionSource. - Added a FIFO queue sample showing per-key serialization using
ContinueAsNew.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/getting-started/quickstart.md | Removes WaitForExternalEvent from the API list in the quickstart narrative. |
| docs/concepts/deterministic-constraints.md | Removes WaitForExternalEvent from the “durable operations” list. |
| docs/concepts/orchestrations.md | Updates external event and human-interaction examples to the OnEvent + TaskCompletionSource pattern. |
| docs/features/timers.md | Updates timer + external-event samples and adds/adjusts guidance around cancellation patterns. |
| docs/features/eternal-orchestrations.md | Updates event-driven eternal orchestration examples and adds a FIFO queue sample using ContinueAsNew. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Address Copilot review feedback on PR #1368. Use the 4-parameter TaskOrchestration<TResult,TInput,TEvent,TStatus> base so the framework deserializes event payloads and OnEvent receives a typed value (the prior string + manual MessageDataConverter.Deserialize pattern would throw for object payloads). Use TrySetResult instead of SetResult for idempotency against duplicate/late events, return default instead of null for generic results, and make the Cancel Unused Timers snippet self-contained.
…payload Address round 2 Copilot review feedback on PR #1368. Create the TaskCompletionSource before awaiting any activity so events raised while an activity runs are captured by OnEvent instead of dropped. Propagate the typed event value in the graceful-termination sample, and correct the MaxUpdatesPerGeneration comment to reflect that ContinueAsNew always runs each generation.
| ApprovalRequest request) | ||
| // The 4-type-parameter base declares bool as the event payload type, so the framework | ||
| // deserializes incoming events and passes OnEvent a typed value. | ||
| public class ApprovalOrchestration : TaskOrchestration<ApprovalResult, ApprovalRequest, bool, string> |
nytian
previously approved these changes
Jun 24, 2026
nytian
left a comment
nytian
left a comment
Contributor
There was a problem hiding this comment.
Left two non-blocking comments. Thanks!
torosent
previously approved these changes
Jun 24, 2026
…ure/durabletask into docs/fix-waitforexternalevent
Comment on lines
+45
to
+46
| Each sample's full source is linked below. For deeper explanations of the patterns | ||
| they demonstrate, see the [DTFx documentation](../../docs/README.md). |
Comment on lines
+69
to
+71
| Schedules `CronTask` to run repeatedly on a [cron](https://en.wikipedia.org/wiki/Cron) | ||
| expression (via NCrontab), using `CreateTimer` to wait between runs. The parameter is the | ||
| cron schedule and is optional (it falls back to a fixed interval when omitted). |
| } | ||
| ``` | ||
| - Source: [Cron/CronOrchestration.cs](Cron/CronOrchestration.cs) | ||
| - Docs: [Timers](../../docs/features/timers.md), [Eternal Orchestrations](../../docs/features/eternal-orchestrations.md) |
| var approvalData = await context.WaitForExternalEvent<ApprovalData>("ApprovalReceived"); | ||
| // The 4-type-parameter base declares ApprovalData as the event payload type, so the | ||
| // framework deserializes incoming events and passes OnEvent a typed value. | ||
| public class ApprovalOrchestration : TaskOrchestration<ApprovalData, string, ApprovalData, string> |
Comment on lines
+376
to
+378
| > [!NOTE] | ||
| > On Azure Storage (the default `Carryover` behavior), events that arrive during the brief `ContinueAsNew` transition are automatically re-delivered to the next generation, so nothing is lost. The Service Fabric provider instead uses `Ignore` and drops them — there, treat the producer as the source of truth and re-drive any unacknowledged update (using `UpdateId` for idempotency). | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The docs used a
WaitForExternalEventAPI that doesn't exist in DTFx. This updates the affected samples and API references across the docs to use the realOnEvent+TaskCompletionSourcepattern.While in here, I also added a FIFO job queue sample to the eternal orchestrations guide showing per-key serialization with
ContinueAsNew.Files touched:
docs/concepts/orchestrations.mddocs/concepts/deterministic-constraints.mddocs/features/eternal-orchestrations.mddocs/features/external-events.md(typed-event guidance and TrySetResult usage)docs/features/timers.mddocs/getting-started/quickstart.md