Skip to content

SAIF.Framework.Version architecture

SAIF.Framework.Version is a small, self-contained value-object utility library that implements a custom four-part (Major.Minor.Build.Revision) version-number representation with parsing, formatting, comparison, and template-based incrementing. It is architecturally isolated from the rest of the SAIF Framework, with no dependencies on data access, security, UI, or other SAIF Framework projects.

Responsibilities

  • Represent a four-segment version number (Major.Minor.Build.Revision) as a value object via the public Version class, which implements IComparable.
  • Parse a version string into its constituent segments, defaulting missing trailing segments to "0".
  • Format a Version instance back to its canonical "{Major}.{Minor}.{Build}.{Revision}" string form via ToString().
  • Compare two Version instances numerically (rather than as strings) via CompareTo and the overloaded =, <>, <, > operators.
  • Produce an incremented version from a template format string via Increment(format), supporting a * auto-increment token, empty-token "retain current value" semantics, and {year}/{month}/{day} date-template substitution.
  • Provide a supporting ToInt string extension method (in the Extensions module) that coerces a version segment's leading digit run to an integer, treating non-numeric or conversion-failing input as 0.

Component boundaries

  • SAIF.Framework.Version.Version (class): The sole domain type. Owns all parsing, formatting, comparison, and increment logic. Implements IComparable. Parallels but does not use or extend System.Version.
  • SAIF.Framework.Version.Extensions (module): A single-purpose extension-method module providing ToInt(value As String) As Integer for the String type, used internally by Version to normalize segment values for comparison.
  • No other components, layers, or sub-namespaces exist in this library — it is a flat, two-type module/class pair with no internal layering.

Interaction model

  • Callers construct a Version either from a delimited string (New Version(input), which internally calls Parse) or from individual major/minor/build/revision parts, or by copying another Version instance.
  • Callers read or compare Version instances using the =, <>, <, > operators or CompareTo, which all compare the four segments in Major → Minor → Build → Revision precedence using ToInt-normalized values.
  • Callers request a new incremented version via Increment(format), supplying a format string whose per-segment tokens can be a literal value, * (auto-increment relative to the prior value), an empty token (retain prior value), or date placeholders ({year}, {month}, {day}). Increment mutates the instance in place (via an internal Update) and returns Me.
  • There are no calls into other SAIF Framework libraries, no I/O, no configuration reads, and no cross-layer dependencies of any kind.

Architecture diagram

The following diagram shows the two-type component structure and the caller interaction surface.

flowchart TD
    Caller[Caller code] --> V[Version class<br>IComparable]
    V --> E[Extensions module<br>ToInt]
    V --> Parse[Parse]
    V --> ToString[ToString]
    V --> Compare[CompareTo / operators]
    V --> Increment[Increment]

The following diagram shows the primary parse-compare-increment sequence.

sequenceDiagram
    participant Caller
    participant Version
    participant Extensions
    Caller->>Version: New Version(input) / Parse(input)
    Version->>Version: Split on "." , default missing segments to "0"
    Caller->>Version: CompareTo / = / <> / < / >
    Version->>Extensions: ToInt(segment)
    Extensions-->>Version: normalized integer
    Version-->>Caller: comparison result
    Caller->>Version: Increment(format)
    Version->>Version: Resolve *, empty, literal, and date tokens, then update in place
    Version-->>Caller: Me (updated instance)

Design constraints

  • The library targets .NET Framework 3.5 and declares no ProjectReference or PackageReference dependencies, reinforcing its role as a leaf utility with zero required consumers within the build graph.
  • No other project in the repository references SAIF.Framework.Version.vbproj; its only inclusion mechanism is the SAIF.Framework.Core nuspec's source-glob, which copies raw .vb files into a NuGet package's src folder rather than compiling the project itself.*
  • The ToInt extension swallows conversion errors via an empty Catch block, coercing any non-numeric or unparsable segment to 0 rather than raising an exception — comparisons and increments will silently treat malformed version segments as 0.
  • Possible copy-paste defect (see BR-007): in the < and > operator overloads, the "majors are equal" branch condition compares v2.Major.ToInt = v2.Major.ToInt (both operands reference v2) instead of the presumably intended v1.Major.ToInt = v2.Major.ToInt. Because Major is evaluated first and correctly gates entry into this branch, the tautological condition does not currently produce incorrect comparison results, but the condition itself does not verify what its structure implies and should be corrected for clarity and correctness.*

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.Version\Version.vb
  • SAIF.Framework.Version\SAIF.Framework.Version.vbproj
  • SAIF.Framework.Core\SAIF.BOF.Framework.Core.nuspec