---
title: SAIF.Framework.Logging operations and processes
summary: Business and technical operations supported by this library.
status: draft
owner: SAIF Documentation
last_reviewed: 2026-07-30
library: SAIF.Framework.Logging
reference_type: package
---

# SAIF.Framework.Logging 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/`.

SAIF.Framework.Logging exposes seven operations. Three are the library's primary logging entry points — audit, error, and (obsolete) trace — and share a common two-sink design: write to a local CSV file when one has been opened, otherwise call the remote `wsLogging` SOAP service. The remaining four are supporting or legacy utilities: opening the file sink, recording login events, and resolving an MSMQ queue path string.

## Operation catalog
| Operation | Intent | Trigger | Inputs | Outputs | Rules | Tables | SQL |
| --- | --- | --- | --- | --- | --- | --- | --- |
| [Dispatch audit message](operations/dispatch-audit-message.md) | Capture ambient context and write an audit record through whichever sink is currently active. | Caller invokes `clsLogAudit.AuditMessage(...)` or `AuditCustomMessage(...)`. | Message text, optional state objects, and (for the custom overload) `performedTo`, optional `performedBy`, `performedAt`, and `overrideApplicationName`. | CSV append, or a `wsLogging.WriteAudit(...)` call; no return value. | [BR-001](business-rules.md#br-001-audit-logging-is-opt-in-and-disabled-by-default), [BR-005](business-rules.md#br-005-logging-failures-must-never-raise-exceptions-to-the-caller) | — | — |
| [Log exception](operations/log-exception.md) | Capture exception details, filter out ViewState noise, and write the surviving error through the active sink. | Caller invokes `clsLogError.CreateError(...)`. | `Exception`, optional state objects. | `Boolean`, plus a CSV append or `wsLogging.WriteError(...)` call when the error is not suppressed. | [BR-004](business-rules.md#br-004-aspnet-viewstate-errors-are-never-logged), [BR-005](business-rules.md#br-005-logging-failures-must-never-raise-exceptions-to-the-caller) | — | — |
| [Log exception and send notification email](operations/log-exception-and-send-notification-email.md) | Persist an exception and additionally send an HTML notification email about it. | Caller invokes `clsLogError.CreateErrorWithEmail(...)`. | Recipient address, `Exception`, optional state objects. | `Boolean`, plus an error-log side effect and an outbound email attempt. | [BR-004](business-rules.md#br-004-aspnet-viewstate-errors-are-never-logged), [BR-005](business-rules.md#br-005-logging-failures-must-never-raise-exceptions-to-the-caller), [BR-006](business-rules.md#br-006-email-error-notification-always-sent-to-a-fixed-corporate-email-domain) | — | — |
| [Evaluate trace request](operations/evaluate-trace-request.md) | Evaluate the obsolete trace gates and assemble trace metadata, which is then discarded by a no-op sink. | Caller invokes `clsLogTrace.MethodBegin(...)`, `MethodEnd(...)`, or `MethodMessage(...)`. | Optional state objects and, for `MethodMessage(...)`, a message string. | No durable output. | [BR-002](business-rules.md#br-002-trace-logging-is-opt-in-via-flag-or-command-line-switch-but-functionally-inert), [BR-005](business-rules.md#br-005-logging-failures-must-never-raise-exceptions-to-the-caller) | — | — |
| [Initialize local log file sink](operations/initialize-local-log-file-sink.md) | Redirect audit, error, or trace output from the SOAP sink to a local CSV file. | Caller invokes `ToFile()` or `ToFile(fileName)`. | Optional file name; the class derives a default path when none is supplied. | An open `StreamWriter` with its matching CSV header already written. | [BR-003](business-rules.md#br-003-file-based-logging-is-prohibited-in-web-applications) | — | — |
| [Record login event](operations/record-login-event.md) | Append a login/access event to the monthly login log file. | Caller invokes `clsLoginLog.LogItem(...)`. | User ID. | CSV append side effect; no return value. | [BR-005](business-rules.md#br-005-logging-failures-must-never-raise-exceptions-to-the-caller) | — | — |
| [Resolve logging queue path](operations/resolve-logging-queue-path.md) | Resolve the configured MSMQ server/queue name pair into a direct-format path string. | Caller invokes `clsLoggingQueues.GetQueueName()`. | None directly; reads `AppSettings` on demand. | `FormatName:DIRECT=OS:{server}\{queue}` string. | [BR-007](business-rules.md#br-007-queue-nameserver-resolution-falls-back-to-hard-coded-defaults) | — | — |

## Process flow diagram
The following diagram visualizes how a caller's request routes through the library's logging and helper entry points to the file or SOAP sink.

```mermaid
flowchart TD
	Start([Caller invokes logging library]) --> Choice{Requested operation}
	Choice -->|Audit| Audit[Dispatch audit message]
	Choice -->|Error| Error[Log exception]
	Choice -->|Error + email| ErrorMail[Log exception and send notification email]
	Choice -->|Trace| Trace[Evaluate trace request]
	Choice -->|ToFile| ToFile[Initialize local log file sink]
	Choice -->|Login| Login[Record login event]
	Choice -->|Queue helper| Queue[Resolve logging queue path]
	Audit --> Sink{File sink active?}
	Error --> Suppress{ViewState noise?}
	Suppress -->|Yes| Drop([Skip error log])
	Suppress -->|No| Sink
	ErrorMail --> Suppress
	Sink -->|Yes| FileWrite[Append CSV row]
	Sink -->|No| SoapWrite[Call wsLogging SOAP service]
	Trace --> NoOp([No-op trace sink])
	ToFile --> FileReady([Writer ready])
	Login --> LoginWrite([Append monthly login row])
	Queue --> QueueName([Return queue path])
	FileWrite --> End([Return to caller])
	SoapWrite --> End
	Drop --> End
	NoOp --> End
	FileReady --> End
	LoginWrite --> End
	QueueName --> End
```

## Inherited operations and processes

Operations in this section originate from collaborator services provided by dependency framework libraries. They are delegated, not implemented, in this library.

### From `clsSecurityPrincipal` (`SAIF.Framework.Security`)

| Operation | Intent | Provided by | Origin | Embedded in |
| --- | --- | --- | --- | --- |
| Current user identity capture | Resolve the current web or Windows user so it can be stamped onto each log record. | `clsSecurityPrincipal` | [SAIF.Framework.Security operations and processes](../saif-framework-security/operations-processes.md#windowsforms-identity-initialization) | [Dispatch audit message](operations/dispatch-audit-message.md), [Log exception](operations/log-exception.md), [Log exception and send notification email](operations/log-exception-and-send-notification-email.md), [Evaluate trace request](operations/evaluate-trace-request.md) |

> **Origin**: These steps are implemented in `SAIF.Framework.Security/clsSecurityPrincipal.vb` and are embedded inline wherever this library constructs or queries a `clsSecurityPrincipal` instance.

### From `EnvironmentServiceBase` (`SAIF.Framework.Security.EnvironmentApi`)

| Operation | Intent | Provided by | Origin | Embedded in |
| --- | --- | --- | --- | --- |
| Retrieve configuration setting | Resolve `loggingServiceUrl` and `legacyMailServiceUrl` from the cached Environment API configuration set. | `IEnvironmentService` / `EnvironmentServiceBase` | [SAIF.Framework.Security.EnvironmentApi operations and processes](../saif-framework-security-environmentapi/operations-processes.md#retrieve-a-configuration-setting) | [Dispatch audit message](operations/dispatch-audit-message.md), [Log exception](operations/log-exception.md), [Log exception and send notification email](operations/log-exception-and-send-notification-email.md) |
| Determine application environment and track | Return the current application environment so the audit custom path can normalize it into a development-environment label. | `IEnvironmentService` / `EnvironmentServiceBase` | [SAIF.Framework.Security.EnvironmentApi operations and processes](../saif-framework-security-environmentapi/operations-processes.md#determine-application-environment-and-track) | [Dispatch audit message](operations/dispatch-audit-message.md) |

> **Origin**: These steps are implemented in `SAIF.Framework.Security.EnvironmentApi/Services.Common/EnvironmentServiceBase.cs` and `SAIF.Framework.Security/EnvironmentServices/EnvironmentExtensions.vb`, then embedded inline wherever this library resolves an endpoint URL or environment label.

### From `clsSAIFMessage` (`SAIF.Framework.Mail`)

| Operation | Intent | Provided by | Origin | Embedded in |
| --- | --- | --- | --- | --- |
| Send email with subject and body | Submit the HTML error notification through the legacy mail SOAP endpoint. | `SAIFMail.clsSAIFMessage` | [SAIF.Framework.Mail operations and processes](../saif-framework-mail/operations-processes.md#send-email-with-subject-and-body) | [Log exception and send notification email](operations/log-exception-and-send-notification-email.md) |

> **Origin**: The generated mail proxy lives in `SAIF.Framework.Mail/Web References/SAIFMail/Reference.vb`; this library assigns the proxy URL and invokes its `SendMail(...)` operation inline.

## Failure and edge-case behavior
- Audit logging produces nothing until a host explicitly sets `clsLogAudit.IsEnabled = True` ([BR-001](business-rules.md#br-001-audit-logging-is-opt-in-and-disabled-by-default)).
- ViewState-noise exceptions are dropped before any file write, SOAP call, or email attempt begins ([BR-004](business-rules.md#br-004-aspnet-viewstate-errors-are-never-logged)).
- Web callers cannot redirect logging to a file — `ToFile(...)` throws immediately rather than silently falling back to the SOAP sink ([BR-003](business-rules.md#br-003-file-based-logging-is-prohibited-in-web-applications)).
- Trace entry points still build metadata and evaluate their enablement gate, but the private sink they call is intentionally empty, so no trace data ever reaches file or SOAP output ([BR-002](business-rules.md#br-002-trace-logging-is-opt-in-via-flag-or-command-line-switch-but-functionally-inert)).
- Runtime failures inside audit, error, trace, and login-event writes are swallowed so that logging infrastructure problems never interrupt the calling application ([BR-005](business-rules.md#br-005-logging-failures-must-never-raise-exceptions-to-the-caller)).

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Business rules](business-rules.md)
- [Configuration](configuration.md)
- [API reference](api/index.md)

## Sources
- `SAIF.Framework.Logging/clsLogAudit.vb`
- `SAIF.Framework.Logging/clsLogError.vb`
- `SAIF.Framework.Logging/clsLogTrace.vb`
- `SAIF.Framework.Logging/clsLoginLog.vb`
- `SAIF.Framework.Logging/clsLoggingQueues.vb`
- `SAIF.Framework.Logging/clsLogCommon.vb`
- `SAIF.Framework.Security/clsSecurityPrincipal.vb`
- `SAIF.Framework.Security/EnvironmentServices/EnvironmentExtensions.vb`
- `SAIF.Framework.Security.EnvironmentApi/Services.Common/EnvironmentServiceBase.cs`
- `SAIF.Framework.Security.EnvironmentApi/Services.Common/EnvironmentConfigKeys.cs`
- `SAIF.Framework.Mail/Web References/SAIFMail/Reference.vb`