PwSh.Fw.Core.psm1
|
<#
.SYNOPSIS PwSh.Fw main module : PwSh.Fw.Core .DESCRIPTION PwSh.Fw.Core contains generic purpose functions. .NOTES Author: Charles-Antoine Degennes <cadegenn@gmail.com> #> # handle $IsWindows prior to Powershell 6 if ($PSVersionTable.PSVersion.Major -lt 6) { # Powershell 1-5 is only on windows $Global:IsWindows = $true } # export $DS as a shortcut for [io.path]::DirectorySeparatorChar $Global:DS = [io.path]::DirectorySeparatorChar <# .SYNOPSIS Template function .DESCRIPTION Skeleton of a typical function to use un PwSh.Fw.Core .PARAMETER string a string .EXAMPLE New-TemplateFunction -string "a string" .NOTES General notes .LINK https://gitlab.com/pwsh.fw/pwsh.fw.core #> function New-TemplateFunction { [CmdletBinding()] [OutputType([System.String])] Param ( [Parameter(Mandatory,ValueFromPipeLine = $true)][string]$string ) Begin { Write-EnterFunction } Process { return $string } End { Write-LeaveFunction } } function Set-PwShFwConfiguration { [CmdletBinding()] [OutputType([String])] Param ( [Alias('Devel')] [Parameter(Mandatory = $false, ValueFromPipeLine = $true)][switch]$dev, [Alias('Debug_')] [Parameter(Mandatory = $false, ValueFromPipeLine = $true)][switch]$d, [Alias('Verbose_')] [Parameter(Mandatory = $false, ValueFromPipeLine = $true)][switch]$v, [Alias('Info_')] [Parameter(Mandatory = $false, ValueFromPipeLine = $true)][switch]$i, [Parameter(Mandatory = $false, ValueFromPipeLine = $true)][switch]$Trace, [Parameter(Mandatory = $false, ValueFromPipeLine = $true)][switch]$Ask, [Parameter(Mandatory = $false, ValueFromPipeLine = $true)][switch]$Quiet, [Parameter(Mandatory = $false, ValueFromPipeLine = $true)][string]$Log, [Parameter(Mandatory = $false, ValueFromPipeLine = $true)][switch]$OverridePSPreferences ) Begin { Write-EnterFunction } Process { $Global:INFO = $i $Global:VERBOSE = $v $Global:DEBUG = $d $Global:DEVEL = $dev $Global:TRACE = $trace $Global:ASK = $ask $Global:QUIET = $quiet $Global:LOG = $log # keep the order as-is please ! $Script:oldDebugPreference = $DebugPreference $Script:oldVerbosePreference = $VerbosePreference $Script:oldInformationPreference = $InformationPreference if ($ASK) { Set-PSDebug -Step } if ($TRACE) { # Set-PSDebug -Trace 1 $Global:DEVEL = $true } if ($DEVEL) { $Global:DEBUG = $true; } if ($DEBUG) { # $DebugPreference= ( $OverridePSPreferences ? "Continue" : "SilentlyContinue") if ($OverridePSPreferences) { $DebugPreference = "Continue" } else { $DebugPreference = "SilentlyContinue" } $Global:VERBOSE = $true } if ($VERBOSE) { # $VerbosePreference= ( $OverridePSPreferences ? "Continue" : "SilentlyContinue") if ($OverridePSPreferences) { $VerbosePreference = "Continue" } else { $VerbosePreference = "SilentlyContinue" } $Global:INFO = $true } if ($INFO) { # $InformationPreference= ( $OverridePSPreferences ? "Continue" : "SilentlyContinue") if ($OverridePSPreferences) { $InformationPreference = "Continue" } else { $InformationPreference = "SilentlyContinue" } } if ($QUIET) { $Global:DEVEL = $false $Global:DEBUG = $false; $Global:VERBOSE = $false $Global:INFO = $false # $DebugPreference= ( $OverridePSPreferences ? "SilentlyContinue" : "SilentlyContinue") # $VerbosePreference= ( $OverridePSPreferences ? "SilentlyContinue" : "SilentlyContinue") # $InformationPreference= ( $OverridePSPreferences ? "SilentlyContinue" : "SilentlyContinue") if ($OverridePSPreferences) { $DebugPreference = "Continue" } else { $DebugPreference = "SilentlyContinue" } if ($OverridePSPreferences) { $VerbosePreference = "Continue" } else { $VerbosePreference = "SilentlyContinue" } if ($OverridePSPreferences) { $InformationPreference = "Continue" } else { $InformationPreference = "SilentlyContinue" } } if ($log) { if ($TRACE) { try { Start-Transcript -Path "$log-trace.log" Register-EngineEvent powershell.exiting -Action { Stop-Transcript } } catch { Write-Error $_ } # } else { # # add -Append:$false to overwrite logfile # # Write-ToLogFile -Message "Initialize log" -Append:$false # Write-ToLogFile -Message "Initialize log" } $null = Load-Module -Name PwSh.Fw.Log -Quiet -Policy Required Write-ToLogFile -Message "Initialize log" } } End { Write-LeaveFunction } } <# .SYNOPSIS Reset PwSh Framework to default configuration .DESCRIPTION Reset all configurations previously set by Set-PwShFwConfiguration .EXAMPLE Reset-PwShFwConfiguration #> function Reset-PwShFwConfiguration { [CmdletBinding()] [OutputType([void])] Param ( # [Parameter(Mandatory = $true, ValueFromPipeLine = $true)][string]$string ) Begin { Write-EnterFunction } Process { if ($Global:TRACE -and $Global:LOG) { Stop-Transcript } $Global:INFO = $false $Global:VERBOSE = $false $Global:DEBUG = $false $Global:DEVEL = $false $Global:TRACE = $false $Global:ASK = $false $Global:QUIET = $false $Global:LOG = $null $DebugPreference = $Script:oldDebugPreference $VerbosePreference = $Script:oldVerbosePreference $InformationPreference = $Script:oldInformationPreference } End { Write-LeaveFunction } } function Get-PwShFwConfiguration { [CmdletBinding()] [OutputType([Void])] Param ( ) Begin { Write-EnterFunction } Process { Write-Message "INFO = $($Global:INFO)" Write-Message "VERBOSE = $($Global:VERBOSE)" Write-Message "DEBUG = $($Global:DEBUG)" Write-Message "DEVEL = $($Global:DEVEL)" Write-Message "TRACE = $($Global:TRACE)" Write-Message "ASK = $($Global:ASK)" Write-Message "QUIET = $($Global:QUIET)" Write-Message "LOG = $($Global:LOG)" } End { Write-LeaveFunction } } # function Get-PwShFwModuleInfos { # [CmdletBinding()][OutputType([String])]Param ( # # [Parameter(Mandatory = $true, ValueFromPipeLine = $true)][string]$string # ) # Begin { # # eenter($Script:NS + '\' + $MyInvocation.MyCommand) # } # Process { # Write-Output "PSCommandPath = $PSCommandPath" # Write-Output "PSScriptRoot = $PSScriptRoot" # } # End { # # eleave($Script:NS + '\' + $MyInvocation.MyCommand) # } # } <# .SYNOPSIS Execute a DOS/Shell command. .DESCRIPTION Wrapper for executing a DOS/Shell command. It handle (not yet) logging, (not yet) simulating and (not yet) asking. Please use following syntax : $rc = Execute-Commande "commande.exe" "arguments" to catch return code. Otherwise it will be printed to stdout and its quite ugly. .EXAMPLE $rc = Execute-Command "net" "use w: \\srv\share" .EXAMPLE $rc = Execute-Command -exe "net" -args "use w: \\srv\share" .LINK https://gitlab.com/pwsh.fw/pwsh.fw.core #> function Execute-Command() { [CmdletBinding(DefaultParameterSetName = "OUTBOOL", SupportsShouldProcess = $true)] [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseApprovedVerbs", "", Justification="Execute-Command is a more intuitive verb for this function and does not conflict with default Invoke-Command cmdlet.")] param( # full path to executable [parameter(mandatory=$true, position=0)][string]$exe, # all arguments enclosed in double-quotes. You may have to escape inner quotes to handle args with special characters. [parameter(mandatory=$false, position=1, ValueFromRemainingArguments=$true)][string]$args, # Return code will be an int [parameter(ParameterSetName = 'OUTINT')][switch]$AsInt, # Return code will be a boolean [parameter(ParameterSetName = 'OUTBOOL')][switch]$AsBool, # Specify to run the command raw, blindly, without trying to guess anything [switch]$Raw, # move to working directory before executing command [string]$WorkingDir = (Get-Location).path, # Return code will be the command's output [parameter(ParameterSetName = 'OUTPUT')][switch]$PassThru ) Push-Location $WorkingDir if ($Raw) { $exe = "& '" + $exe + "'" } else { $cmd = Get-Command -Name "$exe" switch ($cmd.CommandType) { 'Application' { $exe = "& '" + $exe + "'" break } 'ExternalScript' { $exe = "& '" + $exe + "'" break } 'Cmdlet' { } default { $exe = "& '" + $exe + "'" break } } } Write-Debug "$exe $args" # $rcFile = $([System.IO.Path]::GetTempPath() + [IO.Path]::DirectorySeparatorChar + "rc") $rcFile = $([System.IO.Path]::GetTempPath() + "rc") # edevel("rcFile = $rcFile") # try { # if ($Global:DEVEL) { # if ($AsInt) { # Invoke-Expression ("$exe $args; `$LastExitCode | Out-File '$rcFile'") | Foreach-Object { Write-Devel $_ } # } else { # Invoke-Expression ("$exe $args; `$? | Out-File '$rcFile'") | Foreach-Object { Write-Devel $_ } # } # #return $? # } elseif ($Global:DEBUG) { # if ($AsInt) { # Invoke-Expression ("$exe $args; `$LastExitCode | Out-File '$rcFile'") | Out-Null # } else { # Invoke-Expression ("$exe $args; `$? | Out-File '$rcFile'") | Out-Null # } # #return $? # } else { # if ($AsInt) { # Invoke-Expression ("$exe $args; `$LastExitCode | Out-File '$rcFile'") | Out-Null # } else { # Invoke-Expression ("$exe $args; `$? | Out-File '$rcFile'") | Out-Null # } # #return $? # } if ($PSCmdlet.ShouldProcess("$exe $args", "Execute command")) { if ($AsInt) { $out = Invoke-Expression ("$exe $args `n `$LastExitCode | Out-File '$rcFile'") } else { $out = Invoke-Expression ("$exe $args `n `$? | Out-File '$rcFile'") } if ($Global:DEVEL) { $out | Foreach-Object { Write-Devel $_ } # } elseif ($Global:DEBUG) { # $out | Foreach-Object { Write-MyDebug $_ } } } else { # fake successful return return $true } # $rc = Get-Content "$rcFile" -Raw # # edevel("rc = $rc") # Remove-Item "$rcFile" # # edevel("return $rc") # # if ($null -ne $rc) { # return $rc # } else { # return $false # } # return $true # } catch { # return $false # } if ($AsInt) { return Get-Content "$rcFile" -Raw } if ($AsBool) { return Get-Content "$rcFile" | Resolve-Boolean } if ($PassThru) { return $out } Pop-Location } <# .SYNOPSIS Wrapper for Import-Module .DESCRIPTION It handle everything to not worry about error messages. * check if module exist in module path * if an absolute filename is given, check if module exist as well as manifest * load-it with an optional $Force parameter * write a warning if module cannot be found .PARAMETER Name Name of the module to load .PARAMETER FullyQualifiedName Absolute path and name of the module to load. It can be either the manifest file (.psd1) or the module file (.psm1) .PARAMETER Force Force a reload if module is already loaded .LINK https://gitlab.com/pwsh.fw/pwsh.fw.core #> function Load-Module { [CmdletBinding( DefaultParameterSetName="NAME" )] [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseApprovedVerbs", "", Justification="Load-Module is a more intuitive verb for this function and does not conflict with default Get-Module cmdlet.")] Param ( [Parameter(ParameterSetName="NAME",Mandatory,ValueFromPipeLine = $true)] [string]$Name, [Parameter(ParameterSetName="FILENAME",Mandatory,ValueFromPipeLine = $true)] [string]$FullyQualifiedName, [switch]$Force, [ValidateSet('Required', 'Optional')] [string]$Policy = "Required", [switch]$Quiet ) Begin { # eenter($MyInvocation.MyCommand) } Process { if ($Quiet) { $oldQuiet = $Global:QUIET $Global:QUIET = $true } switch ($PSCmdlet.ParameterSetName) { "NAME" { $module = Get-Module -ListAvailable $Name | Sort-Object -Property Version | Select-Object -Last 1 if ($null -eq $module) { # fake module to display correct informations # PowerShell < 5 does not return anything $module = @{ name = $Name; path = $null} } break } "FILENAME" { $module = Get-Module -ListAvailable $FullyQualifiedName -ErrorAction Ignore | Sort-Object -Property Version | Select-Object -Last 1 if ($null -eq $module) { # fake module to display correct informations # PowerShell < 5 does not return anything $module = @{ name = (Split-Path -Leaf $FullyQualifiedName); path = $FullyQualifiedName} } break } } # exit if module is already loaded $rc = Get-Module -Name $module.Name if ($null -ne $rc) { if ($Force -eq $false) { Write-Debug "Module $($module.name) already loaded..." if ($Quiet) { $Global:QUIET = $oldQuiet } return $true } } if ($Global:VERBOSE) { if ($Global:DEBUG) { Write-Debug "Importing module $($module.name) from '$($module.Path)'" } else { Write-Verbose "Importing module $($module.name)" } } switch ($Policy) { 'Required' { $ErrorAction = 'Ignore' # $ErrorAction = 'Continue' } 'Optional' { $ErrorAction = 'Ignore' } } switch ($PSCmdlet.ParameterSetName) { "NAME" { Import-Module -Name $module.name -Global -Force:$Force -DisableNameChecking -ErrorAction $ErrorAction $rc = $? break } "FILENAME" { # -FullyQualifiedName is not supported in PS < 5 if ($PSVersionTable.PSVersion.Major -lt 5) { Import-Module $module.Path -Global -Force:$Force -DisableNameChecking -ErrorAction $ErrorAction } else { Import-Module -FullyQualifiedName $module.Path -Global -Force:$Force -DisableNameChecking -ErrorAction $ErrorAction } $rc = $? break } } switch ($Policy) { 'Required' { if ($rc -eq $false) { efatal("Module $($module.name) was not found and policy is '$Policy'.") } } 'Optional' { } } if ($Global:VERBOSE) { eend $rc } if ($Quiet) { $Global:QUIET = $oldQuiet } return $rc } End { # eleave($MyInvocation.MyCommand) } } <# .SYNOPSIS Override the default Microsoft's Get-ItemPropertyValue .DESCRIPTION Long description .PARAMETER string Parameter description .EXAMPLE An example .NOTES General notes #> function Get-RawItemPropertyValue { [CmdletBinding()] [OutputType([String])] Param ( [Parameter(Mandatory = $true, ValueFromPipeLine = $true)][string]$string ) Begin { Write-EnterFunction } Process { return $string } End { Write-LeaveFunction } } <# .SYNOPSIS Test if a registry property exist .DESCRIPTION There is not yet a builtin function to test existence of registry value. Thanks to Jonathan Medd, here it is. .PARAMETER RegPath Registry path to the key .EXAMPLE Test-RegKeyExist -RegPath HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion .NOTES General notes .LINK https://www.jonathanmedd.net/2014/02/testing-for-the-presence-of-a-registry-key-and-value.html #> function Test-RegKeyExist { param ( [Alias('Path')] [parameter(Mandatory=$true)][ValidateNotNullOrEmpty()]$RegPath ) Test-Path -Path $RegPath -PathType Container } <# .SYNOPSIS Test if a registry property exist .DESCRIPTION There is not yet a builtin function to test existence of registry value. Thanks to Jonathan Medd, here it is. .PARAMETER RegPath Registry path to the key .PARAMETER Name Name of the value to test .EXAMPLE Test-RegValueExist -RegPath HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion -Value ProgramFilesDir .NOTES General notes .LINK https://www.jonathanmedd.net/2014/02/testing-for-the-presence-of-a-registry-key-and-value.html #> function Test-RegValueExist { param ( [parameter(Mandatory=$true)] [ValidateNotNullOrEmpty()]$RegPath, [parameter(Mandatory=$true)] [ValidateNotNullOrEmpty()]$Name ) try { $null = Get-ItemProperty -Path $RegPath -Name $Name -ErrorAction Stop return $true } catch { return $false } } <# .SYNOPSIS Test if a variable exist .DESCRIPTION This function is silent and only return $true if the variable exist or $false otherwise. .PARAMETER Name a variable name to test .EXAMPLE Test-Variable -Name "myvar" .LINK https://gitlab.com/pwsh.fw/pwsh.fw.core #> function Test-Variable { [CmdletBinding()]Param ( [Parameter(Mandatory,ValueFromPipeLine = $true)][string]$Name ) Begin { # eenter($MyInvocation.MyCommand) } Process { Get-Variable -Name $Name -ErrorAction SilentlyContinue | Out-Null return $? } End { # eleave($MyInvocation.MyCommand) } } <# .SYNOPSIS Get a property value from a file .DESCRIPTION Get a property value from a file. The content of the file must be in the StringData format .PARAMETER Filename Path and name of the file to fetch data from .PARAMETER Propertyname Property to fetch .EXAMPLE Get-PropertyValueFromFile -Filename ./project.conf -PropertyName Version .NOTES General notes .LINK https://gitlab.com/pwsh.fw/pwsh.fw.core #> function Get-PropertyValueFromFile { [CmdletBinding()]Param ( [Parameter(Mandatory=$true,ValueFromPipeline=$true)] [string]$Filename, [Parameter(Mandatory=$true,ValueFromPipeline=$true)] [string]$Propertyname ) Begin { # eenter($MyInvocation.MyCommand) } Process { $value = (Get-Content $Filename -Raw | ConvertFrom-StringData).$Propertyname # trim quotes $value = $value -replace "'", "" -replace '"', '' return $value } End { # eleave($MyInvocation.MyCommand) } } <# .SYNOPSIS Add a custom path to the PSModulePath environment variable. .DESCRIPTION Add a custom path to the PSModulePath environment variable. .PARAMETER Path Path to add .PARAMETER First If specified, add the Path at the beginning of PSModulePath .EXAMPLE Add-PSModulePath -Path c:\MyProject\MyModules .EXAMPLE "C:\MyProject\MyModules" | Add-PSModulePath -First .NOTES General notes .LINK https://gitlab.com/pwsh.fw/pwsh.fw.core #> function Add-PSModulePath { [CmdletBinding()]Param ( [Parameter(Mandatory,ValueFromPipeLine = $true)][string]$Path, [switch]$First ) Begin { # eenter($Script:NS + '\' + $MyInvocation.MyCommand) } Process { try { $current = [Environment]::GetEnvironmentVariable('PSModulePath') -split [io.path]::PathSeparator if ($First) { if ($current -is [array]) { [array]$newPSpath = @($Path) + $current } else { [array]$newPSpath = @($Path) + @($current) } } else { if ($current -is [array]) { [array]$newPSpath = $current + @($Path) } else { [array]$newPSpath = @($current) + @($Path) } } $newpath = ($newPSpath | Get-Unique) -join [IO.Path]::PathSeparator [Environment]::SetEnvironmentVariable('PSModulePath', $newpath) Write-Devel "PSModulePath = $([Environment]::GetEnvironmentVariable('PSModulePath'))" } catch { Write-Warning "$($_.Exception.ItemName): $($_.Exception.Message)" } # edevel("env:PSModulePath = " + $env:PSModulePath) } End { # eleave($Script:NS + '\' + $MyInvocation.MyCommand) } } <# .SYNOPSIS Get the current PSModulePath environment variable. .DESCRIPTION Return the current value of the PSModulePath environment variable .EXAMPLE Get-PSModulePath .NOTES General notes .LINK https://gitlab.com/pwsh.fw/pwsh.fw.core #> function Get-PSModulePath { [CmdletBinding()]Param ( ) Begin { } Process { return [Environment]::GetEnvironmentVariable('PSModulePath') } End { } } <# .SYNOPSIS Convert a config file in a Hashtable of "key = value" pair .DESCRIPTION At this time, supported configuration files are .yml containing a list of "key: value" in the YAML language .txt containing a list of "key = value" pair (can be .conf or .whatever) .PARAMETER File Complete path and filename of a file containing key=value pairs .EXAMPLE $conf = ConvertFrom-ConfigFile "./config.conf" This example will load all "key = value" pair into the $conf object #> function ConvertFrom-ConfigFile { [CmdletBinding()][OutputType([Hashtable])]Param ( [Parameter(Mandatory = $true,ValueFromPipeLine = $true)][string]$File ) Begin { } Process { if (-not(fileExist $File)) { eerror("Config file '" + $File + "' not found.") return @{} } $item = Get-Item $File switch ($item.extension) { '.yaml' { $conf = Get-Content $File -Raw | ConvertFrom-Yaml } '.yml' { $conf = Get-Content $File -Raw | ConvertFrom-Yaml } default { $conf = Get-Content $File | ConvertFrom-StringData if ($conf.Keys.Count -gt 0) { $conf = $conf.Keys | ForEach-Object { $c = @{} } { $c[$_] = $conf.$_.Trim('"') } { $c } } else { $conf = @{} } } } return $conf } End { } } <# .SYNOPSIS Helper function for argument completer .DESCRIPTION Get valid values from a path to use with ArgumentCompleter object .PARAMETER Path Path to search in .PARAMETER Filter Optional filter to pass to Get-ChildItem .EXAMPLE [ArgumentCompleter( { param($Command, $Parameter, $WordToComplete, $CommandAst, $FakeBoundParams) Get-ValidValuesFromPath -Path "/my/path" | Where-Object { $_ -like "$wordToComplete*" } } )] [ValidateScript( { $_ -in (Get-ValidValuesFromPath -Path "/my/path") } )] .NOTES General notes #> function Get-ValidValuesFromPath { [CmdletBinding()] param($Path, $Filter) (Get-ChildItem -Path $Path -File -Filter $Filter).Name } Set-Alias -Force -Name eexec -Value Execute-Command Set-Alias -Force -Name fileExist -Value Test-FileExist Set-Alias -Force -Name dirExist -Value Test-DirExist Set-Alias -Force -Name regKeyExist -Value Test-RegKeyExist Set-Alias -Force -Name regValueExist -Value Test-RegValueExist Set-Alias -Force -Name varExist -Value Test-Variable # Export-ModuleMember -Function * -Alias * |