Includes/PwSh.Fw.Build.Powershell.psm1
|
<#
.SYNOPSIS Convert a generic hashtable into useful ModuleSettings metadata .DESCRIPTION Extract from an object useful properties to use as a module manifest settings .PARAMETER Metadata object filled with various properties .EXAMPLE $project = gc ./project.yml -raw | convertfrom-yaml $project | ConvertTo-PowershellModuleSettings This example will convert a project definition file into a useable hashtable to inject into Update-ModuleManifest .NOTES General notes #> function ConvertTo-PowershellModuleSettings { [CmdletBinding()][OutputType([hashtable])]Param ( [Parameter(Mandatory = $true, ValueFromPipeLine = $true)][object]$Metadata ) Begin { } Process { $ModuleSettings = @{} if ($Metadata) { # if ($Metadata.name) { $ModuleSettings.Name = $Metadata.name } if ($Metadata.Version) { $ModuleSettings.ModuleVersion = $Metadata.Version } if ($Metadata.ModuleVersion) { $ModuleSettings.ModuleVersion = $Metadata.ModuleVersion } if ($Metadata.GUID) { $ModuleSettings.GUID = $Metadata.GUID } if ($Metadata.NestedModules) { $ModuleSettings.NestedModules = $Metadata.NestedModules } if ($Metadata.Author) { $ModuleSettings.Author = $Metadata.Author } if ($Metadata.owner) { $ModuleSettings.Author = $Metadata.owner } if ($Metadata.CompanyName) { $ModuleSettings.CompanyName = $Metadata.CompanyName } if ($Metadata.Copyright) { $ModuleSettings.Copyright = $Metadata.Copyright } if ($Metadata.Description) { $ModuleSettings.Description = $Metadata.Description } if ($Metadata.ProcessorArchitecture) { $ModuleSettings.ProcessorArchitecture = $Metadata.ProcessorArchitecture } if ($Metadata.Architecture) { $ModuleSettings.ProcessorArchitecture = $Metadata.Architecture } if ($Metadata.Arch) { $ModuleSettings.ProcessorArchitecture = $Metadata.Arch } # translate Arch to correct values @see @url https://docs.microsoft.com/fr-fr/powershell/scripting/developer/module/how-to-write-a-powershell-module-manifest switch ($ModuleSettings.ProcessorArchitecture) { 'all' { $ModuleSettings.ProcessorArchitecture = 'None' } 'x64' { $ModuleSettings.ProcessorArchitecture = 'AMD64' } 'arm32' { $ModuleSettings.ProcessorArchitecture = 'ARM' } 'arm64' { $ModuleSettings.ProcessorArchitecture = 'ARM' } } if ($Metadata.RequiredModules) { $ModuleSettings.RequiredModules = $Metadata.RequiredModules } if ($Metadata.Depends) { # to be a valid RequiredModule, the module must be installed on the system $Metadata.Depends | ForEach-Object { Install-Module -Name $_ } $ModuleSettings.RequiredModules = $Metadata.Depends } if ($Metadata.PrivateData) { $ModuleSettings.PrivateData = $Metadata.PrivateData } if ($Metadata.Tags) { $ModuleSettings.Tags = $Metadata.Tags } if ($Metadata.ProjectUri) { $ModuleSettings.ProjectUri = $Metadata.ProjectUri } if ($Metadata.ProjectUrl) { $ModuleSettings.ProjectUri = $Metadata.ProjectUrl } if ($Metadata.LicenseUri) { $ModuleSettings.LicenseUri = $Metadata.LicenseUri } if ($Metadata.LicenseUrl) { $ModuleSettings.LicenseUri = $Metadata.LicenseUrl } if ($Metadata.IconUri) { $ModuleSettings.IconUri = $Metadata.IconUri } if ($Metadata.IconUrl) { $ModuleSettings.IconUri = $Metadata.IconUrl } if ($Metadata.ReleaseNotes) { $ModuleSettings.ReleaseNotes = $Metadata.ReleaseNotes } # Powershell < 6 does not know -Prerelease argument if ($PSVersionTable.PSVersion.Major -gt 5) { if ($Metadata.Prerelease) { $ModuleSettings.Prerelease = $Metadata.Prerelease } } if ($Metadata.HelpInfoUri) { $ModuleSettings.HelpInfoUri = $Metadata.HelpInfoUri } } return $ModuleSettings } End { } } <# .SYNOPSIS Create / Update module manifest. It is a wrapper of Microsoft's Update-ModuleManifest .DESCRIPTION The Update-ModuleManifestEx extends the Microsoft cmdlet Update-ModuleManifest. Actually, Update-ModuleManifestEx is a wrapper of Update-ModuleManifest (and New-ModuleManifest). It : * checks if files exists * update / create module manifest * export exact list of functions and aliases, not '*' * trims spaces at end of lines of module psm1 and psd1 files .PARAMETER FullyQualifiedName Full path to module file. Either an already existing manifest (.psd1), or a module content (.psm1) .PARAMETER Metada Metadata of manifest to use. See lists @url https://docs.microsoft.com/en-us/powershell/module/powershellget/update-modulemanifest .PARAMETER PreserveMetadata If specified, instruct Update-ModuleManifestEx to not override Metadata already present in Module Manifest. It only refresh functions to export and aliases to export. .PARAMETER PassThru If specified, return the module object. If not specified, return the path of the module manifest file. .PARAMETER CreateOnly Only create new module manifest. If specified, ignore existing module manifest. They will not be updated. NOTE: if neither CreateOnly or UpdateOnly parameter are specified, then all module manifest will be created/updated, as if both -CreateOnly and -UpdateOnly would have been used. .PARAMETER UpdateOnly Only update existing manifest. If specified, ignore missing module manifest. They will not be created. NOTE: if neither CreateOnly or UpdateOnly parameter are specified, then all module manifest will be created/updated, as if both -CreateOnly and -UpdateOnly would have been used. .EXAMPLE Update-ModuleManifestEx -FullyQualifiedName /path/to/my/module.psm1 -Metadata $Project .OUTPUTS System.Management.Automation.PSModuleInfo This cmdlet returns objects that represent modules. .NOTES General notes #> function Update-ModuleManifestEx { [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Low')][OutputType([Boolean], [String], [PSModuleInfo])]Param ( [Parameter(Mandatory = $true, ValueFromPipeLine = $true)][string]$FullyQualifiedName, [Parameter(Mandatory = $false, ValueFromPipeLine = $true)][object]$Metadata, [switch]$PreserveMetadata, [switch]$CreateOnly, [switch]$UpdateOnly, [switch]$PassThru ) Begin { # eenter($MyInvocation.MyCommand) if ($CreateOnly -eq $UpdateOnly) { $CreateOnly = $UpdateOnly = $true } } Process { # fill / translate metadata to module settings $ModuleSettings = ConvertTo-PowershellModuleSettings -Metadata $Metadata $rc = Test-Path -Path $FullyQualifiedName -PathType Leaf -ErrorAction SilentlyContinue if ($rc -eq $false) { Write-Host -ForegroundColor Red "'$FullyQualifiedName' does not exist." return $false } $file = Get-Item $FullyQualifiedName if (!($file)) { Write-Host -ForegroundColor Red "cannot get '$FullyQualifiedName' item." return $false } # load dependencies before loading module itself if ($Metadata.depends) { $Metadata.depends | Import-Module } # in case we import a module psm1 wthout psd1, we need to first import-it before getting-it # if we don't do that, $module will be empty $module = Import-Module -FullyQualifiedName "$FullyQualifiedName" -Force:$true -DisableNameChecking -PassThru if (!(Test-ModuleObject -Module $module)) { return $null } $rc = $? # Write-Information "Updating module $($module.Name)" if ($rc -eq $true) { switch ($file.Extension) { '.psd1' { $ACTION = "update" } '.psm1' { if (Test-Path "$($module.ModuleBase)/$($module.Name).psd1" -Type Leaf) { $ACTION = "update" } else { $ACTION = "create" } break } default { Throw "The file extension $($file.Extension) is not a Powershell module extension." } } # edevel("ACTION = $ACTION") Write-Debug "ACTION = $ACTION" Write-Output "$ACTION '$($module.ModuleBase)/$($module.Name).psd1'" # edevel ("Functions list :") $functionsList = Get-Command -Module $module.Name # $functionsList.Name | ForEach-Object { edevel $_} # edevel ("Aliases list :") $aliasesList = Get-Alias | Where-Object { $_.ModuleName -eq $module.Name } # $aliasesList.Name | ForEach-Object { edevel $_} if ($aliasesList.count -eq 0) { $aliasesList = '' } # handle privateData # Private metadata handling does not work, # @see issue with New-ModuleManifest @url https://github.com/PowerShell/PowerShell/issues/5922 # and issue with Update-ModuleManifest @url https://github.com/PowerShell/PowerShellGet/issues/294 # $PrivateData = @{} # if ($null -ne $Metadata) { # $PrivateData.PSData = @{} # $PrivateData.PSData.licenseUri = $Metadata.LICENSEURL # $PrivateData.PSData.projectUri = $Metadata.URL # $PrivateData.PSData.iconUri = $Metadata.ICONURL # $PrivateData.PSData.description = $Metadata.DESCRIPTION # $PrivateData.PSData.releaseNotes = $Metadata.RELEASENOTES # $PrivateData.PSData.tags = $Metadata.TAGS # } switch ($ACTION) { 'create' { if ($CreateOnly) { if ($PSCmdlet.ShouldProcess("ShouldProcess?")) { New-ModuleManifest -RootModule "$($module.Name).psm1" -Path "$($module.ModuleBase)/$($module.Name).psd1" -FunctionsToExport $functionsList -AliasesToExport $aliasesList @ModuleSettings $rc = $? } } } 'update' { if ($UpdateOnly) { if ($PSCmdlet.ShouldProcess("ShouldProcess?")) { if ($PreserveMetadata) { Update-ModuleManifest -Path "$($module.ModuleBase)/$($module.Name).psd1" -FunctionsToExport $functionsList -AliasesToExport $aliasesList } else { Update-ModuleManifest -Path "$($module.ModuleBase)/$($module.Name).psd1" -FunctionsToExport $functionsList -AliasesToExport $aliasesList @ModuleSettings } $rc = $? } } } default { Throw "ACTION '$ACTION' is not supported." } } # trim trailing spaces if (Test-Path "$($module.ModuleBase)/$($module.Name).psd1" -Type Leaf) { $content = Get-Content "$($module.ModuleBase)/$($module.Name).psd1" $content | ForEach-Object {$_.TrimEnd()} | Set-Content "$($module.ModuleBase)/$($module.Name).psd1" } else { Write-Host -ForegroundColor Red "Module '$($module.ModuleBase)/$($module.Name).psd1' manifest not found." } $content = Get-Content "$($module.ModuleBase)/$($module.Name).psm1" $content | ForEach-Object {$_.TrimEnd()} | Set-Content "$($module.ModuleBase)/$($module.Name).psm1" } # eend $? $module = Get-Module -ListAvailable -FullyQualifiedName "$($module.ModuleBase)/$($module.Name).psd1" if ($PassThru) { return $module } else { return $module.Path } } End { # eleave($MyInvocation.MyCommand) } } <# .SYNOPSIS Update a module manifest with recursivity .DESCRIPTION A module can embed nested modules. This function take care of this inclusion. It can recurse down directories to find nested modules to * create / update nested modules manifest * export functions and aliases to main module .PARAMETER FullyQualifiedName Full path to module file. Either an already existing manifest (.psd1), or a module content (.psm1) .PARAMETER Metada Metada of manifest to use. See lists @url https://docs.microsoft.com/en-us/powershell/module/powershellget/update-modulemanifest .PARAMETER Recurse If specified, instruct Update-ModuleManifestRecurse to recurse through well-known folders to find nested modules. Following policies apply : * modules found in Includes subdirectory will export their functions and alias to main module * modules found in Private sudirectory will not export anything to main module .PARAMETER PassThru If specified, return the module object. If not specified, return the path of the module manifest file. .EXAMPLE Update-ModuleManifestRecurse -FullyQualifiedName /path/to/my/module.psm1 -Metadata $Project .OUTPUTS System.Management.Automation.PSModuleInfo This cmdlet returns objects that represent modules. .NOTES General notes #> function Update-ModuleManifestRecurse { [CmdletBinding(SupportsShouldProcess = $true)][OutputType([String], [boolean])]Param ( [Parameter(Mandatory = $true, ValueFromPipeLine = $true)][string]$FullyQualifiedName, [Parameter(Mandatory = $false, ValueFromPipeLine = $true)][object]$Metadata, [switch]$CreateOnly, [switch]$UpdateOnly, [switch]$Recurse, [switch]$PassThru ) Begin { Write-EnterFunction } Process { Write-Verbose "FullyQualifiedName = $FullyQualifiedName" try { $mainModule = Update-ModuleManifestEx -FullyQualifiedName $FullyQualifiedName -Metadata $Metadata -PassThru -CreateOnly:$CreateOnly -UpdateOnly:$UpdateOnly } catch { eerror $_ return $null } if (!($mainModule)) { Write-Error "An error occured while updating manifest of '$FullyQualifiedName'." return $false } $FunctionsToExport = $mainModule.ExportedFunctions.Values.Name $AliasesToExport = $mainModule.ExportedAliases.Values.Name if ($Recurse) { $NestedModules = @() # $RequiredModules = @() Get-ChildItem -Path $mainModule.ModuleBase -Recurse -Name "*.psm1" -Exclude $mainModule.RootModule | ForEach-Object { $m = $_ Write-Information "--> Found $m" # skip mainModule if ($mainModule.RootModule -eq $_) { continue } try { $subModule = Update-ModuleManifestEx -FullyQualifiedName "$($mainModule.ModuleBase)/$_" -Metadata $Metadata -PreserveMetadata -PassThru -CreateOnly:$CreateOnly -UpdateOnly:$UpdateOnly } catch { eerror $_ return $null } # $folder = ($m -split [io.path]::DirectorySeparatorChar)[0] $folder = Split-Path -Parent $m # treat Includes as RequiredModules # $psm = Get-Item -Path "$($mainModule.ModuleBase)/$($_)" Write-Information "folder = $folder" switch ($folder) { 'Includes' { # $RequiredModules += $m $NestedModules += @("." + [io.path]::DirectorySeparatorChar + "$m") $FunctionsToExport += $subModule.ExportedFunctions.Values.Name $AliasesToExport += $subModule.ExportedAliases.Values.Name } 'Private' { $NestedModules += @("." + [io.path]::DirectorySeparatorChar + "$m") } default { } } # clean tracks Remove-Module -Name $subModule.Name } # finally update the mainModule with functions and aliases found in NestedModules # if ($RequiredModules) { # # $RequiredModules | fl # Update-ModuleManifest -Path $mainModule.Path -RequiredModules $RequiredModules # } if ($NestedModules.Count -gt 0) { if ($PSCmdlet.ShouldProcess("ShouldProcess?")) { try { Update-ModuleManifest -Path $mainModule.Path -NestedModules $NestedModules -FunctionsToExport ($FunctionsToExport | Sort-Object) -AliasesToExport ($AliasesToExport | Sort-Object) } catch { eerror $_ return $null } } } } $mainModule = Get-Module -ListAvailable -FullyQualifiedName "$($mainModule.ModuleBase)/$($mainModule.Name).psd1" if ($PassThru) { return $mainModule } else { return $mainModule.Path } } End { Write-LeaveFunction } } function Test-ModuleObject { [CmdletBinding()][OutputType([Boolean])]Param ( [AllowNull()] [Parameter(Mandatory = $true, ValueFromPipeLine = $true)][PSModuleInfo]$Module ) Begin { Write-EnterFunction } Process { $rc = $true everbose "Testing module '$($Module.Name)'" if ($null -eq $Module) { Write-Host -ForegroundColor Red "[-] Module is null." $rc = $false } else { Write-Host -ForegroundColor Green "[+] Module is not null" } if ([string]::IsNullOrEmpty($Module.Name)) { Write-Host -ForegroundColor Red "[-] Module name is empty" $rc = $false } else { Write-Host -ForegroundColor Green "[+] Module name is not empty" } if ([string]::IsNullOrEmpty($Module.ModuleBase)) { Write-Host -ForegroundColor Red "[-] ModuleBase is empty (VERY DANGEROUS)" $rc = $false } else { Write-Host -ForegroundColor Green "[+] ModuleBase seems ok (part #1)" } if ($Module.ModuleBase -eq '/') { Write-Host -ForegroundColor Red "[-] ModuleBase is '/' (VERY DANGEROUS)" $rc = $false } else { Write-Host -ForegroundColor Green "[+] ModuleBase seems ok (part #2)" } if ($Module.ModuleBase -eq $env:SystemRoot) { Write-Host -ForegroundColor Red "[-] ModuleBase is '$($env:SystemRoot)' (VERY DANGEROUS)" $rc = $false } else { Write-Host -ForegroundColor Green "[+] ModuleBase seems ok (part #3)" } return $rc } End { Write-LeaveFunction } } |