GlobalFunctions.psm1
|
<#
.Synopsis PowerShell module providing centralizied logging and other helpful functions .Description This module provides centralized file logging capabilities and other helpful stuff Author: Thomas Stensitzki Version 1.2, 2015-07-17 Use the following code to import the module in PowerShell scripts Import-Module GlobalFunctions Make sure that the file path to the PowerShell module has been added to the persistent list of PowerShell module paths using the Set-PersistentPSModulePath.ps1 script. .NOTES Requirements - Windows Server 2008 R2 SP1, Windows Server 2012 or Windows Server 2012 R2 Revision History -------------------------------------------------------------------------------- 1.0 Initial release 1.1 Write to Event log added, send log file added 1.2 CopyFile added 1.3 Updated for PowerShellGallery #> <# .SYNOPSIS Output some text to the command line for testing. .DESCRIPTION Just for testing purposes .PARAMETER Test Switch to output text to the command line .EXAMPLE # Write output to the command line Test-Module -Test #> function Test-Module { param( [switch]$Test ) if($Test) { Write-Host 'Module Test' } } <# .SYNOPSIS Log file logger object to write and purge log files .DESCRIPTION Function that returns an object to write an purge logfiles. The object creates a new log folder as a child object to the script execution folder. The log file folder name can be set, default is "logs". If the folder does not exist it will be created. Severity levels supported are: 0 : Info (default) 1 : Error 2 : Warning The default retnetion time for log files is 30 days. .Write Method to write messages with a given severity level to a log file .WriteEventLog Write an event log entry to the local computer event log .Purge Method to purge log files older than log file retentionin days .SendLogFile Send the current logger log file as an email attachment .PARAMETER ScriptRoot The script folder the referencing script is being executing in. Example: $ScriptDir = Split-Path $script:MyInvocation.MyCommand.Path .PARAMETER ScriptName The name of the script referencing the function. This name is used for Windows event log purposes Default = MyScriptName Example: $ScriptName = $MyInvocation.MyCommand.Name .PARAMETER LogFolder Name of the log files folder Default = logs .PARAMETER FileName Name pattern for the log file names. This parameter is using utilizing the datetiem format notation Default = \LO\G-yyyyMMdd.lo\g .PARAMETER TimeFormat DateTime format to be used as a line prefix when appending messages to the log file Default = yyyy-MM-dd HH:mm .PARAMETER LogFileRetention Retention period in days for expired log files Default = 30 .PARAMETER EventLogName Name of the Windows Event Log events are written to. Default = Application .EXAMPLE # Instantiate a new logger object using a log time renttion of 14 days $ScriptDir = Split-Path $script:MyInvocation.MyCommand.Path $logger = New-Logger -ScriptRoot $ScriptDir -ScriptName $ScriptName -LogFileRetention 14 .EXAMPLE # Write a new informational message to the log $logger.Write("My informational message") .EXAMPLE # Write a new error message to the log $logger.Write("My critical error", 1) .EXAMPLE # Write a new warning message to the log $logger.Write("My standard warning", 2) .EXAMPLE $logger.SendLogFile("sender@mcsmemail.de", "recipient@mcsmemail.de", "smtpserver.mcsmemail.de") .EXAMPLE # Purge log files $logger.Purge() #> function New-Logger { param( [Parameter(Mandatory=$true)] [string]$ScriptRoot, [string]$ScriptName = 'MyScriptName', [string]$LogFolder = 'logs', [string]$FileName = '\LO\G-yyyyMMdd.lo\g', [string]$TimeFormat = 'yyyy-MM-dd HH:mm', [int]$LogFileRetention = 30, [string]$EventLogName = 'Application' ) # create logger object $logger = New-Object PSCustomObject # add logger properties $logger | Add-Member -MemberType NoteProperty -Name ScriptRoot -Value $ScriptRoot $logger | Add-Member -MemberType NoteProperty -Name ScriptName -Value $ScriptName $logger | Add-Member -MemberType NoteProperty -Name LogFolder -Value $LogFolder $logger | Add-Member -MemberType NoteProperty -Name FileName -Value $FileName $logger | Add-Member -MemberType NoteProperty -Name TimeFormat -Value $TimeFormat $logger | Add-Member -MemberType NoteProperty -Name LogFileRetention -Value $LogFileRetention $logger | Add-Member -MemberType NoteProperty -Name EventLogName -Value $EventLogName # add logger script methods # WRITE # Script method to write log messages to disk $logger | Add-Member -MemberType ScriptMethod -Name Write { param ( [Parameter(Mandatory=$true)] [string]$Message, [int]$Severity = 0 ) try { [string]$timeStamp = (Get-Date -Format $this.TimeFormat) [string]$folderPath = Join-Path -Path $this.ScriptRoot -ChildPath $this.LogFolder [string]$file = (Get-Date -Format $this.FileName) [string]$filePath = Join-Path -Path $folderPath -ChildPath $file # log file line prefix $prefix = "$($timeStamp):" # map severity code to string value switch($Severity) { 1 { [string]$SeverityString = 'Error' } 2 { [string]$SeverityString = 'Warning' } default { [string]$SeverityString = 'Info' } #0 } # check if log directory exists if(!(Test-Path -Path $folderPath)) { # create log directory New-Item -Path $folderPath -ItemType Directory | Out-Null } # define log line columns $col1 = $($prefix) $col2 = ([string]$PID).PadRight(10).Substring(0,10) $col3 = ([string]$SeverityString).PadRight(8).Substring(0,8) $col4 = $($Message) # check, if file exists if(!(Test-Path -Path $filePath)) { $line = "$($prefix) LOG FILE CREATED ##############################`r`n" New-Item -Path $filePath -ItemType File -Value $line -Force | Out-Null $line ='TIMESTAMP : PROCESS ID - SEVERITY - MESSAGE' Add-Content -Path $filePath -Value $line } # write message to file $line = "$($prefix) $($col2) - $($col3) - $($col4)" Add-Content -Path $filePath -Value $line } catch {} } # WRITEEVENTLOG # Script method to write messages to event log $logger | Add-Member -MemberType ScriptMethod -Name WriteEventLog { param ( [Parameter(Mandatory=$true)] [string]$Message, [int]$Severity = 0 ) try { # Create new event log source first. Without event log source we cannot write to event log New-EventLog -LogName $this.EventLogName -Source $this.ScriptName # map severity code to string value switch($Severity) { 1 { [string]$SeverityString = 'Error' } 2 { [string]$SeverityString = 'Warning' } default { [string]$SeverityString = 'Information' } #0 } Write-EventLog -LogName $this.EventLogName -Source $this.ScriptName -EntryType $SeverityString -EventId $Severity -Message $Message } catch { $this.Write("Error writing to event log. Error: $($Error)") } } # PURGE # Script method to purge aged log files from disk $logger | Add-Member -MemberType ScriptMethod -Name Purge { param ( [switch]$Detailed ) [string]$timeStamp = (Get-Date -Format $this.TimeFormat) [string]$folderPath = Join-Path -Path $this.ScriptRoot -ChildPath $this.LogFolder try { # fetch list of log files $logFiles = Get-ChildItem -Path $folderPath | Where-Object{$_.LastWriteTimeUtc.Date -le ([datetime]::UtcNow.AddDays(-($this.LogFileRetention))).Date} # write summary to log file $this.Write("Deleting $($logFiles.Count) log files older than $($this.LogFileRetention) days") foreach($file in $logFiles) { Remove-Item $file.FullName -Confirm:$false } } catch {} } # COPYFILE # Script method to copy a file to sub folder $logger | Add-Member -MemberType ScriptMethod -Name CopyFile { param ( [Parameter(Mandatory=$true)] [string]$SourceFilePath, [Parameter(Mandatory=$true)] [string]$RepositoryFolderName ) try { [string]$folderPath = Join-Path -Path $this.ScriptRoot -ChildPath $RepositoryFolderName [string]$sourceFileName = Split-Path -Path $SourceFilePath -Leaf # check if repository directory exists if(!(Test-Path -Path $folderPath)) { # create log directory New-Item -Path $folderPath -ItemType Directory | Out-Null $this.Write("$($folderPath) folder created") } if(Test-Path -Path $SourceFilePath) { $this.Write("Moving $($SourceFilePath) to $(Join-Path -Path $folderPath -ChildPath $sourceFileName)") Move-Item -Path $SourceFilePath -Destination (Join-Path -Path $folderPath -ChildPath $sourceFileName) } else { $this.Write("$($folderPath) does not exist and cannot be copied",2) } } catch {} } # SENDLOGFILE # Script method to send log file via email $logger | Add-Member -MemberType ScriptMethod -Name SendLogFile { param ( [Parameter(Mandatory=$true)] [string]$From, [Parameter(Mandatory=$true)] [string]$To, [Parameter(Mandatory=$true)] [string]$SmtpServer ) try { [string]$timeStamp = (Get-Date -Format $this.TimeFormat) [string]$folderPath = Join-Path -Path $this.ScriptRoot -ChildPath $this.LogFolder [string]$file = (Get-Date -Format $this.FileName) [string]$filePath = Join-Path -Path $folderPath -ChildPath $file [string]$subject = "Requested Log File ($($this.ScriptName))" [string]$body = "<html> <body> <font size=""1"" face=""Arial,sans-serif""> <p2>Please find the requested log file $($filePath) attached to this email.</p> </font> </body>" # Write mail action to log file first $this.Write("Sending log file from $($From) to $($To) via $($SmtpServer)") # Send mail message Send-MailMessage -SmtpServer $SmtpServer -From $From -To $To -Subject $subject -Body $body -BodyAsHtml -Attachments $filePath } catch {} } # return object return $logger } <# .SYNOPSIS Sends an email to given recipient .DESCRIPTION This function is an encapsulation for the Send-MailMessage cmdlet to utilize a common parameter set .PARAMETER From Email address of the sender .PARAMETER To Email address of the recipient .PARAMETER Subject Email subject .PARAMETER MessageBody HTML message body .PARAMETER SMTPServer SMTP Server for relaying the message .EXAMPLE # Send an email Send-Mail -From sender@mcsmemail.de -To recipient@mcsmemail.de -Subject "My message subject" -MessageBody $SomeBodyVariable -SMTPServer myserver.mcsmemail.de #> function Send-Mail { param ( [Parameter(Mandatory=$true)] [string]$From, [Parameter(Mandatory=$true)] [string]$To, [Parameter(Mandatory=$true)] [string]$Subject, [Parameter(Mandatory=$true)] [string]$MessageBody, [Parameter(Mandatory=$true)] [string]$SMTPServer ) try { Send-MailMessage -From $From -To $To -SmtpServer $SMTPServer -BodyAsHtml $MessageBody -Subject $Subject } catch {} } # Exported functions # -------------------------------------------------- Export-ModuleMember -Function Test-Module Export-ModuleMember -Function Write-Log Export-ModuleMember -Function New-Logger Export-ModuleMember -Function Send-Mail |