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> #> $Script:NS = (get-item $PSCommandPath).basename # handle $IsWindows prior to Powershell 6 if ($PSVersionTable.PSVersion.Major -lt 6) { # Powershell 1-5 is only on windows $Global:IsWindows = $true } <# .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 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. .PARAMETER exe full path to executable .PARAMETER args all arguments enclosed in double-quotes. You may have to escape inner quotes to handle args with special characters. .PARAMETER AsInt Return code will be an int instead of a boolean. .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()] [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( [parameter(mandatory=$true, position=0)][string]$exe, [parameter(mandatory=$false, position=1, ValueFromRemainingArguments=$true)][string]$args, [switch]$AsInt ) $cmd = Get-Command -Name "$exe" switch ($cmd.CommandType) { 'Application' { $exe = "& '" + $exe + "'" break } 'ExternalScript' { $exe = "& '" + $exe + "'" break } 'Cmdlet' { } default { } } Write-MyDebug ($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 ($AsInt) { $out = Invoke-Expression ("$exe $args; `$LastExitCode | Out-File '$rcFile'") } else { $out = Invoke-Expression ("$exe $args; `$? | Out-File '$rcFile'") } if ($Global:DEVEL) { $out | Foreach-Object { Write-Devel $_ } # } elseif ($Global:DEBUG) { # $out | Foreach-Object { Write-MyDebug $_ } } # $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 } else { return Get-Content "$rcFile" | Resolve-Boolean } } <# .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 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 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) { ebegin("Module $($module.name) already loaded...") eend $true if ($Quiet) { $Global:QUIET = $oldQuiet } return $true } } if ($Global:VERBOSE) { if ($Global:DEBUG) { ebegin("Importing module $($module.name) from '$($module.Path)'") } else { ebegin("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 Test if a file exist .DESCRIPTION Never know if -PathType is Leaf or File, or whatever. Just use Test-FileExist. If a directory is given to Name parameter it will return $false. Use Test-DirExist instead. .PARAMETER Name Absolute or relative path to filename .EXAMPLE if (Test-FileExist "c:\windows\notepad.exe") { echo "notepad is present" } else { echo "notepad is NOT present" } .NOTES General notes .LINK https://gitlab.com/pwsh.fw/pwsh.fw.core #> function Test-FileExist { [CmdletBinding()] [OutputType([System.Boolean])] Param ( [AllowNull()][AllowEmptyString()] [Parameter(Mandatory,ValueFromPipeLine = $true)] [string]$Name ) Begin { # eenter($MyInvocation.MyCommand) } Process { if ([string]::IsNullOrEmpty($Name)) { return $false } Test-Path $Name -PathType Leaf } End { # eleave($MyInvocation.MyCommand) } } <# .SYNOPSIS Test if a directory exist .DESCRIPTION Never know if -PathType is Container or Directory, or whatever. Just use Test-DirExist. If a file is given to Path parameter it will return $false. Use Test-FileExist instead. .PARAMETER Path Absolute or relative path to test .EXAMPLE if (Test-DirExist "c:\windows") { echo "you are on Windows" } else { echo "you are NOT on Windows" } .NOTES General notes .LINK https://gitlab.com/pwsh.fw/pwsh.fw.core #> function Test-DirExist { [CmdletBinding()][OutputType([System.Boolean])]Param ( [Parameter(Mandatory,ValueFromPipeLine = $true)] [AllowNull()][AllowEmptyString()] [string]$Path ) Begin { # eenter($MyInvocation.MyCommand) } Process { if ([string]::IsNullOrEmpty($Path)) { return $false } Test-Path $Path -PathType Container } End { # eleave($MyInvocation.MyCommand) } } <# .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 | Select-Object -ExpandProperty $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 { if ($First) { $env:PSModulePath = $PATH + [IO.Path]::PathSeparator + $env:PSModulePath } else { $env:PSModulePath = $env:PSModulePath + [IO.Path]::PathSeparator + $PATH } } catch { ewarn($_.Exception.ItemName + ": " + $_.Exception.Message) } # edevel("env:PSModulePath = " + $env:PSModulePath) } End { # eleave($Script:NS + '\' + $MyInvocation.MyCommand) } } <# .SYNOPSIS Convert a config file in a Hashtable of "key = value" pair .DESCRIPTION At this time, supported configuration files are .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) { # 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 { } } 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 * |