---
title: SAIF.Framework.CodeTimer operations and processes
summary: Business and technical operations supported by this library.
status: draft
owner: SAIF
last_reviewed: 2026-07-30
library: SAIF.Framework.CodeTimer
reference_type: package
---

# SAIF.Framework.CodeTimer operations and processes

`SAIF.Framework.CodeTimer` exposes five operations that together let a caller start a timer, stop it, discard all collected timing state, and turn whatever was captured into an XML report or a console listing. The first four are reachable through the public `CodeTimer` façade; the fifth, console rendering, is compiled into the assembly but is only reachable by direct internal calls to `CodeTimerResult`. This page is the operation catalog and cross-operation hub for the library — each operation's step-by-step logic lives in its own page under `operations/`.

## Operation catalog
| Operation | Intent | Trigger | Inputs | Outputs | Rules | Tables | SQL |
| --- | --- | --- | --- | --- | --- | --- | --- |
| [Start a timed operation](operations/start-a-timed-operation.md) | Open a new timer or resume an existing one for an attributed method or custom name, optionally nested under a parent timer. | Caller invokes `CodeTimer.Start(MethodBase...)`. | `MethodBase`, optional custom name, optional parent key | Timer key string; new or resumed `CodeTimerEntry` state | [BR-001](business-rules.md#br-001-a-timer-must-not-be-started-while-already-running), [BR-005](business-rules.md#br-005-timing-is-only-recorded-when-both-the-global-switch-and-any-per-method-attribute-allow-it) | None | None |
| [Stop a timed operation](operations/stop-a-timed-operation.md) | Close a running timer, roll its latest span into cumulative statistics, and hand back the updated record. | Caller invokes `CodeTimer.Stop(MethodBase...)`. | `MethodBase`, optional custom name, optional parent key | Updated `CodeTimerEntry`, or `null` when the call is gated off | [BR-002](business-rules.md#br-002-a-timer-must-not-be-stopped-while-not-running), [BR-004](business-rules.md#br-004-stopping-a-timer-by-key-requires-the-key-to-already-exist), [BR-005](business-rules.md#br-005-timing-is-only-recorded-when-both-the-global-switch-and-any-per-method-attribute-allow-it) | None | None |
| [Reset the timer store](operations/reset-the-timer-store.md) | Wipe every timer entry from the in-memory store in one call, with no partial or selective clearing. | Caller invokes `CodeTimer.Reset()`. | None | Emptied static timer dictionary | None | None | None |
| [Generate timer results XML](operations/generate-timer-results-xml.md) | Turn the flat set of captured timer entries into a hierarchical `<Timer>` XML report. | Caller invokes `CodeTimer.Results()` or `CodeTimer.Results(bool includeTimeSpans)`. | Optional `includeTimeSpans` flag | `XDocument` rooted at `<Timer>`, or `null` when no timing data exists | [BR-003](business-rules.md#br-003-results-cannot-be-requested-while-any-timer-is-still-active), [BR-006](business-rules.md#br-006-result-xml-omits-statistically-insignificant-attributes) | None | None |
| [Render timer results to the console](operations/render-timer-results-to-the-console.md) | Write a tab-indented text listing of an already-built timer item tree. | Internal code calls `CodeTimerResult.OutputConsole()`. | Existing `CodeTimerItem` tree | Console text output | None | None | None |

## Process flow diagram
The following diagram visualizes how a caller typically moves through these operations: start a timer, stop it, and then either produce a report or clear the store.

```mermaid
flowchart TD
	Start([Caller requests timing]) --> StartOp[Start a timed operation]
	StartOp --> Running([Timer entry running])
	Running --> StopOp[Stop a timed operation]
	StopOp --> Next{Next action}
	Next -->|Generate report| ResultsOp[Generate timer results XML]
	Next -->|Discard state| ResetOp[Reset the timer store]
	ResultsOp --> XmlOut([XML report returned])
	ResetOp --> Cleared([Timer store cleared])
```

## Failure and edge-case behavior
- The method-based start/stop overloads are silent no-ops for any method that lacks a `CodeTimerAttribute`, or whose attribute has `Enabled` set to `false` — no timer entry is created, updated, or reported as missing.
- Calling start on a timer key that is already running throws [BR-001](business-rules.md#br-001-a-timer-must-not-be-started-while-already-running) instead of silently extending the existing run.
- Calling stop on a key that was never started throws [BR-004](business-rules.md#br-004-stopping-a-timer-by-key-requires-the-key-to-already-exist); calling stop on a key that exists but is not currently running throws [BR-002](business-rules.md#br-002-a-timer-must-not-be-stopped-while-not-running).
- Requesting results while any timer in the store is still running throws [BR-003](business-rules.md#br-003-results-cannot-be-requested-while-any-timer-is-still-active) — a report can only be produced once every started timer has been stopped.
- Setting `includeTimeSpans` to `true` does not guarantee `<span>` output: a timer with only one recorded span, or a span whose computed duration rounds to zero milliseconds, is still filtered out under [BR-006](business-rules.md#br-006-result-xml-omits-statistically-insignificant-attributes).
- Hierarchical grouping nodes that exist only to organize child timers under a common key are skipped during XML recursion unless that grouping node also carries a positive `Elapsed` value of its own.

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Business rules](business-rules.md)
- [Configuration](configuration.md)
- [API reference](api/index.md)

## Sources
- SAIF.Framework.CodeTimer\SAIF.Framework.CodeTimer\CodeTimer.cs
- SAIF.Framework.CodeTimer\SAIF.Framework.CodeTimer\CodeTimerAttribute.cs
- SAIF.Framework.CodeTimer\SAIF.Framework.CodeTimer\CodeTimerEntry.cs
- SAIF.Framework.CodeTimer\SAIF.Framework.CodeTimer\CodeTimerItem.cs
- SAIF.Framework.CodeTimer\SAIF.Framework.CodeTimer\CodeTimerResult.cs
- SAIF.Framework.CodeTimer\SAIF.Framework.CodeTimer\CustomTimeSpan.cs