Myoddweb.DirectoryWatcher 0.2.0: six years on, still watching

It has been six years since the last release of Myoddweb.DirectoryWatcher, my high-performance, asynchronous file and directory watcher for .NET and C++. Version 0.1.9 went out in August 2020, and then, as these things go, life happened. The library kept quietly doing its job in a couple of my own projects, but it didn’t get the attention it deserved.

This week I finally sat down and gave it the update it was owed. Version 0.2.0 is out now, both on GitHub and on NuGet.

Why this library exists

If you’ve ever used .NET’s built-in FileSystemWatcher, you’ll know it’s… fine, until it isn’t. It has a fixed internal buffer that silently overflows under heavy load, it happily throws exceptions that can bring your whole app down, and it really doesn’t enjoy being pointed at a large volume or a UNC path.

Myoddweb.DirectoryWatcher was built to fix exactly that:

• Non-blocking, asynchronous events — a slow consumer never stalls the watcher.
• No buffer overflow crashes, even under bursts of file activity.
• Duplicate suppression, so three rapid writes to the same file become one clean notification instead of three.
• Volume-wide monitoring of creates, deletes, touches and renames, across multiple paths at once.
• Built-in statistics and logging, so you can see throughput and event rates without instrumenting it yourself.

Under the hood it’s a native C++ core built on Win32’s ReadDirectoryChangesW, wrapped in a clean, platform-agnostic managed interface. That split is what let this update focus so heavily on the native side without touching the public API.

What’s new in 0.2.0

This release is best described as “getting the house back in order” — it’s mostly stability, correctness and modernisation, not new features. But there’s a lot of it. A few highlights from the full changelog:

Toolchain caught up to 2026:

• Solution and projects now build with Visual Studio 2022 (toolset v143).
• The managed libraries target .NET Framework 4.6.2, .NET Standard 2.0 and .NET 8.0 — the old .NET Framework 4.5.2 and .NET Core 3.0 targets, both long out of support, are gone.
• Tests moved to NUnit 4.6.1 and Google Test 1.18.0.
• A GitHub Actions workflow replaces the now-retired Travis CI build.

A genuine bug fix, not just busywork:

• Issue #20 — files could be silently missed when a whole populated folder was copy-pasted into a watched tree. That’s now fixed and covered by a new test.

A pile of native-code hardening:

• An intermittent WorkerPool deadlock that could hang indefinitely.
• A race condition in MonitorsManager::ready() for recursive monitors, where child monitors could report readiness before they’d actually started.
• A use-after-free and a null-pointer dereference in the Windows-specific win::Data handling.
• win::Data::process_error() no longer leaves a watched directory’s read loop silently stalled after a Win32 error.
• A data race between a monitor’s in-flight update and its own cleanup task.
• Several smaller ones: a leaking allocation in win::Data::clone(), a reserve() that should have been resize() in the logger, a null Monitor* dereference in MonitorsManager::start().

None of that changes how you use the library day to day, but it means the thing underneath is considerably more solid than it was in 2020 — particularly around startup/shutdown races and Windows error handling, which is exactly the kind of thing that only turns up under real-world load.

Using it

The public API hasn’t changed, so if you used an earlier version, this is a drop-in upgrade. If you’re new to it, here’s the gist.

Install it:

dotnet add package MyOddWeb.DirectoryWatcher

Watch a few paths and react when files show up:

using (var watch = new Watcher())
{
  watch.Add(new Request("c:\\", true));
  watch.Add(new Request("d:\\foo\\bar\\", true));

  watch.OnAddedAsync += async (f, t) =>
  {
    Console.WriteLine($"Added: {f.FullName}");
  };

  watch.Start();
}

Renames give you both the old and new name:

watch.OnRenamedAsync += async (f, t) =>
{
  Console.WriteLine($"{f.PreviousFullName} -> {f.FullName}");
};

And if you want to keep an eye on throughput, statistics are one line away:

watch.Add(new Request("c:\\", true, new Rates(50, 10000)));

watch.OnStatisticsAsync += async (s, t) =>
{
  Console.WriteLine($"{s.NumberOfEvents} events in the last {s.ElapsedTime}ms");
};

There’s a lot more in the README — logging levels, checking whether all your watch requests are actually ready, disposing cleanly, and so on.

What’s next

This is still Windows-only for now — the public interfaces are deliberately platform-agnostic, so a Linux or macOS backend is possible in principle, but it’s not on the immediate roadmap. For the moment, the goal was simply to bring the project back up to date and squash the bugs that had been sitting there since 2020.

If you use it and hit something, issues and PRs are very welcome — I’d rather it not take another six years for the next release.

Grab it from NuGet or GitHub.