pax_global_header00006660000000000000000000000064136272431060014516gustar00rootroot0000000000000052 comment=11d6c4a06bfce55854b349e360d35d549aa2be97 PSScriptTools-2.20.0/000077500000000000000000000000001362724310600143275ustar00rootroot00000000000000PSScriptTools-2.20.0/.github/000077500000000000000000000000001362724310600156675ustar00rootroot00000000000000PSScriptTools-2.20.0/.github/FUNDING.yml000066400000000000000000000012571362724310600175110ustar00rootroot00000000000000# These are supported funding model platforms github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2] patreon: # Replace with a single Patreon username open_collective: # Replace with a single Open Collective username ko_fi: # Replace with a single Ko-fi username tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry liberapay: # Replace with a single Liberapay username issuehunt: # Replace with a single IssueHunt username otechie: # Replace with a single Otechie username custom: https://paypal.me/jdhitsolutions?locale.x=en_US PSScriptTools-2.20.0/.github/ISSUE_TEMPLATE.md000066400000000000000000000004241362724310600203740ustar00rootroot00000000000000### PSVersion Table ### What is the syntax or expression you are using? ### What happens? ### What do you think should happen? PSScriptTools-2.20.0/PSScriptTools.psd1000066400000000000000000000332541362724310600176570ustar00rootroot00000000000000# # Module manifest for module 'PSScriptTools' # @{ # Script module or binary module file associated with this manifest. RootModule = 'PSScriptTools.psm1' # Version number of this module. ModuleVersion = '2.20.0' # Supported PSEditions CompatiblePSEditions = @('Desktop','Core') # ID used to uniquely identify this module GUID = 'f8deaba5-5c23-43aa-a59f-f508e7369a30' # Author of this module Author = 'Jeff Hicks' # Company or vendor of this module CompanyName = 'JDH Information Technology Solutions, Inc.' # Copyright statement for this module Copyright = '(c) 2017-2020 JDH Information Technology Solutions, Inc.' # Description of the functionality provided by this module Description = 'A set of of PowerShell functions you might use to enhance your own functions and scripts or to facilitate working in the console. Most should work in both Windows PowerShell and PowerShell 7, even cross-platform. Any operating system limitations should be handled on a per command basis.' # Minimum version of the Windows PowerShell engine required by this module PowerShellVersion = '5.1' # Name of the Windows PowerShell host required by this module # PowerShellHostName = '' # Minimum version of the Windows PowerShell host required by this module # PowerShellHostVersion = '' # Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only. # DotNetFrameworkVersion = '' # Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only. # CLRVersion = '' # Processor architecture (None, X86, Amd64) required by this module # ProcessorArchitecture = '' # Modules that must be imported into the global environment prior to importing this module # RequiredModules = @() # Assemblies that must be loaded prior to importing this module # RequiredAssemblies = @() # Script files (.ps1) that are run in the caller's environment prior to importing this module. # ScriptsToProcess = @() # Type files (.ps1xml) to be loaded when importing this module # TypesToProcess = @() # Format files (.ps1xml) to be loaded when importing this module FormatsToProcess = @( "formats\pslocation.format.ps1xml", "formats\windowsversion.format.ps1xml", "formats\timezonedata.format.ps1xml", "formats\whoisresult.format.ps1xml", "formats\foldersizeinfo.format.ps1xml", "formats\psscripttool.format.ps1xml", "formats\serviceansi.format.ps1xml", "formats\modulecommand.format.ps1xml" ) # Modules to import as nested modules of the module specified in RootModule/ModuleToProcess # NestedModules = @() # Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export. FunctionsToExport= @( 'Add-Border', 'Compare-Module', 'Convert-CommandToHashTable', 'Convert-EventLogRecord', 'ConvertFrom-Text', 'ConvertFrom-UTCTime', 'Convert-HashtableString', 'Convert-HashtableToCode', 'ConvertFrom-LexicalTimespan', 'ConvertTo-LexicalTimespan', 'Convertto-Hashtable', 'ConvertTo-LocalTime', 'ConvertTo-Markdown', 'ConvertTo-UTCTime', 'ConvertTo-WPFGrid', 'Copy-Command', 'Find-CimClass', 'Format-Percent', 'Format-String', 'Format-Value', 'Get-FileItem', 'Get-FolderSizeInfo', 'Get-ModuleCommand', 'Get-MyTimeInfo', 'Get-MyVariable', 'Get-ParameterInfo', 'Get-PowerShellEngine', 'Get-PSLocation', 'Get-PSScriptTools' 'Get-PSWho', 'Get-TZData', 'Get-TZList', 'Get-WhoIs', 'Get-WindowsVersion', 'Get-WindowsVersionString', 'Invoke-InputBox', 'Join-Hashtable', 'New-CustomFileName', 'New-PSDriveHere', 'New-PSFormatXML', 'New-RandomFileName', 'New-WPFMessageBox', 'Optimize-Text', 'Out-ConditionalColor', 'Out-More', 'Out-VerboseTee', 'Remove-Runspace', 'Remove-MergedBranch', 'Rename-Hashtable', 'Save-GitSetup', 'Select-First', 'Select-Last', 'Set-ConsoleColor', 'Set-ConsoleTitle', 'Show-Tree', 'Test-EmptyFolder', 'Test-Expression', 'Test-ExpressionForm', 'Test-IsPSWindows', 'Test-WithCulture', 'Write-Detail' ) # Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export. CmdletsToExport = @() # Variables to export from this module VariablesToExport = @() # Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export. AliasesToExport = @( 'first', 'last', 'Tee-Verbose', 'occ', 'pswho', 'cc', 'fv', 'fs', 'fp', 'om', 'ibx', 'tex', 'texf', 'ctm', 'cwg', 'gmv', 'npsd', 'ot', 'nmb', 'cmo', 'wver', 'nfx', 'gpi', 'frut', 'tout', 'gti', 'clt', 'pswhere', 'cft', 'clr', 'rht', 'tv', 'gsi', 'pstree', 'fcc', 'rmb', 'gmc', 'shtree', 'nfn', 'cfnhelp' ) # DSC resources to export from this module # DscResourcesToExport = @() # List of all modules packaged with this module # ModuleList = @() # List of all files packaged with this module # FileList = @() # Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell. PrivateData = @{ PSData = @{ # Tags applied to this module. These help with module discovery in online galleries. Tags = @('scripting','logging','filename','tools','formatdata','cim','hashtable','wpf','resourcekit') # A URL to the license for this module. LicenseUri = 'https://github.com/jdhitsolutions/PSScriptTools/blob/master/license.txt' # A URL to the main website for this project. ProjectUri = 'https://github.com/jdhitsolutions/PSScriptTools' # A URL to an icon representing this module. IconUri = 'https://github.com/jdhitsolutions/PSScriptTools/blob/master/images/psscripttools.png' # ReleaseNotes of this module ReleaseNotes = 'http://bit.ly/31XglKp ' } # End of PSData hashtable } # End of PrivateData hashtable # HelpInfo URI of this module # HelpInfoURI = '' # Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix. # DefaultCommandPrefix = '' } PSScriptTools-2.20.0/PSScriptTools.psm1000066400000000000000000000034101362724310600176570ustar00rootroot00000000000000#enable verbose messaging in the psm1 file if ($myinvocation.line -match "-verbose") { $VerbosePreference = "continue" } Write-Verbose "Loading public functions" Get-ChildItem -path $PSScriptRoot\functions\*.ps1 | ForEach-Object -process { Write-Verbose $_.fullname . $_.FullName } #add ToDo options to the ISE or VS Code if ($psEditor) { #This may not be working in newer versions of the PowerShell extension under PowerShell 7 Write-Verbose "Defining VSCode additions" $sb = { Param( [Microsoft.PowerShell.EditorServices.Extensions.EditorContext]$context ) $prompt = "What do you need to do?" $title = "To Do" $item = Invoke-Inputbox -Title $title -Prompt $prompt $todo = "# [$(Get-Date)] TODO: $item" $context.CurrentFile.InsertText($todo) } $rParams = @{ Name = "Insert.ToDo" DisplayName = "Insert ToDo" ScriptBlock = $sb SuppressOutput = $false } Register-EditorCommand @rParams } elseif ($psise) { Write-Verbose "Defining ISE additions" if ($psISE.CurrentPowerShellTab.AddOnsMenu.Submenus.DisplayName -notcontains "ToDo") { $action = { $prompt = "What do you need to do?" $title = "To Do" $item = Invoke-Inputbox -Title $title -Prompt $prompt $todo = "# [$(Get-Date)] TODO: $item" $psise.CurrentFile.Editor.InsertText($todo) #jump cursor to the end $psise.CurrentFile.editor.SetCaretPosition($psise.CurrentFile.Editor.CaretLine, $psise.CurrentFile.Editor.CaretColumn) } #add the action to the Add-Ons menu $psISE.CurrentPowerShellTab.AddOnsMenu.Submenus.Add("ToDo", $Action, "Ctrl+Alt+2" ) | Out-Null } } PSScriptTools-2.20.0/README.md000066400000000000000000001530321362724310600156120ustar00rootroot00000000000000# PSScriptTools [![PSGallery Version](https://img.shields.io/powershellgallery/v/PSScripttools.png?style=for-the-badge&logo=powershell&label=PowerShell%20Gallery)](https://www.powershellgallery.com/packages/PSScripttools/) [![PSGallery Downloads](https://img.shields.io/powershellgallery/dt/PSScripttools.png?style=for-the-badge&label=Downloads)](https://www.powershellgallery.com/packages/PSScripttools/) This PowerShell module contains a number of functions you might use to enhance your own functions and scripts. The [Samples](./samples) folder contains demonstration script files. ## Current Release You can get the current release from this repository or install this from the PowerShell Gallery: ```powershell Install-Module PSScriptTools ``` or in PowerShell 7: ```powershell Install-Module PSScriptTools -scope CurrentUser ``` Starting in v2.2.0, the module was restructured to better support Desktop and Core editions. But starting with version 2.13.0, the module design has reverted. All commands will be exported. Anything that is platform specific should be handled on a per command basis. It is assumed you will be running this module in Windows PowerShell 5.1 or PowerShell 7. ```powershell Uninstall-Module PSScriptTools -allversions ``` Please post any questions, problems or feedback in [Issues](https://github.com/jdhitsolutions/PSScriptTools/issues). Any input is greatly appreciated. ## General Tools ### [Get-ModuleCommand](docs/Get-ModuleCommand.md) This is an alternative to `Get-Command` to make it easier to see at a glance what commands are contained within a module and what they can do. By default, `Get-ModuleCommand` looks for loaded modules. Use `-ListAvailable` to see commands in module not currently loaded. Note that if the help file is malformed or missing, you might get oddly formatted results. ```powersehell PS C:\> Get-ModuleCommand PSCalendar Verb: Get Name Alias Type Synopsis ---- ----- ---- -------- Get-Calendar cal Function Displays a visual representation of a ... Verb: Show Name Alias Type Synopsis ---- ----- ---- -------- Show-Calendar scal Function Display a colorized calendar month in ... Show-GuiCalendar gcal Function Display a WPF-based calendar ``` Get module commands using the default formatted view. There is also a default view for `Format-List`. ### [Get-PSScriptTools](docs/Get-PSScriptTools.md) You can use this command to get a summary list of functions in this module. ```powershell PS C:\> Get-PSScriptTools Verb: Add Name Alias Synopsis ---- ----- -------- Add-Border Create a text border around a string. Verb: Compare Name Alias Synopsis ---- ----- -------- Compare-Module cmo Compare PowerShell module versions. Verb: Convert Name Alias Synopsis ---- ----- -------- Convert-CommandtoHashtable Convert a PowerShell expression into a hashtable. Convert-EventLogRecord clr Convert EventLogRecords to structured objects Convert-HashtableString Convert a hashtable string into a hashtable object. Convert-HashTableToCode Convert a hashtable to a string representation. ... ``` Here's another way you could use this command to list functions with defined aliases in the PSScriptTools module. ```powershell PS C:\> Get-PSScriptTools | Where-object alias | Select-Object Name,alias,Synopsis Name Alias Synopsis ---- ----- -------- Compare-Module cmo Compare PowerShell module versions. Convert-EventLogRecord clr Convert EventLogRecords to structured objects ConvertFrom-Text cft Convert structured text to objects. ConvertFrom-UTCTime frut Convert a datetime value from universal ConvertTo-LocalTime clt Convert a foreign time to local ... ``` ### [Convert-EventLogRecord](docs/Convert-EventLogRecord.md) When you use [Get-WinEvent](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.diagnostics/get-winevent?view=powershell-7&WT.mc_id=ps-gethelp), the results are objects you can work with in PowerShell. However, often times there is additional information that is part of the eventlog record, such as replacement strings, that are used to construct a message. This additional information is not readily exposed. You can use this command to convert results of a Get-WinEvent command into a PowerShell custom object with additional information. ```powershell PS C:\> get-winevent -FilterHashtable @{Logname='System';ID=7045} -MaxEvents 1 | Convert-EventLogRecord LogName : System RecordType : Information TimeCreated : 1/21/2020 3:49:46 PM ID : 7045 ServiceName : Netwrix Account Lockout Examiner ImagePath : "C:\Program Files (x86)\Netwrix\Account Lockout Examiner\ALEService.exe" ServiceType : user mode service StartType : auto start AccountName : bovine320\jeff Message : A service was installed in the system. Service Name: Netwrix Account Lockout Examiner Service File Name: "C:\Program Files (x86)\Netwrix\Account Lockout Examiner\ALEService.exe" Service Type: user mode service Service Start Type: auto start Service Account: bovine320\jeff Keywords : {Classic} Source : Service Control Manager Computername : Bovine320 ``` ### [Get-WhoIs](docs/Get-WhoIs.md) This command will retrieve WhoIs information from the ARIN database for a given IPv4 address. ```powershell PS C:\> get-whois 208.67.222.222 | select-object -Property * IP : 208.67.222.222 Name : OPENDNS-NET-1 RegisteredOrganization : Cisco OpenDNS, LLC City : San Francisco StartAddress : 208.67.216.0 EndAddress : 208.67.223.255 NetBlocks : 208.67.216.0/21 Updated : 3/2/2012 8:03:18 AM PS C:\> '1.1.1.1','8.8.8.8','208.67.222.222'| get-whois Name IP RegisteredOrganization NetBlocks Updated ---- -- ---------------------- --------- ------- APNIC-1 1.1.1.1 Asia Pacific Network Information Centre 1.0.0.0/8 7/30/2010 8:23:43 AM LVLT-GOGL-8-8-8 8.8.8.8 Google LLC 8.8.8.0/24 3/14/2014 3:52:05 PM OPENDNS-NET-1 208.67.222.222 Cisco OpenDNS, LLC 208.67.216.0/21 3/2/2012 8:03:18 AM ``` This module includes a custom format file for these results. ### [Compare-Module](docs/Compare-Module.md) Use this command to compare module versions between what is installed against an online repository like the PSGallery ```powershell PS C:\> Compare-Module Platyps Name : platyPS OnlineVersion : 0.14.0 InstalledVersion : 0.14.0,0.12.0,0.11.1,0.10.2,0.9.0 PublishedDate : 4/3/2019 12:46:30 AM UpdateNeeded : False ``` Or you can compare and manage multiple modules. ```powershell PS C:\> Compare-Module | Where UpdateNeeded | Out-Gridview -title "Select modules to update" -outputMode multiple | Foreach { Update-Module $_.name } ``` This example compares modules and send results to `Out-Gridview`. Use `Out-Gridview` as an object picker to decide what modules to update. ### [Get-WindowsVersion](docs/Get-WindowsVersion.md) This is a PowerShell version of the `winver.exe` utility. This command uses PowerShell remoting to query the registry on a remote machine to retrieve Windows version information. ```powershell Computername: WIN10 ProductName EditionID ReleaseID Build InstalledUTC ----------- --------- --------- ----- ------------ Windows 10 Enterprise EnterpriseEval 1903 18362 2/6/2020 5:28:34 PM Evaluation Computername: SRV1 ProductName EditionID ReleaseID Build InstalledUTC ----------- --------- --------- ----- ------------ Windows Server 2016 Standard ServerStandardEval 1607 14393 2/6/2020 5:27:42 PM Evaluation Computername: SRV2 ProductName EditionID ReleaseID Build InstalledUTC ----------- --------- --------- ----- ------------ Windows Server 2016 Standard ServerStandardEval 1607 14393 2/6/2020 5:28:13 PM Evaluation ``` The output has a default table view but there are other properties you might want to use. ```powershell PS C:\> get-windowsversion | Select-object * ProductName : Windows 10 Pro EditionID : Professional ReleaseID : 1909 Build : 18363.657 Branch : 19h1_release InstalledUTC : 7/5/2019 10:54:49 PM Computername : BOVINE320 ``` #### [Get-WindowsVersionString](docs/Get-WindowsVersionString.md) This command is a variation of `Get-WindowsVersion` that returns a formatted string with version information. ```powershell PS C:\> Get-WindowsVersionString BOVINE320 Windows 10 Pro Version Professional (OS Build 18363.657) ``` ### [New-PSDriveHere](docs/New-PSDriveHere.md) This function will create a new PSDrive at the specified location. The default is the current location, but you can specify any PSPath. The function will take the last word of the path and use it as the name of the new PSDrive. ```powershell PS C:\users\jeff\documents\Enterprise Mgmt Webinar> new-psdrivehere Name Used (GB) Free (GB) Provider Root CurrentLocation ---- --------- --------- -------- ---- --------------- Webinar 146.57 FileSystem C:\users\jeff\Documents\Enter... ``` ### [Get-MyVariable](docs/Get-MyVariable.md) This function will return all variables not defined by PowerShell or by this function itself. The default is to return all user-created variables from the global scope but you can also specify a scope such as script, local or a number 0 through 5. ```powershell PS C:\> Get-MyVariable NName Value Type ---- ----- ---- a bits ServiceController dt 10/22/2018 10:49:38 AM DateTime foo 123 Int32 r {1, 2, 3, 4...} Object[] ... ``` Depending on the value and how PowerShell chooses to display it, you may not see the type. ### [ConvertFrom-Text](docs/ConvertFrom-Text.md) This command can be used to convert text from a file or a command line tool into objects. It uses a regular expression pattern with named captures and turns the result into a custom object. You have the option of specifying a typename in case you are using custom format files. ```powershell PS C:\> $arp = '(?(\d{1,3}\.){3}\d{1,3})\s+(?(\w{2}-){5}\w{2})\s+(?\w+$)' PS C:\> arp -g -N 172.16.10.22 | select -skip 3 | foreach {$_.Trim()} | ConvertFrom-Text $arp -TypeName arpData -NoProgress IPAddress MAC Type --------- --- ---- 172.16.10.1 b6-fb-e4-16-41-be dynamic 172.16.10.100 00-11-32-58-7b-10 dynamic 172.16.10.115 5c-aa-fd-0c-bf-fa dynamic 172.16.10.120 5c-1d-d9-58-81-51 dynamic 172.16.10.159 3c-e1-a1-17-6d-0a dynamic 172.16.10.162 00-0e-58-ce-8b-b6 dynamic 172.16.10.178 00-0e-58-8c-13-ac dynamic 172.16.10.185 d0-04-01-26-b5-61 dynamic 172.16.10.186 e8-b2-ac-95-92-98 dynamic 172.16.10.197 fc-77-74-9f-f4-2f dynamic 172.16.10.211 14-20-5e-93-42-fb dynamic 172.16.10.222 28-39-5e-3b-04-33 dynamic 172.16.10.226 00-0e-58-e9-49-c0 dynamic 172.16.10.227 48-88-ca-e1-a6-00 dynamic 172.16.10.239 5c-aa-fd-83-f1-a4 dynamic 172.16.255.255 ff-ff-ff-ff-ff-ff static 224.0.0.2 01-00-5e-00-00-02 static 224.0.0.7 01-00-5e-00-00-07 static 224.0.0.22 01-00-5e-00-00-16 static 224.0.0.251 01-00-5e-00-00-fb static 224.0.0.252 01-00-5e-00-00-fc static 239.255.255.250 01-00-5e-7f-ff-fa static ``` This example uses a previously created and import format.ps1xml file for the custom type name. ### [Get-PSWho](docs/Get-PSWho.md) 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 : BOVINE320\Jeff Elevated : True Computername : BOVINE320 OperatingSystem : Microsoft Windows 10 Pro [64-bit] OSVersion : 10.0.18363 PSVersion : 5.1.18362.145 Edition : Desktop PSHost : ConsoleHost WSMan : 3.0 ExecutionPolicy : RemoteSigned Culture : English (United States) ``` ### [Find-CimClass](docs/Find-CimClass.md) This function is designed to search an entire CIM repository for a class name. Sometimes, you may have a guess about a class name but not know the full name or even the correct namespace. `Find-CimClass` will recursively search for a given classname. You can use wildcards and search remote computers. ![find-cimclass](images/find-cimclass.png) ### [Out-VerboseTee](docs/Out-VerboseTee.md) 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 aliases of `Tee-Verbose` and `tv`. ```powershell Begin { $log = New-RandomFilename -useTemp -extension log Write-Detail "Starting $($myinvocation.mycommand)" -Prefix begin | Tee-Verbose $log Write-Detail "Logging verbose output to $log" -prefix begin | Tee-Verbose -append Write-Detail "Initializing data array" -Prefix begin | Tee-Verbose $log -append $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. ### [Remove-Runspace](docs/Remove-Runspace.md) During the course of your PowerShell work, you may discover that some commands and scripts can leave behind runspaces such as `ConvertTo-WPFGrid`. You may even deliberately be creating additional runspaces. These runspaces will remain until you exit your PowerShell session. Or use this command to cleanly close and dispose of runspaces. ```powershell PS C:\> Get-RunSpace | where ID -gt 1 | Remove-RunSpace ``` Get all runspaces with an ID greater than 1, which is typically your current session, and remove the runspace. ### [Get-PSLocation](docs/Get-PSLocation.md) A simple function to get common locations. This can be useful with cross-platform scripting. ![windows locations](./images/pslocation-win.png) ![linux locations](./images/pslocation-linux.png) ### [Get-PowerShellEngine](docs/Get-PowerShellEngine.md) 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 on non-Windows platforms is a bit different: ```powershell PS /home/jhicks> Get-PowerShellEngine /opt/microsoft/powershell/7/pwsh ``` You can also get detailed information. ![Windows PowerShell](./images/get-powershellengine1.png) ![PowerShell Core on Windows](./images/get-powershellengine2.png) ![PowerShell Core on Linux](./images/get-powershellengine3.png) Results will vary depending on whether you are running PowerShell on Windows nor non-Windows systems. ## File Tools ### [Test-EmptyFolder](docs/Test-EmptyFolder.md) This command will test if a given folder path is empty of all files anywhere in the path. This includes hidden files. The command will return True even if there are empty sub-folders. The default output is True or False but you can use -Passthru to get more information. ```powershell PS C:\> Get-Childitem c:\work -Directory | test-EmptyFolder -passthru | Where-object {$_.Isempty} | Foreach-Object { Remove-Item -LiteralPath $_.path -Recurse -force -whatif} What if: Performing the operation "Remove Directory" on target "C:\work\demo3". What if: Performing the operation "Remove Directory" on target "C:\work\installers". What if: Performing the operation "Remove Directory" on target "C:\work\new". What if: Performing the operation "Remove Directory" on target "C:\work\sqlback". What if: Performing the operation "Remove Directory" on target "C:\work\todd". What if: Performing the operation "Remove Directory" on target "C:\work\[data]". ``` Find all empty sub-folders under C:\Work and pipe them to Remove-Item. This is one way to remove empty folders. The example is piping objects to ForEach-Object so that Remove-Item can use the -LiteralPath parameter, because C:\work\[data] is a non-standard path. ### [Get-FolderSizeInfo](docs/Get-FolderSizeInfo.md) Use this command to quickly get the size of a folder. You also have an option to include hidden files. The command will measure all files in all subdirectories. ```powershell PS C:\> get-foldersizeinfo c:\work Computername Path TotalFiles TotalSize ------------ ---- ---------- --------- BOVINE320 C:\work 931 137311146 PS C:\> get-foldersizeinfo c:\work -Hidden Computername Path TotalFiles TotalSize ------------ ---- ---------- --------- BOVINE320 C:\work 1375 137516856 ``` The command includes a format file with additional view to display the total size in KB, MB or GB. ```powershell PS C:\> Get-Childitem D:\ -Directory | Get-FolderSizeInfo -Hidden | Where-Object TotalSize -gt 1gb | Sort-Object TotalSize -Descending | format-table -View gb Computername Path TotalFiles TotalSizeGB ------------ ---- ---------- ----------- BOVINE320 D:\Autolab 159 137.7192 BOVINE320 D:\VMDisks 18 112.1814 BOVINE320 D:\ISO 17 41.5301 BOVINE320 D:\FileHistory 104541 36.9938 BOVINE320 D:\Vagrant 13 19.5664 BOVINE320 D:\Vms 83 5.1007 BOVINE320 D:\2016 1130 4.9531 BOVINE320 D:\video 125 2.592 BOVINE320 D:\blog 21804 1.1347 BOVINE320 D:\pstranscripts 122092 1.0914 ``` Or you can use the `name` view. ```powershell PS C:\> Get-Childitem c:\work -Directory | Get-FolderSizeInfo -Hidden | Where-Object {$_.totalsize -ge 2mb} | Format-Table -view name Path: C:\work Name TotalFiles TotalKB ---- ---------- ------- A 20 5843.9951 keepass 15 5839.084 PowerShellBooks 26 4240.3779 sunday 47 24540.6523 ``` ### [Optimize-Text](docs/Optimize-Text.md) Use this command to clean and optimize content from text files. Sometimes text files have blank lines or the content has trailing spaces. These sorts of issues can cause problems when passing the content to other commands. This command will strip out any lines that are blank or have nothing by white space, and trim leading and trailing spaces. The optimized text is then written back to the pipeline. Optionally, you can specify a property name. This can be useful when your text file is a list of computer names and you want to take advantage of pipeline binding. ### [Get-FileItem](docs/Get-FileItem.md) A PowerShell version of the CLI `where.exe` command. You can search with a simple or regex pattern. ```powershell PS C:\> pswhere winword.exe -Path c:\ -Recurse -first C:\Program Files\Microsoft Office\root\Office16\WINWORD.EXE ``` Note that you might see errors for directories where you don't have access permission. This is normal. ### [New-CustomFileName](docs/New-CustomFileName.md) 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_28Nov19-142138.log PS C:\> New-CustomFileName %dayofweek-%####.dat Tuesday-3128.dat ``` You can create a template string using any of these variables. Most of these should be self-explanatory - %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 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](docs/New-RandomFileName.md) 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 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 ``` ### [ConvertTo-Markdown](docs/ConvertTo-Markdown.md) This command is designed to accept pipelined output and create a markdown document. The pipeline output will formatted as a text block or a table You can optionally define a title, content to appear before the output and content to appear after the output. You can run a command like this: ```powershell Get-Service Bits,Winrm | Convertto-Markdown -title "Service Check" -precontent "## $($env:computername)" -postcontent "_report $(Get-Date)_" ``` which generates this markdown: ```markdown # Service Check ## BOVINE320 ```text Status Name DisplayName ------ ---- -----------+ Running Bits Background Intelligent Transfer Ser... Running Winrm Windows Remote Management (WS-Manag... ``` _report 09/25/2019 09:57:12_ ``` Because the function writes markdown to the pipeline you will need to pipe it to a command `Out-File` to create a file. ## 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: ```text # [12/13/2018 16:52:40] TODO: Add parameters ``` In the PowerShell ISE, you will get a new menu under Add-Ons. ![new menu](./images/todo-1.png) You can use the menu or keyboard shortcut which will launch an input box. ![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. ## [Test-Expression](docs/Test-Expression.md) The primary command can be used to test a PowerShell expression or scriptblock for a specified number of times and calculate the average runtime, in milliseconds, over all the tests. ### Why When you run a single test with `Measure-Command` the result might be affected by any number of factors. Likewise, running multiple tests may also be influenced by things such as caching. The goal in this module is to provide a test framework where you can run a test repeatedly with either a static or random interval between each test. The results are aggregated and analyzed. Hopefully, this will provide a more meaningful or realistic result. ### Examples The output will also show the median and trimmed values as well as some metadata about the current PowerShell session. ```powershell PS C:\> $cred = Get-credential globomantics\administrator PS C:\> Test-Expression {param($cred) get-wmiobject win32_logicaldisk -computer chi-dc01 -credential $cred } -argumentList $cred Tests : 1 TestInterval : 0.5 AverageMS : 1990.6779 MinimumMS : 1990.6779 MaximumMS : 1990.6779 MedianMS : 1990.6779 TrimmedMS : PSVersion :5.1.17763.134 OS : Microsoft Windows 10 Pro ``` You can also run multiple tests with random time intervals. ```powershell PS C:\>Test-Expression {param([string[]]$Names) get-service $names} -count 5 -IncludeExpression -argumentlist @('bits','wuauserv','winrm') -RandomMinimum .5 -RandomMaximum 5.5 Tests : 5 TestInterval : Random AverageMS : 1.91406 MinimumMS : 0.4657 MaximumMS : 7.5746 MedianMS : 0.4806 TrimmedMS : 0.51 PSVersion : 5.1.17763.134 OS : Microsoft Windows 10 Pro Expression : param([string[]]$Names) get-service $names Arguments : {bits, wuauserv, winrm} ``` For very long running tests, you can run them as a background job. ### Graphical Testing The module also includes a graphical command called `Test-ExpressionForm`. This is intended to serve as both an entry and results form. ![Test Expression](images/testexpressionform.png) When you quit the form the last result will be written to the pipeline including all metadata, the scriptblock and any arguments. ## Graphical Tools ### [Invoke-InputBox](docs/Invoke-InputBox.md) 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" ``` ![input box](./images/ibx-1.png) You can also capture a secure string. ```powershell Invoke-Inputbox -Prompt "Enter a password for $Name" -AsSecureString -BackgroundColor red ``` ![secure input box](./images/ibx-2.png) This example also demonstrates that you can change form's background color. This function will **not** work in PowerShell Core. ### [New-WPFMessageBox](docs/New-WPFMessageBox.md) This function creates a Windows Presentation Foundation (WPF) based message box. This is intended to replace the legacy MsgBox function from VBScript and the Windows Forms library. The command uses a set of predefined button sets, each of which will close the form and write a value to the pipeline. - OK = 1 - Cancel = 0 - Yes = $True - No = $False You can also create an ordered hashtable of your own buttons and values. It is assumed you will typically use this function in a script where you can capture the output and take some action based on the value. ```powershell PS C:\> New-WPFMessageBox -Message "Are you sure you want to do this?" -Title Confirm -Icon Question -ButtonSet YesNo ``` ![A YesNo WPF Message box](/images/wpfbox-1.png) You can also create your own custom button set as well as modify the background color. ```powershell PS C:\> New-WPFMessageBox -Message "Select a system option from these choices:" -Title "You Decide" -Background cornsilk -Icon Warning -CustomButtonSet ([ordered]@{"Reboot"=1;"Shutdown"=2;"Cancel"=3}) ``` ![A customized WPF Message box](/images/wpfbox-2.png) ### [ConvertTo-WPFGrid](docs/ConvertTo-WPFGrid.md) This command is an alternative to `Out-Gridview`. It works much the same way. Run a PowerShell command and pipe it to this command. The output will be displayed in an auto-sized data grid. You can click on column headings to sort. You can resize columns and you can re-order columns. ```powershell get-eventlog -list -ComputerName DOM1,SRV1,SRV2 | Select Machinename,Log,MaximumKilobytes,Overflowaction, @{Name="RetentionDays";Expression={$_.MinimumRetentionDays}}, @{Name="Entries";Expression = {$_.entries.count}} | ConvertTo-WPFGrid -Title "Event Log Report" ``` ![Displaying Eventlog Info](images/wpfgrid.png) You can also have automatically refresh the data. ```powershell get-process | sort-object WS -Descending | Select -first 20 ID,Name,WS,VM,PM,Handles,StartTime | Convertto-WPFGrid -Refresh -timeout 20 -Title "Top Processes" ``` ![Displaying Top Processes](images/wpfgrid2.png) Note that in v2.4.0 the form layout was modified and may not be reflected in these screen shots. ## Hashtable Tools ### [Convert-CommandtoHashtable](docs/Convert-CommandtoHashtable.md) This command is intended to convert a long PowerShell expression with named parameters into a splatting alternative. ```powershell PS C:\> Convert-CommandtoHashtable -Text "get-eventlog -listlog -computername a,b,c,d -erroraction stop" $paramHash = @{ listlog = $True computername = "a","b","c","d" erroraction = "stop" } Get-EventLog @paramHash ``` ### [Convert-HashtableString](docs/Convert-HashtableString.md) This function is similar to `Import-PowerShellDataFile`. But where that command can only process a file, this command will take any hashtable-formatted string and convert it into an actual hashtable. ```powershell PS C:\> get-content c:\work\test.psd1 | unprotect-cmsmessage | Convert-HashtableString Name Value ---- ----- CreatedBy BOVINE320\Jeff CreatedAt 10/02/2018 21:28:47 UTC Computername Think51 Error Completed True Date 10/02/2018 21:29:35 UTC Scriptblock restart-service spooler -force CreatedOn BOVINE320 ``` The test.psd1 file is protected as a CMS Message. In this example, the contents are decoded as a string which is then in turn converted into an actual hashtable. ### [Convert-HashTableToCode](docs/Convert-HashTableToCode.md) Use this command to convert a hashtable into its text or string equivalent. ```powershell PS C:\> $h = @{Name="SRV1";Asset=123454;Location="Omaha"} PS C:\> convert-hashtabletocode $h @{ Name = 'SRV1' Asset = 123454 Location = 'Omaha' } ``` Convert a hashtable object to a string equivalent that you can copy into your script. ### [ConvertTo-HashTable](docs/ConvertTo-HashTable.md) This command will take an object and create a hashtable based on its properties. You can have the hashtable exclude some properties as well as properties that have no value. ```powershell PS C:\> Get-Process -id $pid | select name,id,handles,workingset | ConvertTo-HashTable Name Value ---- ----- WorkingSet 418377728 Name powershell_ise Id 3456 Handles 958 ``` ### [Join-HashTable](docs/Join-HashTable.md) This command will combine two hashtables into a single hashtable.Join-Hashtable will test for duplicate keys. If any of the keys from the first, or primary hashtable are found in the secondary hashtable, you will be prompted for which to keep. Or you can use -Force which will always keep the conflicting key from the first hashtable. ```powershell PS C:\> $a=@{Name="Jeff";Count=3;Color="Green"} PS C:\> $b=@{Computer="HAL";Enabled=$True;Year=2020;Color="Red"} PS C:\> join-hashtable $a $b Duplicate key Color A Green B Red Which key do you want to KEEP \[AB\]?: A Name Value ---- ----- Year 2020 Name Jeff Enabled True Color Green Computer HAL Count 3 ``` ### [Rename-Hashtable](docs/Rename-HashTable.md) This command allows you to rename a key in an existing hashtable or ordered dictionary object. ```powershell PS C:\> $h = Get-Service Spooler | ConvertTo-HashTable ``` The hashtable in $h has Machinename property which can be renamed. ```powershell PS C:\> Rename-HashTable -Name h -Key Machinename -NewKey Computername -Passthru Name Value ---- ----- ServiceType Win32OwnProcess, InteractiveProcess ServiceName Spooler Container CanPauseAndContinue False RequiredServices {RPCSS, http} ServicesDependedOn {RPCSS, http} Computername . CanStop True StartType Automatic Site ServiceHandle SafeServiceHandle DisplayName Print Spooler CanShutdown False Status Running Name Spooler DependentServices {Fax} ``` ## Select Functions The module contains 2 functions which simplify the use of `Select-Object`. The commands are intended to make it easier to select the first or last X number of objects. The commands include features so that you can sort the incoming objects on a given property first. ```powershell PS C:\> get-process | select-first 5 -Property WS -Descending Handles NPM(K) PM(K) WS(K) CPU(s) Id SI ProcessName ------- ------ ----- ----- ------ -- -- ----------- 696 89 615944 426852 391.97 7352 0 sqlservr 541 78 262532 274576 278.41 6208 8 Code 1015 70 227824 269504 137.39 16484 8 powershell_ise 1578 111 204852 254640 98.58 21332 8 firefox 884 44 221872 245712 249.23 12456 8 googledrivesync ``` ## Time Functions The module has a few date and time related commands. ### [ConvertTo-UTCTime](docs/ConvertTo-UTCTime.md) Convert a local datetime value to universal time. The default is to convert now but you can specify a datetime value. ```powershell PS C:\> ConvertTo-UTCTime Monday, March 4, 2019 5:51:26 PM ``` Convert a datetime that is UTC-5 to universal time. ### [ConvertFrom-UTCTime](docs/ConvertFrom-UTCTime.md) ```powershell PS C:\> ConvertFrom-UTCTime "3/4/2019 6:00PM" Monday, March 4, 2019 1:00:00 PM ``` Convert a universal datetime to the local time. ### [Get-MyTimeInfo](docs/Get-MyTimeInfo.md) Display a time settings for a collection of locations. This command is a PowerShell equivalent of a world clock. It will display a datetime value against a collection of locations. You can specify an ordered hashtable of locations and time zones. You can run command like: ```powershell [System.TimeZoneinfo]::GetSystemTimeZones() | out-gridview ``` or ```powershell Get-TimeZone -listavailable ``` To discover time zone names. Note that the ID is case-sensitive. You can then use the command like this: ```powershell PS C:\> Get-MyTimeInfo -Locations ([ordered]@{Seattle="Pacific Standard time";"New Zealand" = "New Zealand Standard Time"}) -HomeTimeZone "central standard time" | Select Now,Home,Seattle,'New Zealand' Now Home Seattle New Zealand --- ---- ------- ----------- 3/4/2019 1:18:36 PM 3/4/2019 12:18:36 PM 3/4/2019 10:18:36 AM 3/5/2019 7:18:36 AM ``` This is a handy command when traveling and your laptop is using a locally derived time and you want to see the time in other locations. It is recommended that you set a PSDefaultParameter value for the HomeTimeZone parameter in your PowerShell profile. ### [ConvertTo-LocalTime](docs/ConvertTo-LocalTime.md) It can be tricky sometimes to see a time in a foreign location and try to figure out what that time is locally. This command attempts to simplify this process. In addition to the remote time, you need the base UTC offset for the remote location. ```powershell PS C:\> get-timezone -ListAvailable | where id -match hawaii Id : Hawaiian Standard Time DisplayName : (UTC-10:00) Hawaii StandardName : Hawaiian Standard Time DaylightName : Hawaiian Daylight Time BaseUtcOffset : -10:00:00 SupportsDaylightSavingTime : False PS C:\> Convertto-LocalTime "10:00AM" -10:00:00 Thursday, March 14, 2019 4:00:00 PM ``` In this example, the user if first determining the UTC offset for Hawaii. Then 10:00AM in say Honolulu, is converted to local time which in this example is in the Eastern Time zone. ### [Get-TZList](docs/Get-TZList.md) This command uses a free and publicly available REST API offered by [http://worldtimeapi.org](http://worldtimeapi.org) to get a list of time zone areas. You can get a list of all areas or by geographic location. Use Get-TZData to then retrieve details. ```powershell PS S:\PSScriptTools> get-tzlist Australia Australia/Adelaide Australia/Brisbane Australia/Broken_Hill Australia/Currie Australia/Darwin Australia/Eucla Australia/Hobart Australia/Lindeman Australia/Lord_Howe Australia/Melbourne Australia/Perth Australia/Sydney ``` ### [Get-TZData](docs/Get-TZData.md) This command also uses the API from worldtimeapi.org to retrieve details about a give time zone area. ```powershell PS C:\> Get-TZData Australia/Hobart Timezone Label Offset DST Time -------- ----- ------ --- ---- Australia/Hobart AEDT 11:00:00 True 3/16/2019 3:43:14 AM ``` The Time value is the current time at the remote location. The command presents a formatted object but you can also get the raw data. ```powershell PS C:\> Get-TZData Australia/Hobart -Raw week_number : 11 utc_offset : +11:00 unixtime : 1552668285 timezone : Australia/Hobart dst_until : 2019-04-06T16:00:00+00:00 dst_from : 2018-10-06T16:00:00+00:00 dst : True day_of_year : 75 day_of_week : 6 datetime : 2019-03-16T03:44:45.689655+11:00 abbreviation : AEDT ``` ### [ConvertTo-LexicalTime](docs/ConvertTo-LexicalTime.md) When working with timespans or durations in XML files, such as those from scheduled tasks, the format is a little different than what you mgiht expect. The specification is described at [https://www.w3.org/TR/xmlschema-2/#duration](https://www.w3.org/TR/xmlschema-2/#duration). Use this command to convert a timespan into a lexical format you can use in an XML file where you need to specify a duration. ```powershell ConvertTo-LexicalTimespan (New-TimeSpan -Days 7 -hours 12) P7DT12H ``` ### [ConvertFrom-LexicalTime](docs/ConvertFrom-LexicalTime.md) Likewise, you might need to convert a lexical value back into a timespan. ```powershell ConvertFrom-LexicalTimespan P7DT12H Days : 7 Hours : 12 Minutes : 0 Seconds : 0 Milliseconds : 0 Ticks : 6480000000000 TotalDays : 7.5 TotalHours : 180 TotalMinutes : 10800 TotalSeconds : 648000 TotalMilliseconds : 648000000 ``` These functions were first described at [https://jdhitsolutions.com/blog/powershell/7101/converting-lexical-timespans-with-powershell/](https://jdhitsolutions.com/blog/powershell/7101/converting-lexical-timespans-with-powershell/) ## Console Utilities ### [Out-More](docs/Out-More.md) 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 ``` ![out-more](./images/out-more.png) This also works in PowerShell Core. ### [Out-ConditionalColor](docs/Out-ConditionalColor.md) 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. ![out-conditionalcolor-1](./images/occ-1.png) Or you can specify an ordered hashtable for more complex processing. ![out-conditionalcolor-2](./images/occ-2.png) 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. ### [Set-ConsoleTitle](docs/Set-ConsoleTitle.md) Set the title bar of the current PowerShell console window. ```powershell PS C:\> if (Test-IsAdministrator) { Set-ConsoleTitle "Administrator: $($PSVersionTable.PSedition) $($PSVersionTable.PSVersion)" -Verbose } VERBOSE: [10:33:17.0420820 BEGIN ] Starting Set-ConsoleTitle VERBOSE: [10:33:17.0440568 PROCESS] Setting console title to Administrator: Desktop 5.1.17763.316 VERBOSE: Performing the operation "Set-ConsoleTitle" on target "Administrator: Desktop 5.1.17763.316". VERBOSE: [10:33:17.0584056 END ] Ending Set-ConsoleTitle ``` ### [Set-ConsoleColor](docs/Set-ConsoleColor.md) Configure the foreground or background color of the current PowerShell console window. Note that if you are running the PSReadline module, this command won't work. You should use `Set-PSReadlineOption` or similar command to configure your session settings. ```powershell PS C:\> Set-ConsoleColor -background DarkGray -foreground Yellow ``` ### [Add-Border](docs/Add-Border.md) 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 ************* * COWPC * ************* ``` ### [Show-Tree](docs/Show-Tree.md) Shows the specified path as a graphical tree in the console. This is intended as PowerShell alternative to the tree DOS command. This function should work for any type of PowerShell provider and can be used to explore providers used for configuration like the WSMan provider or the registry. By default, the output will only show directory or equivalent structures. But you can opt to include items well as item details. ![show file system tree](images/show-tree1.png) If you are running PowerShell 7 and specifying a file system path, you can display the tree in a colorized format by using the `-InColor` dynamic parameter. ![show file system tree](images/show-tree2.png) I have long term plans to have a user-configurable color map for different item types. This command has an alias of `pstree`. ```powershell PS C:\> pstree c:\work\alpha -files -properties LastWriteTime,Length C:\work\Alpha\ +-- LastWriteTime = 02/28/2020 11:19:32 +--bravo | +-- LastWriteTime = 02/28/2020 11:20:30 | +--delta | | +-- LastWriteTime = 02/28/2020 11:17:35 | | +--FunctionDemo.ps1 | | | +-- Length = 888 | | | \-- LastWriteTime = 06/01/2009 15:50:47 | | +--function-form.ps1 | | | +-- Length = 1117 | | | \-- LastWriteTime = 04/17/2019 17:18:28 | | +--function-logstamp.ps1 | | | +-- Length = 598 | | | \-- LastWriteTime = 05/23/2007 11:39:55 | | +--FunctionNotes.ps1 | | | +-- Length = 617 | | | \-- LastWriteTime = 02/24/2016 08:59:03 | | \--Function-SwitchTest.ps1 | | +-- Length = 242 | | \-- LastWriteTime = 06/09/2008 15:55:44 | +--gamma ... ``` Show a tree listing with files including a few properties. This example is using parameter and command aliases. ## Format-Functions A set of simple commands to make it easier to format values. ### [Format-Percent](docs/Format-Percent.md) Treat a value as a percentage. This will write a [double] and not include the % sign. ```powershell PS C:\> format-percent -Value 123.5646MB -total 1GB -Decimal 4 12.0669 ``` ### [Format-String](docs/Format-String.md) Use this command to perform one of several string manipulation "tricks". ```powershell PS C:\> format-string "powershell" -Reverse -Case Proper Llehsrewop PS C:\> format-string PowerShell -Randomize wSlhoeePlr PS C:\> format-string "!MySecretPWord" -Randomize -Replace @{S="$";e=&{Get-Random -min 1 -max 9};o="^"} -Reverse yr7!^7WcMtr$Pd ``` ### [Format-Value](docs/Format-Value.md) This command will format a given numeric value. By default it will treat the number as an integer. Or you can specify a certain number of decimal places. The command will also allow you to format the value in KB, MB, etc. ```powershell PS C:\> format-value 1235465676 -Unit kb 1206509 PS C:\> format-value 123.45 -AsCurrency $123.45 PS C:\> (get-process | measure ws -sum).sum | format-value -Unit mb | format-value -AsNumber 9,437 ``` Or pull it all together: ```powershell PS C:\> Get-CimInstance win32_operatingsystem | select-object @{Name = "TotalMemGB";Expression={Format-Value $_.TotalVisibleMemorySize -Unit mb}}, @{Name="FreeMemGB";Expression={Format-Value $_.FreePhysicalMemory -unit mb -Decimal 2}}, @{Name="PctFree";Expression={Format-Percent -Value $_.FreePhysicalMemory -Total $_.totalVisibleMemorySize -Decimal 2}} TotalMemGB FreeMemGB PctFree ---------- --------- ------- 32 14.05 44.06 ``` ## Scripting Tools ### [Remove-MergedBranch](docs/Remove-MergedBranch.md) When using git you may create a number of branches. Presumably you merge these branches into the main or master branch. You can this command to remove all merged branches other than master and the current branch. You must be in the root of your project to run this command. ```powershell PS C:\MyProject> Remove-MergedBranch Remove merged branch from MyProject? 2.1.1 [Y] Yes [N] No [S] Suspend [?] Help (default is "Y"): n Remove merged branch from MyProject? dev1 [Y] Yes [N] No [S] Suspend [?] Help (default is "Y"): y Deleted branch dev1 (was 75f6ab8). Remove merged branch from MyProject? dev2 [Y] Yes [N] No [S] Suspend [?] Help (default is "Y"): y Deleted branch dev2 (was 75f6ab8). Remove merged branch from MyProject? patch-254 [Y] Yes [N] No [S] Suspend [?] Help (default is "Y"): n PS C:\MyProject> ``` By default you will be prompted to remove each branch. ### [Test-WithCulture](docs/Test-WithCulture.md) When writing PowerShell commands, sometimes the culture you are running under becomes critical. For example, European countries use a different datetime format than North Americans which might present a problem with your script or command. Unless you have a separate computer running under the foreign culture, it is difficult to test. This command will allow you to test a scriptblock or even a file under a different culture, such as DE-DE for German. ```powershell PS C\> Test-WithCulture fr-fr -Scriptblock { Get-winEvent -log system -max 500 | Select-Object -Property TimeCreated,ID,OpCodeDisplayname,Message | Sort-Object -property TimeCreated | Group-Object {$_.TimeCreated.ToShortDateString()} -NoElement } Count Name ----- ---- 165 10/07/2019 249 11/07/2019 17 12/07/2019 16 13/07/2019 20 14/07/2019 26 15/07/2019 7 16/07/2019 ``` ### [Copy-Command](docs/Copy-Command.md) 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. ### [Get-ParameterInfo](docs/Get-ParameterInfo.md) Using Get-Command, this function will return information about parameters for any loaded cmdlet or function. The common parameters like Verbose and ErrorAction are omitted. Get-ParameterInfo returns a custom object with the most useful information an administrator might need to know. ```powershell PS C:\> Get-ParameterInfo -Command Get-Counter -Parameter computername Name : computername Aliases : Cn Mandatory : False Position : Named ValueFromPipeline : False ValueFromPipelineByPropertyName : False Type : System.String[] IsDynamic : False ParameterSet : __AllParameterSets ``` ### [New-PSFormatXML](docs/New-PSFormatXML.md) When defining custom objects with a new typename, PowerShell by default will display all properties. However, you may wish to have a specific default view, be it a table or list. Or you may want to have different views display the object differently. Format directives are stored in format.ps1xml files which can be tedious to create. This command simplifies that process. Define a custom object: ```powershell $tname = "myThing" $obj = [PSCustomObject]@{ PSTypeName = $tname Name = "Jeff" Date = (Get-Date) Computername = $env:computername OS = (Get-CimInstance win32_operatingsystem -Property Caption).caption } Update-TypeData -TypeName $tname -MemberType "ScriptProperty" -MemberName "Runtime" -value {(Get-Date) - [datetime]"1/1/2019"} -force ``` The custom object looks like this by default: ```powershell PS C:\> $obj Name : Jeff Date : 2/10/2019 8:49:10 PM Computername : BOVINE320 OS : Microsoft Windows 10 Pro Runtime : 40.20:49:43.9205882 ``` Now you can create new formatting directives. ```powershell PS C:\> $obj | New-PSFormatXML -Properties Name, Date, Computername, OS -FormatType Table -path "C:\work\$tname.format.ps1xml" PS C:\> $obj | New-PSFormatXML -Properties Name, OS, Runtime -FormatType Table -view runtime -path "C:\work\$tname.format.ps1xml" -append PS C:\> $obj | New-PSFormatXML -FormatType List -path "C:\work\$tname.format.ps1xml" -append PS C:\> Update-FormatData -appendpath "C:\work\$tname.format.ps1xml" ``` And here is what the object looks like now: ```powershell PS C:\> $obj Name Date Computername Operating System ---- ---- ------------ ---------------- Jeff 2/10/2019 8:49:10 PM BOVINE320 Microsoft Windows 10 Pro PS C:\> $obj | format-table -View runtime Name OS Runtime ---- -- ------- Jeff 40.20:56:24.5411481 PS C:\> $obj | format-list Name : Jeff Date : Sunday, February 10, 2019 Computername : BOVINE320 OperatingSystem : Microsoft Windows 10 Pro Runtime : 40.21:12:01 ``` If you run this command within VS Code and specify `-Passthru`, the resulting file will be opened in your editor. ### [Test-IsPSWindows](docs/Test-IsPSWindows.md) PowerShell Core introduced the `$IsWindows` variable. However it is not available on Windows PowerShell. Use this command to perform a simple test if the computer is either running Windows or using the Desktop PSEdition. The command returns True or False. ### [Write-Detail](docs/Write-Detail.md) 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 ``` In a script you might use it like this: ```powershell Begin { Write-Detail "Starting $($myinvocation.mycommand)" -Prefix begin -time | Write-Verbose $tabs = "`t" * $tab Write-Detail "Using a tab of $tab" -Prefix BEGIN -time | Write-Verbose } #begin ``` ### [Save-GitSetup](docs/Save-GitSetup.md) This command is intended for Windows users to easily download the latest 64bit version of `Git`. ```powershell PS C:\> Save-GitSetup -Path c:\work -Passthru Directory: C:\work Mode LastWriteTime Length Name ---- ------------- ------ ---- -a--- 1/23/2020 4:31 PM 46476880 Git-2.25.0-64-bit.exe ``` You will need to manually install the file. ## Other From time to time I will include additional items that you might find useful. One item that you get when you import this module is a custom format.ps1xml file for services. If you are running PowerShell 7, you can run `Get-Service` and pipe it to the table view. ```powershell PS C:\> Get-Service | Format-Table -view ansi ``` This will display the service status color-coded. ![ServiceAnsi](images/serviceansi.png) ## Related Modules If you find this module useful, you might also want to look at my tools for [creating and managing custom type extensions](https://github.com/jdhitsolutions/PSTypeExtensionTools), [managing scheduled jobs](https://github.com/jdhitsolutions/ScheduledJobTools) and [running remote commands outside of PowerShell Remoting](https://github.com/jdhitsolutions/PSRemoteOperations) ## Compatibility Where possible these commands have been tested with PowerShell 7, but not every platform. If you encounter problems, have suggestions or other feedback, please post an issue. It is assumed you will __not__ be running this commands on any edition of PowerShell Core or any beta releases of PowerShell 7. Last Updated *2020-03-02 17:43:53Z UTC* PSScriptTools-2.20.0/Tests/000077500000000000000000000000001362724310600154315ustar00rootroot00000000000000PSScriptTools-2.20.0/Tests/Test-Expression.tests.ps1000066400000000000000000000027671362724310600223070ustar00rootroot00000000000000#pester tests for Test-Expression Import-Module $PSScriptRoot\..\functions\Test-Expression.ps1 -force Describe "Test-Expression" { It "Should have an alias" { (Get-Alias tex).ResolvedCommand.Name | Should Be "Test-Expression" } It "Should do a single test" { $result = Test-Expression -expression {1..50} $result.Tests | Should Be 1 $result.TestInterval | Should be 500 $result.AverageMS | Should BeGreaterThan 0 } It "Should allow setting an interval" { $result = Test-Expression -expression {1..50} -interval .1 $result.TestInterval | Should Be 100 } It "Should allow setting a random interval" { $result = Test-Expression -expression {1..50} -randomMinimum .1 -randomMaximum .5 -count 2 $result.TestInterval | Should Be "Random" } It "Should allow for multiple tests" { $result = Test-Expression -expression {1..50} -count 5 -interval .1 $result.Tests | Should Be 5 $result.TrimmedMS | Should BeGreaterThan 0 } It "Should accept scriptblock arguments" { $sb = {Param([int]$x,[int]$y) $x..$y} $result = Test-Expression -expression $sb -argument 1,100 $result.Tests | Should Be 1 } It "Should include the expression when asked" { $result = Test-Expression -expression {1..50} -IncludeExpression $result.Expression.GetType().Name | Should Be "ScriptBlock" $result.Expression.ToString() | Should Be "1..50" } } #Describe PSScriptTools-2.20.0/changelog.md000066400000000000000000000327441362724310600166120ustar00rootroot00000000000000# Change Log for PSScriptTools ## v2.20.0 + Restructured `Get-FileSizeInfo` to better handle Windows PowerShell. (Issue #70) + Added `Remove-MergedBranch` with an alias of `rmb`. (Issue #71) + Added `Get-ModuleCommand` with an alias of `gmc`. + Added `modulecommand.format.ps1xml` to format `Get-ModuleCommand` results. + Added an alias of `shtree` for `Show-Tree` because `pstree` is a Linux command. + Added parameter alias `files` for `-ShowItem` in `Show-Tree`. + Added parameter alias `properties` for `-ShowProperties` in `Show-Tree`. + Added parameter alias `ansi` for dynamic parameter `InColor` in `Show-Tree`. (Issue #73) + Set the default parameter value for `-Path` in `Show-Tree` to the current directory. + Modified `Show-Tree` to allow the user to specify an array of properties. This is a __breaking change__ as the parameter has been changed from a `switch` to `string[]`. (Issue #72) + Removed `PROPERTY` label in `Show-Tree` output when displaying properties. + Corrected errors in module manifest. + Added auto completer for `Runspace` parameter in `Remove-Runspace`. + Added alias `rfn` for `New-RandomFileName`. + Added alias `cfn` for `New-CustomFileName`. + Updated `README.md`. + `ChangeLog.md` clean up. ## v2.19.0 + Modified `Get-FolderSizeInfo` to use [system.collections.arraylist]` to improve performance. (Issue #68) + Fixed bug in `Get-FolderSizeInfo` running in PowerShell 7 that wasn't including System files. + Updated help for `Get-FolderSizeInfo`. + Added online help link for `Get-PSScriptTools`. + Added better error handling to `Test-EmptyFolder`. + Added `Computername` property to passthru output from `Test-EmptyFolder`. + Added alias `fcc` for `Find-CimClass`. + Added alias `pstree` for `Show-Tree`. + Revised `Show-Tree` to use splatting for internal commands. + Added a dynamic parameter `InColor` for `Show-Tree` to display results in ANSI color if running PowerShell 7. + Added format file `serviceansi.format.ps1xml` to display service status colored when using PowerShell 7. + Updated `README.md`. ## v2.18.0 + Fixed missing `ReleaseID` property in `Get-WindowsVersion`. (Issue #67) + Added `BuildBranch` property to `Get-WindowsVersion`. + Updated `windowsversion.format.ps1xml` to include new properties and not use Autosize. + Added `Name` property to output from `Get-FolderSizeInfo` (Issue #66) + Added a new table view called `name` for `Get-FolderSizeInfo`. + Added `Get-PSScriptTools` function to display summary information about commands in this module. + Added `psscripttools.format.ps1xml` to define a default table view for `Get-PSScriptTools`. + Help updates. + Added online help link for `Test-EmptyFolder`. + Updated `README.md`. ## v2.17.0 + Updated `Get-FolderSizeInfo` to handle directory names like `[data]`. (Issue #65) + Updated `Get-FolderSizeInfo` to show a TotalSize of 0 for empty directories. (Issue #64) + Cleaned up code in `Get-FolderSizeInfo` script file now that it is part of this module. + Added `Test-EmptyFolder`. + Updated `README.md`. ## v2.16.0 + Fixed bug in `New-CustomFileName` when using a 24 hour value. (Issue #62) + Updated `Test-ExpressionForm` to clear the text results. (Issue #61) + Updated `Convertto-WPFGrid` to display a refresh message. (Issue #43) + Updated `foldersizeinfo.format.ps1xml` to include a KB formatted view. ## v2.15.1 + Fixed bug in `Get-FolderSizeInfo` that was returning incorrect data. (Issue #60) + Updated newer help with online links. + Updated `README.md`. ## v2.15.0 + Added `Get-FolderSizeInfo` and its alias `gsi` along with a corresponding format.ps1xml file. + Fixed IsWindows bug in `New-WPFMessageBox`. (Issue #59) + Fixed IsWindows bug in `Convertto-WPFGrid`, `Find-CimClass`, `Test-ExpressionForm`, `Get-WindowsVersion`,`Get-WindowsVersionString` and `Invoke-InputBox` by using a new function `Test-IsPSWindows`. + Updated `Get-PSWho` to better work cross-platform. + Help updates. + Updated `README.md`. ## v2.14.1 + Fixed bug in `Save-GitSetup` that relies on `$IsWindows` (Issue #58). Now this command should work on Windows PowerShell 5.1 as well. + Updated help for `Save-GitSetup`. + Updated help files with missing online links. ## v2.14.0 + Updated `New-PSFormatXML` to support Wide table formats. (Issue #55) + Updated `Test-ExpressionForm` to better handle non-Windows platforms. + Added `Save-GitSetup` to download the latest x64 version of `git`. + Modified `New-CustomFileName` to support a new template element, `%hour24`. (Issue #57) + Added `tv` alias to `Out-VerboseTee`. + Added `ConvertTo-LexicalTimespan`. + Added `ConvertFrom-LexicalTimespan`. + Updated manifest description. + Updated help for `Get-PowerShellEngine`. + Updated `README.md`. ## v2.13.0 + Added `New-RunspaceCleanupJob` command to be used with WPF commands running in a new runspace. + Modified `ConvertTo-WPFGrid` to clean up runspace when closed. (Issue #25) + Modified `ConvertTo-WPFGrid` to attempt to run on all platforms and gracefully fail where it won't work. (Issue #56) + Added 'Convert-EventLogRecord' function and its alias `clr`. + Added `Rename-Hashtable` function and its alias `rht`. + Updated `Convertto-Markdown` to include options to format as a table. + Updated module manifest to export `ConvertTo-WPFGrid` to all hosts. Code in the command will determine compatibility. + Updated `Find-FileItem` to work better cross-platform. + Updated `New-WPFMessagebox` to work on PowerShell 7 on Windows platforms. + Help Updates. + Modified module and manifest to export all functions regardless of edition. Any OS limitations will be handled on a per command basis. + Updated `README.md`. ## v2.12.0 + Help updates. + Replaced GitHub online help links with bit.ly short links. + Minor updates to `README.md`. + Updated `Out-More` to work better with output from `Get-Help`. ## v2.11.0 + Added a grouping feature to `New-PSFormatXML`. (Issue #54) + Modified `New-PSFormatXML` to open the XML file if the command is run in VS Code as part of `-Passthru`. + Help updates. ## v2.10.0 + Added `Test-WithCulture`. + Fixed typo in `Copy-Command` help. + Created yaml formatted help files. + Updated `README.md`. + Updated help documentation with online links. + Updated `PSScriptTools.md`. ## v2.9.0 + Added `ConvertFrom-Text` and its alias `cft`. (Issue #53) + Updated `ConvertTo-UTC` to include an option to format result as a sortable string. (Issue #52) + Added `Get-WhoIs` and `whoisresult.format.ps1xml`. + help documentation clean up. + Updated and reorganized `README.md`. ## v2.8.0 + Added `Get-FileItem` with an alias of `pswhere`. + Renamed `timezonedata.format.ps1xml` to all lower case. + Replaced using `Out-Null` to use `[void]` in `Convertto-WPFGrid`, `New-PSFormatXML`, `Copy-Command`,`New-WPFMessageBox`, `Write-Detail`, `Test-Expression`,`Invoke-Inputbox`. (Issue #47) + Revised warning message in `New-PSFormatXML`. (Issue #50) + Fixed icon path error in `New-WPFMessageBox`. ## v2.7.0 + Modified `ConvertTo-LocalTime` to allow for locations supporting Daylight Saving Time. (Issue #44) + Fixed bug in `New-PSFormatXML` that wasn't using auto detected property names. (Issue #45) + Added `Get-TZList` and `Get-TZData` commands. + Added format file `timeZoneData.format.ps1xml`. + Modified `ConvertTo-WPFGrid` to allow the user to control which gridlines are displayed + Modified `New-CustomFilename` to improve parameter help. + Modified `New-CustomFilename` to add %seconds. + Modified `New-CustomFilename` so that %month, %day and %minute will use a leading zero if necessary. + Added new help examples for `New-CustomFilename`. + Help updates. + File re-organization. + Updated `README.md`. ## v2.6.0 + Modified `Convertto-WPFGrid` to set maximum size equal to total available working area. (Issue #36) + Modified `Convertto-WPFGrid` to change cursor on refresh and display a refresh message in the title bar + Added InitializationScript option for `ConvertTo-WPFGrid`. (Issue #42) + Added `ConvertTo-LocalTime` with an alias of `clt`. + Updated `README.md`. + Help updates. ## v2.5.0 + fixed bug which was hiding the horizontal scroll bar in `ConvertTo-WPFGrid`. (Issue #40) + fixed bug which prevented status bar from updating when manually refreshing in `ConvertTo-WPFGrid`. (Issue #34) + Changed time display in `ConvertTo-WPFGrid` as a timespan instead of raw seconds. (Issue #41) + Markdown help cleanup. + Added `Set-ConsoleTitle`. + Added `Set-ConsoleColor`. + Updated `README.md`. ## v2.4.0 + Made datagrid in `ConvertTo-WPFGrid` read-only. (Issue #38) + Modified datagrid in `ConvertTo-WPFGrid` to better handle resizing. (Issue #36) + Modified statusbar in `ConvertTo-WPFGrid` to better handle resizing. (Issue #37) + Modified form in `ConvertTo-WPFGrid` to better fit in the screen and not exceed the screen area. (Issue #39) + Added parameter to allow usage of local variables in `ConvertTo-WPFGrid`. (Issue #35) + Help updates. + Reorganized `README.md`. ## v2.3.0 + Fixed bug in `ConvertTo-WPFGrid` that wasn't updating last update time. (Issue #30) + Modified `ConvertTo-WPFGrid` to allow user to load their profile scripts into the runspace. (Issue #29) + Modified auto sizing code in `ConvertTo-WPFGrid`. + Modified `ConvertTo-WPFGrid` to automatically display scroll bars when necessary. + Modified `New-PSFormatXML` to display a warning on invalid property names. (Issue #33) + Added `Get-myTimeInfo`, `ConvertTo-UTCTime` and `ConvertFrom-UTCTime` (Issue #31) + help updates. + Updated `README.md`. ## v2.2.0 + Code revisions in `ConvertTo-WPFGrid` (Issue #27) + Updated `Get-ParameterInfo` to reflect dynamic parameters. (Issue #28) + Updated `Get-PSLocation` to better reflect locations and use a custom format file. + Updated `Get-WindowsVersion` with custom type for format file. Also better handling of non-Windows platforms. + Updated `Get-WindowsVersionString` to include the computername. + Updated `New-WPFMessageBox` to gracefully exit if running on PowerShell Core. + Updated `Test-ExpressionForm` to gracefully exit if running on PowerShell Core. + Updated `New-RandomFilename` to better reflect locations using `[environment]`. + Modified manifest to be more aware of PSEdition and only load compatible commands. + Help updates. + Updated `README.md`. ## v2.1.0 + Added parameter to allow user to specify a type name with `New-PSFormatXML`. (Issue #26) + Added `Get-ParameterInfo` command with an alias of `gpi`. + Updated help for `Optimize-Text`. + Help updates. + Updated `README.md`. ## v2.0.0 + Added `New-PSFormatXml` and its alias `nfx`. + Raised minimum PowerShell version to 5.1. + Modified manifest to support both `Desktop` and `Core`. + Added `Remove-Runspace`. + Modified `ConvertTo-WPFGrid` to autosize the display and support an automatic refresh. + Modified `ConvertTo-WPFGrid` to use a runspace. (Issue #22) + Updated `README.md`. + Updated help documentation. + Raised version number to reflect a number of potentially breaking changes. ## v1.8.1 + minor corrections to `Compare-Module`. (Issue #21) ## v1.8.0 + fixed typo in `Write-Detail`. (Thanks @AndrewPla) + Added `Compare-Module` function. (Issue #19) + Added `Get-WindowsVersion` function. (Issue #20) + Added `Get-WindowsVersionString` function. + Updated `README.md`. + Updated module manifest. + reorganized module. + Updated Pester test for `Test-Expression`. + Updated external help file. ## v1.7.0 + Added `New-WPFMessagebox` function. (Issue #11) + Added alias `nmb` for `New-WPFMessageBox`. + Added icon files for WPF Message box. + Updated `README.md`. ## v1.6.0 + Added `Optimize-Text` and its alias `ot`. + Added `Show-Tree`. + Help and documentation updates. ## v1.5.1 + code cleanup for the published module in the PowerShell Gallery. ## v1.5.0 + Added `Select-First` and its alias `first`. + Added `Select-Last` and its alias `last`. + Added `Get-MyVariable` and its alias `gmv`. + Added `New-PSDriveHere` and its alias `npsd`. + Updated `README.md`. ## v1.4.0 + Added hashtable tools. + Updated `README.md`. + minor code cleanup. ## v1.3.0 + Fixed documentation errors for `Out-ConditionalColor`. (Issue #13) + Added alias definitions to functions. + Added my `Test-Expression` commands. (Issue #14) + Added my `Find-CimClass` function. (Issue #16) + Added my `ConvertTo-Markdown` function. (Issue #17) + Added `ConvertTo-WPFGrid`. (Issue #15) + help cleanup and updates. + Code cleanup and formatting. ## v1.2.0 + Updated `Write-Detail`. + Updated `README.md`. ## v1.1.0 + Cleaned up ToDo code. (Issue #12) + Updated `README.md`. + Help cleanup. ## v1.0.1 + fixed version number mistake. + updated `README.md`. ## v1.0.0 + initial release to the PowerShell Gallery. ## v0.5.0 + Added `Get-PSLocation` function. (Issue #4) + Added `Get-PowerShellEngine` function. (Issue #5) + Added `Out-More` and alias `om`. (Issue #10) + Added icon to manifest. + Added `Invoke-InputBox` and alias `ibx`. + Added code to insert ToDo comments for the ISE and VSCode. (Issue #7) + Updated `README.md`. + Updated documentation. ## v0.4.0 + Added `Copy-Command`. (Issue #2) + Updated `Copy-Command` to open new file in the ISE or VSCode. + Added Format functions. (Issue #3) + Updated help. + Added new sample files. ## v0.3.0 + Added help documentation. + Updated `README.md`. + Added samples. + Reverted `Get-PSWho` to not trim when using -AsString. + Added code to `New-CustomFileName` to preserve case for non-placeholders. + Modified `Out-VerboseTee` to turn on VerboseTee. ## v0.2.0 + Modified verbose output to use `Write-Detail`. + Expanded aliases to full cmdlet names. + Modified `Get-PSWho` to trim when using -AsString. + Added `Out-ConditionalColor`. + Added `Get-RandomFileName`. + Added `New-CustomFileName`. ## v0.1.0 + initial module files PSScriptTools-2.20.0/docs/000077500000000000000000000000001362724310600152575ustar00rootroot00000000000000PSScriptTools-2.20.0/docs/Add-Border.md000066400000000000000000000073771362724310600175220ustar00rootroot00000000000000--- external help file: PSScriptTools-help.xml Module Name: PSScriptTools online version: http://bit.ly/31PzBsZ schema: 2.0.0 --- # Add-Border ## SYNOPSIS Create a text border around a string. ## SYNTAX ### single (Default) ```yaml Add-Border [-Text] [-Character ] [-InsertBlanks] [-Tab ] [] ``` ### block ```yaml Add-Border [-TextBlock] [-Character ] [-InsertBlanks] [-Tab ] [] ``` ## DESCRIPTION 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. ## EXAMPLES ### EXAMPLE 1 ```powershell PS C:\> add-border "PowerShell Wins!" ******************** * PowerShell Wins! * ******************** ``` ### EXAMPLE 2 ```powershell PS C:\> add-border "PowerShell Wins!" -tab 1 ******************** * PowerShell Wins! * ******************** ``` Note that this EXAMPLE may not format properly in the console. ### EXAMPLE 3 ```powershell PS C:\> add-border "PowerShell Wins!" -character "-" -insertBlanks -------------------- - - - PowerShell Wins! - - - -------------------- ``` ### EXAMPLE 4 ```powershell PS C:\> add-border -textblock (get-service win* | out-string).trim() ********************************************************************** * Status Name DisplayName * * ------ ---- ----------- * * Stopped WinDefend Windows Defender Antivirus Service * * Running WinHttpAutoProx... WinHTTP Web Proxy Auto-Discovery Se... * * Running Winmgmt Windows Management Instrumentation * * Stopped WinRM Windows Remote Management (WS-Manag... * ********************************************************************** ``` Create a border around the output of a Get-Service command. ## PARAMETERS ### -Text A single line of text that will be wrapped in a border. ```yaml Type: String Parameter Sets: single Aliases: Required: True Position: 1 Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: False ``` ### -TextBlock A multi-line block of text. You might want to trim blank lines from the beginning, end or both. ```yaml Type: String[] Parameter Sets: block Aliases: Required: True Position: 1 Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -Character The character to use for the border. It must be a single character. ```yaml Type: String Parameter Sets: (All) Aliases: Required: False Position: Named Default value: * Accept pipeline input: False Accept wildcard characters: False ``` ### -InsertBlanks Insert blank lines before and after the text. The default behavior is to create a border box close to the text. See examples. ```yaml Type: SwitchParameter Parameter Sets: (All) Aliases: Required: False Position: Named Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -Tab Insert X number of tabs. ```yaml Type: Int32 Parameter Sets: (All) Aliases: Required: False Position: Named Default value: 0 Accept pipeline input: False Accept wildcard characters: False ``` ### CommonParameters This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### None ## OUTPUTS ### System.String ## NOTES Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/ ## RELATED LINKS PSScriptTools-2.20.0/docs/Compare-Module.md000066400000000000000000000065641362724310600204250ustar00rootroot00000000000000--- external help file: PSScriptTools-help.xml Module Name: PSScriptTools online version: http://bit.ly/31UsaRA schema: 2.0.0 --- # Compare-Module ## SYNOPSIS Compare PowerShell module versions. ## SYNTAX ```yaml Compare-Module [[-Name] ] [-Gallery ] [] ``` ## DESCRIPTION Use this command to compare module versions between what is installed against an online repository like the PSGallery. Results will be automatically sorted by module name. ## EXAMPLES ### EXAMPLE 1 ```powershell PS C:\> Compare-Module | Where-object {$_.UpdateNeeded} Name : DNSSuffix OnlineVersion : 0.4.1 InstalledVersion : 0.2.0 PublishedDate : 10/22/2018 8:21:46 PM UpdateNeeded : True Name : InvokeBuild OnlineVersion : 5.4.2 InstalledVersion : 3.2.2 PublishedDate : 12/7/2018 1:30:46 AM UpdateNeeded : True ... ``` List all modules that could be updated. ### EXAMPLE 2 ```powershell PS C:\> Compare-Module | Where UpdateNeeded | Out-Gridview -title "Select modules to update" -outputMode multiple | Foreach { Update-Module $_.name } ``` Compare modules and send results to Out-Gridview. Use Out-Gridview as an object picker to decide what modules to update. ### EXAMPLE 3 ```powershell PS C:\> compare-module -name xWin* | format-table Name OnlineVersion InstalledVersion PublishedDate UpdateNeeded ---- ------------- ---------------- ------------- ------------ xWindowsUpdate 2.7.0.0 2.7.0.0,2.5.0.0 7/12/2017 10:43:54 PM False xWinEventLog 1.2.0.0 1.2.0.0 6/13/2018 8:06:45 PM False ``` Compare all modules that start with xWin* and display results in a table format. ### EXAMPLE 4 ```powershell PS C:\> get-dscresource xAD* | Select moduleName -Unique | compare-module Name : xActiveDirectory OnlineVersion : 2.22.0.0 InstalledVersion : 2.16.0.0,2.14.0.0 PublishedDate : 10/25/2018 5:25:24 PM UpdateNeeded : True Name : xAdcsDeployment OnlineVersion : 1.4.0.0 InstalledVersion : 1.1.0.0,1.0.0.0 PublishedDate : 12/20/2017 10:10:43 PM UpdateNeeded : True ``` Get all DSC Resources that start with xAD and select the corresponding module name. Since the module name will be listed for every resource, get a unique list and pipe that to Compare-Module. ## PARAMETERS ### -Name The name of a module to check. Wildcards are permitted. ```yaml Type: String Parameter Sets: (All) Aliases: modulename Required: False Position: 1 Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: True ``` ### -Gallery Specify the remote repository or gallery to check. ```yaml Type: String Parameter Sets: (All) Aliases: Required: False Position: Named Default value: PSGallery Accept pipeline input: False Accept wildcard characters: False ``` ### CommonParameters This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### [string] ## OUTPUTS ### PSCustomObject ## NOTES Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/ ## RELATED LINKS [Find-Module]() [Get-Module]() [Update-Module]() PSScriptTools-2.20.0/docs/Convert-CommandtoHashtable.md000066400000000000000000000027471362724310600227660ustar00rootroot00000000000000--- external help file: PSScriptTools-help.xml Module Name: PSScriptTools online version: http://bit.ly/31SLyhD schema: 2.0.0 --- # Convert-CommandtoHashtable ## SYNOPSIS Convert a PowerShell expression into a hashtable. ## SYNTAX ```yaml Convert-CommandtoHashtable [-Text] [] ``` ## DESCRIPTION This command is intended to convert a long PowerShell expression with named parameters into a splatting alternative. ## EXAMPLES ### Example 1 ```powershell PS C:\> Convert-CommandtoHashtable -Text "get-eventlog -listlog -computername a,b,c,d -erroraction stop" $paramHash = @{ listlog = $True computername = "a","b","c","d" erroraction = "stop" } Get-EventLog @paramHash ``` ## PARAMETERS ### -Text A PowerShell expression, preferably with named parameters. ```yaml Type: String Parameter Sets: (All) Aliases: Required: True Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### CommonParameters This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### None ## OUTPUTS ### [Hashtable] ## NOTES Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/ ## RELATED LINKS [Convert-HashTableToCode]() PSScriptTools-2.20.0/docs/Convert-EventLogRecord.md000066400000000000000000000173061362724310600221100ustar00rootroot00000000000000--- external help file: PSScriptTools-help.xml Module Name: PSScriptTools online version: http://bit.ly/314L8W9 schema: 2.0.0 --- # Convert-EventLogRecord ## SYNOPSIS Convert EventLogRecords to structured objects. ## SYNTAX ```yaml Convert-EventLogRecord [-LogRecord] [] ``` ## DESCRIPTION When you use Get-WinEvent, the results are objects you can work with in PowerShell. However, often times there is additional information that is part of the eventlog record, such as replacement strings, that are used to construct a message. This additional information is not readily exposed. You can use this command to convert results of a Get-WinEvent command into a PowerShell custom object with additional information. For best results you, should pipe the same event IDs to this command. Note that not every event record exposes data that is compatible with this command. For those types of event log records, you will see a RawProperties property with most likely an array of strings. Use the Message property for more information. ## EXAMPLES ### EXAMPLE 1 ```powershell PS C:\> Get-WinEvent -FilterHashtable @{Logname = 'security';ID=5059} | Convert-EventLogRecord | Select-Object -Property TimeCreated,Subject*,Computername TimeCreated : 1/20/2020 10:48:45 AM SubjectUserSid : S-1-5-83-1-2951761591-1086169693-630393256-923523501 SubjectUserName : AFF04EB7-A25D-40BD-A809-9325ADD90B37 SubjectDomainName : NT VIRTUAL MACHINE SubjectLogonId : 0x7cbf5 Computername : Bovine320 TimeCreated : 1/20/2020 10:48:45 AM SubjectUserSid : S-1-5-83-1-2951761591-1086169693-630393256-923523501 SubjectUserName : AFF04EB7-A25D-40BD-A809-9325ADD90B37 SubjectDomainName : NT VIRTUAL MACHINE SubjectLogonId : 0x7cbf5 Computername : Bovine320 ``` ### EXAMPLE 2 ```powershell PS C:\> Get-WinEvent -FilterHashtable @{Logname = 'security';ID=4624} -MaxEvents 100 -computername win10 | Convert-EventLogRecord | Where-Object {$_.LogonType -eq 3} | Select-Object -first 10 -property TargetUsername,TargetDomainName,IPAddress,TimeCreated,Computername | Format-Table TargetUserName TargetDomainName IpAddress TimeCreated Computername -------------- ---------------- --------- ----------- ------------ ArtD COMPANY.PRI fe80::ddae:8ade:c3ff:e584 1/20/2020 12:05:12 PM WIN10.Company.Pri WIN10$ COMPANY.PRI - 1/20/2020 11:56:52 AM WIN10.Company.Pri WIN10$ COMPANY.PRI - 1/20/2020 11:56:52 AM WIN10.Company.Pri WIN10$ COMPANY.PRI - 1/20/2020 11:56:52 AM WIN10.Company.Pri WIN10$ COMPANY.PRI - 1/20/2020 11:56:51 AM WIN10.Company.Pri ArtD COMPANY.PRI 192.168.3.10 1/20/2020 11:45:31 AM WIN10.Company.Pri WIN10$ COMPANY.PRI ::1 1/20/2020 11:39:52 AM WIN10.Company.Pri ArtD COMPANY.PRI 192.168.3.10 1/20/2020 11:35:49 AM WIN10.Company.Pri ArtD COMPANY.PRI 192.168.3.10 1/20/2020 11:34:36 AM WIN10.Company.Pri ArtD COMPANY.PRI 192.168.3.10 1/20/2020 11:32:06 AM WIN10.Company.Pri ``` This example filters on a property added by this command to only show interactive logons. ### EXAMPLE 3 ```powershell PS C:\> Get-WinEvent -FilterHashtable @{Logname ='system';ID =7040} -MaxEvent 10 | Convert-EventlogRecord | Select-Object -Property TimeCreated,@{Name="Service";Expression={$_.param4}},@{Name="OriginalState";Expression = {$_.param2}},@{Name="NewState";Expression={$_.param3}},Computername | Format-Table TimeCreated Service OriginalState NewState Computername ----------- ------- ------------- -------- ------------ 1/20/2020 9:26:08 AM BITS demand start auto start Bovine320 1/20/2020 5:47:17 AM BITS auto start demand start Bovine320 1/20/2020 5:45:11 AM BITS demand start auto start Bovine320 1/20/2020 1:44:31 AM BITS auto start demand start Bovine320 1/20/2020 1:42:30 AM BITS demand start auto start Bovine320 1/19/2020 8:53:37 PM BITS auto start demand start Bovine320 1/17/2020 8:27:10 PM TrustedInstaller demand start auto start Bovine320 1/17/2020 8:27:10 PM TrustedInstaller auto start demand start Bovine320 1/17/2020 8:26:29 PM TrustedInstaller demand start auto start Bovine320 1/17/2020 8:26:20 PM TrustedInstaller auto start demand start Bovine320 ``` Once you know the type of data, you can customize the output or build a script around it. ### EXAMPLE 4 ```powershell PS C:\> Get-WinEvent -FilterHashtable @{Logname = "Application";ID=17137} -MaxEvents 1 | Convert-EventLogRecord LogName : Application RecordType : Information TimeCreated : 1/20/2020 2:31:52 PM ID : 17137 RawProperties : {TickleEventDB} Message : Starting up database 'TickleEventDB'. Keywords : {Classic} Source : MSSQL$SQLEXPRESS Computername : Bovine320 ``` This record doesn't have structured extra data. The replacement strings are stored as text so the command displays the data using the RawProperties property. ### EXAMPLE 5 ```powershell PS C:\> $all = New-PSSession -ComputerName 'win10','srv1','srv2','dom1' PS C:\> $local = Get-Item Function:\Convert-EventLogRecord PS C:\> Invoke-Command -ScriptBlock {New-item -Path Function: -Name $using:local.name -Value $using:local.ScriptBlock} -Session $all PS C:\> Invoke-Command { Get-WinEvent -FilterHashtable @{Logname='security';id=4624} -MaxEvents 10 | Convert-EventLogRecord | Select-Object -Property Computername,Time*,TargetUser*,TargetDomainName,Subject*} -session $all -HideComputerName | Select-Object -Property * -ExcludeProperty runspaceID Computername : WIN10.Company.Pri TimeCreated : 1/20/2020 5:21:17 PM TargetUserSid : S-1-5-18 TargetUserName : SYSTEM TargetDomainName : NT AUTHORITY SubjectUserSid : S-1-5-18 SubjectUserName : WIN10$ SubjectDomainName : COMPANY SubjectLogonId : 0x3e7 Computername : WIN10.Company.Pri TimeCreated : 1/20/2020 5:18:51 PM TargetUserSid : S-1-5-18 TargetUserName : SYSTEM TargetDomainName : NT AUTHORITY SubjectUserSid : S-1-5-18 SubjectUserName : WIN10$ SubjectDomainName : COMPANY SubjectLogonId : 0x3e7 Computername : WIN10.Company.Pri TimeCreated : 1/20/2020 5:16:07 PM TargetUserSid : S-1-5-21-278538743-3177530655-100218012-1105 TargetUserName : ArtD TargetDomainName : COMPANY.PRI SubjectUserSid : S-1-0-0 SubjectUserName : - SubjectDomainName : - SubjectLogonId : 0x0 ... ``` The first command creates PSSessions to several remote computers. The local copy of this command is created in the remote PSSessions. Then event log data is retrieved in the remote sessions and converted using the Convert-EventlogRecord function in each session. ## PARAMETERS ### -LogRecord An event log record from the Get-WinEvent command. ```yaml Type: EventLogRecord[] Parameter Sets: (All) Aliases: Required: True Position: 1 Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: False ``` ### CommonParameters This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### [System.Diagnostics.Eventing.Reader.EventLogRecord[]] ## OUTPUTS ### PSCustomObject Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/ ## RELATED LINKS [Get-WinEvent]() PSScriptTools-2.20.0/docs/Convert-HashTableToCode.md000066400000000000000000000030531362724310600221510ustar00rootroot00000000000000--- external help file: PSScriptTools-help.xml Module Name: PSScriptTools online version: http://bit.ly/31SLU7X schema: 2.0.0 --- # Convert-HashTableToCode ## SYNOPSIS Convert a hashtable to a string representation. ## SYNTAX ```yaml Convert-HashTableToCode [-Hashtable] [] ``` ## DESCRIPTION Use this command to convert a hashtable into its text or string equivalent. ## EXAMPLES ### Example 1 ```powershell PS C:\> $h = @{Name="SRV1";Asset=123454;Location="Omaha"} PS C:\> convert-hashtabletocode $h @{ Name = 'SRV1' Asset = 123454 Location = 'Omaha' } ``` Convert a hashtable object to a string equivalent that you can copy into your script. ## PARAMETERS ### -Hashtable A hashtable to convert. In can be standard or ordered hashtable. ```yaml Type: Hashtable Parameter Sets: (All) Aliases: Required: True Position: 0 Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: False ``` ### CommonParameters This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### System.Collections.Hashtable ## OUTPUTS ### System.String ## NOTES Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/ ## RELATED LINKS [Convert-HashtableString](./Convert-HashtableString.md) PSScriptTools-2.20.0/docs/Convert-HashtableString.md000066400000000000000000000040331362724310600223010ustar00rootroot00000000000000--- external help file: PSScriptTools-help.xml Module Name: PSScriptTools online version: http://bit.ly/31VA9Of schema: 2.0.0 --- # Convert-HashtableString ## SYNOPSIS Convert a hashtable string into a hashtable object. ## SYNTAX ```yaml Convert-HashtableString [-Text] [] ``` ## DESCRIPTION This function is similar to Import-PowerShellDataFile. But where that command can only process a file, this command will take any hashtable-formatted string and convert it into an actual hashtable. ## EXAMPLES ### Example 1 ```powershell PS C:\> get-content c:\work\test.psd1 | unprotect-cmsmessage | Convert-HashtableString Name Value ---- ----- CreatedBy BOVINE320\Jeff CreatedAt 10/02/2018 21:28:47 UTC Computername Think51 Error Completed True Date 10/02/2018 21:29:35 UTC Scriptblock restart-service spooler -force CreatedOn BOVINE320 ``` The test.psd1 file is protected as a CMS Message. In this example, the contents are decoded as a string which is then in turn converted into an actual hashtable. ## PARAMETERS ### -Text Enter your hashtable string. ```yaml Type: String Parameter Sets: (All) Aliases: Required: True Position: 0 Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: False ``` ### CommonParameters This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### System.String ## OUTPUTS ### [hashtable] ## NOTES Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/ ## RELATED LINKS [Import-PowerShellDatafile]() [Convert-HashtabletoCode](./Convert-HashtabletoCode.md) PSScriptTools-2.20.0/docs/ConvertFrom-LexicalTimespan.md000066400000000000000000000044451362724310600231340ustar00rootroot00000000000000--- external help file: PSScriptTools-help.xml Module Name: PSScriptTools online version: http://bit.ly/37C3gJJ schema: 2.0.0 --- # ConvertFrom-LexicalTimespan ## SYNOPSIS Convert a lexical timespan into a PowerShell timespan. ## SYNTAX ```yaml ConvertFrom-LexicalTimespan [-String] [-AsString] [] ``` ## DESCRIPTION When working with some XML data, such as that from scheduled tasks, timespans or durations are stored in a lexical format like P0DT0H0M47S. You can use this command to convert that value into a timespan object. ## EXAMPLES ### Example 1 ```powershell PS C:\> ConvertFrom-LexicalTimespan P0DT0H0M47S Days : 0 Hours : 0 Minutes : 0 Seconds : 47 Milliseconds : 0 Ticks : 470000000 TotalDays : 0.000543981481481481 TotalHours : 0.0130555555555556 TotalMinutes : 0.783333333333333 TotalSeconds : 47 TotalMilliseconds : 47000 ``` ### Example 2 ```powershell PS C:\> Get-ScheduledTask -TaskName DailyWatcher | Select-Object Taskname,@{Name="ExecutionLimit";Expression = { ConvertFrom-LexicalTimespan $_.settings.ExecutionTimeLimit }} Taskname ExecutionLimit -------- -------------- DailyWatcher 3.00:00:00 ``` ## PARAMETERS ### -AsString Format the timespan as a string ```yaml Type: SwitchParameter Parameter Sets: (All) Aliases: Required: False Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -String Enter a lexical time string like P23DT3H43M. This is case-sensitive. ```yaml Type: String Parameter Sets: (All) Aliases: Required: True Position: 0 Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: False ``` ### CommonParameters This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### System.String ## OUTPUTS ### String ### Timespan ## NOTES Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/ ## RELATED LINKS [ConvertTo-LexicalTime](./ConvertTo-LexicalTime) PSScriptTools-2.20.0/docs/ConvertFrom-Text.md000066400000000000000000000226011362724310600207700ustar00rootroot00000000000000--- external help file: PSScriptTools-help.xml Module Name: PSScriptTools online version: http://bit.ly/31VAujZ schema: 2.0.0 --- # ConvertFrom-Text ## SYNOPSIS Convert structured text to objects. ## SYNTAX ### File (Default) ```yaml ConvertFrom-Text [-Pattern] [-Path] [-TypeName ] [-NoProgress] [] ``` ### Inputobject ```yaml ConvertFrom-Text [-Pattern] [-InputObject] [-TypeName ] [-NoProgress] [] ``` ## DESCRIPTION This command will take structured text such as from a log file and convert it to objects that you can use in the PowerShell pipeline. You can specify the path to a text file, or pipe content directly into this command. The piped content could even be output from command-line tools. You have to specify a regular expression pattern that uses named captures. The names will become property names in the custom objects. The command will write a generic custom object to the pipeline. However, you can specify a custom type name. You might want to do this if you have your own format ps1xml file and want to handle formatting through that file. ## EXAMPLES ### EXAMPLE 1 ```powershell PS C:\> $b = "(?\d{2}-\d{2}-\d{4}\s\d{2}:\d{2}).*(?\d+),\s+(?.*):\s+(?\w+),\s+(?(\w+\\)*\w+\.\w+)" PS C:\> convertfrom-text -pattern $b -path C:\windows\DtcInstall.log Date : 10-18-2018 10:49 Error : 0 Step : CMsdtcUpgradePlugin::PostApply Action : Enter Path : com\complus\dtc\dtc\msdtcstp\msdtcplugin.cpp Date : 10-18-2018 10:49 Error : 0 Step : CMsdtcUpgradePlugin::PostApply Action : Exit Path : com\complus\dtc\dtc\msdtcstp\msdtcplugin.cpp ... ``` The first command creates a variable to hold the regular expression pattern that defines named captures for content in the DtcInstall.log. The second line runs the command using the pattern and the log file. ### EXAMPLE 2 ```powershell PS C:\> $wu = "(?\d{4}-\d{2}-\d{2})\s+(?