Properties - lsgroi/Pask GitHub Wiki

Build properties are usual PowerShell script variables explicitly defined in the build script or passed as parameters or environment variables. They should be defined using the command Set-Property and referenced simply as variables in the local scope.
By convention, build-wide properties are defined in .build\scripts\Properties.ps1 which is automatically imported by the build runner. Task specific properties can be defined close to the task definition.
Properties can be defined with a static value, default value or expected value.

Example: $Configuration is a static property.

Set-Property Configuration -Value Release

Task Build {
    Exec { MSBuild Project.csproj /t:Build /p:Configuration=$Configuration }
}

Environment variables should be referenced explicitly as $env:var or obtained by using the notation Set-Property name -Default value. The latter gets a value of the existing property or value of session or environment variable or the default.

Example: $Configuration and $ModuleDir may come to the script in three ways; as variable defined in a parent scope, as script parameter or existing environment variable. If nothing is the case for both, then Set-Property Configuration -Default Release uses the default value Release while Set-Property ModuleDir throws an exception because there is no default value specified.

Set-Property Configuration -Default Release
Set-Property ModuleDir

Task Install {
    Copy-Item Bin/$Configuration/MyModule.dll $ModuleDir/MyModule
}

When a property semantically depends on another property, you can leverage script blocks to impose dependencies. When changing values, the flag -Update (or alternatively the command Update-Properties) will enforce consistency.

Example: the change of $ModuleDir value is propagated to $ModuleLib.

Set-Property ModuleDir -Value Bin/MyModule
Set-Property ModuleLib -Value { $ModuleDir/MyModule.dll }

Set-Property ModuleDir -Value Bin/MyNewModule -Update

Properties can be passed as parameters as long as they do not conflict with Pask core properties.

Example: $Configuration passed as parameter; in this case there is no need to declare the variable, but it would be good practice to do so.

PS C:\Source> .\Pask.ps1 -Configuration Release

Task Build {
    Exec { MSBuild Project.csproj /t:Build /p:Configuration=$Configuration }
}

A Pask extension could define its own set of properties; they will be automatically imported by the build runner before any task is executed.

Example: Get all the build properties and write them to the display.

Task Write-BuildProperties {
    Write-Host (Get-Properties | Out-String)
}

Build Write-BuildProperties C:\Users\l.sgroi\AppData\Local\Temp\v2gfjfns.hxx.ps1
Task /Write-BuildProperties

Name                           Value
----                           -----
ArtifactFullPath               C:\Source\WebApplication\.build\output\WebApplication
ArtifactName                   WebApplication
BuildFullPath                  C:\Source\WebApplication\.build
BuildOutputFullPath            C:\Source\WebApplication\.build\output
PaskFullPath                   C:\Source\WebApplication
ProjectFullName                C:\Source\WebApplication\WebApplication\WebApplication.cssproj
ProjectFullPath                C:\Source\WebApplication\WebApplication
ProjectName                    WebApplication
SolutionFullName               C:\Source\WebApplication\WebApplication.sln
SolutionFullPath               C:\Source\WebApplication\
TestResultsFullPath            C:\Source\WebApplication\.build\output\TestResults
Version                        @{...}

Done /Write-BuildProperties 00:00:00.0330342

Pask core properties

A set of properties are defined and managed by Pask but widely available to use as variables:

$PaskFullPath: the absolute path of Pask directory
$SolutionName: base name of the solution (MySolution); by convention it is the first solution found in Pask build runner directory
$SolutionFullPath: the absolute path of the solution directory (C:\SolutionDir)
$SolutionFullName: full name of the solution ($SolutionFullPath\$SolutionName.sln)
$ProjectName: name of the default project (MyProject); by convention it would be a project named after the solution or the first project defined in the solution file
$ProjectFullPath: the absolute path of the default project directory (C:\SolutionDir\MyProject)
$ProjectFullName: full name of the default project ($ProjectFullPath\$ProjectName.csproj)
$BuildFullPath: the absolute path of the build directory (C:\SolutionDir\.build)
$BuildOutputFullPath: the absolute path of the build output directory ($BuildFullPath\output)
$ArtifactName: the name of the artifact (default to $ProjectName)
$ArtifactFullPath: the absolute path to the artifact directory ($BuildOutputFullPath\$ArtifactName)
$TestResultsFullPath: the absolute path to the test results directory ($BuildOutputFullPath\TestResults)

While there is flexibility in defining solution/project names, these properties cannot be overridden, with the exception of $ArtifactName.

Example: Custom solution name and location C:\src\Project\SolutionFiles\MySolution.sln.

PS C:\src\Project> .\Pask.ps1 -SolutionPath SolutionFiles -SolutionName MySolution

Example: Custom default project.

PS C:\src\Project> .\Pask.ps1 -ProjectName MyDefaultProject

Ideally you would have a single deployable component per solution hence the concept of default project. There is however a way to redefine the default project at run-time if you wish to do so.

Example: The task sets the default project explicitly.

Task BuildMyProject {
    Set-Project -Name MyProject
    ...
}

Override properties

Often enough you'd want to override the default value of properties used by some task. To do so, simply assign a new value to the property in question.
Generally, you can override a property anywhere within the build scripts. Pay attention in regards to properties which have dependent script block properties; make sure you override (and -Update) the property after all dependent properties are defined.
If you create a Pask extension and you want to override a build-wide property defined in a dependent extension, it would be good practice to explicitly import properties from the extension to force-load the property before actually overriding it; in case of task specific properties, after importing the task.

Example: Override a build-wide property defined by a dependency of a Pask extension.

Import-Properties -Package Pask.Test

Set-Property TestNamePattern -Value '\.Tests'

Example: Override a property defined by a task.

Import-Task Build

Set-Property Configuration -Value 'Deployment'