SCOrchDev-Utility.psm1
|
#requires -Version 2 <# .SYNOPSIS Converts an object into a text-based represenation that can easily be written to logs. .DESCRIPTION Format-ObjectDump takes any object as input and converts it to a text string with the name and value of all properties the object's type information. If the property parameter is supplied, only the listed properties will be included in the output. .PARAMETER InputObject The object to convert to a textual representation. .PARAMETER Property An optional list of property names that should be displayed in the output. #> Function Format-ObjectDump { [CmdletBinding()] [OutputType([string])] Param( [Parameter(Position = 0, Mandatory = $True,ValueFromPipeline = $True)] [Object]$InputObject, [Parameter(Position = 1, Mandatory = $False)] [string[]] $Property = @('*') ) $typeInfo = $InputObject.GetType() | Out-String $objList = $InputObject | ` Format-List -Property $Property | ` Out-String return "$typeInfo`r`n$objList" } <# .SYNOPSIS Converts an input string into a boolean value. .DESCRIPTION $values = @($null, [String]::Empty, "True", "False", "true", "false", " true ", "0", "1", "-1", "-2", '2', "string", 'y', 'n' 'yes', 'no', 't', 'f'); foreach ($value in $values) { Write-Verbose -Message "[$($Value)] Evaluated as [`$$(ConvertTo-Boolean -InputString $value)]" -Verbose } VERBOSE: [] Evaluated as [$False] VERBOSE: [] Evaluated as [$False] VERBOSE: [True] Evaluated as [$True] VERBOSE: [False] Evaluated as [$False] VERBOSE: [true] Evaluated as [$True] VERBOSE: [false] Evaluated as [$False] VERBOSE: [ true ] Evaluated as [$True] VERBOSE: [0] Evaluated as [$False] VERBOSE: [1] Evaluated as [$True] VERBOSE: [-1] Evaluated as [$True] VERBOSE: [-2] Evaluated as [$True] VERBOSE: [2] Evaluated as [$True] VERBOSE: [string] Evaluated as [$True] VERBOSE: [y] Evaluated as [$True] VERBOSE: [n] Evaluated as [$False] VERBOSE: [yes] Evaluated as [$True] VERBOSE: [no] Evaluated as [$False] VERBOSE: [t] Evaluated as [$True] VERBOSE: [f] Evaluated as [$False] .PARAMETER InputString The string value to convert #> Function ConvertTo-Boolean { [OutputType([string])] Param( [Parameter(Mandatory = $True, ValueFromPipeline = $True)] [AllowNull()] [string] $InputString ) if(-not [System.String]::IsNullOrEmpty($InputString)) { $res = $True $success = [bool]::TryParse($InputString,[ref]$res) if($success) { return $res } else { $InputString = ([string]$InputString).ToLower() Switch ($InputString) { 'f' { $False } 'false' { $False } 'off' { $False } 'no' { $False } 'n' { $False } default { try { return [bool]([int]$InputString) } catch { return [bool]$InputString } } } } } else { return $False } } <# .SYNOPSIS Given a list of values, returns the first value that is valid according to $FilterScript. .DESCRIPTION Select-FirstValid iterates over each value in the list $Value. Each value is passed to $FilterScript as $_. If $FilterScript returns true, the value is considered valid and will be returned if no other value has been already. If $FilterScript returns false, the value is deemed invalid and the next element in $Value is checked. If no elements in $Value are valid, returns $Null. .PARAMETER Value A list of values to check for validity. .PARAMETER FilterScript A script block that determines what values are valid. Elements of $Value can be referenced by $_. By default, values are simply converted to Bool. #> Function Select-FirstValid { # Don't allow values from the pipeline. The pipeline does weird things with # nested arrays. Param( [Parameter(Mandatory = $True, ValueFromPipeline = $False)] [AllowNull()] $Value, [Parameter(Mandatory = $False)] $FilterScript = { $_ -As [Bool] } ) ForEach($_ in $Value) { If($FilterScript.InvokeWithContext($Null, (Get-Variable -Name '_'), $Null)) { Return $_ } } Return $Null } <# .SYNOPSIS Returns a dictionary mapping the name of a PowerShell command to the file containing its definition. .DESCRIPTION Find-DeclaredCommand searches $Path for .ps1 files. Each .ps1 is tokenized in order to determine what functions and workflows are defined in it. This information is used to return a dictionary mapping the command name to the file in which it is defined. .PARAMETER Path The path to search for command definitions. #> function Find-DeclaredCommand { Param( [Parameter(Mandatory = $True, ValueFromPipeline = $True)] [String] $Path ) $RunbookPaths = Get-ChildItem -Path $Path -Include '*.ps1' -Recurse $DeclaredCommandMap = @{} foreach ($Path in $RunbookPaths) { $Tokens = [System.Management.Automation.PSParser]::Tokenize((Get-Content -Path $Path), [ref] $Null) For($i = 0 ; $i -lt $Tokens.Count - 1 ; $i++) { $Token = $Tokens[$i] if($Token.Type -eq 'Keyword' -and $Token.Content -in @('function', 'workflow')) { Write-Debug -Message "Found command $($NextToken.Content) in $Path of type $($Token.Content)" $NextToken = $Tokens[$i+1] $DeclaredCommandMap."$($NextToken.Content)" = @{ 'Path' = $Path 'Type' = $Token.Content } } } } return $DeclaredCommandMap } <# .SYNOPSIS A wrapper around [String]::IsNullOrWhiteSpace. .DESCRIPTION Provides a PowerShell function wrapper around [String]::IsNullOrWhiteSpace, since PowerShell Workflow will not allow a direct method call. .PARAMETER String The string to pass to [String]::IsNullOrWhiteSpace. #> Function Test-IsNullOrWhiteSpace { [OutputType([bool])] Param([Parameter(Mandatory = $True, ValueFromPipeline = $True)] [AllowNull()] $String) Return [String]::IsNullOrWhiteSpace($String) } <# .SYNOPSIS A wrapper around [String]::IsNullOrEmpty. .DESCRIPTION Provides a PowerShell function wrapper around [String]::IsNullOrEmpty, since PowerShell Workflow will not allow a direct method call. .PARAMETER String The string to pass to [String]::IsNullOrEmpty. #> Function Test-IsNullOrEmpty { [OutputType([bool])] Param( [Parameter(Mandatory = $True, ValueFromPipeline = $True)] [AllowNull()] $String ) Return [String]::IsNullOrEmpty($String) } <# .Synopsis Takes a pscustomobject and converts into a IDictionary. Translates all membertypes into keys for the IDictionary .Parameter InputObject The input pscustomobject object to convert .Parameter MemberType The membertype to change into a key property .Parameter KeyFilterScript A script to run to manipulate the keyname during grouping. #> Function ConvertFrom-PSCustomObject { [OutputType([hashtable])] Param( [Parameter(Mandatory = $True, ValueFromPipeline = $True)] [AllowNull()] $InputObject, [Parameter(Mandatory = $False)] [System.Management.Automation.PSMemberTypes] $MemberType = [System.Management.Automation.PSMemberTypes]::NoteProperty, [Parameter(Mandatory = $False)] [ScriptBlock] $KeyFilterScript = { Param($KeyName) $KeyName } ) $outputObj = @{} foreach($KeyName in ($InputObject | Get-Member -MemberType $MemberType).Name) { $KeyName = Invoke-Command -ScriptBlock $KeyFilterScript -ArgumentList $KeyName if(-not (Test-IsNullOrEmpty -String $KeyName)) { if($outputObj.ContainsKey($KeyName)) { $outputObj += $InputObject."$KeyName" } else { $Null = $outputObj.Add($KeyName, $InputObject."$KeyName") } } } return $outputObj } <# .Synopsis Converts an object or array of objects into a hashtable by grouping them by the target key property .Parameter InputObject The object or array of objects to convert .Parameter KeyName The name of the property to group the objects by .Parameter KeyFilterScript A script to run to manipulate the keyname during grouping. #> Function ConvertTo-Hashtable { [OutputType([hashtable])] Param( [Parameter(Mandatory = $True, ValueFromPipeline = $True)] [AllowNull()] $InputObject, [Parameter(Mandatory = $True)][string] $KeyName, [Parameter(Mandatory = $False)][ScriptBlock] $KeyFilterScript = { Param($Key) $Key } ) $outputObj = @{} foreach($Object in $InputObject) { $Key = $Object."$KeyName" $Key = Invoke-Command -ScriptBlock $KeyFilterScript -ArgumentList $Key if(-not (Test-IsNullOrEmpty -String $Key)) { if($outputObj.ContainsKey($Key)) { $outputObj[$Key] += $Object } else { $Null = $outputObj.Add($Key, @($Object)) } } } return $outputObj } <# .Synopsis Updates the local powershell environment path. Sets the target path as a part of the environment path if it does not already exist there .Parameter Path The path to add to the system environment variable 'path'. Only adds if it is not already there #> Function Add-PSEnvironmentPathLocation { Param( [Parameter( Mandatory = $True, ValueFromPipeline = $True, Position = 0 )] $Path, [Parameter( Mandatory = $False, ValueFromPipeline = $True, Position = 1 )] [System.EnvironmentVariableTarget] $Location = [System.EnvironmentVariableTarget]::User ) $CurrentPSModulePath = [System.Environment]::GetEnvironmentVariable('PSModulePath', $Location) if(-not($CurrentPSModulePath.ToLower().Contains($Path.ToLower()))) { Write-Verbose -Message "The path [$Path] was not in the environment path [$CurrentPSModulePath]. Adding." [Environment]::SetEnvironmentVariable( 'PSModulePath', "$CurrentPSModulePath;$Path", $Location ) } } <# .Synopsis Looks for the tag workflow in a file and returns the next string .Parameter FilePath The path to the file to search #> Function Get-WorkflowNameFromFile { Param([Parameter(Mandatory=$true)][string] $FilePath) $DeclaredCommands = Find-DeclaredCommand -Path $FilePath Foreach($Command in $DeclaredCommands.Keys) { if($DeclaredCommands.$Command.Type -eq 'Workflow') { return $Command -as [string] } } Throw-Exception -Type 'NoWorkflowDefined' -Message 'No workflow defined in file' } <# .Synopsis Tests to see if a file has a PS workflow defined inside of it .Parameter FilePath The path to the file to search #> Function Test-FileIsWorkflow { Param([Parameter(Mandatory=$true)][string] $FilePath) try { Get-WorkflowNameFromFile -FilePath $FilePath } catch { $Exception = $_ $ExceptionInformation = Get-ExceptionInfo -Exception $Exception Switch ($ExceptionInformation.FullyQualifiedErrorId) { 'NoWorkflowDefined' { return $false } } } return $true } <# .Synopsis Creates a script name based on the filename .Parameter FilePath The path to the file #> Function Get-ScriptNameFromFileName { Param([Parameter(Mandatory=$true)][string] $FilePath) $CompletedParams = Write-StartingMessage -Stream Debug $MatchRegex = '([^\.]+)' -as [string] $FileInfo = Get-Item -Path $FilePath if($FileInfo.Name -match $MatchRegex) { Return $Matches[1] } else { Throw-Exception -Type 'CouldNotDetermineName' -Message 'Could not determine the script name' } Write-CompletedMessage @CompletedParams } <# .SYNOPSIS Given a hashtable, filters entries based on their value. Returns a new hashtable whose elements are only those whose value cause $FilterScript to return $True. .PARAMETER Hashtable The hashtable to filter. .PARAMETER FilterScript The filter script to apply to each element of the hashtable. #> Function Select-Hashtable { param( [Parameter(Mandatory=$True)] [Hashtable] $Hashtable, [Parameter(Mandatory=$False)] [ScriptBlock] $FilterScript = { $_ -as [Bool] } ) $FilteredHashtable = @{} foreach($Element in $Hashtable.GetEnumerator()) { $_ = $Element.Value if($FilterScript.InvokeWithContext($null, (Get-Variable -Name '_'), $null)) { $FilteredHashtable[$Element.Name] = $Element.Value } } return $FilteredHashtable } <# .Synopsis Writes a finished verbose message #> function Write-CompletedMessage { Param( [Parameter(Mandatory=$True)] [datetime] $StartTime, [Parameter(Mandatory=$True)] [String] $Name, [Parameter(Mandatory=$False)] [String] $Status = $Null, [Parameter(Mandatory=$False)] [ValidateSet('Debug', 'Error', 'Verbose', 'Warning')] [String] $Stream = 'Verbose', [Parameter(Mandatory=$False)] [switch] $PassThru ) if($Name -notmatch '^\[.*]$') { $Name = "[$Name]" } if($Status -as [bool]) { $Name = "$Name [$Status]" } $LogCommand = (Get-Command -Name "Write-$Stream") $EndTime = Get-Date $ElapsedTime = ($EndTime - $StartTime).TotalSeconds $Message = "Completed $Name in [$($ElapsedTime)] Seconds" & $LogCommand -Message $Message ` -WarningAction Continue if($PassThru.IsPresent) { Write-Output -InputObject @{ 'Name' = $Name 'StartTime' = $StartTime 'EndTime' = $EndTime 'ElapsedTime' = $ElapsedTime 'Message' = $Message } } } <# .Synopsis Writes the standard starting message .Parameter String An additional string to write out .Parameter Stream The stream to write the starting message to #> function Write-StartingMessage { Param( [Parameter(Mandatory=$False)] [String] $CommandName = '', [Parameter(Mandatory=$False)] [String] $String = '', [Parameter(Mandatory=$False)] [ValidateSet('Debug', 'Error', 'Verbose', 'Warning')] [String] $Stream = 'Verbose' ) $ErrorActionPreference = [System.Management.Automation.ActionPreference]::Stop $_CommandName = Select-FirstValid $Commandname, ((Get-PSCallStack)[1].Command -as [string]) $Name = [string]::Empty if($_CommandName -as [bool]) { if($String -as [bool]) { $Name = "[$_CommandName] [$String]" } else { $Name = "[$_CommandName]" } } elseif($String -as [bool]) { $Name = "[$String]" } else { $ExceptionMessage = 'Could not determine the current name. Please pass the -string parameter with $WorkflowCommandName if running from workflow' -replace "`r`n", ' ' -replace ' ', '' Throw-Exception -Type 'CannotDetermineName' ` -Message $ExceptionMessage } $LogCommand = (Get-Command -Name "Write-$Stream") & $LogCommand -Message "Starting $Name" ` -WarningAction Continue ` -ErrorAction Continue Return @{ 'Name' = $Name ; 'StartTime' = (Get-Date) ; 'Stream' = $Stream} } Function Start-SleepUntil { Param( [Parameter(Mandatory=$False)] [DateTime] $DateTime = (Get-Date).AddSeconds(1) ) $ErrorActionPreference = [System.Management.Automation.ActionPreference]::Stop $CompletedParams = Write-StartingMessage -String "DateTime [$DateTime]" $SleepSeconds = ($DateTime - (Get-Date)).TotalSeconds if($SleepSeconds -gt 0) { Write-Verbose -Message "Sleeping for [$SleepSeconds] seconds" Start-Sleep -Seconds $SleepSeconds } Write-CompletedMessage @CompletedParams } Export-ModuleMember -Function * -Verbose:$False -Debug:$False |