Add state to core

[MehakBindra]

This pull request introduces a new state management feature for Teams bots, enabling persistent per-conversation and per-user state using .NET's IDistributedCache abstraction. The design is opt-in, does not affect existing bots unless enabled, and is fully documented in a new design document. A new sample bot is also added to demonstrate usage.

State Management Feature:

• Design Document:
  Added State-Design.md detailing the architecture, API, usage patterns, and edge cases for the new TurnState feature, which provides persistent state across turns and conversations using any IDistributedCache backend. The document covers key design choices, API surface, serialization, atomic semantics, and what the feature is (and is not) intended for.

Sample Update:

• New Sample Bot:
  Added the StateBot sample project to the solution, demonstrating how to use the new state management APIs in practice. (core/core.slnx updated to include samples/StateBot/StateBot.csproj)

[Copilot]

Pull request overview

This PR introduces an opt-in turn state feature in Microsoft.Teams.Apps that loads per-conversation and per-user state at the start of each turn and saves it on successful completion, backed by IDistributedCache. It wires state through TeamsBotApplication and Context<TActivity>, adds a sample bot demonstrating the feature, and adds unit tests + a design document.

Changes:

• Add new state primitives (TurnState, StateScope, TurnStateStore, StateSerializer) under Microsoft.Teams.Apps.State.
• Wire state enablement via TeamsBotApplicationOptions.UseState() / AppBuilder.UseState() and load/save around routing in TeamsBotApplication.OnActivity.
• Add StateBot sample, documentation, and unit tests covering routing, serialization, and persistence semantics.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
core/test/Microsoft.Teams.Apps.UnitTests/StateWiringTests.cs	Verifies UseState() toggles options and DI wiring registers TurnStateStore.
core/test/Microsoft.Teams.Apps.UnitTests/State/TurnStateTests.cs	Tests scoped-path API routing and validation behavior.
core/test/Microsoft.Teams.Apps.UnitTests/State/TurnStateStoreTests.cs	Tests load/save semantics, change detection, delete-on-clear, and after-turn sealing.
core/test/Microsoft.Teams.Apps.UnitTests/State/StateSerializerTests.cs	Tests serializer round-trips and camelCase behavior.
core/test/Microsoft.Teams.Apps.UnitTests/State/StateScopeTests.cs	Tests scope CRUD behavior, change tracking, snapshotting, and completion guard.
core/src/Microsoft.Teams.Apps/TeamsBotApplicationOptions.cs	Adds UseState() and internal configuration flags for state.
core/src/Microsoft.Teams.Apps/TeamsBotApplication.HostingExtensions.cs	Registers default distributed cache + TurnStateStore when state is enabled.
core/src/Microsoft.Teams.Apps/TeamsBotApplication.cs	Loads state before dispatch, saves on success, seals in finally.
core/src/Microsoft.Teams.Apps/State/TurnStateStore.cs	Implements cache-backed load/save, change detection, and delete-on-empty behavior.
core/src/Microsoft.Teams.Apps/State/TurnState.cs	Defines per-turn state container, key derivation, and scoped-path helpers.
core/src/Microsoft.Teams.Apps/State/StateSerializer.cs	Defines JSON serialization settings and helpers for scope documents.
core/src/Microsoft.Teams.Apps/State/StateScope.cs	Implements per-scope bag API with change tracking and after-turn guard.
core/src/Microsoft.Teams.Apps/Routing/Route.cs	Forwards ctx.State into typed contexts created during routing.
core/src/Microsoft.Teams.Apps/Microsoft.Teams.Apps.csproj	Adds caching abstractions package references for IDistributedCache.
core/src/Microsoft.Teams.Apps/Context.cs	Adds TurnState? to context and exposes Context.State.
core/src/Microsoft.Teams.Apps/AppBuilder.cs	Adds UseState() builder method delegating to options.
core/samples/StateBot/StateBot.csproj	Adds a sample project demonstrating state usage (optional Redis).
core/samples/StateBot/README.md	Documents sample commands and how state persists with/without Redis.
core/samples/StateBot/Program.cs	Implements sample bot handlers demonstrating conversation/user state and sealing behavior.
core/samples/StateBot/appsettings.json	Sample configuration (logging + connection strings).
core/docs/State-Design.md	Design document describing state semantics, architecture, and constraints.
core/core.slnx	Adds the new StateBot sample to the solution.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 31 out of 31 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 30 out of 30 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 30 out of 30 changed files in this pull request and generated 8 comments.

[Copilot]

Pull request overview

Copilot reviewed 30 out of 30 changed files in this pull request and generated 2 comments.