---
title: SAIF.Presentation.ConsoleApplication architecture
summary: Architectural responsibilities, boundaries, and interaction patterns.
status: draft
owner: <owner>
last_reviewed: 2026-07-24
library: SAIF.Presentation.ConsoleApplication
reference_type: package
---

# 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.

```mermaid
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.

```mermaid
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.

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

## 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`