Skip to content

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 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, BR-005 — —
Log exception 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, BR-005 — —
Log exception and send notification email 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, BR-005, BR-006 — —
Evaluate trace request 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, BR-005 — —
Initialize local log file sink 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 — —
Record login event 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 — —
Resolve logging queue path 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 — —

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.

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 Dispatch audit message, Log exception, Log exception and send notification email, Evaluate trace request

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 Dispatch audit message, Log exception, Log exception and send notification email
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 Dispatch audit message

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 Log exception and send notification email

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).
  • ViewState-noise exceptions are dropped before any file write, SOAP call, or email attempt begins (BR-004).
  • Web callers cannot redirect logging to a file — ToFile(...) throws immediately rather than silently falling back to the SOAP sink (BR-003).
  • 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).
  • Runtime failures inside audit, error, trace, and login-event writes are swallowed so that logging infrastructure problems never interrupt the calling application (BR-005).

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