Skip to content

SAIF.Presentation.ConsoleApplication architecture

SAIF.Presentation.ConsoleApplication is a presentation-tier base-class library (OutputType=Library, no entry point) that defines clsConsoleBase and clsBatchBase, the abstract ancestor classes consumed by actual SAIF console/batch applications elsewhere. Despite its folder location and name, it is not itself a BOF console batch application: its pipeline uses the NuGet packaging template rather than the console-app template, and it contains no concrete subclass or Sub Main entry point.

Responsibilities

  • Provide the template-method lifecycle (Execute() → Initialize() → ValidateCommandLine() → RunAppLogic() → Uninitialize()) that concrete console/batch applications implement by subclassing clsConsoleBase or clsBatchBase.
  • Parse and normalize command-line arguments (/Name:Value or -Name:Value style, case-insensitive) via GetParamName, GetParamValue, ParamExists.
  • Format exception diagnostics recursively, including special handling for the framework's clsSAIFException type, via GetExceptionInfo.
  • Add multi-stream, environment-variable-driven file logging and batch header/footer status reporting on top of the console base lifecycle (clsBatchBase).

Component boundaries

  • clsConsoleBase (MustInherit): root ancestor for all SAIF console applications. Owns the Execute() template method, ReturnCodes enum (Success, BadParameter, DatabaseError, DataError, FileIOError, UnknownError, NoDataFound), command-line parsing helpers, exception-formatting (GetExceptionInfo), and a concrete EnvironmentService As WindowsEnvironmentService field (instantiated directly, not injected)*.
  • clsBatchBase (MustInherit, Inherits clsConsoleBase): adds the BatchStreams enum (StandardFile, File0-File4), multi-stream log-file registration keyed by FILE?-pattern environment variables, and batch header/footer console reporting. Overrides Initialize()/Uninitialize() to layer this behavior around the base lifecycle.
  • Logging is delegated throughout both classes to SAIF.Framework.Logging.clsLogTrace.MethodMessage/MethodBegin/MethodEnd — a framework-inherited facility, not implemented locally.
  • No web, UI-control, or data-access responsibilities are implemented directly; this library is purely lifecycle/plumbing code for command-line applications.
  • Both base classes are MustInherit (abstract) with no concrete subclass present in this library — actual console/batch applications that inherit them live in separate repositories/deployables.

Interaction model

  • A downstream console/batch application's entry point (Sub Main, not present in this library) instantiates a subclass of clsConsoleBase or clsBatchBase and calls Execute().
  • Execute() orchestrates: Initialize() (parses Environment.GetCommandLineArgs, normalizes leading //- and casing; for clsBatchBase, also pre-registers log streams from FILE? environment variables and writes a batch header) → checks a /DEBUG flag → calls the abstract ValidateCommandLine() → if valid, calls the abstract RunAppLogic(); if invalid, prompts "Press enter to continue..." and waits for input → always calls Uninitialize() (for clsBatchBase, writes a batch footer and flushes/closes open log streams before calling the base Uninitialize()).
  • Consuming subclasses write output via WriteStatusMsg (console), WriteErrorMsg (Console.Error), and WriteAppLogMsg (console or a named log stream resolved from an environment variable, or a default {AppName}.log file for StandardFile).
  • Exception diagnostics are retrieved on demand via GetExceptionInfo(ex), which recursively unwinds InnerException chains.

The following diagram shows the base-class inheritance and lifecycle relationship that downstream console/batch applications build on.

flowchart TD
    App["Downstream console/batch application<br>(Sub Main, not in this library)"] --> Batch["clsBatchBase<br>(multi-stream logging, batch header/footer)"]
    Batch --> Console["clsConsoleBase<br>(Execute lifecycle, arg parsing, exception formatting)"]
    Console --> EnvSvc["WindowsEnvironmentService<br>(Saif.Framework.Security)"]
    Console --> LogTrace["clsLogTrace<br>(SAIF.Framework.Logging)"]
    Batch --> LogFiles["Environment-variable-resolved<br>log file streams (FILE0-FILE4)"]

The following diagram shows the Execute() template-method sequence a downstream application follows.

sequenceDiagram
    participant Main as Subclass Sub Main
    participant Base as clsConsoleBase/clsBatchBase
    participant App as Subclass RunAppLogic
    Main->>Base: Execute()
    Base->>Base: Initialize()
    Base->>Base: ValidateCommandLine()
    alt validation succeeds
        Base->>App: RunAppLogic()
        App-->>Base: return
    else validation fails
        Base->>Base: Console.WriteLine("Press enter to continue...")
    end
    Base->>Base: Uninitialize()
    Base-->>Main: return (Environment.ExitCode set via ReturnCode)

Design constraints

  • No <ProjectReference> elements; clsBatchBase's dependency on clsConsoleBase is source-level inheritance within the same assembly, not a cross-project reference.
  • EnvironmentService is typed as the concrete WindowsEnvironmentService class and instantiated directly (New WindowsEnvironmentService()), not injected through an IEnvironmentService abstraction — a concrete dependency, not an abstraction seam*.
  • Batch log-stream configuration is sourced from process environment variables (Environment.GetEnvironmentVariable), not ConfigurationManager.AppSettings or <appSettings> keys.
  • No IEnvironmentService, ConfigurationManager.AppSettings, DbConnectionManager, or AD/security enforcement points were found — this library does not qualify for Phase 1c (security) or Phase 1d (config) documentation gates, though the concrete WindowsEnvironmentService instantiation is flagged for awareness.*
  • No IBusinessCriteria implementations or application-layer SQL usage exist; Oracle.ManagedDataAccess is referenced and ODP.NET is registered in app.config, but no direct database-client code appears in the scanned source — likely inherited project scaffolding rather than active database access*. The ReturnCodes.DatabaseError enum value indicates consuming applications are expected to signal database errors via this exit code, though no such logic exists in this library itself.
  • Classified as documentation type Component, not Console App: the pipeline (Pipelines\build.yml) references the NuGet packaging template (Steps/build-steps-nuget.yml@templates), not the console-app template, and no concrete class inheriting clsBatchBase exists in this library.

Note: Statements marked with * are inferred from code behavior rather than explicit documentation or comments.

Sources

  • Presentation\SAIF.Presentation.ConsoleApplication\clsConsoleBase.vb
  • Presentation\SAIF.Presentation.ConsoleApplication\clsBatchBase.vb
  • Presentation\SAIF.Presentation.ConsoleApplication\SAIF.BOF.Presentation.ConsoleApplication.vbproj
  • Presentation\SAIF.Presentation.ConsoleApplication\app.config
  • Presentation\SAIF.Presentation.ConsoleApplication\Pipelines\build.yml