---
title: Write to the console/application log (contract only)
summary: Define (without implementing) a console/file logging contract.
status: draft
owner: saif-docgen
last_reviewed: 2026-09-15
library: SAIF.Framework.Common
reference_type: package
operation_id: OP-038
trigger: A consuming console/batch application writes progress, errors, or exception detail to one or more log files*
---

# Write to the console/application log (contract only)

Define (without implementing) a console/file logging contract, triggered when a consuming console/batch application writes progress, errors, or exception detail to one or more log files*.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-038 |
| **Trigger** | A consuming console/batch application writes progress, errors, or exception detail to one or more log files* |
| **Inputs** | `message`, `logId` or `LogType`, `filePath`, `Exception` |
| **Outputs** | Log output (implementation-defined) |
| **Primary components** | ``SAIF.Common.Interfaces.IConsoleLogService` and `SAIF.Common.Interfaces.ILogWriter`` |
| **Entry point** | `Common/SAIF.Common/Interfaces/IConsoleLogService.cs` |

## Steps

1. The application registers a log file against a string `logId` using `RegisterLogFile(logId, filePath)`. ([BR-091](../business-rules.md#br-091-a-log-file-must-be-registered-against-a-log-id-before-it-can-be-written-to%2C-and-log-writers-are-retrieved-by-that-id))
2. It retrieves an `ILogWriter` by string id (`GetLog(string)`) or by the `LogType` enum (`GetLog(LogType)` — `File0`-`File4` or `Custom`), or enumerates them all via `Logs`. ([BR-091](../business-rules.md#br-091-a-log-file-must-be-registered-against-a-log-id-before-it-can-be-written-to%2C-and-log-writers-are-retrieved-by-that-id), [BR-092](<../business-rules.md#br-092-a-console-application-may-address-at-most-five-conventional-log-files-(file0-file4)-plus-a-custom-category>))
3. It writes through `Write`/`WriteError` (service level) or `Write`/`WriteLine`/`WriteTimedLine` (writer level). `WriteToAppLog(message, logId, bool line = true)` defaults to appending a line break, while `WriteToAppLog(message, LogType, bool line = false)` defaults to not appending one. ([BR-093](../business-rules.md#br-093-writetoapplog-appends-a-line-break-by-default-when-addressed-by-string-log-id%2C-but-not-by-default-when-addressed-by-logtype))
4. Timestamp rendering on `WriteTimedLine` is configured per writer through `SetTimeFormat`, `SetTimeDelimiter`, and `SetWriteLinePrefix`. ([BR-091](../business-rules.md#br-091-a-log-file-must-be-registered-against-a-log-id-before-it-can-be-written-to%2C-and-log-writers-are-retrieved-by-that-id))
5. `LogException(Exception)` records an exception; buffered output is pushed with `Flush()`, `Flush(logId)`, or `Flush(LogType)`. ([BR-091](../business-rules.md#br-091-a-log-file-must-be-registered-against-a-log-id-before-it-can-be-written-to%2C-and-log-writers-are-retrieved-by-that-id))
6. Both interfaces extend `IDisposable`, so the application is expected to dispose the service (and thereby its writers) at shutdown. ([BR-094](../business-rules.md#br-094-log-services-and-log-writers-are-disposable-resources-and-must-be-released-by-the-consuming-application))

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start(["Consuming app writes progress,<br>errors, or exception detail"]) --> S1["Register a log file against<br>logId via RegisterLogFile"]
	S1 --> S2["Retrieve an ILogWriter by string id,<br>by the LogType enum, or<br>enumerate all via Logs"]
	S2 --> S3["Write via Write/WriteError,<br>or WriteToAppLog (line-break<br>default varies by overload)"]
	S3 --> S4["Configure timestamp rendering per<br>writer via SetTimeFormat,<br>SetTimeDelimiter, SetWriteLinePrefix"]
	S4 --> S5["LogException records an exception;<br>Flush pushes buffered output"]
	S5 --> S6["Application disposes the service<br>and its writers at shutdown"]
	S6 --> End(["Log output written and<br>resources released"])
```

## Failure and edge-case behavior

- These are contracts only — this library provides no implementation of `IConsoleLogService` or `ILogWriter`. The step sequence above describes the contract's intended usage, inferred from the member signatures; the actual behavior is defined by whichever consuming assembly implements them.*

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)

> **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/Interfaces/IConsoleLogService.cs`
- `Common/SAIF.Common/Interfaces/ILogWriter.cs`
- `Common/SAIF.Common/Enums/LogType.cs`