Skip to content

Commit 3719e2f

Browse files
FriedrichWeinmannFriedrichWeinmann
committed
Added build command parameter help
1 parent 5f36bb8 commit 3719e2f

15 files changed

Lines changed: 415 additions & 17 deletions

‎PSModuleDevelopment/PSModuleDevelopment.psd1‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,7 @@
9090
'Remove-PSMDModuleDebug'
9191
'Remove-PSMDTemplate'
9292
'Rename-PSMDParameter'
93+
'Resolve-PSMDBuildStepParameter'
9394
'Restart-PSMDShell'
9495
'Search-PSMDPropertyValue'
9596
'Select-PSMDBuildProject'

‎PSModuleDevelopment/functions/build/Get-PSMDBuildArtifact.ps1‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,12 +41,13 @@
4141
)
4242

4343
process {
44-
$script:buildArtifacts.Values | Where-Object Name -Like $Name | Where-Object {
44+
$artifacts = $script:buildArtifacts.Values | Where-Object Name -Like $Name | Where-Object {
4545
if (-not $Tag) { return $true }
4646
foreach ($tagName in $Tag) {
4747
if ($_.Tags -contains $Tag) { return $true }
4848
}
4949
return $false
5050
}
51+
$($artifacts)
5152
}
5253
}

‎PSModuleDevelopment/functions/build/Invoke-PSMDBuildProject.ps1‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,42 @@
11
function Invoke-PSMDBuildProject {
2+
<#
3+
.SYNOPSIS
4+
Execute a build project.
5+
6+
.DESCRIPTION
7+
Execute a build project.
8+
A build project is a configured chain of actions that have been configured in json.
9+
They will be processed in their specified order and allow manageable, configurable steps without having to reinvent the same action again and again.
10+
11+
+ Individual action types become available using Register-PSMDBuildAction.
12+
+ Create new build projects using New-PSMDBuildProject
13+
+ Set up steps taken during a build using Set-PSMDBuildStep
14+
+ Select the default build project using Select-PSMDBuildProject
15+
16+
.PARAMETER Path
17+
The path to the build project file to execute.
18+
Mandatory if no build project has been selected as the default project.
19+
Use the Select-PSMDBuildProject to define a default project (and optionally persist the choice across sessions)
20+
21+
.PARAMETER RetainArtifacts
22+
Whether, after executing the project, its artifacts should be retained.
23+
By default, any artifacts created during a build project will be discarded upon project completion.
24+
25+
Artifacts are similar to variables to the pipeline and can be used to pass data throughout the pipeline.
26+
27+
+ Use Publish-PSMDBuildArtifact to create a new artifact.
28+
+ Use Get-PSMDBuildArtifact to access existing build artifacts.
29+
30+
.EXAMPLE
31+
PS C:\> Invoke-PSMDBuildProject -Path .\VMDeployment.build.Json
32+
33+
Execute the build file "VMDeployment.build.json" from the current folder
34+
35+
.EXAMPLE
36+
PS C:\> build
37+
38+
Execute the default build project.
39+
#>
240
[Alias('build')]
341
[CmdletBinding()]
442
param (
@@ -114,7 +152,10 @@
114152
$parameters = @{
115153
RootPath = Split-Path -Path $projectPath
116154
Parameters = $step.Parameters
155+
ProjectName = $projectObject.Name
156+
StepName = $step.Name
117157
}
158+
if (-not $parameters.Parameters) { $parameters.Parameters = @{ } }
118159
try { $null = & $actionObject.Action $parameters }
119160
catch {
120161
Write-StepResult @resultDef -Status Failed -Data $_ -ContinueLabel main

‎PSModuleDevelopment/functions/build/New-PSMDBuildProject.ps1‎

Lines changed: 60 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,56 @@
1-
function New-PSMDBuildProject
2-
{
3-
[CmdletBinding()]
1+
function New-PSMDBuildProject {
2+
<#
3+
.SYNOPSIS
4+
Create a new build project file.
5+
6+
.DESCRIPTION
7+
Create a new build project file.
8+
Build projects are used to configure a repeatable, managed set of steps that make up a workflow.
9+
It is designed with software build processes in mind, but can be used for pretty much anything that works in separate steps.
10+
11+
See the help on Invoke-PSMDBuildProject for more details.
12+
13+
NOTE: This is not the tool or component to create new PowerShell _code_ projects / repositories!
14+
To create a new PowerShell module project, instead run:
15+
16+
Invoke-PSMDTemplate PSFProject
17+
18+
.PARAMETER Name
19+
The name of the build project.
20+
21+
.PARAMETER Path
22+
The path to the folder in which the build project file is created.
23+
Final path will be: "<Path>\<Name>.build.json"
24+
25+
.PARAMETER Condition
26+
A condition - a filter expression - that must be met in order for the build to proceed.
27+
For more details on filter conditions, see the PSFramework documentation on its feature:
28+
https://psframework.org/documentation/documents/psframework/filters.html
29+
30+
.PARAMETER ConditionSet
31+
The name of the condition set to use.
32+
This is part of the PSFramework filter system:
33+
https://psframework.org/documentation/documents/psframework/filters.html
34+
35+
Specify as "<module> <conditionsetname>" format.
36+
Default Value: PSFramework Environment
37+
38+
.PARAMETER NoSelect
39+
Do not select the newly created build project as the default project for the current session.
40+
By default, the newly created build project will be set as default project, in order to facilitate adding steps to it.
41+
Use Select-PSMDBuildProject to explicitly set a default project file.
42+
43+
.PARAMETER Register
44+
Persist the newly created build project as default build project beyond the current session.
45+
By default, the newly created build project will already be set as default project, in order to facilitate adding steps to it.
46+
But ONLY for the current session. This parameter makes it remember in new PowerShell sessions as well.
47+
48+
.EXAMPLE
49+
PS C:\> New-PSMDBuildProject -Name 'VMDeployment' -Path 'C:\Code\VMDeployment'
50+
51+
Create a new build project named 'VMDeployment' in the folder 'C:\Code\VMDeployment'
52+
#>
53+
[CmdletBinding(DefaultParameterSetName = 'default')]
454
param (
555
[Parameter(Mandatory = $true)]
656
[string]
@@ -17,23 +67,24 @@
1767
[string]
1868
$ConditionSet = 'PSFramework Environment',
1969

70+
[Parameter(ParameterSetName = 'NoSelect')]
2071
[switch]
2172
$NoSelect,
2273

74+
[Parameter(ParameterSetName = 'Register')]
2375
[switch]
2476
$Register
2577
)
2678

27-
process
28-
{
79+
process {
2980
$project = [pscustomobject]@{
30-
Name = $Name
31-
Condition = $Condition
81+
Name = $Name
82+
Condition = $Condition
3283
ConditionSet = $ConditionSet
33-
Steps = @()
84+
Steps = @()
3485
}
3586
$outPath = Join-Path -Path $Path -ChildPath "$Name.build.Json"
36-
$project | ConvertTo-Json -Depth 10 | Set-Content -Path $outPath -Encoding UTF8 -ErrorAction Stop
87+
$project | Export-PsmdBuildProjectFile -OutPath $outPath -ErrorAction Stop
3788
if (-not $NoSelect) {
3889
Set-PSFConfig -Module PSModuleDevelopment -Name 'Build.Project.Selected' -Value $outPath
3990
if ($Register) { Register-PSFConfig -Module PSModuleDevelopment -Name 'Build.Project.Selected' }

‎PSModuleDevelopment/functions/build/Publish-PSMDBuildArtifact.ps1‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,34 @@
11
function Publish-PSMDBuildArtifact {
2+
<#
3+
.SYNOPSIS
4+
Create a new artifact for the current build pipeline.
5+
6+
.DESCRIPTION
7+
Create a new artifact for the current build pipeline.
8+
Use this create artifacts that are accessible in later steps in the pipeline.
9+
10+
Usually, artifacts are deleted at the end of a build process.
11+
They are always cleared at the beginning of a new one.
12+
13+
Artifacts are NOT persisted across PowerShell sessions.
14+
15+
.PARAMETER Name
16+
Name of the Artifact to create.
17+
Technically there are no limits to which character to chose, but we strongly encourage restricting yourself to letters, numbers, dash, underscore and dot.
18+
19+
.PARAMETER Value
20+
The value to assign to the artifact.
21+
22+
.PARAMETER Tag
23+
Any tags to add to an artifact.
24+
Tags can be searched for in order to bulk-operate against all artifacts of that tag.
25+
For example, the "remove-pssession" action can remove all remoting sessions for all artifacts tagged as "pssession".
26+
27+
.EXAMPLE
28+
PS C:\> Publish-PSMDBuildArtifact -Name 'session' -Value $session -Tag 'pssession'
29+
30+
Publishes an artifact named "session" containing the content of $session that is tagged as a PowerShell remoting session.
31+
#>
232
[CmdletBinding()]
333
param (
434
[Parameter(Mandatory = $true)]

‎PSModuleDevelopment/functions/build/Register-PSMDBuildAction.ps1‎

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,52 @@
11
function Register-PSMDBuildAction {
2+
<#
3+
.SYNOPSIS
4+
Register a new action usable in build projects.
5+
6+
.DESCRIPTION
7+
Register a new action usable in build projects.
8+
Actions are the actual implementation logic that turns the configuration in a build project file into ... well, actions.
9+
Anyway, these are basically named scriptblocks with some metadata.
10+
This command is used to provide all the builtin actions and can be used to freely define your own actions.
11+
12+
Whenever you use a "script" action in your build projects, consider ... would it make a good configurable option valuable for other builds?
13+
If so, that might just mark the birth of the next action!
14+
15+
.PARAMETER Name
16+
The name of the action.
17+
18+
.PARAMETER Action
19+
The actual code implementing the action.
20+
Each action scriptblock will receive exactly one .
21+
22+
.PARAMETER Description
23+
A description explaining what the action is all about.
24+
25+
.PARAMETER Parameters
26+
The parameters the action accepts.
27+
Provider a hashtable, with the keys being the parameter names and the values being a description of its parameter.
28+
29+
.EXAMPLE
30+
PS C:\> Register-PSMDBuildAction -Name 'script' -Action $actionCode -Description 'Execute a custom scriptfile as part of your workflow' -Parameters $parameters
31+
32+
Creates / registers the action "script".
33+
#>
234
[CmdletBinding()]
335
param (
36+
[Parameter(Mandatory = $true)]
437
[string]
538
$Name,
639

40+
[Parameter(Mandatory = $true)]
741
[ScriptBlock]
842
$Action,
943

44+
[Parameter(Mandatory = $true)]
1045
[string]
1146
$Description,
1247

13-
[hashtable[]]
48+
[Parameter(Mandatory = $true)]
49+
[hashtable]
1450
$Parameters
1551
)
1652

‎PSModuleDevelopment/functions/build/Remove-PSMDBuildArtifact.ps1‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,29 @@
11
function Remove-PSMDBuildArtifact
22
{
3+
<#
4+
.SYNOPSIS
5+
Removes an artifact from the build pipeline.
6+
7+
.DESCRIPTION
8+
Removes an artifact from the build pipeline.
9+
Only interacts with the PSModuleDevelopment build system.
10+
11+
.PARAMETER Name
12+
Name of the artifact to remove.
13+
14+
.EXAMPLE
15+
PS C:\> Remove-PSMDBuildArtifact -Name 'session'
16+
17+
Removes the artifact 'session' from the build pipeline.
18+
19+
.EXAMPLE
20+
PS C:\> Get-PSMDBuildArtifact -Tag pssession | Remove-PSMDBuildArtifact
21+
22+
Removes all artifacts with the 'pssession' tag from the build pipeline.
23+
#>
324
[CmdletBinding()]
425
param (
5-
[Parameter(Mandatory = $true)]
26+
[Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
627
[string[]]
728
$Name
829
)

‎PSModuleDevelopment/functions/build/Resolve-PSMDBuildStepParameter.ps1‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
function Resolve-PSMDBuildStepParameter {
2+
<#
3+
.SYNOPSIS
4+
Update missing build action parameters from the configuration system.
5+
6+
.DESCRIPTION
7+
Update missing build action parameters from the configuration system.
8+
This command is for use within the defined code of build actions.
9+
10+
.PARAMETER Parameters
11+
The hashtable containing the currently specified parameters from the step configuration within the build project file.
12+
Only settings not already defined there are taken from configuration.
13+
14+
.PARAMETER ProjectName
15+
The name of the project being executed.
16+
Supplementary parameters taken from configuration will pick up settings based on this name:
17+
"PSModuleDevelopment.BuildParam.<ProjectName>.<StepName>.*"
18+
19+
.PARAMETER StepName
20+
The name of the step being executed.
21+
Supplementary parameters taken from configuration will pick up settings based on this name:
22+
"PSModuleDevelopment.BuildParam.<ProjectName>.<StepName>.*"
23+
24+
.EXAMPLE
25+
PS C:\> Resolve-PSMDBuildStepParameter -Parameters $actualParameters -ProjectName VMDeployment -StepName 'Create Session'
26+
27+
Adds parameters provided through configuration.
28+
#>
29+
[CmdletBinding()]
30+
param (
31+
[Parameter(Mandatory = $true)]
32+
[hashtable]
33+
$Parameters,
34+
35+
[Parameter(Mandatory = $true)]
36+
[string]
37+
$ProjectName,
38+
39+
[Parameter(Mandatory = $true)]
40+
[string]
41+
$StepName
42+
)
43+
44+
process {
45+
$configObject = Select-PSFConfig -FullName "PSModuleDevelopment.BuildParam.$ProjectName.$StepName.*"
46+
if (-not $configObject) { return $Parameters }
47+
48+
foreach ($property in $configObject.PSObject.Properties) {
49+
if ($property.Name -in '_Name', '_FullName', '_Depth', '_Children') { continue }
50+
if ($Parameters.ContainsKey($property.Name)) { continue }
51+
$Parameters[$property.Name] = $property.Value
52+
}
53+
54+
$Parameters
55+
}
56+
}

0 commit comments

Comments
 (0)