[Bernd Verst (berndverst)]

Summary

What changed?

• Expanded XML API documentation for StartOrchestrationOptions.DedupeStatuses and WithDedupeStatuses.
• Added a README singleton example and guidance on supported statuses, null versus empty lists, duplicate exceptions, active-instance replacement, and backend support.
• No public API or runtime behavior changes.

Why is this change needed?

• Make deduplication configuration discoverable and explain how to prevent duplicate starts without accidentally replacing an active orchestration.

Issues / work items

• Resolves Missing documentation for DedupeStatuses #768
• Related: N/A

---

Project checklist

• Release notes are not required for the next release
  • Otherwise: Notes added to release_notes.md
• Backport is not required
  • Otherwise: Backport tracked by issue/PR #issue_or_pr
• All required tests have been added/updated (unit tests, E2E tests) — no test changes required for documentation-only edits
• Breaking change?
  • If yes:
    • Impact: N/A
    • Migration guidance: N/A

---

AI-assisted code disclosure (required)

Was an AI tool used? (select one)

• No
• Yes, AI helped write parts of this PR (e.g., GitHub Copilot)
• Yes, an AI agent generated most of this PR

If AI was used:

• Tool(s): GitHub Copilot
• AI-assisted areas/files: README.md, src/Abstractions/TaskOptions.cs, src/Client/Core/StartOrchestrationOptionsExtensions.cs
• What you changed after AI output: No subsequent human edits recorded; reviewed the documentation against client implementations and existing tests, and corrected the exception namespace in the example and XML reference.

AI verification (required if AI was used):

• I understand the code and can explain it
• I verified referenced APIs/types exist and are correct
• I reviewed edge cases/failure paths (timeouts, retries, cancellation, exceptions)
• I reviewed concurrency/async behavior
• I checked for unintended breaking or behavior changes

---

Testing

Automated tests

• Result: Not run — documentation and XML comments only; no runtime behavior changed.
• git diff --check — passed before commit.
• Reviewed documented repository build/test commands; did not run dotnet build Microsoft.DurableTask.sln --configuration Release or dotnet test Microsoft.DurableTask.sln --configuration Release --no-build --verbosity normal because the change is documentation-only.

Manual validation (only if runtime/behavior changed)

• Environment (OS, .NET version, components): N/A — no runtime/behavior changes.
• Steps + observed results:
  1. Compared documented semantics with the gRPC client, orchestration-service shim, reuse-policy conversion, and existing deduplication tests; documentation reflects the existing behavior and backend caveats.
  2. Confirmed the example uses the existing scheduling overload and exception namespace.
  3. Confirmed the diff changes only README content and XML documentation comments.
• Evidence (optional): N/A

---

Notes for reviewers

• This PR adds repository guidance and XML comments used for API documentation. Updating the Microsoft Learn conceptual singleton page and publishing refreshed API reference content are separate documentation steps.

[Copilot]

🟢 Approval recommended

No active review issues remain for this documentation-only update clarifying orchestration deduplication and singleton configuration.

No open issues 🎉

What changed in this PR

This documentation-only PR addresses #768 by explaining orchestration deduplication in the SDK’s API comments and README. It makes singleton configuration more discoverable without changing public APIs or runtime behavior.

Changes:

• Clarifies supported statuses, null versus empty lists, duplicate exceptions, and instance ID reuse.
• Adds a singleton scheduling example that protects active instances from replacement.
• Documents replacement risks, configuration restrictions, and backend support caveats.

File	Description
src/​Client/​Core/​StartOrchestrationOptionsExtensions.cs	Expands WithDedupeStatuses XML documentation and adds a singleton configuration example.
src/​Abstractions/​TaskOptions.cs	Documents DedupeStatuses semantics, defaults, supported values, and restrictions.
README.md	Adds singleton scheduling guidance, exception handling, and backend caveats.

_{Review effort: Balanced}