v1.2.0

Updated Write-Detail
Updated README

Author: jdhitsolutions

PSScriptTools.psd1

@@ -6,21 +6,24 @@ This PowerShell module contains a number of functions you might use to enhance y
 The current release is [PSScriptTools-v1.0.1](https://github.com/jdhitsolutions/PSScriptTools/archive/v1.0.1.zip)
 
 You can also install this from the PowerShell Gallery:
-```
+
+```powershell
 Install-Module PSScriptTools
 ```
+
 or in PowerShell Core:
-```
+
+```powershell
 Install-Module PSScriptTools -scope currentuser
 ```
 
-
 Please post any questions, problems or feedback in Issues. Any input is greatly appreciated.
 
 ## Add-Border
+
 This command will create a character or text based border around a line of text. You might use this to create a formatted text report or to improve the display of information to the screen.
 
-```
+```powershell
 PS C:\> add-border $env:computername
 
 *************
@@ -29,9 +32,10 @@ PS C:\> add-border $env:computername
 ```
 
 ## Get-PSWho
+
 This command will provide a summary of relevant information for the current user in a PowerShell Session. You might use this to troubleshoot an end-user problem running a script or command.
 
-```
+```powershell
 PS C:\> Get-PSWho
 
 User            : COWPC\Jeff
@@ -46,10 +50,12 @@ WSMan           : 3.0
 ExecutionPolicy : RemoteSigned
 Culture         : en-US
 ```
+
 ## New-CustomFileName
+
 This command will generate a custom file name based on a template string that you provide. 
 
-```
+```powershell
 PS C:\> New-CustomFileName %computername_%day%monthname%yr-%time.log
 COWPC_28Nov17-142138.log
 
@@ -59,65 +65,77 @@ Tuesday-3128.dat
 
 You can create a template string using any of these variables. Most of these should be self-explanatory
 
-- %username     
+- %username
 - %computername 
-- %year  - 4 digit year        
-- %yr  - 2 digit year         
-- %monthname - The abbreviated month name   
-- %month  - The month number      
-- %dayofweek - The full name of the week day   
-- %day          
-- %hour         
-- %minute       
-- %time         
-- %string - A random string       
-- %guid       
+- %year  - 4 digit year
+- %yr  - 2 digit year
+- %monthname - The abbreviated month name
+- %month  - The month number
+- %dayofweek - The full name of the week day
+- %day
+- %hour
+- %minute
+- %time
+- %string - A random string
+- %guid
 
 You can also insert a random number using %### with a # character for each digit. If you want a 2 digit random number use %##. If you want 6 digits, use %######.
 
 ## New-RandomFileName
+
 Create a new random file name. The default is a completely random name including the extension.
-```
+
+```powershell
 PS C:\> new-randomfilename
 fykxecvh.ipw
 ```
-But you can specify an extentions.
-```
+
+But you can specify an extension.
+
+```powershell
 PS C:\> new-randomfilename -extension dat
 emevgq3r.dat
 ```
+
 Optionally you can create a random file name using the TEMP folder or your HOME folder. On Windows platforms this will default to your Documents folder.
-```
+
+```powershell
 PS C:\> new-randomfilename -extension log -UseHomeFolder
 C:\Users\Jeff\Documents\kbyw4fda.log
 ```
+
 On Linux machines it will be the home folder.
-```
+
+```powershell
 PS /mnt/c/scripts> new-randomfilename -home -Extension tmp
 /home/jhicks/oces0epq.tmp
 ```
 ## Write-Detail
-This command is designed to be used within your functions and scripts to make it easier to write a detailed message that you can use as verbose output. The assumption is that you are using an advanced function with a Begin, Process and End scriptblocks. You can create a detailed message to indicate what part of the code is being executed. The output will include a full time stamp, although you can shorten it to be only a time string which includes a millisecond value.
 
+This command is designed to be used within your functions and scripts to make it easier to write a detailed message that you can use as verbose output. The assumption is that you are using an advanced function with a Begin, Process and End scriptblocks. You can create a detailed message to indicate what part of the code is being executed. The output can be configured to include a datetime stamp or just the time.
+
+```powershell
+PS C:\> write-detail "Getting file information" -Prefix Process -Date
+9/15/2018 11:42:43 [PROCESS] Getting file information
 ```
-PS C:\>write-detail "Getting file information" -Prefix Process -NoDate
-02:39:18:4874 [PROCESS] Getting file information
-```
+
 In a script you might use it like this:
-```
+
+```powershell
 Begin {
-    Write-Detail "Starting $($myinvocation.mycommand)" -Prefix begin | Write-Verbose
+    Write-Detail "Starting $($myinvocation.mycommand)" -Prefix begin -time | Write-Verbose
     $tabs = "`t" * $tab
-    Write-Detail "Using a tab of $tab" -Prefix BEGIN | Write-Verbose
+    Write-Detail "Using a tab of $tab" -Prefix BEGIN -time | Write-Verbose
 } #begin
 ```
 
 ## Out-VerboseTee
+
 This command is intended to let you see your verbose output and write the verbose messages to a log file. It will only work if the verbose pipeline is enabled, usually when your command is run with -Verbose. This function is designed to be used within your scripts and functions. You either have to hard code a file name or find some other way to define it in your function or control script. You could pass a value as a parameter or set it as a PSDefaultParameterValue.
 
 This command has an alias of Tee-Verbose.
 
-```
+```powershell
 Begin {
     $log = New-RandomFilename -useTemp -extension log
     Write-Detail "Starting $($myinvocation.mycommand)" -Prefix begin | Tee-Verbose $log
@@ -126,9 +144,11 @@ Begin {
     $data = @()
 } #begin
 ```
+
 When the command is run with -Verbose you will see the verbose output and it will be saved to the specified log file.
 
 ## Out-ConditionalColor
+
 This command is designed to take pipeline input and display it in a colorized format,based on a set of conditions. Unlike Write-Host which doesn't write to the pipeline, this command will write to the pipeline. 
 
 You can use a simple hashtable to define a color if the given property matches the hashtable key.
@@ -141,11 +161,14 @@ Or you can specify an ordered hashtable for more complex processing.
 This command doesn't always work depending on the type of object you pipe to it. The problem appears to be related to the formatting system. Development and testing is ongoing.
 
 ## Copy-Command
+
 This command will copy a PowerShell command, including parameters and help to a new user-specified command. You can use this to create a "wrapper" function or to easily create a proxy function. The default behavior is to create a copy of the command complete with the original comment-based help block.
 
 ## Format-Functions
+
 A set of simple commands to make it easier to format values.
-```
+
+```powershell
 PS C:\> format-percent -Value 123.5646MB -total 1GB -Decimal 4
 12.0669
 PS C:\> format-string "powershell" -Reverse -Case Proper
@@ -155,6 +178,7 @@ PS C:\>  format-value 1235465676 -Unit kb
 ```
 
 ## Get-PSLocation
+
 A simple function to get common locations. This can be useful with cross-platform scripting.
 
 ![](./images/pslocation-win.png)
@@ -163,15 +187,19 @@ A simple function to get common locations. This can be useful with cross-platfor
 
 
 ## Get-PowerShellEngine
+
 Use this command to quickly get the path to the PowerShell executable. In Windows you should get a result like this:
-```
+
+```powershell
 PS C:\> Get-PowerShellEngine
 C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
 ```
+
 But PowerShell Core is a bit different:
-```
+
+```powershell
 PS /home/jhicks> Get-PowerShellEngine 
-/opt/microsoft/powershell/6.0.0-rc/pwsh
+/opt/microsoft/powershell/6/pwsh
 ```
 
 You can also get detailed information.
@@ -182,36 +210,48 @@ You can also get detailed information.
 ![PowerShell Core on Linux](./images/get-powershellengine3.png)
 
 Results will vary depending on whether you are running Windows PowerShell or PowerShell Core.
+
 ## Out-More
+
 This command provides a PowerShell alternative to the cmd.exe MORE command, which doesn't work in the PowerShell ISE. When you have screens of information, you can page it with this function.
-```
+
+```powershell
 get-service | out-more
 ```
+
 ![](./images/out-more.png)
 
 This also works in PowerShell Core.
 
 ## Invoke-InputBox
+
 This function is a graphical replacement for Read-Host. It creates a simple WPF form that you can use to get user input. The value of the text box will be written to the pipeline.
-```
+
+```powershell
 $name = Invoke-InputBox -Prompt "Enter a user name" -Title "New User Setup"
 ```
+
 ![](./images/ibx-1.png)
 
 You can also capture a secure string.
-```
+
+```powershell
 Invoke-Inputbox -Prompt "Enter a password for $Name" -AsSecureString -BackgroundColor red
 ```
+
 ![](./images/ibx-2.png)
 
 This example also demonstrates that you can change form's background color.
 This function will **not** work in PowerShell Core.
 
 ## ToDo
+
 Because this module is intended to make scripting easier for you, it adds options to insert ToDo statements into PowerShell files. If you are using the PowerShell ISE or VS Code and import this module, it will add the capability to insert a line like this:
-```
+
+```yaml
 # [12/13/2017 16:52:40] TODO: Add parameters
 ```
+
 In the PowerShell ISE, you will get a new menu under Add-Ons
 
 ![](./images/todo-1.png)
@@ -221,9 +261,11 @@ You can use the menu or keyboard shortcut which will launch an input box.
 ![](./images/todo-2.png)
 
 The comment will be inserted at the current cursor location.
+
 In VS Code, access the command palette (Ctrl+Shift+P) and then "PowerShell: Show Additional Commands from PowerShell Modules". Select "Insert ToDo" from the list and you'll get the same input box. Note that this will only work for PowerShell files.
 
 ### Compatibility
+
 Where possible these commands have been tested with PowerShell Core, but not every platform. If you encounter problems,have suggestions or other feedback, please post an issue.
 
-*last updated 14 December 2017*
+*last updated 15 September 2018*

README.md

@@ -1,22 +1,40 @@
 Function Write-Detail {
-    [cmdletbinding()]
+    [cmdletbinding(DefaultParameterSetName="Default")]
     Param(
         [Parameter(Position = 0, Mandatory)]
+        [Parameter(ParameterSetName="Default")]
+        [Parameter(ParameterSetName="Date")]
+        [Parameter(ParameterSetName="Time")]
+        [ValidateNotNullorEmpty()]
         [string]$Message,
-        [ValidateSet("BEGIN","PROCESS","END")]
+
+        [Parameter(ParameterSetName="Default")]
+        [Parameter(ParameterSetName="Date")]
+        [Parameter(ParameterSetName="Time")]
         [string]$Prefix = "PROCESS",
-        [switch]$NoDate
+
+        [Parameter(ParameterSetName="Date")]
+        [switch]$Date,
+        [Parameter(ParameterSetName="Time")]
+        [Switch]$Time
     )
 
-    $pfx = $($Prefix.ToUpper()).PadRight("process".length)
-    if ($Nodate) {
+    #$pfx = $($Prefix.ToUpper()).PadRight("process".length)
+    if ($time) {
         $dt = (Get-Date -Format "hh:mm:ss:ffff")
     }
+    elseif ($Date) {
+        $dt = "{0} {1}" -f (Get-Date).ToShortDateString(),(Get-Date -Format "hh:mm:ss")
+    }
+    
+    if ($PSCmdlet.ParameterSetName -eq 'Default') {
+        $Text = "[$($prefix.ToUpper())] $Message"
+
+    }
     else {
-        $dt = "{0} {1}" -f (Get-Date).ToShortDateString(),(Get-Date -Format "hh:mm:ss:ffff")
+        $Text = "$dt [$($prefix.toUpper())] $Message"
     }
-    $Text = "$dt [$pfx] $Message"
-    Write-Output $Text
+    $Text
 
 } #close Write-Detail
 

Write-Detail.ps1

@@ -1,5 +1,9 @@
 #Changelog for PSScriptTools
 
+v1.2.0
+Updated Write-Detail
+Updated README
+
 v1.1.0
 Cleaned up ToDo code (Issue #12)
 Updated README