---
title: SAIF.Framework.Common overview
summary: High-level purpose, scope, and responsibilities for this library.
status: draft
owner: saif-docgen
last_reviewed: 2026-09-15
library: SAIF.Framework.Common
reference_type: package
---

# SAIF.Framework.Common overview

> **Documentation context:** Package library
> **Documented via:** `.nuspec`-referenced package (`Common/SAIF.Common/SAIF.Framework.Common.nuspec`)

`SAIF.Framework.Common` is a foundation, zero-dependency .NET Framework 4.6.2 utility library that supplies cross-cutting primitives — date/date-range semantics, string normalization and casing, validation result modelling, argument guards, sequence generation, serialization helpers, exception formatting, and logging contracts — for consumption by application and component layers above it in the SAIF stack (Stage 1 analysis, "Responsibility boundary").

## Purpose
- Supplies fail-fast argument guards, date/date-range reasoning, text normalization, validation-result modelling, in-memory sequence generation, JSON/XML serialization helpers, exception formatting, and console/file logging contracts — all as static/extension methods with no persisted state beyond a sequence generator's current value or a validation result's collections (Stage 1 analysis, "Functional groupings").
- Consumed by SAIF MVC/web applications, console batch applications, and other component libraries that reference it as a foundation layer; it has zero outbound dependencies of its own, making it safely referenceable from any layer above it (Stage 1 analysis, "Responsibility boundary", "Design constraints").

## Responsibilities
- Fail-fast argument and precondition guarding (`Enforce`, `GenericExtensions.IsNull`/`IfNullThrow`).
- Date and date-range modelling: validity, overlap, contiguity, EDI/Julian encoding (`DateRange`, `NullableDateRange`, `DateRangeExtensions`, `DateMaker`, `Julian`).
- Text normalization: casing, truncation, character-class filtering, Unicode-to-ASCII folding, truthy-string parsing (`StringExtensions`, `StringUtilities`, `BooleanExtensions`).
- Validation-result modelling and exception surfacing (`ValidationResult`, `ValidationFailure`, `SaifValidationException`).
- Contextual (view-routing) exception carrying for a consuming presentation layer (`ContextException` and its subclasses).
- In-memory monotonic sequence generation (`Sequence`, `LongSequence`).
- JSON/XML serialization, stream-to-byte-array conversion, MD5 hashing, and binary header search (`Serializer`, `FileExtensions`, `ByteExtensions`).
- Console/file logging contract definitions and exception-chain formatting for logs (`IConsoleLogService`, `ILogWriter`, `ExceptionExtensions`).
- Reflection-based property discovery and assignment (`Reflector`, `ExpressionExtensions`).
- LINQ/collection gap-filling and dictionary merge/upsert (`IEnumerableExtensions`, `DictionaryExtensions`).

## Key components
- `Enforce`: Central fail-fast argument/precondition guard used throughout the library.
- `DateRange` / `DateRangeExtensions`: Core date-interval type and its overlap/contiguity/membership algorithms.
- `StringExtensions` / `StringUtilities`: The library's text-normalization surface.
- `ValidationResult` / `SaifValidationException`: Validation-outcome modelling and exception surfacing.
- `Serializer`: JSON/XML round-tripping helpers.
- `IConsoleLogService` / `ILogWriter`: Logging contracts implemented by consumers, not this library.

## Related documentation
- [Index](index.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [API reference](api/index.md)

## Sources
- `Common/SAIF.Common/SAIF.Framework.Common.csproj`
- `Common/SAIF.Common/SAIF.Framework.Common.nuspec`
- `SAIF.Framework.Common.sln`
- `Common/SAIF.Common/Classes/Enforce.cs`
- `Common/SAIF.Common/Classes/DateRange.cs`
- `Common/SAIF.Common/Classes/NullableDateRange.cs`
- `Common/SAIF.Common/Extensions/DateRangeExtensions.cs`
- `Common/SAIF.Common/Classes/DateMaker.cs`
- `Common/SAIF.Common/Classes/Julian.cs`
- `Common/SAIF.Common/Extensions/StringExtensions.cs`
- `Common/SAIF.Common/Utility/StringUtilities.cs`
- `Common/SAIF.Common/Extensions/BooleanExtensions.cs`
- `Common/SAIF.Common/Classes/ValidationResult.cs`
- `Common/SAIF.Common/Classes/ValidationFailure.cs`
- `Common/SAIF.Common/Classes/SaifValidationException.cs`
- `Common/SAIF.Common/Classes/ContextException.cs`
- `Common/SAIF.Common/Classes/Sequence.cs`
- `Common/SAIF.Common/Classes/LongSequence.cs`
- `Common/SAIF.Common/Classes/Serializer.cs`
- `Common/SAIF.Common/Extensions/FileExtensions.cs`
- `Common/SAIF.Common/Extensions/ByteExtensions.cs`
- `Common/SAIF.Common/Interfaces/IConsoleLogService.cs`
- `Common/SAIF.Common/Interfaces/ILogWriter.cs`
- `Common/SAIF.Common/Extensions/ExceptionExtensions.cs`
- `Common/SAIF.Common/Classes/Reflector.cs`
- `Common/SAIF.Common/Extensions/ExpressionExtensions.cs`
- `Common/SAIF.Common/Extensions/IEnumerableExtensions.cs`
- `Common/SAIF.Common/Extensions/DictionaryExtensions.cs`