Add injectable IScenarioStateStore for distributed scenario state by m4tchl0ck · Pull Request #1430 · wiremock/WireMock.Net

m4tchl0ck · 2026-03-10T22:07:10Z

Summary

Introduce IScenarioStateStore abstraction so users can inject a distributed implementation (Redis, SQL, etc.) to share scenario state across multiple WireMock.Net instances
Add InMemoryScenarioStateStore as the default implementation, preserving exact current behavior (backed by ConcurrentDictionary with OrdinalIgnoreCase)
Add FileBasedScenarioStateStore for persistent scenario state across restarts — in-memory cache backed by JSON file persistence in __admin/scenarios/
Move ScenarioState to WireMock.Net.Abstractions so the interface can reference it
Add ScenarioStateStore property to WireMockServerSettings for injection (following the IFileSystemHandler pattern)
Replace all direct ConcurrentDictionary<string, ScenarioState> usage in middleware, matcher, and server with IScenarioStateStore
Use TryGet pattern (bool TryGet(string, out ScenarioState?)) instead of nullable Get for safer state lookups

FileBasedScenarioStateStore

Reads come from an in-memory ConcurrentDictionary; all mutations (TryAdd, Update, AddOrUpdate, TryRemove, Clear) write through to disk as indented JSON files. The constructor loads existing state from disk on startup, enabling persistence across restarts and visibility into state via the filesystem.

var server = WireMockServer.Start(new WireMockServerSettings
{
    ScenarioStateStore = new FileBasedScenarioStateStore("/path/to/storage")
});

Test plan

All 15 InMemoryScenarioStateStoreTests pass (TryAdd, TryGet, GetAll, Update, AddOrUpdate, TryRemove, Clear, case-insensitivity)
All 20 FileBasedScenarioStateStoreTests pass (15 mirrored behavior tests + 5 file-persistence tests: disk write, disk delete, clear files, constructor loading, update persistence)
All 13 existing StatefulBehaviorTests pass unchanged — backward compatibility confirmed
All 4 additional Scenario-related tests pass
Full build succeeds with 0 errors across all target frameworks

StefH · 2026-03-11T09:49:51Z

@m4tchl0ck
Thank you for this.

However I'm working on a 2.0 version which has a lot of changes, so I will complete that one first...

About the CI fix:
I did also encounter some issues in my development on version 2, and this is the change:
https://github.com/wiremock/WireMock.Net/pull/1359/changes#diff-b803fcb7f17ed9235f1e5cb1fcd2f5d3b2838429d4368ae4c57ce4436577f03f

So maybe revert the CI changes for this PR

m4tchl0ck · 2026-03-11T10:43:09Z

@m4tchl0ck Thank you for this.

However I'm working on a 2.0 version which has a lot of changes, so I will complete that one first...

About the CI fix: I did also encounter some issues in my development on version 2, and this is the change: https://github.com/wiremock/WireMock.Net/pull/1359/changes#diff-b803fcb7f17ed9235f1e5cb1fcd2f5d3b2838429d4368ae4c57ce4436577f03f

So maybe revert the CI changes for this PR

Hi @StefH,
I changed my approach based on your approach in the mentioned commit.

If you are working on version 2.0 and would like to finish it before merging my feature, maybe you have an easy way to release a preview package with my changes?
Then I could try to use the sharing scenarios state between instances in my environment already.

m4tchl0ck · 2026-03-11T10:54:02Z

@m4tchl0ck Thank you for this.
However I'm working on a 2.0 version which has a lot of changes, so I will complete that one first...
About the CI fix: I did also encounter some issues in my development on version 2, and this is the change: https://github.com/wiremock/WireMock.Net/pull/1359/changes#diff-b803fcb7f17ed9235f1e5cb1fcd2f5d3b2838429d4368ae4c57ce4436577f03f
So maybe revert the CI changes for this PR

Hi @StefH, I changed my approach based on your approach in the mentioned commit.

If you are working on version 2.0 and would like to finish it before merging my feature, maybe you have an easy way to release a preview package with my changes? Then I could try to use the sharing scenarios state between instances in my environment already.

Ok, I reverted my change about CI as it doesn't work

StefH · 2026-03-11T11:50:54Z

Would it also make sense to create a default implementation for file-based IScenarioStateStore ?

m4tchl0ck · 2026-03-11T12:41:27Z

Would it also make sense to create a default implementation for file-based IScenarioStateStore ?

Yes, I agree. It was not my goal... yet.
I need to check a few things, and I will propose the solution.
We could also deliver in next PR :)

StefH · 2026-03-11T13:45:27Z

Can be done in next PR sure.

StefH · 2026-03-11T16:44:22Z

@m4tchl0ck

Version 2 is merged to master, so you probably need to resolve merge conflicts.

m4tchl0ck · 2026-03-12T08:52:28Z

@StefH

Would it also make sense to create a default implementation for file-based IScenarioStateStore ?

I added FileBasedScenarioStateStore

StefH · 2026-03-14T09:40:10Z

@m4tchl0ck
Can you fix merge conflict?

m4tchl0ck · 2026-03-14T16:26:26Z

@m4tchl0ck Can you fix merge conflict?

done

src/WireMock.Net.Abstractions/Handlers/IScenarioStateStore.cs

src/WireMock.Net.Minimal/Owin/IWireMockMiddlewareOptions.cs

StefH · 2026-03-15T09:00:34Z

src/WireMock.Net.Minimal/Owin/WireMockMiddlewareOptionsHelper.cs

        options.FileSystemHandler = settings.FileSystemHandler;
        options.HandleRequestsSynchronously = settings.HandleRequestsSynchronously;
        options.Logger = settings.Logger;
+        options.Scenarios = settings.ScenarioStateStore ?? options.Scenarios;


This should be

options.ScenarioStateStore = setings.ScenarioStateStore ?

I guess the ?? is not needed. No need to take options.Scenarios ?

And also rename options.Scenarios also to options.ScenarioStateStore ?

ScenarioStateStore is nullable in WireMockServerSettings

done

Renamed to options.ScenarioStateStore. The ?? is kept because settings.ScenarioStateStore is nullable.

ScenarioState is moved to the Abstractions project so it can be referenced by the new IScenarioStateStore interface. The interface defines the contract for storing and retrieving scenario states, enabling distributed implementations.

Wraps ConcurrentDictionary with OrdinalIgnoreCase comparer, preserving exact current behavior. The Update method encapsulates read-modify-write so distributed implementations can make it atomic.

…mers Replace direct ConcurrentDictionary<string, ScenarioState> usage with IScenarioStateStore across all consumer files. The store is injectable via WireMockServerSettings.ScenarioStateStore, defaulting to the InMemoryScenarioStateStore for backward compatibility.

In-memory ConcurrentDictionary backed by JSON file persistence in __admin/scenarios/. Reads from cache, mutations write through to disk. Constructor loads existing state from disk on startup.

m4tchl0ck · 2026-03-16T11:10:26Z

Review comments addressed:

Changed Get to TryGet / TryGetValue pattern in IScenarioStateStore and both implementations
Renamed Scenarios to ScenarioStateStore in IWireMockMiddlewareOptions
Fixed WireMockMiddlewareOptionsHelper assignment to options.ScenarioStateStore = settings.ScenarioStateStore

src/WireMock.Net.Shared/Settings/WireMockServerSettings.cs

…teStore Move InMemoryScenarioStateStore from WireMock.Net.Minimal to WireMock.Net.Shared so it lives alongside WireMockServerSettings. This allows WireMockServerSettings.ScenarioStateStore to be non-nullable with a default value, following the same pattern as DefaultJsonSerializer. The null-coalescing fallback in WireMockMiddlewareOptionsHelper is no longer needed.

m4tchl0ck force-pushed the injectable-scenario-state-store branch 3 times, most recently from 31d252c to 0d0881a Compare March 10, 2026 23:19

mert-ozturk-lgs approved these changes Mar 11, 2026

View reviewed changes

StefH added the feature label Mar 11, 2026

daijmon approved these changes Mar 11, 2026

View reviewed changes

m4tchl0ck force-pushed the injectable-scenario-state-store branch from a7f78fb to b304b90 Compare March 11, 2026 10:37

m4tchl0ck force-pushed the injectable-scenario-state-store branch from b304b90 to 0d0881a Compare March 11, 2026 10:53

m4tchl0ck force-pushed the injectable-scenario-state-store branch 4 times, most recently from 180e1fb to 42f9513 Compare March 12, 2026 06:53

m4tchl0ck requested review from daijmon and mert-ozturk-lgs March 13, 2026 15:29

m4tchl0ck force-pushed the injectable-scenario-state-store branch from 42f9513 to 54dd45c Compare March 14, 2026 16:26

StefH requested changes Mar 15, 2026

View reviewed changes

m4tchl0ck added 4 commits March 16, 2026 10:57

Add InMemoryScenarioStateStore default implementation

80446e6

Wraps ConcurrentDictionary with OrdinalIgnoreCase comparer, preserving exact current behavior. The Update method encapsulates read-modify-write so distributed implementations can make it atomic.

Add FileBasedScenarioStateStore for persistent scenario state

37652f8

In-memory ConcurrentDictionary backed by JSON file persistence in __admin/scenarios/. Reads from cache, mutations write through to disk. Constructor loads existing state from disk on startup.

m4tchl0ck force-pushed the injectable-scenario-state-store branch from 54dd45c to 37652f8 Compare March 16, 2026 11:10

m4tchl0ck requested a review from StefH March 16, 2026 11:57

StefH requested changes Mar 16, 2026

View reviewed changes

m4tchl0ck requested a review from StefH March 17, 2026 07:33

m4tchl0ck commented Mar 19, 2026

View reviewed changes

src/WireMock.Net.Shared/Settings/WireMockServerSettings.cs Outdated Show resolved Hide resolved

m4tchl0ck force-pushed the injectable-scenario-state-store branch from 8a2f593 to 2e3f52c Compare March 23, 2026 21:51

StefH approved these changes Mar 24, 2026

View reviewed changes

StefH merged commit f919929 into wiremock:master Mar 25, 2026
6 checks passed

Uh oh!

Conversation

m4tchl0ck commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

FileBasedScenarioStateStore

Test plan

Uh oh!

StefH commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

m4tchl0ck commented Mar 11, 2026

Uh oh!

m4tchl0ck commented Mar 11, 2026

Uh oh!

StefH commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

m4tchl0ck commented Mar 11, 2026

Uh oh!

StefH commented Mar 11, 2026

Uh oh!

StefH commented Mar 11, 2026

Uh oh!

m4tchl0ck commented Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

StefH commented Mar 14, 2026

Uh oh!

m4tchl0ck commented Mar 14, 2026

Uh oh!

Uh oh!

Uh oh!

StefH Mar 15, 2026

Choose a reason for hiding this comment

Uh oh!

m4tchl0ck Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

StefH Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

m4tchl0ck Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

m4tchl0ck Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

m4tchl0ck commented Mar 16, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

m4tchl0ck commented Mar 10, 2026 •

edited

Loading

StefH commented Mar 11, 2026 •

edited

Loading

StefH commented Mar 11, 2026 •

edited

Loading

m4tchl0ck commented Mar 12, 2026 •

edited

Loading

m4tchl0ck Mar 16, 2026 •

edited

Loading