Added build command parameter help

Author: FriedrichWeinmann

PSModuleDevelopment/PSModuleDevelopment.psd1

@@ -90,6 +90,7 @@
 		'Remove-PSMDModuleDebug'
 		'Remove-PSMDTemplate'
 		'Rename-PSMDParameter'
+		'Resolve-PSMDBuildStepParameter'
 		'Restart-PSMDShell'
 		'Search-PSMDPropertyValue'
 		'Select-PSMDBuildProject'

PSModuleDevelopment/functions/build/Get-PSMDBuildArtifact.ps1

@@ -41,12 +41,13 @@
 	)
 
 	process {
-		$script:buildArtifacts.Values | Where-Object Name -Like $Name | Where-Object {
+		$artifacts = $script:buildArtifacts.Values | Where-Object Name -Like $Name | Where-Object {
 			if (-not $Tag) { return $true }
 			foreach ($tagName in $Tag) {
 				if ($_.Tags -contains $Tag) { return $true }
 			}
 			return $false
 		}
+		$($artifacts)
 	}
 }

PSModuleDevelopment/functions/build/Invoke-PSMDBuildProject.ps1

@@ -1,4 +1,42 @@
 function Invoke-PSMDBuildProject {
+<#
+	.SYNOPSIS
+		Execute a build project.
+	
+	.DESCRIPTION
+		Execute a build project.
+		A build project is a configured chain of actions that have been configured in json.
+		They will be processed in their specified order and allow manageable, configurable steps without having to reinvent the same action again and again.
+		
+		+ Individual action types become available using Register-PSMDBuildAction.
+		+ Create new build projects using New-PSMDBuildProject
+		+ Set up steps taken during a build using Set-PSMDBuildStep
+		+ Select the default build project using Select-PSMDBuildProject
+	
+	.PARAMETER Path
+		The path to the build project file to execute.
+		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 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')]
 	[CmdletBinding()]
 	param (
@@ -114,7 +152,10 @@
 			$parameters = @{
 				RootPath = Split-Path -Path $projectPath
 				Parameters = $step.Parameters
+				ProjectName = $projectObject.Name
+				StepName = $step.Name
 			}
+			if (-not $parameters.Parameters) { $parameters.Parameters = @{ } }
 			try { $null = & $actionObject.Action $parameters }
 			catch {
 				Write-StepResult @resultDef -Status Failed -Data $_ -ContinueLabel main

PSModuleDevelopment/functions/build/New-PSMDBuildProject.ps1

@@ -1,6 +1,56 @@
-function New-PSMDBuildProject
-{
-	[CmdletBinding()]
+function New-PSMDBuildProject {
+<#
+	.SYNOPSIS
+		Create a new build project file.
+	
+	.DESCRIPTION
+		Create a new build project file.
+		Build projects are used to configure a repeatable, managed set of steps that make up a workflow.
+		It is designed with software build processes in mind, but can be used for pretty much anything that works in separate steps.
+	
+		See the help on Invoke-PSMDBuildProject for more details.
+	
+		NOTE: This is not the tool or component to create new PowerShell _code_ projects / repositories!
+		To create a new PowerShell module project, instead run:
+		
+			Invoke-PSMDTemplate PSFProject
+	
+	.PARAMETER Name
+		The name of the build project.
+	
+	.PARAMETER Path
+		The path to the folder in which the build project file is created.
+		Final path will be: "<Path>\<Name>.build.json"
+	
+	.PARAMETER Condition
+		A condition - a filter expression - that must be met in order for the build to proceed.
+		For more details on filter conditions, see the PSFramework documentation on its feature:
+		https://psframework.org/documentation/documents/psframework/filters.html
+	
+	.PARAMETER ConditionSet
+		The name of the condition set to use.
+		This is part of the PSFramework filter system:
+		https://psframework.org/documentation/documents/psframework/filters.html
+	
+		Specify as "<module> <conditionsetname>" format.
+		Default Value: PSFramework Environment
+	
+	.PARAMETER NoSelect
+		Do not select the newly created build project as the default project for the current session.
+		By default, the newly created build project will be set as default project, in order to facilitate adding steps to it.
+		Use Select-PSMDBuildProject to explicitly set a default project file.
+	
+	.PARAMETER Register
+		Persist the newly created build project as default build project beyond the current session.
+		By default, the newly created build project will already be set as default project, in order to facilitate adding steps to it.
+		But ONLY for the current session. This parameter makes it remember in new PowerShell sessions as well.
+	
+	.EXAMPLE
+		PS C:\> New-PSMDBuildProject -Name 'VMDeployment' -Path 'C:\Code\VMDeployment'
+	
+		Create a new build project named 'VMDeployment' in the folder 'C:\Code\VMDeployment'
+#>
+	[CmdletBinding(DefaultParameterSetName = 'default')]
 	param (
 		[Parameter(Mandatory = $true)]
 		[string]
@@ -17,23 +67,24 @@
 		[string]
 		$ConditionSet = 'PSFramework Environment',
 
+		[Parameter(ParameterSetName = 'NoSelect')]
 		[switch]
 		$NoSelect,
 
+		[Parameter(ParameterSetName = 'Register')]
 		[switch]
 		$Register
 	)
 
-	process
-	{
+	process {
 		$project = [pscustomobject]@{
-			Name = $Name
-			Condition = $Condition
+			Name		 = $Name
+			Condition    = $Condition
 			ConditionSet = $ConditionSet
-			Steps = @()
+			Steps	     = @()
 		}
 		$outPath = Join-Path -Path $Path -ChildPath "$Name.build.Json"
-		$project | ConvertTo-Json -Depth 10 | Set-Content -Path $outPath -Encoding UTF8 -ErrorAction Stop
+		$project | Export-PsmdBuildProjectFile -OutPath $outPath -ErrorAction Stop
 		if (-not $NoSelect) {
 			Set-PSFConfig -Module PSModuleDevelopment -Name 'Build.Project.Selected' -Value $outPath
 			if ($Register) { Register-PSFConfig -Module PSModuleDevelopment -Name 'Build.Project.Selected' }

PSModuleDevelopment/functions/build/Publish-PSMDBuildArtifact.ps1

@@ -1,4 +1,34 @@
 function Publish-PSMDBuildArtifact {
+<#
+	.SYNOPSIS
+		Create a new artifact for the current build pipeline.
+	
+	.DESCRIPTION
+		Create a new artifact for the current build pipeline.
+		Use this create artifacts that are accessible in later steps in the pipeline.
+	
+		Usually, artifacts are deleted at the end of a build process.
+		They are always cleared at the beginning of a new one.
+	
+		Artifacts are NOT persisted across PowerShell sessions.
+	
+	.PARAMETER Name
+		Name of the Artifact to create.
+		Technically there are no limits to which character to chose, but we strongly encourage restricting yourself to letters, numbers, dash, underscore and dot.
+	
+	.PARAMETER Value
+		The value to assign to the artifact.
+	
+	.PARAMETER Tag
+		Any tags to add to an artifact.
+		Tags can be searched for in order to bulk-operate against all artifacts of that tag.
+		For example, the "remove-pssession" action can remove all remoting sessions for all artifacts tagged as "pssession".
+	
+	.EXAMPLE
+		PS C:\> Publish-PSMDBuildArtifact -Name 'session' -Value $session -Tag 'pssession'
+	
+		Publishes an artifact named "session" containing the content of $session that is tagged as a PowerShell remoting session.
+#>
 	[CmdletBinding()]
 	param (
 		[Parameter(Mandatory = $true)]

PSModuleDevelopment/functions/build/Register-PSMDBuildAction.ps1

@@ -1,16 +1,52 @@
 function Register-PSMDBuildAction {
+<#
+	.SYNOPSIS
+		Register a new action usable in build projects.
+	
+	.DESCRIPTION
+		Register a new action usable in build projects.
+		Actions are the actual implementation logic that turns the configuration in a build project file into ... well, actions.
+		Anyway, these are basically named scriptblocks with some metadata.
+		This command is used to provide all the builtin actions and can be used to freely define your own actions.
+		
+		Whenever you use a "script" action in your build projects, consider ... would it make a good configurable option valuable for other builds?
+		If so, that might just mark the birth of the next action!
+	
+	.PARAMETER Name
+		The name of the action.
+	
+	.PARAMETER Action
+		The actual code implementing the action.
+		Each action scriptblock will receive exactly one .
+	
+	.PARAMETER Description
+		A description explaining what the action is all about.
+	
+	.PARAMETER Parameters
+		The parameters the action accepts.
+		Provider a hashtable, with the keys being the parameter names and the values being a description of its parameter.
+	
+	.EXAMPLE
+		PS C:\> Register-PSMDBuildAction -Name 'script' -Action $actionCode -Description 'Execute a custom scriptfile as part of your workflow' -Parameters $parameters
+	
+		Creates / registers the action "script".
+#>
 	[CmdletBinding()]
 	param (
+		[Parameter(Mandatory = $true)]
 		[string]
 		$Name,
 
+		[Parameter(Mandatory = $true)]
 		[ScriptBlock]
 		$Action,
 
+		[Parameter(Mandatory = $true)]
 		[string]
 		$Description,
 
-		[hashtable[]]
+		[Parameter(Mandatory = $true)]
+		[hashtable]
 		$Parameters
 	)
 

PSModuleDevelopment/functions/build/Remove-PSMDBuildArtifact.ps1

@@ -1,8 +1,29 @@
 function Remove-PSMDBuildArtifact
 {
+<#
+	.SYNOPSIS
+		Removes an artifact from the build pipeline.
+	
+	.DESCRIPTION
+		Removes an artifact from the build pipeline.
+		Only interacts with the PSModuleDevelopment build system.
+	
+	.PARAMETER Name
+		Name of the artifact to remove.
+	
+	.EXAMPLE
+		PS C:\> Remove-PSMDBuildArtifact -Name 'session'
+	
+		Removes the artifact 'session' from the build pipeline.
+	
+	.EXAMPLE
+		PS C:\> Get-PSMDBuildArtifact -Tag pssession | Remove-PSMDBuildArtifact
+	
+		Removes all artifacts with the 'pssession' tag from the build pipeline.
+#>
 	[CmdletBinding()]
 	param (
-		[Parameter(Mandatory = $true)]
+		[Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
 		[string[]]
 		$Name
 	)

PSModuleDevelopment/functions/build/Resolve-PSMDBuildStepParameter.ps1

@@ -0,0 +1,56 @@
+function Resolve-PSMDBuildStepParameter {
+<#
+	.SYNOPSIS
+		Update missing build action parameters from the configuration system.
+	
+	.DESCRIPTION
+		Update missing build action parameters from the configuration system.
+		This command is for use within the defined code of build actions.
+	
+	.PARAMETER Parameters
+		The hashtable containing the currently specified parameters from the step configuration within the build project file.
+		Only settings not already defined there are taken from configuration.
+	
+	.PARAMETER ProjectName
+		The name of the project being executed.
+		Supplementary parameters taken from configuration will pick up settings based on this name:
+		"PSModuleDevelopment.BuildParam.<ProjectName>.<StepName>.*"
+	
+	.PARAMETER StepName
+		The name of the step being executed.
+		Supplementary parameters taken from configuration will pick up settings based on this name:
+		"PSModuleDevelopment.BuildParam.<ProjectName>.<StepName>.*"
+	
+	.EXAMPLE
+		PS C:\> Resolve-PSMDBuildStepParameter -Parameters $actualParameters -ProjectName VMDeployment -StepName 'Create Session'
+	
+		Adds parameters provided through configuration.
+#>
+	[CmdletBinding()]
+	param (
+		[Parameter(Mandatory = $true)]
+		[hashtable]
+		$Parameters,
+		
+		[Parameter(Mandatory = $true)]
+		[string]
+		$ProjectName,
+		
+		[Parameter(Mandatory = $true)]
+		[string]
+		$StepName
+	)
+	
+	process {
+		$configObject = Select-PSFConfig -FullName "PSModuleDevelopment.BuildParam.$ProjectName.$StepName.*"
+		if (-not $configObject) { return $Parameters }
+		
+		foreach ($property in $configObject.PSObject.Properties) {
+			if ($property.Name -in '_Name', '_FullName', '_Depth', '_Children') { continue }
+			if ($Parameters.ContainsKey($property.Name)) { continue }
+			$Parameters[$property.Name] = $property.Value
+		}
+		
+		$Parameters
+	}
+}