---
title: CodeTimer
summary: API reference for CodeTimer.
status: draft
owner: <owner>
last_reviewed: 2026-07-23
library: SAIF.Framework.CodeTimer
reference_type: package
---

# CodeTimer

`CodeTimer` is the static façade and sole public entry point of the library. It starts and stops named or method-scoped timers keyed by a hierarchical string, aggregates elapsed time in a process-wide static dictionary, and produces an XML summary of captured results.

## Purpose
- Provide start/stop/reset operations for hierarchical, named or method-scoped timers.
- Gate timing collection through a global `Enabled` switch and (for method-based overloads) a per-method [CodeTimerAttribute](CodeTimerAttribute.md).
- Produce an `XDocument` summary of all captured timer data via `Results()`/`Results(bool)`.

## Context
- Namespace: `SAIF.Framework.CodeTimer`
- Assembly/package: `SAIF.Framework.CodeTimer.dll` (also packaged as source into the `SAIF.BOF.Framework` NuGet package via nuspec file glob)

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| Enabled | `public static bool Enabled` | Global on/off switch for all timing; checked in the private key-based `Start(string)` overload. |
| GetCodeTimerParent | `public static string GetCodeTimerParent(string method, string parentTimerKey)` | Builds a `;`-delimited hierarchical key from a parent key and method/timer name. |
| Start | `public static string Start(MethodBase method)` | Starts timing for a method, honoring `CodeTimerAttribute.Enabled` if present. Returns the resolved key. |
| Start | `public static string Start(MethodBase method, string parentTimerKey)` | Starts timing for a method nested under the given parent key. |
| Start | `public static string Start(MethodBase method, string customName, string parentTimerKey)` | Starts timing for a method using a custom name suffix and parent key. |
| Stop | `public static CodeTimerEntry Stop(MethodBase method)` | Stops timing for a method and returns the updated [CodeTimerEntry](CodeTimerEntry.md). |
| Stop | `public static CodeTimerEntry Stop(MethodBase method, string parentTimerKey)` | Stops timing for a method nested under the given parent key. |
| Stop | `public static CodeTimerEntry Stop(MethodBase method, string customName, string parentTimerKey)` | Stops timing for a method using a custom name suffix and parent key. |
| Reset | `public static void Reset()` | Clears all captured timer data. |
| Results | `public static XDocument Results()` | Returns an `XDocument` summarizing all captured timers (equivalent to `Results(false)`), or `null` if no data was collected. |
| Results | `public static XDocument Results(bool includeTimeSpans)` | Returns an `XDocument` summarizing all captured timers, optionally including per-span millisecond detail, or `null` if no data was collected. |

## Behavioral notes
- All timer state is held in a `private static Dictionary<string, CodeTimerEntry> data` field — process-wide/AppDomain-wide global mutable state with no locking, so concurrent calls from multiple threads could race*.
- The `Start`/`Stop` overloads that accept a `MethodBase` check for a `CodeTimerAttribute` on the method via reflection; if present and its `Enabled` flag is `false`, the call is skipped and no timer is created/stopped for that call.
- `Start`/`Stop` overloads without a `MethodBase`-based attribute check still respect the global `Enabled` switch through the private key-based overloads.
- Calling `Stop` for a key that has never been started throws `ApplicationException` (see [BR-004](../../business-rules.md#br-004-stopping-a-timer-by-key-requires-the-key-to-already-exist)).
- `Results()`/`Results(bool)` delegate to the internal `CodeTimerResult` type, which throws `ApplicationException` if any timer is still running when results are requested (see [BR-003](../../business-rules.md#br-003-results-cannot-be-requested-while-any-timer-is-still-active)).
- A call to the WinForms results viewer (`(new CodeTimerResults(data)).ShowDialog();`) is present in `Results(bool)` but commented out, so it has no effect on current behavior.

## Constraints and usage notes
- `CodeTimer` is a static class; it cannot be instantiated and all state is shared across the entire process/AppDomain.
- Because there is no synchronization around the internal `data` dictionary, this type should not be used for concurrent multi-threaded timing without external coordination*.
- Setting `Enabled = false` disables timing globally regardless of any `CodeTimerAttribute` settings on individual methods.

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with ** could not be confirmed; treat as unknown until verified.

## Sources
- SAIF.Framework.CodeTimer\SAIF.Framework.CodeTimer\CodeTimer.cs