SAIF.Framework.Common.Files operations and processes

This page is the operation catalog and cross-operation hub for this library. Each operation's detailed, step-by-step logic lives in its own page under operations/.

Operation catalog

Operation	Intent	Trigger	Inputs	Outputs	Rules
Read a typed flat file	Map delimited/fixed-width file rows to POCO records via attribute or fluent configuration.	Caller calls FileReader<TRecord>.Read(path).	File path; optional FileFormats or IFileConfiguration.	IEnumerable<TRecord>.	BR-001, BR-002, BR-003, BR-004, BR-005, BR-006, BR-007, BR-011, BR-012
Read an untyped flat file	Read a whole file into raw Record/TabDelimitedRecord rows without a typed configuration.	Caller calls FileReader.Read(path) / FileReader.ReadDelimited(path, delimiter).	File path (+ delimiter for ReadDelimited).	IEnumerable<IRecord> / IEnumerable<IDelimitedRecord>.	BR-013
Write a typed flat file	Serialise POCO records to a delimited or fixed-width file via attribute or fluent configuration.	Caller calls FileWriter<TRecord>.Write(path, data).	Path or open StreamWriter, record collection, optional format/configuration.	Written file; no return value.	BR-001, BR-008, BR-009, BR-010, BR-011, BR-014, BR-015
Configure a layout fluently	Provide a code-first alternative to attribute-based layout declaration.	Consumer subclasses FileConfiguration<T> and calls builder methods in its constructor.	Lambda property expressions.	An IFileConfiguration usable by read/write.	BR-016
Read an EDI interchange file	Parse a physical EDI file into a populated EdiFile with segments and the functional-group hierarchy.	Caller calls EdiManager.File().Path(p).Read().	File path.	Populated EdiFile.	BR-017, BR-029, BR-030
Parse EDI text into segments and elements	Lexically split raw EDI text into segments, data elements, and composite sub-elements.	Called by the EDI file read operation, or directly by a consumer.	Raw EDI string.	List<IEdiSegment>.	BR-018, BR-019, BR-020
Serialise segments and elements	Build ordered IEdiDataElement collections into an X12 segment text fragment.	ISegmentData.Build(), EdiSegment.ToString(), EDI file write.	Ordered data elements.	EDI text fragment.	BR-021, BR-022, BR-023, BR-024, BR-025, BR-026, BR-027, BR-028
Build the X12 envelope hierarchy	Convert a flat, index-ordered segment list into the interchange → functional group → transaction set → hierarchical transaction → hierarchical level tree.	SetSegments, Add of a control segment, or first access to EdiFile.FunctionalGroups.	Flat segment list.	IFunctionalGroupContainer tree.	BR-029, BR-030, BR-031, BR-032, BR-033, BR-034, BR-035, BR-036
Write an EDI interchange file	Serialise an IEdiFile's segments to a single-line EDI text file.	Caller calls EdiFileBuilder.Write(file).	IEdiFile.	Single-line EDI text file at the target path.	BR-027, BR-037
Map a segment to/from a typed segment object	Convert between an untyped IEdiSegment and a strongly-typed segment object (ISegmentData).	EdiGroupParser (for envelope segments) or application code.	An IEdiSegment (read) or populated properties (write).	A typed segment object or a built IEdiSegment.	BR-038, BR-039, BR-040, BR-041, BR-042, BR-043, BR-044, BR-045, BR-046, BR-047, BR-048, BR-049, BR-050, BR-051, BR-052, BR-053, BR-054, BR-059, BR-060, BR-061, BR-062
Generate an outbound EDI file name	Produce a timestamped, environment-tagged file name for an outbound EDI file.	Caller request prior to writing an EDI file.	fileType, isProd.	Formatted file name string.	BR-055
Convert EDI date/time strings	Convert between EDI date/time string representations and DateTime.	Fill/Build of every date-bearing segment (BHT, GS, ISA, DTM, DTP, BPR, DMG, HI, STC).	EDI date/time strings.	DateTime values (and the reverse).	BR-056, BR-057, BR-058

Process flow diagram

The following diagram visualizes the primary operational flow for the EDI subsystem, from reading a file through envelope grouping and typed segment mapping.

flowchart TD
    Start([Caller requests EDI read]) --> Read[Read an EDI interchange file]
    Read --> Parse["Parse EDI text into<br>segments and elements"]
    Parse --> Group[Build the X12 envelope hierarchy]
    Group --> Map["Map a segment to/from<br>a typed segment object"]
    Map --> Decision{Consumer modifies typed segments?}
    Decision -->|Yes| Serialise[Serialise segments and elements]
    Serialise --> Write[Write an EDI interchange file]
    Decision -->|No| EndRead(["Typed segment objects<br>returned to caller"])
    Write --> EndWrite([Single-line EDI file written])

Failure and edge-case behavior

• FileReader<TRecord>.Read/FileWriter<TRecord>.Write throw ApplicationException when no resolvable configuration exists (BR-001, BR-002, BR-003); FileWriter<TRecord>.Write(string, IEnumerable<TRecord>) throws this exception unconditionally, even after a successful write, because the throw sits outside the success-path if block.*
• FileReader<TRecord>.BuildRecord wraps any per-row mapping failure in an ApplicationException carrying the layout id and raw row data (BR-007).
• SegmentBuilder throws ApplicationException for a duplicate identifying element (BR-022) or a composite sub-element added to a non-composite parent (BR-025), and an ArgumentException for a null element list or blank segment id (BR-021, BR-023).
• EdiFile.RefreshGroupings silently leaves the functional-group tree unbuilt when ISA/IEA/GS/GE are not all present, rather than throwing (BR-030).
• DmgSegment.Build, HiSegment.Build, Sv1Segment.Build, Sv2Segment.Build, and Sv3Segment.Build always throw NotImplementedException because those segments are inbound-only (BR-054).
• SvcSegment.Parse returns an Sv1Segment instance instead of an SvcSegment — a likely copy/paste defect with no in-repo consumer available to confirm impact.*

Related documentation

• Index
• Overview
• Architecture
• Dependencies
• Business rules
• API reference

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts.

Sources

• Common\SAIF.Common.Files\Core\FileReader.cs
• Common\SAIF.Common.Files\Core\FileWriter.cs
• Common\SAIF.Common.Files\Core\Configurations\FileConfiguration.cs
• Common\SAIF.Common.Files\Edi\EdiManager.cs
• Common\SAIF.Common.Files\Edi\Core\Builders\EdiFileBuilder.cs
• Common\SAIF.Common.Files\Edi\Core\Readers\EdiFileReader.cs
• Common\SAIF.Common.Files\Edi\Core\Parsers\EdiSegmentParser.cs
• Common\SAIF.Common.Files\Edi\Core\Parsers\EdiGroupParser.cs
• Common\SAIF.Common.Files\Edi\Core\Builders\SegmentBuilder.cs
• Common\SAIF.Common.Files\Edi\Core\Builders\EdiRecordBuilder.cs
• Common\SAIF.Common.Files\Edi\Core\Writers\EdiFileWriter.cs
• Common\SAIF.Common.Files\Edi\NameBuilder.cs
• Common\SAIF.Common.Files\Edi\Core\DateMaker.cs
• Common\SAIF.Common.Files\Edi\Segments\SvcSegment.cs