bugfix & Actions update

Author: Friedrich Weinmann

PSModuleDevelopment/bin/PSModuleDevelopment.dll

@@ -1,5 +1,13 @@
 # Changelog
 
+## ???
+
++ New: Action: deployModule - Deploys a module to the target computer(s)
++ Upd: Invoke-PSMDBuildProject - Added parameter resolution from artifacts and configuration
++ Upd: Invoke-PSMDBuildProject - Added automatic artifacts resolution based on value of a parameter: %!Name!% will be resolved to the artifact named "Name".
++ Upd: Invoke-PSMDBuildProject - Added `-InheritArtifacts` parameter to allow keeping artifacts around created before starting the pipeline
++ Fix: Invoke-PSMDTemplate - Invoking templates on PS5.1 fails with invalid replace
+
 ## 2.2.10.123 (2021-07-21)
 
 - Fix: Template PSFProject - fixed string test modulename

PSModuleDevelopment/bin/PSModuleDevelopment.pdb

@@ -18,23 +18,27 @@
 		Mandatory if no build project has been selected as the default project.
 		Use the Select-PSMDBuildProject to define a default project (and optionally persist the choice across sessions)
 	
+	.PARAMETER InheritArtifacts
+		Accept artifacts that were generated before ever executing this pipeline.
+		By default, any artifacts previously provisioned are cleared on pipeline start.
+	
 	.PARAMETER RetainArtifacts
 		Whether, after executing the project, its artifacts should be retained.
 		By default, any artifacts created during a build project will be discarded upon project completion.
-	
+		
 		Artifacts are similar to variables to the pipeline and can be used to pass data throughout the pipeline.
 		
 		+ Use Publish-PSMDBuildArtifact to create a new artifact.
 		+ Use Get-PSMDBuildArtifact to access existing build artifacts.
 	
 	.EXAMPLE
 		PS C:\> Invoke-PSMDBuildProject -Path .\VMDeployment.build.Json
-	
+		
 		Execute the build file "VMDeployment.build.json" from the current folder
 	
 	.EXAMPLE
 		PS C:\> build
-	
+		
 		Execute the default build project.
 #>
 	[Alias('build')]
@@ -43,12 +47,17 @@
 		[string]
 		$Path,
 
+		[switch]
+		$InheritArtifacts,
+		
 		[switch]
 		$RetainArtifacts
 	)
 
 	begin {
-		$script:buildArtifacts = @{ }
+		if (-not $InheritArtifacts) {
+			$script:buildArtifacts = @{ }
+		}
 		$buildStatus = @{ }
 
 		$projectPath = $Path
@@ -158,6 +167,10 @@
 			}
 			if (-not $parameters.Parameters) { $parameters.Parameters = @{ } }
 			if (-not $parameters.ParametersFromArtifacts) { $parameters.ParametersFromArtifacts = @{ } }
+			
+			# Resolve Parameters
+			$parameters.Parameters = Resolve-PSMDBuildStepParameter -Parameters $parameters.Parameters -FromArtifacts $parameters.ParametersFromArtifacts -ProjectName $parameters.ProjectName -StepName $parameters.StepName
+			
 			try { $null = & $actionObject.Action $parameters }
 			catch {
 				Write-StepResult @resultDef -Status Failed -Data $_ -ContinueLabel main

PSModuleDevelopment/bin/PSModuleDevelopment.xml

@@ -1,11 +1,18 @@
 function Resolve-PSMDBuildStepParameter {
 <#
 	.SYNOPSIS
-		Update missing build action parameters from the configuration system.
+		Resolves and consolidates the overall parameters of a given step.
 	
 	.DESCRIPTION
-		Update missing build action parameters from the configuration system.
-		This command is for use within the defined code of build actions.
+		Resolves and consolidates the overall parameters of a given step.
+		This ensures that individual actions do not have to implement manual resolution and complex conditionals.
+		Sources of parameters:
+		- Explicitly defined parameter in the step
+		- Value from Artifacts
+		- Value from Configuration (only if not otherwise sourced)
+		- Value from implicit artifact resolution: Any value that is formatted like this:
+		  "%!NameOfArtifact!%" will be replaced with the value of the artifact of the same name.
+		  This supports wildcard resolution, so "%!Session.*!%" will resolve to all artifacts with a name starting with "Session."
 	
 	.PARAMETER Parameters
 		The hashtable containing the currently specified parameters from the step configuration within the build project file.
@@ -64,6 +71,14 @@
 			$Parameters[$pair.Key] = (Get-PSMDBuildArtifact -Name $pair.Value).Value
 		}
 
+		# Resolve implicit artifact references
+		foreach ($pair in $Parameters.GetEnumerator()) {
+			if ($pair.Value -notlike '%!*!%') { continue }
+			
+			$artifactName = $pair.Value -replace '^%!(.+?)!%$', '$1'
+			$Parameters[$pair.Key] = (Get-PSMDBuildArtifact -Name $artifactName).Value
+		}
+		
 		$Parameters
 	}
 }

PSModuleDevelopment/changelog.md

@@ -320,10 +320,10 @@
 				$fileName = $Item.Name
 				if (-not $Raw) {
 					foreach ($param in $Item.FileSystemParameterFlat) {
-						$fileName = $fileName.Replace("$($identifier)$($param)$($identifier)", $ParameterFlat[$param], $true, $null)
+						$fileName = [PSModuleDevelopment.Utility.UtilityHost]::Replace($fileName,"$($identifier)$($param)$($identifier)", $ParameterFlat[$param], $false)
 					}
 					foreach ($param in $Item.FileSystemParameterScript) {
-						$fileName = $fileName.Replace("$($identifier)$($param)$($identifier)", $ParameterScript[$param], $true, $null)
+						$fileName = [PSModuleDevelopment.Utility.UtilityHost]::Replace($fileName, "$($identifier)$($param)$($identifier)", $ParameterScript[$param], $false)
 					}
 				}
 				$destPath = Join-Path $Path $fileName
@@ -332,10 +332,10 @@
 					$text = $Item.Value
 					if (-not $Raw) {
 						foreach ($param in $Item.ContentParameterFlat) {
-							$text = $text.Replace("$($identifier)$($param)$($identifier)", $ParameterFlat[$param], $true, $null)
+							$text = [PSModuleDevelopment.Utility.UtilityHost]::Replace($text, "$($identifier)$($param)$($identifier)", $ParameterFlat[$param], $false)
 						}
 						foreach ($param in $Item.ContentParameterScript) {
-							$text = $text.Replace("$($identifier)!$($param)!$($identifier)", $ParameterScript[$param], $true, $null)
+							$text = [PSModuleDevelopment.Utility.UtilityHost]::Replace($text, "$($identifier)!$($param)!$($identifier)", $ParameterScript[$param], $false)
 						}
 					}
 					[System.IO.File]::WriteAllText($destPath, $text, $Encoding)

PSModuleDevelopment/functions/build/Invoke-PSMDBuildProject.ps1

@@ -5,7 +5,6 @@
 
 	$rootPath = $Parameters.RootPath
 	$actualParameters = $Parameters.Parameters
-	$actualParameters = Resolve-PSMDBuildStepParameter -Parameters $actualParameters -FromArtifacts $Parameters.ParametersFromArtifacts -ProjectName $Parameters.ProjectName -StepName $Parameters.StepName
 
 	#region Process Parameters
 	if (-not $actualParameters.Command) {

PSModuleDevelopment/functions/build/Resolve-PSMDBuildStepParameter.ps1

@@ -5,7 +5,6 @@
 
 	$rootPath = $Parameters.RootPath
 	$actualParameters = $Parameters.Parameters
-	$actualParameters = Resolve-PSMDBuildStepParameter -Parameters $actualParameters -FromArtifacts $Parameters.ParametersFromArtifacts -ProjectName $Parameters.ProjectName -StepName $Parameters.StepName
 
 	#region Utility Functions
 	function ConvertTo-PSSession {

PSModuleDevelopment/functions/templating/Invoke-PSMDTemplate.ps1

@@ -0,0 +1,88 @@
+$action = {
+	param (
+		$Parameters
+	)
+	
+	$rootPath = $Parameters.RootPath
+	$actualParameters = $Parameters.Parameters
+	
+	#region Validate Input
+	if (-not $actualParameters.Session) {
+		throw "No Sessions specified!"
+	}
+	
+	if ($actualParameters.Session | Where-Object State -NE Open) {
+		throw "Sessions not open!"
+	}
+	if ($actualParameters.Repository -and (-not (Get-PSRepository -Name $actualParameters.Repository -ErrorAction Ignore))) {
+		throw "Repository $($actualParameters.Repository) not found!"
+	}
+	
+	foreach ($module in $actualParameters.Module) {
+		if ($module -notmatch '\\|/') { continue }
+		
+		try { $null = Resolve-PSFPath -Path $module -Provider FileSystem }
+		catch { throw "Unable to resolve path: $module"}
+	}
+	#endregion Validate Input
+	
+	#region Prepare modules to transfer
+	$workingDirectory = Join-Path -Path (Get-PSFPath -Name temp) -ChildPath "psmd_action_$(Get-Random)"
+	$null = New-Item -Path $workingDirectory -ItemType Directory -Force -ErrorAction Stop
+	trap {
+		Remove-Item -Path $workingDirectory -Recurse -Force -ErrorAction SilentlyContinue
+		throw $_
+	}
+	
+	$saveModuleParam = @{
+		Path = $workingDirectory
+		Repository = $actualParameters.Repository
+	}
+	
+	foreach ($module in $actualParameters.Module) {
+		if ($module -notmatch '\\|/') {
+			if ($actualParameters.Repository) {
+				Save-Module $module @saveModuleParam
+				continue
+			}
+			$moduleObject = Get-Module -Name $module -ListAvailable | Sort-Object Version -Descending | Select-Object -First 1
+			if (-not $moduleObject) {
+				throw "Cannot find module $module!"
+			}
+			Copy-Item -Path $moduleObject.ModuleBase -Destination "$workingDirectory\$($moduleObject.Name)" -Recurse -Force
+			continue
+		}
+		
+		foreach ($path in Resolve-PSFPath -Path $module -Provider FileSystem) {
+			if (Test-Path -LiteralPath $path -PathType Leaf) { $path = Split-Path -LiteralPath $path }
+			Copy-Item -LiteralPath $path -Destination $workingDirectory -Recurse -Force
+		}
+	}
+	#endregion Prepare modules to transfer
+	
+	foreach ($moduleFolder in Get-ChildItem -Path $workingDirectory) {
+		if (-not $actualParameters.NoDelete) {
+			Invoke-Command -Session $actualParameters.Session -ScriptBlock {
+				param ($Name)
+				Remove-Item -Path "$env:ProgramFiles\WindowsPowerShell\Modules\$Name" -Recurse -Force
+			} -ArgumentList $moduleFolder.Name
+		}
+		foreach ($session in $actualParameters.Session) {
+			Copy-Item -LiteralPath $moduleFolder.FullName -Destination "$env:ProgramFiles\WindowsPowerShell\Modules" -Recurse -Force -ToSession $session -ErrorAction Stop
+		}
+	}
+}
+
+$params = @{
+	Name	    = 'deployModule'
+	Action	    = $action
+	Description = 'Deploys a module to the target computer(s)'
+	Parameters  = @{
+		Session    = '(mandatory) The PSRemoting sessions to deploy the module through.'
+		Module	   = '(mandatory) A list of names or paths of modules to deploy. Can be used in any combination, specifying by name will use the latest version found on the local computer unless also using he "Repository" parameter to specify an alternate source.'
+		Repository = 'The repository from which to download the module(s) (and any dependencies). Modules will be sourced locally if empty.'
+		NoDelete   = '[bool] Whether to keep other versions of the target module on the remote machine. By default, all other versions will be deleted.'
+	}
+}
+
+Register-PSMDBuildAction @params