---

Mastering State and Time in C#: Building a Split-Second Stopwatch from Scratch

Learn to build a high-precision C# stopwatch using state management and the TimeProvider class. This guide covers handling Ready, Running, and Stopped states, calculating lap times, and writing testable code for accurate time tracking applications, all part of the exclusive kodikra.com learning path.

You've always coded for the thrill of it—building small projects, solving puzzles. But now, you're leveling up. You're joining the ranks of professional developers where performance, accuracy, and testability aren't just nice-to-haves; they are fundamental requirements. Every millisecond of latency and every edge case in your application logic matters.

You've encountered a common challenge: accurately tracking time in a way that is robust, manageable, and, most importantly, testable. It sounds simple, but as you'll soon discover, managing time and state is a deceptively complex task. This is where you need more than just a simple timer; you need a high-precision, state-aware tool. This guide will walk you through building exactly that: a Split-Second Stopwatch in C#, a core module from the kodikra C# learning path that will become an indispensable part of your developer toolkit.

---

What is a State-Driven Stopwatch? The Core Concept

Before we write a single line of code, it's crucial to understand the foundational concept that powers our stopwatch: a Finite State Machine (FSM). In software engineering, a state machine is a model of computation that can be in exactly one of a finite number of "states" at any given time. It can change from one state to another in response to external inputs or "commands."

Our stopwatch isn't just a passive timer; it's an interactive system with distinct modes of operation. It can be waiting to start, actively running, or stopped after a session. These are its states. The user's actions—pressing 'start', 'stop', 'lap'—are the commands that trigger transitions between these states.

The three core states of our stopwatch are:

• Ready: The initial state. The stopwatch is reset and waiting for the start command. No time is being tracked.
• Running: The active state. The stopwatch is actively tracking elapsed time. From here, it can be stopped or a lap can be recorded.
• Stopped: The paused state. The stopwatch is not tracking new time, but it retains the time that was tracked before it was stopped. It can be reset or started again to resume tracking.

Visualizing these transitions is key to understanding the logic we're about to build. A command is only valid if the stopwatch is in the correct state. For example, you can't 'stop' a stopwatch that isn't 'running'. This state-driven design prevents illogical operations and makes our code predictable and robust.

The State Transition Flow

Here is a simplified flow diagram illustrating how commands move the stopwatch between its states. This is the blueprint for our application's logic.

    ● Initial State
    │
    ▼
  ┌──────────┐
  │  Ready   │
  └────┬─────┘
       │ [start]
       ▼
  ┌──────────┐
  │ Running  │ ⇄ [lap]
  └────┬─────┘
       │ [stop]
       ▼
  ┌──────────┐
  │ Stopped  │
  └────┬─────┘
       │ [reset]
       ├─────────┐
       │         │ [start]
       ▼         │
  ┌──────────┐   │
  │  Ready   │   │
  └──────────┘   │
                 ▼
            ┌──────────┐
            │ Running  │
            └──────────┘

---

Why TimeProvider is a Game-Changer for Testable C# Code

A classic challenge in software development is dealing with time. If your code directly calls DateTime.Now or DateTime.UtcNow, it creates a hidden, external dependency: the system clock. This makes unit testing incredibly difficult, if not impossible. How can you reliably test a method that calculates a 5-minute timeout if you have to wait an actual 5 minutes for the test to run? You can't.

This is where dependency injection and abstraction come into play. For years, developers created their own IClock interfaces to solve this problem. Recognizing this common pattern, .NET 8 introduced the abstract TimeProvider class as a first-class citizen in the base class library.

TimeProvider is an abstraction over the system clock. Instead of your code knowing about the "real" time, it simply asks the provided TimeProvider for the current time. In your application's production environment, you use TimeProvider.System, which returns the actual system time. But in your unit tests, you can use a special FakeTimeProvider (from the Microsoft.Extensions.Time.Testing package) that gives you complete control over time. You can instantly advance time by seconds, minutes, or days, allowing you to test time-based logic deterministically and instantaneously.

By designing our stopwatch to accept a TimeProvider in its constructor, we are adhering to the Dependency Inversion Principle and making our component highly testable from the outset. This is a hallmark of modern, professional C# development, a practice emphasized throughout the kodikra C# curriculum.

---

How to Build the Split-Second Stopwatch: A Detailed Implementation

Now, let's dive into the C# code. We'll build the class piece by piece, explaining the purpose of every field, property, and method. This structured approach will transform the abstract concepts of state and time into concrete, working code.

Step 1: Defining the State and Class Structure

First, we need to define our states using an enum. An enumeration is the perfect tool for representing a fixed set of constants, making our code more readable and less prone to errors than using magic strings or integers.

public enum StopwatchState
{
    Ready,
    Running,
    Stopped
}

Next, we define the class itself. We'll use a primary constructor (a feature from C# 12) to inject our `TimeProvider` dependency cleanly. We also initialize the private fields that will hold the stopwatch's internal state.

public class SplitSecondStopwatch(TimeProvider time)
{
    // A list to store the duration of all completed laps.
    private List<TimeSpan> _previousLaps = [];

    // The tracked time for the current lap before it was last stopped.
    private TimeSpan _currentLapTrackedTime = TimeSpan.Zero;

    // The timestamp when the current tracking session started.
    // It's nullable because it's only set when the stopwatch is Running.
    private DateTimeOffset? _currentLapTrackingTimeSince;

    // The current state of the stopwatch.
    public StopwatchState State { get; private set; } = StopwatchState.Ready;

    // We inject the TimeProvider for testability.
    private readonly TimeProvider _time = time;
}

• _previousLaps: A List<TimeSpan> that accumulates the duration of each completed lap.
• _currentLapTrackedTime: A TimeSpan that holds the duration of the current lap *before* it was last stopped. This is important for the stop/start functionality.
• _currentLapTrackingTimeSince: A nullable DateTimeOffset?. When the stopwatch is running, this holds the exact moment it started (or resumed). When not running, it's null. This is the key to calculating elapsed time on the fly.
• State: A public property to expose the current state, but with a private setter to ensure it can only be changed from within the class logic.

Step 2: Implementing Calculated Properties for Time

To provide a clean API, we use properties to expose the calculated times. These properties encapsulate the logic for calculating total time and lap times, ensuring consumers of our class don't need to understand the internal mechanics.

// Calculates the total duration of all previously completed laps.
private TimeSpan PreviousLapsTotal => _previousLaps.Aggregate(TimeSpan.Zero, (total, lap) => total + lap);

// Calculates the elapsed time for the current, active tracking session.
private TimeSpan CurrentLapTrackingTime =>
    _currentLapTrackingTimeSince is null
        ? TimeSpan.Zero
        : _time.GetUtcNow() - _currentLapTrackingTimeSince.Value;

// Public property for the current lap's total time.
public TimeSpan CurrentLapTime => _currentLapTrackedTime + CurrentLapTrackingTime;

// Public property for the total elapsed time across all laps.
public TimeSpan TotalTime => PreviousLapsTotal + CurrentLapTime;

// Public property to get a copy of the completed lap times.
public IReadOnlyList<TimeSpan> Laps => _previousLaps.AsReadOnly();

• PreviousLapsTotal: This uses LINQ's Aggregate method to efficiently sum up all the TimeSpan values in the _previousLaps list.
• CurrentLapTrackingTime: This is the dynamic part. If _currentLapTrackingTimeSince has a value, it calculates the duration from that start time to the current time (provided by our _time provider). Otherwise, it's zero.
• CurrentLapTime: The total time for the current lap is the sum of any previously tracked time (_currentLapTrackedTime) and the currently running time (CurrentLapTrackingTime).
• TotalTime: The grand total is simply the sum of all completed laps and the current lap's time.
• Laps: Exposes the list of laps as an IReadOnlyList, preventing external code from modifying our internal list.

Step 3: Implementing the Command Methods

This is where the state machine logic comes alive. Each method represents a command that can change the stopwatch's state and time values. Crucially, each method starts by checking if it's being called from a valid state.

The Start() Method

This method begins or resumes time tracking.

public void Start()
{
    if (State == StopwatchState.Running)
    {
        return; // Already running, do nothing.
    }

    _currentLapTrackingTimeSince = _time.GetUtcNow();
    State = StopwatchState.Running;
}

The logic is straightforward. If the stopwatch is already running, we simply ignore the command. Otherwise, we record the current timestamp in _currentLapTrackingTimeSince and transition the state to Running.

The Stop() Method

This method pauses the time tracking.

public void Stop()
{
    if (State != StopwatchState.Running)
    {
        throw new InvalidOperationException("Cannot stop a stopwatch that is not running.");
    }

    _currentLapTrackedTime += CurrentLapTrackingTime;
    _currentLapTrackingTimeSince = null;
    State = StopwatchState.Stopped;
}

First, it validates that the state is Running. If not, it throws an InvalidOperationException, which is the correct behavior for an illegal state transition. It then "bakes" the currently elapsed time (CurrentLapTrackingTime) into _currentLapTrackedTime, sets _currentLapTrackingTimeSince back to null to stop the clock, and changes the state to Stopped.

The Lap() Method Logic Flow

The lap command is the most complex. It needs to finalize the current lap, add it to our list, and immediately start the next lap without losing a single tick of time.

    ● Lap Command Received
    │
    ▼
    ◆ State == Running?
   ╱                  ╲
  Yes                  No
  │                     │
  ▼                     ▼
┌───────────────────┐  ┌───────────────────────────┐
│ Calculate Lap Time│  │ Throw InvalidOperationEx  │
└─────────┬─────────┘  └───────────────────────────┘
          │
          ▼
┌───────────────────┐
│ Add Lap to List   │
└─────────┬─────────┘
          │
          ▼
┌───────────────────┐
│ Reset Current Lap │
│  Tracked Time     │
└─────────┬─────────┘
          │
          ▼
┌───────────────────┐
│ Set New Lap Start │
│  Time (Now)       │
└─────────┬─────────┘
          │
          ▼
    ● Lap Recorded

And here is the code that implements this flow:

public void Lap()
{
    if (State != StopwatchState.Running)
    {
        throw new InvalidOperationException("Cannot record a lap when the stopwatch is not running.");
    }

    var now = _time.GetUtcNow();
    var currentLapTime = _currentLapTrackedTime + (now - _currentLapTrackingTimeSince!.Value);
    
    _previousLaps.Add(currentLapTime);
    
    // Reset for the next lap
    _currentLapTrackedTime = TimeSpan.Zero;
    _currentLapTrackingTimeSince = now;
}

This method performs several actions in a careful sequence: 1. It validates the state is Running. 2. It captures the current time (now) to ensure all subsequent calculations are based on the exact same moment. 3. It calculates the total duration of the lap being completed. 4. It adds this completed lap time to the _previousLaps list. 5. It immediately resets the trackers for the *next* lap. _currentLapTrackedTime is reset to zero, and the new lap's start time (_currentLapTrackingTimeSince) is set to now. This ensures seamless transition with no time lost.

The Reset() Method

This method returns the stopwatch to its initial state.

public void Reset()
{
    if (State == StopwatchState.Running)
    {
        throw new InvalidOperationException("Cannot reset a running stopwatch. Stop it first.");
    }

    _previousLaps.Clear();
    _currentLapTrackedTime = TimeSpan.Zero;
    _currentLapTrackingTimeSince = null;
    State = StopwatchState.Ready;
}

The reset command is only valid if the stopwatch is not actively running. It clears all tracked time—both previous laps and the current one—and sets the state back to Ready, making the instance look as if it were newly created.

---

Where This Pattern Shines: Real-World Applications

While a stopwatch is a simple example, the underlying principles of state machines and testable time management are ubiquitous in software engineering. Mastering this pattern from the kodikra learning module prepares you for much more complex challenges.

• E-commerce Order Processing: An order moves through states like `Pending`, `Paid`, `Shipped`, `Delivered`, `Cancelled`. Each state transition is triggered by an event (e.g., payment confirmation) and has specific rules.
• Game Development: A character in a game has states like `Idle`, `Walking`, `Running`, `Jumping`, `Attacking`. The game loop constantly checks for input to transition the character between these states.
• UI Component Lifecycles: A video player component has states like `Loading`, `Playing`, `Paused`, `Buffering`, `Ended`. User interactions (clicking play/pause) or network events (buffering) trigger state changes.
• Infrastructure Provisioning: A cloud resource (like a virtual machine) goes through states like `Provisioning`, `Running`, `Stopping`, `Stopped`, `Terminated`.

In all these scenarios, explicitly defining states and valid transitions makes the system's behavior predictable, easier to debug, and simpler to reason about.

---

Comparing Approaches: Custom Stopwatch vs. System.Diagnostics.Stopwatch

C# already has a built-in System.Diagnostics.Stopwatch class. So, when should you use that versus building a custom one like we just did? The answer depends entirely on your requirements, especially regarding testability and state complexity.

Feature	Our SplitSecondStopwatch	System.Diagnostics.Stopwatch
Primary Use Case	Application logic requiring complex state (laps, stop/resume) and unit testing.	High-performance code profiling and measuring execution time of code blocks.
Testability	Excellent. Uses TimeProvider for dependency injection, allowing full control over time in tests.	Poor. Directly tied to the system's high-frequency timer. Cannot be easily mocked or controlled.
Time Source	Abstracted via TimeProvider. Can be system clock or a fake clock.	Hardware-dependent high-resolution performance counter. Very precise but not abstract.
State Management	Explicit. Manages Ready, Running, Stopped states and complex lap logic.	Implicit. Essentially just IsRunning (true/false). No built-in concept of laps or complex states.
Complexity	More complex to implement, but provides more control and flexibility.	Very simple to use for its intended purpose (Start(), Stop(), Elapsed).

The verdict: Use System.Diagnostics.Stopwatch when you need to quickly and accurately measure how long a piece of code takes to run. Use a custom, state-driven, `TimeProvider`-backed stopwatch when time is part of your application's core business logic and needs to be rigorously tested.

---

Frequently Asked Questions (FAQ)

What's the difference between this custom stopwatch and System.Diagnostics.Stopwatch?

The primary difference is testability and purpose. Our custom stopwatch is designed for application logic; it uses the injectable TimeProvider, making it fully testable. System.Diagnostics.Stopwatch is a high-performance tool for code profiling that is tied to the system hardware timer and is not easily testable.

Why use TimeProvider instead of DateTime.UtcNow?

DateTime.UtcNow is a static property that directly calls the system clock, creating a hard dependency. This makes unit testing code that relies on time nearly impossible. TimeProvider is an abstraction that can be replaced with a "fake" time provider in tests, giving you full control to simulate the passage of time instantly and deterministically.

How could I make this stopwatch thread-safe?

The current implementation is not thread-safe. If multiple threads called Start() and Stop() concurrently, you could get race conditions. To make it thread-safe, you would need to use locking mechanisms, such as a lock statement (e.g., lock (_lockObject) { ... }) around the body of every public method that modifies the internal state.

What is a state machine and why is it useful here?

A state machine is a behavioral model that defines a set of states a system can be in and the rules for transitioning between those states. It's useful for the stopwatch because the stopwatch has distinct operational modes (Ready, Running, Stopped), and the validity of commands (start, stop, lap) depends entirely on the current mode. This pattern prevents illegal operations and makes the code's logic clear and robust.

Can I extend this stopwatch with more features, like pausing?

Absolutely. The current Stop() method effectively acts as a pause. You could rename it to Pause() and then perhaps add a Finish() method that stops and prevents any further starts until a reset. The state machine design makes it easy to add new states (e.g., Paused) and transitions as your requirements grow.

How does the Aggregate method work for calculating total lap time?

Enumerable.Aggregate is a powerful LINQ method that applies an accumulator function over a sequence. In our code, _previousLaps.Aggregate(TimeSpan.Zero, (total, lap) => total + lap) starts with an initial value of TimeSpan.Zero. It then iterates through each lap in the _previousLaps list, adding it to the running total. It's a concise way to sum up all the TimeSpan objects in the list.

What does TimeSpan.Zero represent in this context?

TimeSpan.Zero represents a duration of zero time. We use it as the initial value for time accumulations (like _currentLapTrackedTime) and as the starting seed for our Aggregate function. It's the additive identity for TimeSpan objects, meaning that adding it to another TimeSpan doesn't change the value.

---

Conclusion: Beyond Just Telling Time

You have successfully built more than just a stopwatch. You've implemented a robust, testable, and state-aware component using modern C# features and best practices. You've learned the critical importance of abstracting dependencies like the system clock with TimeProvider and how to model behavior cleanly using a finite state machine. These are not just academic exercises; they are practical skills essential for building reliable and maintainable software.

This project, a cornerstone of the kodikra.com curriculum, demonstrates how simple requirements can teach profound software engineering principles. By mastering these concepts, you are well-equipped to tackle more complex, real-world challenges with confidence.

Ready to continue your journey? Explore the full C# learning roadmap to build on these skills, or dive deeper into language specifics with our complete C# language guide.

Disclaimer: All code snippets and concepts are based on C# 12 and .NET 8. The TimeProvider class was introduced in .NET 8. For earlier versions, a custom IClock interface would be required to achieve similar testability.

---

Published by Kodikra — Your trusted Csharp learning resource.