Properties

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'