FreeLog

1.0.0

Public/Write-LogFile.ps1

<#
.SYNOPSIS
Writes messages to the active log file using different severity levels.

.DESCRIPTION
The Write-LogFile function provides an interface for logging messages.
It supports four distinct logging levels and automatically routes messages to the
appropriate logger method.

.PARAMETER TaskMessage
Specifies a standard informational message to log.

.PARAMETER TaskWarn
Specifies a warning message to log.

.PARAMETER TaskError
Specifies an error message to log.

.PARAMETER TaskFail
Specifies a critical failure message to log.

.INPUTS
System.String
You can pipe strings to any of the four message parameters using property names that
match the parameter names (TaskMessage, TaskWarn, TaskError, TaskFail).

.OUTPUTS
System.String
The function outputs a formatted string showing the log type and message that was logged.

.EXAMPLE
New-LogFile -Path "C:\Logs\app.log"

Write-LogFile -TaskMessage "Processing started"
Write-LogFile -TaskWarn "Memory usage is high"
Write-LogFile -TaskError "Failed to connect to service"
Write-LogFile -TaskFail "Application must shut down"

.EXAMPLE
$tasks = @(
    [PSCustomObject]@{TaskMessage = "Step 1 completed"},
    [PSCustomObject]@{TaskWarn = "Step 2 completed with warnings"},
    [PSCustomObject]@{TaskError = "Step 3 failed"}
)
$tasks | Write-LogFile

.EXAMPLE
$result = Write-LogFile -TaskMessage "User login successful"
$result # Outputs: "LOG: User login successful"

.EXAMPLE
try {
    Write-LogFile -TaskMessage "Test message"
}
catch {
    Write-Error "Logging failed: $_" # Throws if New-LogFile hasn't been called
}

.NOTES
Function Name : Write-LogFile
Requires : PowerShell 5.0 or later
Dependencies : FreeLogClass, New-LogFile function
Scope : Depends on script-scoped $logger variable
Module : FreeLog

Example Pipeline Integration:
    Get-Process | ForEach-Object {
        [PSCustomObject]@{
            TaskMessage = "Process $($_.Name) running with ID $($_.Id)"
        }
    } | Write-LogFile
#>
function Write-LogFile {
  [CmdletBinding()]
  param (
    [Parameter(Mandatory = $false, ValueFromPipelineByPropertyName = $true)]
    [string]$TaskMessage,

    [Parameter(Mandatory = $false, ValueFromPipelineByPropertyName = $true)]
    [string]$TaskWarn,

    [Parameter(Mandatory = $false, ValueFromPipelineByPropertyName = $true)]
    [string]$TaskError,

    [Parameter(Mandatory = $false, ValueFromPipelineByPropertyName = $true)]
    [string]$TaskFail
  )

  process {
    if ($null -eq $script:logger) {
      throw 'Logger not initialized. Run New-LogFile first.'
    }

    $message = $null
    $logType = $null

    if ($TaskFail) {
      $message = $TaskFail
      $logType = 'Fail'
      $script:logger.Fail($message)
    }
    elseif ($TaskError) {
      $message = $TaskError
      $logType = 'Error'
      $script:logger.Error($message)
    }
    elseif ($TaskWarn) {
      $message = $TaskWarn
      $logType = 'Warn'
      $script:logger.Warn($message)
    }
    elseif ($TaskMessage) {
      $message = $TaskMessage
      $logType = 'Log'
      $script:logger.Log($message)
    }
    else {
      throw 'No log data provided. You must specify TaskMessage, TaskWarn, TaskError, or TaskFail.'
    }

    "$($logType.ToUpper()): $message"
  }
}