Invoke-psake Runs a psake build script. Invoke psake This function runs a psake build script Invoke-psake buildFile String taskList String[] framework String docs SwitchParameter parameters Hashtable properties Hashtable nologo SwitchParameter notr SwitchParameter buildFile The path to the psake build script to execute String String 'psakefile.ps1' taskList A comma-separated list of task names to execute String[] String[] framework The version of the .NET framework you want to use during build. You can append x86 or x64 to force a specific framework. If not specified, x86 or x64 will be detected based on the bitness of the PowerShell process. Possible values: '1.0', '1.1', '2.0', '2.0x86', '2.0x64', '3.0', '3.0x86', '3.0x64', '3.5', '3.5x86', '3.5x64', '4.0', '4.0x86', '4.0x64', '4.5', '4.5x86', '4.5x64', '4.5.1', '4.5.1x86', '4.5.1x64' String String '3.5' docs Prints a list of tasks and their descriptions SwitchParameter SwitchParameter parameters A hashtable containing parameters to be passed into the current build script. These parameters will be processed before the 'Properties' function of the script is processed. This means you can access parameters from within the 'Properties' function! Hashtable Hashtable properties A hashtable containing properties to be passed into the current build script. These properties will override matching properties that are found in the 'Properties' function of the script. Hashtable Hashtable nologo Do not display the startup banner and copyright message. SwitchParameter SwitchParameter notr Do not display the time report. SwitchParameter SwitchParameter None None ---- Exceptions ---- If there is an exception thrown during the running of a build script psake will set the '$psake.build_success' variable to $false. To detect failue outside PowerShell (for example by build server), finish PowerShell process with non-zero exit code when '$psake.build_success' is $false. Calling psake from 'cmd.exe' with 'psake.cmd' will give you that behaviour. ---- $psake variable ---- When the psake module is loaded a variable called $psake is created which is a hashtable containing some variables: $psake.version # contains the current version of psake $psake.context # holds onto the current state of all variables $psake.run_by_psake_build_tester # indicates that build is being run by psake-BuildTester $psake.config_default # contains default configuration # can be overriden in psake-config.ps1 in directory with psake.psm1 or in directory with current build script $psake.build_success # indicates that the current build was successful $psake.build_script_file # contains a System.IO.FileInfo for the current build script $psake.build_script_dir # contains the fully qualified path to the current build script You should see the following when you display the contents of the $psake variable right after importing psake PS projects:\psake> Import-Module .\psake.psm1 PS projects:\psake> $psake Name Value ---- ----- run_by_psake_build_tester False version 4.2 build_success False build_script_file build_script_dir config_default @{framework=3.5; ... context {} After a build is executed the following $psake values are updated: build_script_file, build_script_dir, build_success PS projects:\psake> Invoke-psake .\examples\psakefile.ps1 Executing task: Clean Executed Clean! Executing task: Compile Executed Compile! Executing task: Test Executed Test! Build Succeeded! ---------------------------------------------------------------------- Build Time Report ---------------------------------------------------------------------- Name Duration ---- -------- Clean 00:00:00.0798486 Compile 00:00:00.0869948 Test 00:00:00.0958225 Total: 00:00:00.2712414 PS projects:\psake> $psake Name Value ---- ----- build_script_file YOUR_PATH\examples\psakefile.ps1 run_by_psake_build_tester False build_script_dir YOUR_PATH\examples context {} version 4.2 build_success True config_default @{framework=3.5; ... -------------- EXAMPLE 1 -------------- C:\PS> Invoke-psake Description ----------- Runs the 'default' task in the '.build.ps1' build script -------------- EXAMPLE 2 -------------- C:\PS> Invoke-psake '.\build.ps1' Tests,Package Description ----------- Runs the 'Tests' and 'Package' tasks in the '.build.ps1' build script -------------- EXAMPLE 3 -------------- C:\PS> Invoke-psake Tests Description ----------- This example will run the 'Tests' tasks in the 'psakefile.ps1' build script. The 'psakefile.ps1' is assumed to be in the current directory. -------------- EXAMPLE 4 -------------- C:\PS> Invoke-psake 'Tests, Package' Description ----------- This example will run the 'Tests' and 'Package' tasks in the 'psakefile.ps1' build script. The 'psakefile.ps1' is assumed to be in the current directory. NOTE: The quotes around the list of tasks to execute is required if you want to execute more than 1 task. -------------- EXAMPLE 5 -------------- C:\PS> Invoke-psake .\build.ps1 -docs Description ----------- Prints a report of all the tasks and their dependencies and descriptions and then exits -------------- EXAMPLE 6 -------------- C:\PS> Invoke-psake .\parameters.ps1 -parameters @{"p1"="v1";"p2"="v2"} Description ----------- Runs the build script called 'parameters.ps1' and passes in parameters 'p1' and 'p2' with values 'v1' and 'v2' Here's the .\parameters.ps1 build script: properties { $my_property = $p1 + $p2 } task default -depends TestParams task TestParams { Assert ($my_property -ne $null) '$my_property should not be null' } Notice how you can refer to the parameters that were passed into the script from within the “properties” function. The value of the $p1 variable should be the string “v1” and the value of the $p2 variable should be “v2”. -------------- EXAMPLE 7 -------------- C:\PS> Invoke-psake .\properties.ps1 -properties @{"x"="1";"y"="2"} Description ----------- Runs the build script called 'properties.ps1' and passes in parameters 'x' and 'y' with values '1' and '2' This feature allows you to over-ride existing properties in your build script. Here's the .\properties.ps1 build script properties { $x = $null $y = $null $z = $null } task default -depends TestProperties task TestProperties { Assert ($x -ne $null) "x should not be null" Assert ($y -ne $null) "y should not be null" Assert ($z -eq $null) "z should be null" } Task Include Properties FormatTaskName TaskSetup TaskTearDown Assert Framework TaskTearDown Adds a scriptblock to the build that will be executed after each task This function will accept a scriptblock that will be executed after each task in the build script. TaskTearDown teardown ScriptBlock teardown A scriptblock to execute ScriptBlock ScriptBlock None None -------------- EXAMPLE 1 -------------- C:\PS> A sample build script is shown below: Task default -depends Test Task Test -depends Compile, Clean { } Task Compile -depends Clean { } Task Clean { } TaskTearDown { "Running 'TaskTearDown' for task $context.Peek().currentTaskName" } Description ----------- The script above produces the following output: Executing task, Clean... Running 'TaskTearDown' for task Clean Executing task, Compile... Running 'TaskTearDown' for task Compile Executing task, Test... Running 'TaskTearDown' for task Test Build Succeeded Task Include Properties Invoke-psake TaskSetup TaskTearDown Assert Framework TaskSetup Adds a scriptblock that will be executed before each task This function will accept a scriptblock that will be executed before each task in the build script. TaskSetup setup ScriptBlock setup A scriptblock to execute ScriptBlock ScriptBlock None None -------------- EXAMPLE 1 -------------- C:\PS> A sample build script is shown below: Task default -depends Test Task Test -depends Compile, Clean { } Task Compile -depends Clean { } Task Clean { } TaskSetup { "Running 'TaskSetup' for task $context.Peek().currentTaskName" } Description ----------- The script above produces the following output: Running 'TaskSetup' for task Clean Executing task, Clean... Running 'TaskSetup' for task Compile Executing task, Compile... Running 'TaskSetup' for task Test Executing task, Test... Build Succeeded Task Include Properties Invoke-psake FormatTaskName TaskTearDown Assert Framework Framework Sets the version of the .NET framework you want to use during build. This function will accept a string containing version of the .NET framework to use during build. Possible values: '1.0', '1.1', '2.0', '2.0x86', '2.0x64', '3.0', '3.0x86', '3.0x64', '3.5', '3.5x86', '3.5x64', '4.0', '4.0x86', '4.0x64', '4.5', '4.5x86', '4.5x64', '4.5.1', '4.5.1x86', '4.5.1x64'. Default is '3.5*', where x86 or x64 will be detected based on the bitness of the PowerShell process. Framework framework string framework Version of the .NET framework to use during build. string string None None -------------- EXAMPLE 1 -------------- Framework "4.0" Task default -depends Compile Task Compile -depends Clean { msbuild /version } Description ----------- The script above will output detailed version of msbuid v4 Task Include Properties Invoke-psake FormatTaskName TaskSetup TaskTearDown Assert FormatTaskName This function allows you to change how psake renders the task name during a build. This function takes either a string which represents a format string (formats using the -f format operator see “help about_operators”) or it can accept a script block that has a single parameter that is the name of the task that will be executed. FormatTaskName format String or ScriptBlock format A format string or a scriptblock to execute String or ScriptBlock String or ScriptBlock None None -------------- EXAMPLE 1 -------------- C:\PS> A sample build script that uses a format string is shown below: Task default -depends TaskA, TaskB, TaskC FormatTaskName "-------- {0} --------" Task TaskA { "TaskA is executing" } Task TaskB { "TaskB is executing" } Task TaskC { "TaskC is executing" } Description ----------- The script above produces the following output: -------- TaskA -------- TaskA is executing -------- TaskB -------- TaskB is executing -------- TaskC -------- TaskC is executing Build Succeeded! -------------- EXAMPLE 2 -------------- C:\PS> A sample build script that uses a ScriptBlock is shown below: Task default -depends TaskA, TaskB, TaskC FormatTaskName { param($taskName) write-host "Executing Task: $taskName" -foregroundcolor blue } Task TaskA { "TaskA is executing" } Task TaskB { "TaskB is executing" } Task TaskC { "TaskC is executing" } Description ----------- The preceding example uses the scriptblock parameter to the FormatTaskName function to render each task name in the color blue. Note: the $taskName parameter is arbitrary it could be named anything Task Include Properties Invoke-psake TaskSetup TaskTearDown Assert Framework Get-PSakeScriptTasks Returns meta data about all the tasks defined in the provided psake script. Get PSakeScriptTasks Returns meta data about all the tasks defined in the provided psake script. Get-PSakeScriptTasks buildFile The path to the psake build script to read the tasks from. String InformationAction ActionPreference InformationVariable String buildFile The path to the psake build script to read the tasks from. String String 'psakefile.ps1' InformationAction ActionPreference ActionPreference InformationVariable String String Include Include the functions or code of another powershell script file into the current build script's scope A build script may declare an "includes" function which allows you to define a file containing powershell code to be included and added to the scope of the currently running build script. Code from such file will be executed after code from build script. Include fileNamePathToInclude String fileNamePathToInclude A string containing the path and name of the powershell file to include String String None None -------------- EXAMPLE 1 -------------- C:\PS> A sample build script is shown below: Include ".\build_utils.ps1" Task default -depends Test Task Test -depends Compile, Clean { } Task Compile -depends Clean { } Task Clean { } Description ----------- The script above includes all the functions and variables defined in the ".\build_utils.ps1" script into the current build script's scope Note: You can have more than 1 "Include" function defined in the build script Task FormatTaskName Properties Invoke-psake TaskSetup TaskTearDown Assert Framework Properties Define a scriptblock that contains assignments to variables that will be available to all tasks in the build script A build script may declare a "Properies" function which allows you to define variables that will be available to all the "Task" functions in the build script. Properties properties ScriptBlock properties The script block containing all the variable assignment statements ScriptBlock ScriptBlock None None -------------- EXAMPLE 1 -------------- C:\PS> A sample build script is shown below: Properties { $build_dir = "c:\build" $connection_string = "datasource=localhost;initial catalog=northwind;integrated security=sspi" } Task default -depends Test Task Test -depends Compile, Clean { } Task Compile -depends Clean { } Task Clean { } Description ----------- Note: You can have more than 1 "Properties" function defined in the build script Task FormatTaskName Include Invoke-psake TaskSetup TaskTearDown Assert Framework Task Defines a build task to be executed by psake This function creates a 'task' object that will be used by the psake engine to execute a build task. Note: There must be at least one task called 'default' in the build script Task Name String Action ScriptBlock PreAction ScriptBlock PostAction ScriptBlock Precondition ScriptBlock Postcondition ScriptBlock ContinueOnError Boolean Depends String[] RequiredVariables String[] Description String[] Name The name of the task String String Action A scriptblock containing the statements to execute for the task. ScriptBlock ScriptBlock PreAction A scriptblock to be executed before the 'Action' scriptblock. Note: This parameter is ignored if the 'Action' scriptblock is not defined. ScriptBlock ScriptBlock PostAction A scriptblock to be executed after the 'Action' scriptblock. Note: This parameter is ignored if the 'Action' scriptblock is not defined. ScriptBlock ScriptBlock Precondition A scriptblock that is executed to determine if the task is executed or skipped. This scriptblock should return $true or $false ScriptBlock ScriptBlock Postcondition A scriptblock that is executed to determine if the task completed its job correctly. An exception is thrown if the scriptblock returns $false. ScriptBlock ScriptBlock ContinueOnError If this switch parameter is set then the task will not cause the build to fail when an exception is thrown by the task SwitchParameter SwitchParameter Depends An array of task names that this task depends on. These tasks will be executed before the current task is executed. String[] String[] RequiredVariables An array of names of variables that must be set to run this task. String[] String[] Description A description of the task. String String None None -------------- EXAMPLE 1 -------------- C:\PS> A sample build script is shown below: Task default -Depends Test Task Test -Depends Compile, Clean { "This is a test" } Task Compile -Depends Clean { "Compile" } Task Clean { "Clean" } The 'default' task is required and should not contain an 'Action' parameter. It uses the 'Depends' parameter to specify that 'Test' is a dependency The 'Test' task uses the 'Depends' parameter to specify that 'Compile' and 'Clean' are dependencies The 'Compile' task depends on the 'Clean' task. Note: The 'Action' parameter is defaulted to the script block following the 'Clean' task. An equivalent 'Test' task is shown below: Task Test -Depends Compile, Clean -Action { $testMessage } The output for the above sample build script is shown below: Executing task, Clean... Clean Executing task, Compile... Compile Executing task, Test... This is a test Build Succeeded! ---------------------------------------------------------------------- Build Time Report ---------------------------------------------------------------------- Name Duration ---- -------- Clean 00:00:00.0065614 Compile 00:00:00.0133268 Test 00:00:00.0225964 Total: 00:00:00.0782496 Properties FormatTaskName Include Invoke-psake TaskSetup TaskTearDown Assert Framework Assert Helper function for "Design by Contract" assertion checking. This is a helper function that makes the code less noisy by eliminating many of the "if" statements that are normally required to verify assumptions in the code. Assert conditionToCheck Boolean failureMessage String conditionToCheck The boolean condition to evaluate Boolean Boolean failureMessage The error message used for the exception if the conditionToCheck parameter is false String String None None -------------- EXAMPLE 1 -------------- C:\PS> Assert $false "This always throws an exception" -------------- EXAMPLE 2 -------------- C:\PS> Assert ( ($i % 2) -eq 0 ) "$i is not an even number" Description ----------- This exmaple may throw an exception if $i is not an even number Note: It might be necessary to wrap the condition with paranthesis to force PS to evaluate the condition so that a boolean value is calculated and passed into the 'conditionToCheck' parameter. Example: Assert 1 -eq 2 "1 doesn't equal 2" PS will pass 1 into the condtionToCheck variable and PS will look for a parameter called "eq" and throw an exception with the following message "A parameter cannot be found that matches parameter name 'eq'" The solution is to wrap the condition in () so that PS will evaluate it first. Assert (1 -eq 2) "1 doesn't equal 2" Task FormatTaskName Include Invoke-psake TaskSetup TaskTearDown Properties Framework Exec Helper function for executing command-line programs. This is a helper function that runs a scriptblock and checks the PS variable $lastexitcode to see if an error occcured. If an error is detected then an exception is thrown. This function allows you to run command-line programs without having to explicitly check fthe $lastexitcode variable. Exec cmd ScriptBlock errorMessage String cmd The scriptblock to execute. This scriptblock will typically contain the command-line invocation. ScriptBlock Boolean failureMessage The error message used for the exception that is thrown. String String None None -------------- EXAMPLE 1 -------------- C:\PS> exec { svn info $repository_trunk } "Error executing SVN. Please verify SVN command-line client is installed" This example calls the svn command-line client. Assert FormatTaskName Include Invoke-psake Properties Task TaskSetup TaskTearDown Framework Invoke-Task Executes another task in the current build script. This is a function that will allow you to invoke a Task from within another Task in the current build script. Invoke-Task taskName String taskName The name of the task to execute. String String None None -------------- EXAMPLE 1 -------------- C:\PS> Invoke-Task "Compile" This example calls the "Compile" task. Assert Exec FormatTaskName Include Invoke-psake Properties Task TaskSetup TaskTearDown Framework