documentation

hobointhecorner · Dec 15, 2021 · 0aa64d0 · 0aa64d0
1 parent 9018e13
commit 0aa64d0
Show file tree

Hide file tree

Showing 9 changed files with 591 additions and 2 deletions.
diff --git a/Hobo.Log.format.ps1xml b/Hobo.Log.format.ps1xml
@@ -11,7 +11,7 @@
 
             <TableHeaders>
               <TableColumnHeader>
-                <Width>24</Width>
+                <Width>22</Width>
               </TableColumnHeader>
 
               <TableColumnHeader>

diff --git a/Hobo.Log.psm1 b/Hobo.Log.psm1
@@ -30,10 +30,48 @@ function Merge-LogPref
     }
 }
 
+<#
+
+.SYNOPSIS
+This is a Powershell cmdlet to write output to the console, a log file, or the Windows Event Log with one command.
+
+.DESCRIPTION
+This cmdlet allows a user to write output to the console using their preferred output pipeline, as well as write the output to a file log and the Windows Event Log at the same time with one command.
+
+.PARAMETER Message
+The message to be logged
+
+.PARAMETER LogType
+The event type of the log entry being written.  (INFO, WARN, ERROR)
+
+.PARAMETER LogOutputPipeline
+Choose to write to alternative pipelines (OUTPUT, INFO)
+
+.PARAMETER LogOutputRaw
+Writes a string to console output instead of a LogOutput object
+
+.PARAMETER LogFile
+Enables writing to the file log.
+
+.PARAMETER LogFilePref
+A hashtable of parameters to be sent to the Write-LogFile command.
+
+.PARAMETER LogFileRaw
+Writes a string to file output instead of a LogOutput object
+
+.PARAMETER LogEvent
+Enables writing to the Windows Event Log.
+
+.PARAMETER LogEventPref
+A hashtable of parameters to be sent to the Write-LogEvent command.
+
+#>
+
 function Write-LogTee
 {
     [cmdletbinding()]
     param(
+        [parameter(Mandatory)]
         [string]$Message,
 
         [ValidateSet('INFO', 'WARN', 'ERROR')]

diff --git a/README.md b/README.md
@@ -1 +1,123 @@
-# Hobo.Log
+# Hobo.Log
+
+A collection of logging tools for powershell
+
+**[Hobo.Log.Event](modules/Hobo.Log.Event/README.md)**: Write to the Windows Event Log
+
+**[Hobo.Log.File](modules/Hobo.Log.File/README.md)**: Write to a file-based log
+
+**[Hobo.Log.Output](modules/Hobo.Log.Output/README.md)**: Write output to the console with standardized formatting
+
+## Write-LogTee
+```
+NAME
+    Write-LogTee
+
+SYNOPSIS
+    This is a Powershell cmdlet to write output to the console, a log file, or the Windows Event Log with one command.
+
+
+SYNTAX
+    Write-LogTee [-Message] <String> [[-LogType] <String>] [[-LogOutputPref] <Hashtable>] [[-LogOutputPipeline] <String>] [-LogOutputRaw] [-LogFile] [[-LogFilePref] <Hashtable>] [-LogFileRaw] [-LogEvent] [[-LogEventPref] <Hashtable>] [<CommonParameters>]
+
+
+DESCRIPTION
+    This cmdlet allows a user to write output to the console using their preferred output pipeline, as well as write the output to a file log and the Windows Event Log at the same time with one command.
+
+
+PARAMETERS
+    -Message <String>
+        The message to be logged
+
+        Required?                    true
+        Position?                    1
+        Default value
+        Accept pipeline input?       false
+        Accept wildcard characters?  false
+
+    -LogType <String>
+        The event type of the log entry being written.  (INFO, WARN, ERROR)
+
+        Required?                    false
+        Position?                    2
+        Default value                INFO
+        Accept pipeline input?       false
+        Accept wildcard characters?  false
+
+    -LogOutputPref <Hashtable>
+
+        Required?                    false
+        Position?                    3
+        Default value                @{}
+        Accept pipeline input?       false
+        Accept wildcard characters?  false
+
+    -LogOutputPipeline <String>
+        Choose to write to alternative pipelines (OUTPUT, INFO)
+
+        Required?                    false
+        Position?                    4
+        Default value                OUTPUT
+        Accept pipeline input?       false
+        Accept wildcard characters?  false
+
+    -LogOutputRaw [<SwitchParameter>]
+        Writes a string to console output instead of a LogOutput object
+
+        Required?                    false
+        Position?                    named
+        Default value                False
+        Accept pipeline input?       false
+        Accept wildcard characters?  false
+
+    -LogFile [<SwitchParameter>]
+        Enables writing to the file log.
+
+        Required?                    false
+        Position?                    named
+        Default value                False
+        Accept pipeline input?       false
+        Accept wildcard characters?  false
+
+    -LogFilePref <Hashtable>
+        A hashtable of parameters to be sent to the Write-LogFile command.
+
+        Required?                    false
+        Position?                    5
+        Default value                @{}
+        Accept pipeline input?       false
+        Accept wildcard characters?  false
+
+    -LogFileRaw [<SwitchParameter>]
+        Writes a string to file output instead of a LogOutput object
+
+        Required?                    false
+        Position?                    named
+        Default value                False
+        Accept pipeline input?       false
+        Accept wildcard characters?  false
+
+    -LogEvent [<SwitchParameter>]
+        Enables writing to the Windows Event Log.
+
+        Required?                    false
+        Position?                    named
+        Default value                False
+        Accept pipeline input?       false
+        Accept wildcard characters?  false
+
+    -LogEventPref <Hashtable>
+        A hashtable of parameters to be sent to the Write-LogEvent command.
+
+        Required?                    false
+        Position?                    6
+        Default value                @{}
+        Accept pipeline input?       false
+        Accept wildcard characters?  false
+
+    <CommonParameters>
+        This cmdlet supports the common parameters: Verbose, Debug,
+        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
+        OutBuffer, PipelineVariable, and OutVariable. For more information, see
+        about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216).
+```
diff --git a/modules/Hobo.Log.Event/Hobo.Log.Event.psm1 b/modules/Hobo.Log.Event/Hobo.Log.Event.psm1
@@ -46,6 +46,24 @@ function Test-LogEventSourceEnabled
     }
 }
 
+<#
+
+.SYNOPSIS
+Create a new log source in the Windows Event Log.
+
+.DESCRIPTION
+This is a Powershell cmdlet to create a new log source in the Windows Event Log.  This command requires the user have administrative privileges.
+
+.PARAMETER LogName
+The name of the log to create the source in.  Will create a new log with the defined name if one does not already exist.
+
+.PARAMETER LogSource
+The name of the log source to create.
+
+.PARAMETER Force
+This will remove the log source if it already exists before creating it.  This does NOT bypass administrative privilege checks.
+
+#>
 function New-LogEventSource
 {
     [cmdletbinding()]
@@ -105,6 +123,36 @@ function New-LogEventSource
 }
 
 
+<#
+
+.SYNOPSIS
+Write messages to the Windows Event Log.
+
+.DESCRIPTION
+This is a Powershell cmdlet to write messages to the Windows Event Log. It will automatically attempt to create the defined event log and source if they do not already exist.
+
+.PARAMETER Message
+The message to be written to the log
+
+.PARAMETER LogName
+The name of the event log to be written to.  Defaults to the Application log.
+
+.PARAMETER LogSource
+The name of the log source to be written from.  This will create the source in the event viewer if the user has administrative privileges.
+
+.PARAMETER LogType
+The event type of the log entry being written.  (INFO, WARN, ERROR)
+
+.PARAMETER EventId
+The ID number of the event being written.  Defaults to 0.
+
+.PARAMETER Force
+Bypasses administrative privilege and log source existence checks and attempts to write to the defined event log and source.
+
+.PARAMETER PassThru
+Writes object to console output as well
+
+#>
 function Write-LogEvent
 {
     [cmdletbinding()]

diff --git a/modules/Hobo.Log.Event/README.md b/modules/Hobo.Log.Event/README.md
@@ -0,0 +1,134 @@
+# Hobo.Log.Event
+
+Write to Windows Event Viewer logs
+
+### Write-LogEvent
+```
+NAME
+    Write-LogEvent
+
+SYNOPSIS
+    Write messages to the Windows Event Log.
+
+
+SYNTAX
+    Write-LogEvent [-Message] <String> [-LogSource] <String> [[-LogName] <String>] [[-LogType] <String>] [[-EventId] <String>] [-PassThru] [<CommonParameters>]
+
+
+DESCRIPTION
+    This is a Powershell cmdlet to write messages to the Windows Event Log. It will automatically attempt to create the defined event log and source if they do not already exist.
+
+
+PARAMETERS
+    -Message <String>
+        The message to be written to the log
+
+        Required?                    true
+        Position?                    1
+        Default value
+        Accept pipeline input?       false
+        Accept wildcard characters?  false
+
+    -LogSource <String>
+        The name of the log source to be written from.  This will create the source in the event viewer if the user has administrative privileges.
+
+        Required?                    true
+        Position?                    2
+        Default value
+        Accept pipeline input?       false
+        Accept wildcard characters?  false
+
+    -LogName <String>
+        The name of the event log to be written to.  Defaults to the Application log.
+
+        Required?                    false
+        Position?                    3
+        Default value                Application
+        Accept pipeline input?       false
+        Accept wildcard characters?  false
+
+    -LogType <String>
+        The event type of the log entry being written.  This can be Information, Warning, or Error.  Defaults to Information.
+
+        Required?                    false
+        Position?                    4
+        Default value                INFO
+        Accept pipeline input?       false
+        Accept wildcard characters?  false
+
+    -EventId <String>
+        The ID number of the event being written.  Defaults to 0.
+
+        Required?                    false
+        Position?                    5
+        Default value                0
+        Accept pipeline input?       false
+        Accept wildcard characters?  false
+
+    -PassThru [<SwitchParameter>]
+        Writes object to console output as well
+
+        Required?                    false
+        Position?                    named
+        Default value                False
+        Accept pipeline input?       false
+        Accept wildcard characters?  false
+
+    <CommonParameters>
+        This cmdlet supports the common parameters: Verbose, Debug,
+        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
+        OutBuffer, PipelineVariable, and OutVariable. For more information, see
+        about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216).
+```
+
+### New-LogEventSource
+```
+NAME
+    New-LogEventSource
+
+SYNOPSIS
+    Create a new log source in the Windows Event Log.
+
+
+SYNTAX
+    New-LogEventSource [-LogName] <String> [-LogSource] <String> [-Force] [<CommonParameters>]
+
+
+DESCRIPTION
+    This is a Powershell cmdlet to create a new log source in the Windows Event Log.  This command requires the user have administrative privileges.
+
+
+PARAMETERS
+    -LogName <String>
+        The name of the log to create the source in.  Will create a new log with the defined name if one does not already exist.
+
+        Required?                    true
+        Position?                    1
+        Default value
+        Accept pipeline input?       false
+        Accept wildcard characters?  false
+
+    -LogSource <String>
+        The name of the log source to create.
+
+        Required?                    true
+        Position?                    2
+        Default value
+        Accept pipeline input?       false
+        Accept wildcard characters?  false
+
+    -Force [<SwitchParameter>]
+        This will remove the log source if it already exists before creating it.  This does NOT bypass administrative privilege checks.
+
+        Required?                    false
+        Position?                    named
+        Default value                False
+        Accept pipeline input?       false
+        Accept wildcard characters?  false
+
+    <CommonParameters>
+        This cmdlet supports the common parameters: Verbose, Debug,
+        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
+        OutBuffer, PipelineVariable, and OutVariable. For more information, see
+        about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216).
+```