diff --git a/.gitignore b/.gitignore index 6919d98..265a103 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,6 @@ npm-debug.log* yarn-debug.log* yarn-error.log* bun-error.log + +# psake v5 task cache +.psake/ diff --git a/CLAUDE.md b/CLAUDE.md index 6174576..40f7ebe 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -33,6 +33,8 @@ The build system uses **PowerShell + psake** for orchestration, with Docusaurus/ .\build.ps1 -Help ``` +> **Token efficiency**: Always prefer `.\build.ps1 -Quiet -Task ` when running builds from Claude Code. The `-Quiet` flag suppresses verbose console output and returns a structured `PsakeBuildResult` object, which dramatically reduces token usage while still capturing success/failure. + **Important**: The `Server` task runs `bun run serve` which serves the production build. For local development with hot-reload, use: ```powershell .\build.ps1 -Task Init # Install dependencies first @@ -54,11 +56,11 @@ bun start # Then start dev server directly Command documentation is **auto-generated** from the psake PowerShell module: -- **Generator**: `New-DocusaurusHelp` from `Alt3.Docusaurus.Powershell` module +- **Generator**: `New-PsakeDocusaurusHelp` in `scripts/New-PsakeDocusaurusHelp.ps1`, powered by `Microsoft.PowerShell.PlatyPS` - **Source**: psake module help (from the main psake repository) - **Output**: `docs/commands/*.mdx` files - **Sidebar**: Auto-imported via `docs/commands/docusaurus.sidebar.js` -- **Configuration**: See `$docusaurusOptions` in `psakeFile.ps1:12-34` +- **Configuration**: See `$docusaurusOptions` in `psakeFile.ps1` **Never manually edit files in `docs/commands/`** - they will be overwritten. Edit the source help in the [psake repository](https://github.com/psake/psake) instead. diff --git a/build.ps1 b/build.ps1 index d49daa8..5cb4757 100644 --- a/build.ps1 +++ b/build.ps1 @@ -2,7 +2,7 @@ param( # Build task(s) to execute [parameter(ParameterSetName = 'task', position = 0)] - [ArgumentCompleter( { + [ArgumentCompleter({ param($Command, $Parameter, $WordToComplete, $CommandAst, $FakeBoundParams) try { Get-PSakeScriptTasks -BuildFile './psakeFile.ps1' -ErrorAction 'Stop' | @@ -12,34 +12,45 @@ param( @() } })] - [string[]]$Task = 'default', + [string[]] $Task = 'default', # Bootstrap dependencies - [switch]$Bootstrap, + [switch] $Bootstrap, # List available build tasks [parameter(ParameterSetName = 'Help')] - [switch]$Help, + [switch] $Help, + + # Suppress console output; returns structured PsakeBuildResult. + # LLM should prefer this option. + [switch] $Quiet, + + # Bypass task caching for this run + [switch] $NoCache, + + # Output format for CI integration + [ValidateSet('Default', 'JSON', 'GitHubActions')] + [string] $OutputFormat = 'Default', # Optional properties to pass to psake - [hashtable]$Properties, + [hashtable] $Properties, # Optional parameters to pass to psake - [hashtable]$Parameters + [hashtable] $Parameters ) $ErrorActionPreference = 'Stop' # Bootstrap dependencies -if ($Bootstrap.IsPresent) { +if ($Bootstrap) { PackageManagement\Get-PackageProvider -Name Nuget -ForceBootstrap | Out-Null Set-PSRepository -Name PSGallery -InstallationPolicy Trusted - if ((Test-Path -Path ./requirements.psd1)) { + if (Test-Path -Path './requirements.psd1') { if (-not (Get-Module -Name PSDepend -ListAvailable)) { Install-Module -Name PSDepend -Repository PSGallery -Scope CurrentUser -Force } Import-Module -Name PSDepend -Verbose:$false - Invoke-PSDepend -Path './requirements.psd1' -Install -Import -Force -WarningAction SilentlyContinue + Invoke-PSDepend -Path './requirements.psd1' -Install -Force -WarningAction SilentlyContinue } else { Write-Warning 'No [requirements.psd1] found. Skipping build dependency installation.' } @@ -51,6 +62,16 @@ if ($PSCmdlet.ParameterSetName -eq 'Help') { Get-PSakeScriptTasks -BuildFile $psakeFile | Format-Table -Property Name, Description, Alias, DependsOn } else { - Invoke-Psake -BuildFile $psakeFile -TaskList $Task -NoLogo -Properties $Properties -Parameters $Parameters - exit ([int](-not $psake.build_success)) + $invokeSplat = @{ + BuildFile = $psakeFile + TaskList = $Task + NoLogo = $true + Properties = $Properties + Parameters = $Parameters + Quiet = $Quiet + NoCache = $NoCache + OutputFormat = $OutputFormat + } + $result = Invoke-Psake @invokeSplat + exit ([int](-not $result.Success)) } diff --git a/docs/commands/Assert.mdx b/docs/commands/Assert.mdx index 2a2454d..e5accac 100644 --- a/docs/commands/Assert.mdx +++ b/docs/commands/Assert.mdx @@ -22,14 +22,17 @@ Helper function for "Design by Contract" assertion checking. ## SYNTAX -```powershell -Assert [-conditionToCheck] [-failureMessage] [-ProgressAction ] - [] +### __AllParameterSets + +``` +Assert [-ConditionToCheck] [-FailureMessage] [] ``` ## DESCRIPTION -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. +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. ## EXAMPLES @@ -39,6 +42,7 @@ This is a helper function that makes the code less noisy by eliminating many of Assert $false "This always throws an exception" ``` + Example of an assertion that will always fail. ### EXAMPLE 2 @@ -47,75 +51,82 @@ Example of an assertion that will always fail. Assert ( ($i % 2) -eq 0 ) "$i is not an even number" ``` -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. +This example may throw an exception if $i is not an even number -Example: - Assert 1 -eq 2 "1 doesn't equal 2" +It might be necessary to wrap the condition with parentheses to force +PowerShell to evaluate the condition so that a boolean value is calculated +and passed into the 'ConditionToCheck' parameter. -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'" +### EXAMPLE 3 -The solution is to wrap the condition in () so that PS will evaluate it first. - -Assert (1 -eq 2) "1 doesn't equal 2" +```powershell +Assert 1 -eq 2 "1 doesn't equal 2" +``` -## PARAMETERS -### -conditionToCheck +PowerShell will pass 1 into the ConditionToCheck 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 boolean condition to evaluate +The solution is to wrap the condition in () so that PowerShell will evaluate +it first. -```yaml -Type: Object -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +```powershell +Assert (1 -eq 2) "1 doesn't equal 2" ``` -### -failureMessage +## PARAMETERS -The error message used for the exception if the conditionToCheck parameter is false +### -ConditionToCheck + +The boolean condition to evaluate ```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 2 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Object +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` -### -ProgressAction +### -FailureMessage -\{\{ Fill ProgressAction Description \}\} +The error message used for the exception if the ConditionToCheck parameter +is false ```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: proga - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 1 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -125,26 +136,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Exec](Exec.mdx) - -[FormatTaskName](FormatTaskName.mdx) - -[Framework](Framework.mdx) - -[Get-PSakeScriptTasks](Get-PSakeScriptTasks.mdx) - -[Include](Include.mdx) - -[Invoke-psake](Invoke-psake.mdx) - -[Properties](Properties.mdx) - -[Task](Task.mdx) - -[TaskSetup](TaskSetup.mdx) - -[TaskTearDown](TaskTearDown.mdx) - ## VERSION - -*This page was generated using comment-based help in [Psake 4.9.0](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/BuildSetup.mdx b/docs/commands/BuildSetup.mdx new file mode 100644 index 0000000..2723222 --- /dev/null +++ b/docs/commands/BuildSetup.mdx @@ -0,0 +1,105 @@ +--- +id: BuildSetup +title: BuildSetup +description: Help page for the PowerShell Psake "BuildSetup" command +keywords: + - PowerShell + - Psake + - Help + - Documentation +hide_title: false +hide_table_of_contents: false +custom_edit_url: null +--- + +:::info This page was generated +Contributions are welcome in [Psake-repo](https://github.com/psake/psake). +::: + +:::note Since Psake 5.0 +This command was introduced in Psake 5.0 and is not available in earlier versions. +::: + +## SYNOPSIS + +Adds a scriptblock that will be executed once at the beginning of the build + +## SYNTAX + +### __AllParameterSets + +``` +BuildSetup [-Setup] [] +``` + +## DESCRIPTION + +Runs once before the first task executes. +Use this to set up shared +state, logging, or environment validation for the whole build. + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +Task default -Depends Test +Task Test -Depends Compile, Clean {} +Task Compile -Depends Clean {} +Task Clean {} +BuildSetup { + "Running 'BuildSetup'" +} +``` + + +The script above produces the following output: + +``` +Running 'BuildSetup' +Executing task, Clean... +Executing task, Compile... +Executing task, Test... +Build Succeeded +``` + +## PARAMETERS + +### -Setup + +Executed once before any tasks run. + +```yaml +Type: System.Management.Automation.ScriptBlock +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +## VERSION +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/BuildTearDown.mdx b/docs/commands/BuildTearDown.mdx new file mode 100644 index 0000000..1f52490 --- /dev/null +++ b/docs/commands/BuildTearDown.mdx @@ -0,0 +1,131 @@ +--- +id: BuildTearDown +title: BuildTearDown +description: Help page for the PowerShell Psake "BuildTearDown" command +keywords: + - PowerShell + - Psake + - Help + - Documentation +hide_title: false +hide_table_of_contents: false +custom_edit_url: null +--- + +:::info This page was generated +Contributions are welcome in [Psake-repo](https://github.com/psake/psake). +::: + +:::note Since Psake 5.0 +This command was introduced in Psake 5.0 and is not available in earlier versions. +::: + +## SYNOPSIS + +Adds a scriptblock that will be executed once at the end of the build + +## SYNTAX + +### __AllParameterSets + +``` +BuildTearDown [-Setup] [] +``` + +## DESCRIPTION + +Runs after all tasks complete, even if the build failed. +Use this for +cleanup, notifications, or post-build reporting. + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +Task default -Depends Test +Task Test -Depends Compile, Clean {} +Task Compile -Depends Clean {} +Task Clean {} +BuildTearDown { + "Running 'BuildTearDown'" +} +``` + + +The script above produces the following output: + +``` +Executing task, Clean... +Executing task, Compile... +Executing task, Test... +Running 'BuildTearDown' +Build Succeeded +``` + +### EXAMPLE 2 + +```powershell +Task default -Depends Test +Task Test -Depends Compile, Clean { + throw "forced error" +} +Task Compile -Depends Clean {} +Task Clean {} +BuildTearDown { + "Running 'BuildTearDown'" +} +``` + + +The script above produces the following output: + +``` +Executing task, Clean... +Executing task, Compile... +Executing task, Test... +Running 'BuildTearDown' +forced error +At line:x char:x ... +``` + +## PARAMETERS + +### -Setup + +Executed after all tasks finish, whether or not the build succeeded. + +```yaml +Type: System.Management.Automation.ScriptBlock +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +## VERSION +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Clear-PsakeCache.mdx b/docs/commands/Clear-PsakeCache.mdx new file mode 100644 index 0000000..ec3dcfa --- /dev/null +++ b/docs/commands/Clear-PsakeCache.mdx @@ -0,0 +1,124 @@ +--- +id: Clear-PsakeCache +title: Clear-PsakeCache +description: Help page for the PowerShell Psake "Clear-PsakeCache" command +keywords: + - PowerShell + - Psake + - Help + - Documentation +hide_title: false +hide_table_of_contents: false +custom_edit_url: null +--- + +:::info This page was generated +Contributions are welcome in [Psake-repo](https://github.com/psake/psake). +::: + +:::note Since Psake 5.0 +This command was introduced in Psake 5.0 and is not available in earlier versions. +::: + +## SYNOPSIS + +Clears the psake build cache. + +## SYNTAX + +### __AllParameterSets + +``` +Clear-PsakeCache [[-Path] ] [[-TaskName] ] [] +``` + +## DESCRIPTION + +Removes cached task state from the .psake/cache/ directory. +This forces all tasks to re-execute on the next build. + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +Clear-PsakeCache +``` + + +Clears all cached task state in the current directory. + +### EXAMPLE 2 + +```powershell +Clear-PsakeCache -TaskName 'Build' +``` + + +Clears cached state for the 'Build' task only. + +## PARAMETERS + +### -Path + +The directory containing the .psake/cache/ folder. +Defaults to the current +directory. + +```yaml +Type: System.String +DefaultValue: . +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -TaskName + +Optional: clear cache for a specific task only. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 1 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +- [Invoke-Psake](/docs/commands/Invoke-Psake) + +## VERSION +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Exec.mdx b/docs/commands/Exec.mdx deleted file mode 100644 index d81ef24..0000000 --- a/docs/commands/Exec.mdx +++ /dev/null @@ -1,183 +0,0 @@ ---- -id: Exec -title: Exec -description: Help page for the PowerShell Psake "Exec" command -keywords: - - PowerShell - - Psake - - Help - - Documentation -hide_title: false -hide_table_of_contents: false -custom_edit_url: null ---- - -:::info This page was generated -Contributions are welcome in [Psake-repo](https://github.com/psake/psake). -::: - -## SYNOPSIS - -Helper function for executing command-line programs. - -## SYNTAX - -```powershell -Exec [-cmd] [[-errorMessage] ] [[-maxRetries] ] - [[-retryTriggerErrorPattern] ] [[-workingDirectory] ] [-ProgressAction ] - [] -``` - -## DESCRIPTION - -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. - -## EXAMPLES - -### EXAMPLE 1 - -```powershell -exec { svn info $repository_trunk } "Error executing SVN. Please verify SVN command-line client is installed" -``` - -This example calls the svn command-line client. - -## PARAMETERS - -### -cmd - -The scriptblock to execute. -This scriptblock will typically contain the command-line invocation. - -```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -errorMessage - -The error message to display if the external command returned a non-zero exit code. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: 2 -Default value: ($msgs.error_bad_command -f $cmd) -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -maxRetries - -The maximum number of times to retry the command before failing. - -```yaml -Type: Int32 -Parameter Sets: (All) -Aliases: - -Required: False -Position: 3 -Default value: 0 -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -retryTriggerErrorPattern - -If the external command raises an exception, match the exception against this regex to determine if the command can be retried. -If a match is found, the command will be retried provided [maxRetries] has not been reached. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: 4 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -workingDirectory - -The working directory to set before running the external command. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: 5 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ProgressAction - -\{\{ Fill ProgressAction Description \}\} - -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: proga - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS - -[Assert](Assert.mdx) - -[FormatTaskName](FormatTaskName.mdx) - -[Framework](Framework.mdx) - -[Get-PSakeScriptTasks](Get-PSakeScriptTasks.mdx) - -[Include](Include.mdx) - -[Invoke-psake](Invoke-psake.mdx) - -[Properties](Properties.mdx) - -[Task](Task.mdx) - -[TaskSetup](TaskSetup.mdx) - -[TaskTearDown](TaskTearDown.mdx) - -[Properties](Properties.mdx) - -## VERSION - -*This page was generated using comment-based help in [Psake 4.9.0](https://github.com/psake/psake).* diff --git a/docs/commands/Execute.mdx b/docs/commands/Execute.mdx new file mode 100644 index 0000000..9e4933d --- /dev/null +++ b/docs/commands/Execute.mdx @@ -0,0 +1,229 @@ +--- +id: Execute +title: Execute +description: Help page for the PowerShell Psake "Execute" command +keywords: + - PowerShell + - Psake + - Help + - Documentation +hide_title: false +hide_table_of_contents: false +custom_edit_url: null +--- + +:::info This page was generated +Contributions are welcome in [Psake-repo](https://github.com/psake/psake). +::: + +:::note Since Psake 5.0 +This command was introduced in Psake 5.0 and is not available in earlier versions. +::: + +## SYNOPSIS + +Helper function for executing command-line programs. + +## SYNTAX + +### __AllParameterSets + +``` +Execute [-Cmd] [[-ErrorMessage] ] [[-MaxRetries] ] + [[-RetryTriggerErrorPattern] ] [[-WorkingDirectory] ] [[-TimeoutSeconds] ] + [-NewProcess] [] +``` + +## DESCRIPTION + +Throws a terminating error if $lastexitcode is non-zero after the +command runs, so callers don't need to check it after each invocation. + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +Execute { svn info $repository_trunk } "Error executing SVN. Please verify SVN command-line client is installed" +``` + + +This example calls the svn command-line client. + +## PARAMETERS + +### -Cmd + +The scriptblock to execute. +This scriptblock will typically contain the +command-line invocation. + +```yaml +Type: System.Management.Automation.ScriptBlock +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -ErrorMessage + +The error message to display if the external command returned a non-zero +exit code. + +```yaml +Type: System.String +DefaultValue: ($msgs.error_bad_command -f $Cmd.ToString().Trim()) +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 1 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -MaxRetries + +The maximum number of times to retry the command before failing. + +```yaml +Type: System.Int32 +DefaultValue: 0 +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 2 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -NewProcess + +If set, the command will be executed in a new process. +This can be used to +isolate the command's environment from the current process. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -RetryTriggerErrorPattern + +If the external command raises an exception, match the exception against +this regex to determine if the command can be retried. +If a match is found, +the command will be retried provided [MaxRetries] has not been reached. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 3 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -TimeoutSeconds + +If set, the command will be terminated if it runs longer than this number of +seconds. +Defaults to 300 seconds (5 minutes). + +```yaml +Type: System.Int32 +DefaultValue: 300 +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 5 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -WorkingDirectory + +The working directory to set before running the external command. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: +- wd +ParameterSets: +- Name: (All) + Position: 4 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +## VERSION +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/FormatTaskName.mdx b/docs/commands/FormatTaskName.mdx index b892022..19779fb 100644 --- a/docs/commands/FormatTaskName.mdx +++ b/docs/commands/FormatTaskName.mdx @@ -18,44 +18,48 @@ Contributions are welcome in [Psake-repo](https://github.com/psake/psake). ## SYNOPSIS -This function allows you to change how psake renders the task name during a build. +This function allows you to change how psake renders the task name during a +build. ## SYNTAX -```powershell -FormatTaskName [-format] [-ProgressAction ] [] +### __AllParameterSets + +``` +FormatTaskName [-Format] [] ``` ## DESCRIPTION -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. +Useful for adding visual separators or color to task names in the +build output. +Accepts a -f format string or a scriptblock that +receives the task name as its only argument. ## EXAMPLES ### EXAMPLE 1 ```powershell -A sample build script that uses a format string is shown below: -``` - Task default -depends TaskA, TaskB, TaskC - -FormatTaskName "-------- \{0\} --------" - -Task TaskA \{ +FormatTaskName "-------- {0} --------" +Task TaskA { "TaskA is executing" -\} - -Task TaskB \{ +} +Task TaskB { "TaskB is executing" -\} - -Task TaskC \{ +} +Task TaskC { "TaskC is executing" +} +``` ------------ -The script above produces the following output: +A sample build script that uses a format string. +The script above produces +the following output: + +``` -------- TaskA -------- TaskA is executing -------- TaskB -------- @@ -64,74 +68,64 @@ TaskB is executing TaskC is executing Build Succeeded! +``` ### EXAMPLE 2 ```powershell -A sample build script that uses a ScriptBlock is shown below: -``` - Task default -depends TaskA, TaskB, TaskC - -FormatTaskName \{ +FormatTaskName { param($taskName) - write-host "Executing Task: $taskName" -foregroundcolor blue -\} - -Task TaskA \{ + write-host "Executing Task: $taskName" -ForegroundColor blue +} +Task TaskA { "TaskA is executing" -\} - -Task TaskB \{ +} +Task TaskB { "TaskB is executing" -\} - -Task TaskC \{ +} +Task TaskC { "TaskC is executing" -\} +} +``` + ------------ -The above example uses the scriptblock parameter to the FormatTaskName function to render each task name in the color blue. +A sample build script that uses a ScriptBlock. +The above 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. +Note: the $taskName parameter name is arbitrary, it could be named anything. ## PARAMETERS -### -format +### -Format A format string or a scriptblock to execute ```yaml -Type: Object -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ProgressAction - -\{\{ Fill ProgressAction Description \}\} - -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: proga - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Object +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -141,26 +135,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Assert](Assert.mdx) - -[Exec](Exec.mdx) - -[Framework](Framework.mdx) - -[Get-PSakeScriptTasks](Get-PSakeScriptTasks.mdx) - -[Include](Include.mdx) - -[Invoke-psake](Invoke-psake.mdx) - -[Properties](Properties.mdx) - -[Task](Task.mdx) - -[TaskSetup](TaskSetup.mdx) - -[TaskTearDown](TaskTearDown.mdx) - ## VERSION - -*This page was generated using comment-based help in [Psake 4.9.0](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Framework.mdx b/docs/commands/Framework.mdx index 91e7b9d..ddda1d2 100644 --- a/docs/commands/Framework.mdx +++ b/docs/commands/Framework.mdx @@ -22,15 +22,16 @@ Sets the version of the .NET framework you want to use during build. ## SYNTAX -```powershell -Framework [-framework] [-ProgressAction ] [] +### __AllParameterSets + +``` +Framework [-Framework] [] ``` ## DESCRIPTION -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. +Overrides the psake default framework, determining which MSBuild and +runtime directories are used by all tasks in the build. ## EXAMPLES @@ -38,54 +39,50 @@ Default is '3.5*', where x86 or x64 will be detected based on the bitness of the ```powershell Framework "4.0" -``` - Task default -depends Compile - -Task Compile -depends Clean \{ +Task Compile -depends Clean { msbuild /version -\} - ------------ -The script above will output detailed version of msbuid v4 - -## PARAMETERS +} +``` -### -framework -Version of the .NET framework to use during build. +Uses MSBuild v4.0 for the build. -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` +## PARAMETERS -### -ProgressAction +### -Framework -\{\{ Fill ProgressAction Description \}\} +Framework version string. +Append 'x86' or 'x64' to force bitness; +otherwise bitness matches the current PowerShell process. +Supported 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*' (bitness auto-detected). ```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: proga - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -95,26 +92,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Assert](Assert.mdx) - -[Exec](Exec.mdx) - -[FormatTaskName](FormatTaskName.mdx) - -[Get-PSakeScriptTasks](Get-PSakeScriptTasks.mdx) - -[Include](Include.mdx) - -[Invoke-psake](Invoke-psake.mdx) - -[Properties](Properties.mdx) - -[Task](Task.mdx) - -[TaskSetup](TaskSetup.mdx) - -[TaskTearDown](TaskTearDown.mdx) - ## VERSION - -*This page was generated using comment-based help in [Psake 4.9.0](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Get-PSakeScriptTasks.mdx b/docs/commands/Get-PSakeScriptTasks.mdx index 86cda12..5584c83 100644 --- a/docs/commands/Get-PSakeScriptTasks.mdx +++ b/docs/commands/Get-PSakeScriptTasks.mdx @@ -22,22 +22,27 @@ Returns meta data about all the tasks defined in the provided psake script. ## SYNTAX -```powershell -Get-PSakeScriptTasks [[-buildFile] ] [-ProgressAction ] [] +### __AllParameterSets + +``` +Get-PSakeScriptTasks [[-BuildFile] ] [] ``` ## DESCRIPTION -Returns meta data about all the tasks defined in the provided psake script. +Loads the build file and evaluates task definitions without executing +any tasks. +Useful for tooling, IDE integrations, and tab completion. ## EXAMPLES ### EXAMPLE 1 ```powershell -Get-PSakeScriptTasks -buildFile '.\build.ps1' +Get-PSakeScriptTasks -BuildFile '.\build.ps1' ``` + DependsOn Alias Name Description --------- ----- ---- ----------- \{\} Compile @@ -49,41 +54,33 @@ Gets the psake tasks contained in the 'build.ps1' file. ## PARAMETERS -### -buildFile +### -BuildFile The path to the psake build script to read the tasks from. ```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ProgressAction - -\{\{ Fill ProgressAction Description \}\} - -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: proga - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -93,8 +90,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Invoke-psake](Invoke-psake.mdx) - ## VERSION - -*This page was generated using comment-based help in [Psake 4.9.0](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Get-PsakeBuildPlan.mdx b/docs/commands/Get-PsakeBuildPlan.mdx new file mode 100644 index 0000000..12bf406 --- /dev/null +++ b/docs/commands/Get-PsakeBuildPlan.mdx @@ -0,0 +1,150 @@ +--- +id: Get-PsakeBuildPlan +title: Get-PsakeBuildPlan +description: Help page for the PowerShell Psake "Get-PsakeBuildPlan" command +keywords: + - PowerShell + - Psake + - Help + - Documentation +hide_title: false +hide_table_of_contents: false +custom_edit_url: null +--- + +:::info This page was generated +Contributions are welcome in [Psake-repo](https://github.com/psake/psake). +::: + +:::note Since Psake 5.0 +This command was introduced in Psake 5.0 and is not available in earlier versions. +::: + +## SYNOPSIS + +Compiles a build file and returns the build plan without executing any tasks. + +## SYNTAX + +### __AllParameterSets + +``` +Get-PsakeBuildPlan [[-BuildFile] ] [[-TaskList] ] [] +``` + +## DESCRIPTION + +This is the primary testability API for psake v5. +It loads a build file, +validates the dependency graph, and returns a PsakeBuildPlan object that +can be inspected in tests. + +This function always returns a [PsakeBuildPlan]. +If the build file cannot +be loaded or the dependency graph is invalid, an invalid plan is returned +with IsValid = $false and ValidationErrors populated. + +The returned plan can be piped into Invoke-Psake for execution. +Note that +when piping, the build file is re-loaded during the execution phase to +resolve properties, setup, and teardown blocks. + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +$plan = Get-PsakeBuildPlan -BuildFile './psakefile.ps1' +$plan.Tasks | Should -HaveCount 4 +$plan.ExecutionOrder | Should -Be @('Clean', 'Compile', 'Test', 'Default') +``` + + +This example compiles the build file and asserts that there are 4 tasks and +that the execution order is correct. + +### EXAMPLE 2 + +```powershell +$plan = Get-PsakeBuildPlan +$plan.TaskMap['build'].DependsOn | Should -Contain 'Clean' +$plan.IsValid | Should -BeTrue +``` + + +This example compiles the default build file and asserts that the 'build' +task depends on the 'Clean' task and that the plan is valid. + +### EXAMPLE 3 + +```powershell +Get-PsakeBuildPlan -BuildFile './psakefile.ps1' | Invoke-Psake +``` + + +Compiles the build plan and pipes it into Invoke-Psake for execution. +Note: the build file is re-loaded during the execution phase. + +## PARAMETERS + +### -BuildFile + +The path to the psake build script. +Defaults to 'psakefile.ps1'. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -TaskList + +A list of task names to include in the plan. +Defaults to 'default'. + +```yaml +Type: System.String[] +DefaultValue: "@('default')" +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 1 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +## VERSION +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Include.mdx b/docs/commands/Include.mdx index 65f816e..8623016 100644 --- a/docs/commands/Include.mdx +++ b/docs/commands/Include.mdx @@ -18,112 +18,127 @@ Contributions are welcome in [Psake-repo](https://github.com/psake/psake). ## SYNOPSIS -Include the functions or code of another powershell script file into the current build script's scope +Include the functions or code of another powershell script file into the +current build script's scope ## SYNTAX -```powershell -Include [-fileNamePathToInclude] [-ProgressAction ] [] +### Path (Default) + +``` +Include [-Path] [] +``` + +### LiteralPath + +``` +Include [-LiteralPath] [] ``` ## DESCRIPTION -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. +Included scripts are dot-sourced into the build script's scope after +the build file finishes loading. +You can call Include more than once. ## EXAMPLES ### EXAMPLE 1 ```powershell -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 { +} +``` -Task Test -depends Compile, Clean \{ -\} -Task Compile -depends Clean \{ -\} +Includes all functions and variables from build_utils.ps1 in the +build script's scope. -Task Clean \{ -\} +### EXAMPLE 2 + +```powershell +@("File1.ps1","File2.ps1") | Include +Get-ChildItem | Include +``` ------------ -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. +Strings or FileInfo objects can be piped to the Include function ## PARAMETERS -### -fileNamePathToInclude +### -LiteralPath -A string containing the path and name of the powershell file to include +Path to the script file to include. +No wildcard expansion. ```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: LiteralPath + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: true + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` -### -ProgressAction +### -Path -\{\{ Fill ProgressAction Description \}\} +Path to the script file(s) to include. +Supports wildcards. ```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: proga - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.String +DefaultValue: '' +SupportsWildcards: true +Aliases: +- fileNamePathToInclude +ParameterSets: +- Name: Path + Position: 0 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: true + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS -## OUTPUTS - -## NOTES - -## RELATED LINKS - -[Assert](Assert.mdx) - -[Exec](Exec.mdx) +### System.String -[FormatTaskName](FormatTaskName.mdx) +The path(s) to the script file(s) to include in the build. -[Framework](Framework.mdx) -[Get-PSakeScriptTasks](Get-PSakeScriptTasks.mdx) +### System.String -[Invoke-psake](Invoke-psake.mdx) -[Properties](Properties.mdx) - -[Task](Task.mdx) +## OUTPUTS -[TaskSetup](TaskSetup.mdx) +## NOTES -[TaskTearDown](TaskTearDown.mdx) +## RELATED LINKS ## VERSION - -*This page was generated using comment-based help in [Psake 4.9.0](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Invoke-Psake.mdx b/docs/commands/Invoke-Psake.mdx new file mode 100644 index 0000000..8ee7b2c --- /dev/null +++ b/docs/commands/Invoke-Psake.mdx @@ -0,0 +1,464 @@ +--- +id: Invoke-Psake +title: Invoke-Psake +description: Help page for the PowerShell Psake "Invoke-Psake" command +keywords: + - PowerShell + - Psake + - Help + - Documentation +hide_title: false +hide_table_of_contents: false +custom_edit_url: null +--- + +:::info This page was generated +Contributions are welcome in [Psake-repo](https://github.com/psake/psake). +::: + +## SYNOPSIS + +Runs a psake build script. + +## SYNTAX + +### __AllParameterSets + +``` +Invoke-Psake [[-BuildFile] ] [[-TaskList] ] [[-Framework] ] [-Docs] + [[-Parameters] ] [[-Properties] ] [[-Initialization] ] [-NoLogo] + [-DetailedDocs] [-NoTimeReport] [-OutputFormat ] [-NoCache] [-CompileOnly] [-Quiet] + [-BuildPlan ] [] +``` + +## DESCRIPTION + +This function runs a psake build script using a two-phase compile/run model. +The compile phase loads the build file and validates the dependency graph. +The run phase executes tasks in the resolved order. + +A pre-compiled [PsakeBuildPlan] from Get-PsakeBuildPlan can be piped in to +skip the compile phase. +When doing so, the build file is re-loaded for the +execution phase to resolve properties, setup, and teardown blocks. + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +Invoke-psake +``` + + +Runs the 'default' task in the 'psakefile.ps1' build script + +### EXAMPLE 2 + +```powershell +Invoke-psake '.\build.ps1' Tests,Package +``` + + +Runs the 'Tests' and 'Package' tasks in the 'build.ps1' build script + +### EXAMPLE 3 + +```powershell +Invoke-psake -CompileOnly +``` + + +Returns the build plan without executing any tasks. + +### EXAMPLE 4 + +```powershell +Get-PsakeBuildPlan | Invoke-Psake +``` + + +Compiles the build plan then executes it. +The build file is re-loaded +during the execution phase. + +### EXAMPLE 5 + +```powershell +Invoke-psake -OutputFormat JSON +``` + + +Runs the build and outputs the result as JSON. + +## PARAMETERS + +### -BuildFile + +The path to the psake build script to execute + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -BuildPlan + +A pre-compiled [PsakeBuildPlan] to execute, typically from Get-PsakeBuildPlan +via the pipeline. +Compile-phase parameters (BuildFile, TaskList, Framework, +Docs, DetailedDocs, CompileOnly) are ignored when a plan is provided. +Note: the build file is re-loaded during the execution phase. + +```yaml +Type: PsakeBuildPlan +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -CompileOnly + +Return the build plan without executing any tasks. +Delegates to +Get-PsakeBuildPlan. +Useful for tooling and testing. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -DetailedDocs + +Prints a more descriptive list of tasks and their descriptions. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 8 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Docs + +Prints a list of tasks and their descriptions + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 3 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -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: '4.0', '4.0x86', '4.0x64', '4.5', '4.5x86', '4.5x64', +'4.5.1', '4.5.1x86', '4.5.1x64', '4.6', '4.6.1', '4.6.2', '4.7', '4.7.1', +'4.7.2', '4.8', '4.8.1' + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 2 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Initialization + +A script block that will be executed before the tasks are executed. + +```yaml +Type: System.Management.Automation.ScriptBlock +DefaultValue: '{}' +SupportsWildcards: false +Aliases: +- init +ParameterSets: +- Name: (All) + Position: 6 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -NoCache + +Bypass task caching. +All tasks will execute regardless of cache state. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -NoLogo + +Do not display the startup banner and copyright message. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 7 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -NoTimeReport + +Do not display the time report. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: +- notr +ParameterSets: +- Name: (All) + Position: 9 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -OutputFormat + +Output format. +'Default' for console, 'JSON' for stdout JSON, +'GitHubActions' for workflow annotations (::error::, ::warning::, +::debug::), 'Annotated' for console + annotation lines (VS Code +problem matcher). +Falls back to PSAKE_OUTPUT_FORMAT env variable. + +```yaml +Type: System.String +DefaultValue: Default +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -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. + +```yaml +Type: System.Collections.Hashtable +DefaultValue: '@{}' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 4 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -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. + +```yaml +Type: System.Collections.Hashtable +DefaultValue: '@{}' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 5 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Quiet + +Suppress all console output. +The PsakeBuildResult is still returned. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -TaskList + +A comma-separated list of task names to execute + +```yaml +Type: System.String[] +DefaultValue: "@('default')" +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 1 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### PsakeBuildPlan + +A pre-compiled build plan from Get-PsakeBuildPlan + + +### PsakeBuildPlan + + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +## VERSION +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Invoke-Task.mdx b/docs/commands/Invoke-Task.mdx index 328c348..a4ce37f 100644 --- a/docs/commands/Invoke-Task.mdx +++ b/docs/commands/Invoke-Task.mdx @@ -22,13 +22,16 @@ Executes another task in the current build script. ## SYNTAX -```powershell -Invoke-Task [-taskName] [-ProgressAction ] [] +### __AllParameterSets + +``` +Invoke-Task [-TaskName] [] ``` ## DESCRIPTION -This is a function that will allow you to invoke a Task from within another Task in the current build script. +Use this inside a task's Action when you need to sequence tasks +programmatically rather than declaring them with -Depends. ## EXAMPLES @@ -38,45 +41,38 @@ This is a function that will allow you to invoke a Task from within another Task Invoke-Task "Compile" ``` + This example calls the "Compile" task. ## PARAMETERS -### -taskName +### -TaskName The name of the task to execute. ```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ProgressAction - -\{\{ Fill ProgressAction Description \}\} - -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: proga - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -86,28 +82,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Assert](Assert.mdx) - -[Exec](Exec.mdx) - -[FormatTaskName](FormatTaskName.mdx) - -[Framework](Framework.mdx) - -[Get-PSakeScriptTasks](Get-PSakeScriptTasks.mdx) - -[Include](Include.mdx) - -[Invoke-psake](Invoke-psake.mdx) - -[Properties](Properties.mdx) - -[Task](Task.mdx) - -[TaskSetup](TaskSetup.mdx) - -[TaskTearDown](TaskTearDown.mdx) - ## VERSION - -*This page was generated using comment-based help in [Psake 4.9.0](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Invoke-psake.mdx b/docs/commands/Invoke-psake.mdx deleted file mode 100644 index 4b02b36..0000000 --- a/docs/commands/Invoke-psake.mdx +++ /dev/null @@ -1,193 +0,0 @@ ---- -id: Invoke-psake -title: Invoke-psake -description: Help page for the PowerShell Psake "Invoke-psake" command -keywords: - - PowerShell - - Psake - - Help - - Documentation -hide_title: false -hide_table_of_contents: false -custom_edit_url: null ---- - -:::info This page was generated -Contributions are welcome in [Psake-repo](https://github.com/psake/psake). -::: - -## SYNOPSIS - -Runs a psake build script. - -## SYNTAX - -```powershell -Invoke-psake [[-buildFile] ] [[-taskList] ] [[-framework] ] [-docs] - [[-parameters] ] [[-properties] ] [[-initialization] ] [-nologo] - [-detailedDocs] [-notr] [-ProgressAction ] [] -``` - -## DESCRIPTION - -This function runs a psake build script - -## EXAMPLES - -### EXAMPLE 1 - -```powershell -Invoke-psake -``` - -Runs the 'default' task in the '.build.ps1' build script - -### EXAMPLE 2 - -```powershell -Invoke-psake '.\build.ps1' Tests,Package -``` - -Runs the 'Tests' and 'Package' tasks in the '.build.ps1' build script - -### EXAMPLE 3 - -```powershell -Invoke-psake Tests -``` - -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 - -```powershell -Invoke-psake 'Tests, Package' -``` - -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. - -### EXAMPLE 5 - -```powershell -Invoke-psake .\build.ps1 -docs -``` - -Prints a report of all the tasks and their dependencies and descriptions and then exits - -### EXAMPLE 6 - -```powershell -Invoke-psake .\parameters.ps1 -parameters @{"p1"="v1";"p2"="v2"} -``` - -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 - -```powershell -Invoke-psake .\properties.ps1 -properties @{"x"="1";"y"="2"} -``` - -Runs the build script called 'properties.ps1' and passes in parameters 'x' and 'y' with values '1' and '2' - -This feature allows you to override 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" -\} - -## PARAMETERS - -### -buildFile - -The path to the psake build script to execute - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -taskList - -A comma-separated list of task names to execute - -```yaml -Type: String[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: 2 -Default value: @() -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -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' - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: 3 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -docs - -Prints a list of tasks and their descriptions - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: 4 -Default value: False -Acc diff --git a/docs/commands/Properties.mdx b/docs/commands/Properties.mdx index 23e8d9a..72e1833 100644 --- a/docs/commands/Properties.mdx +++ b/docs/commands/Properties.mdx @@ -18,81 +18,137 @@ Contributions are welcome in [Psake-repo](https://github.com/psake/psake). ## SYNOPSIS -Define a scriptblock that contains assignments to variables that will be available to all tasks in the build script +Define a scriptblock that contains assignments to variables that will be +available within all tasks in the build script ## SYNTAX -```powershell -Properties [-properties] [-ProgressAction ] [] +### ScriptBlock (Default) + +``` +Properties [-Properties] [] +``` + +### Hashtable + +``` +Properties [-Hashtable] [] ``` ## DESCRIPTION -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. +A build script may declare a "Properties" function which allows you to +define variables that will be available within all the "Task" functions in +the build script. ## EXAMPLES ### EXAMPLE 1 ```powershell -A sample build script is shown below: -``` - -Properties \{ +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 { +} +``` -Task Test -depends Compile, Clean \{ -\} -Task Compile -depends Clean \{ -\} +Note: You can have more than one "Properties" function defined in the build script. -Task Clean \{ -\} +### EXAMPLE 2 -Note: You can have more than one "Properties" function defined in the build script. +```powershell +Properties { + $script:build_dir = "c:\build" + $script:connection_string = "datasource=localhost;initial catalog=northwind;integrated security=sspi" +} +Task Compile { + "Building to: $build_dir" # No PSScriptAnalyzer warning, variable is recognized +} +``` + + +Recommended: Use script-scoped variables to avoid PSScriptAnalyzer warnings +The $script: prefix has identical runtime behavior but satisfies +PSScriptAnalyzer's static analysis requirements. + +### EXAMPLE 3 + +```powershell +Properties { + $build_dir = "c:\build" # Warning: PSUseDeclaredVarsMoreThanAssignments +} +Task Compile { + "Building to: $build_dir" # Works at runtime, but PSScriptAnalyzer warns +} +``` + + +Alternative: Non-scoped variables (generates PSScriptAnalyzer warnings) + +Variables still work correctly at runtime, but PSScriptAnalyzer cannot detect +that they will be used in tasks. ## PARAMETERS -### -properties +### -Hashtable -The script block containing all the variable assignment statements +An alternative to the scriptblock parameter, you can provide a hashtable of +key-value pairs that will be converted into variables. +This is useful when +you want to define properties programmatically or from an external source. ```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Collections.Hashtable +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: Hashtable + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` -### -ProgressAction +### -Properties -\{\{ Fill ProgressAction Description \}\} +The script block containing all the variable assignment statements ```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: proga - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Management.Automation.ScriptBlock +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: ScriptBlock + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -100,28 +156,16 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES -## RELATED LINKS - -[Assert](Assert.mdx) - -[Exec](Exec.mdx) - -[FormatTaskName](FormatTaskName.mdx) - -[Framework](Framework.mdx) - -[Get-PSakeScriptTasks](Get-PSakeScriptTasks.mdx) +Properties scriptblocks are dot-sourced into each task's scope at +runtime. +Variables are not accessible outside of task scriptblocks. -[Include](Include.mdx) +PSScriptAnalyzer may flag declared variables as unused — this is a +false positive. +Use the $script: prefix to suppress it (see examples). -[Invoke-psake](Invoke-psake.mdx) -[Task](Task.mdx) - -[TaskSetup](TaskSetup.mdx) - -[TaskTearDown](TaskTearDown.mdx) +## RELATED LINKS ## VERSION - -*This page was generated using comment-based help in [Psake 4.9.0](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Task.mdx b/docs/commands/Task.mdx index 50f61f9..0b1b254 100644 --- a/docs/commands/Task.mdx +++ b/docs/commands/Task.mdx @@ -24,162 +24,507 @@ Defines a build task to be executed by psake ### Normal (Default) -```powershell -Task [-name] [[-action] ] [[-preaction] ] [[-postaction] ] - [[-precondition] ] [[-postcondition] ] [-continueOnError] [[-depends] ] - [[-requiredVariables] ] [[-description] ] [[-alias] ] - [-ProgressAction ] [] +``` +Task [-Name] [[-Action] ] [-PreAction ] + [-PostAction ] [-PreCondition ] [-PostCondition ] + [-ContinueOnError] [-Depends ] [-RequiredVariables ] [-Description ] + [-Alias ] [] ``` ### SharedTask -```powershell -Task [-name] [[-action] ] [[-preaction] ] [[-postaction] ] - [[-precondition] ] [[-postcondition] ] [-continueOnError] [[-depends] ] - [[-requiredVariables] ] [[-description] ] [[-alias] ] [-FromModule] - [[-requiredVersion] ] [[-minimumVersion] ] [[-maximumVersion] ] - [[-lessThanVersion] ] [-ProgressAction ] [] +``` +Task [-Name] [[-Action] ] -FromModule [-PreAction ] + [-PostAction ] [-PreCondition ] [-PostCondition ] + [-ContinueOnError] [-Depends ] [-RequiredVariables ] [-Description ] + [-Alias ] [-RequiredVersion ] [-MinimumVersion ] [-MaximumVersion ] + [-LessThanVersion ] [] +``` + +### Declarative + +``` +Task [-Name] [[-Definition] ] [] ``` ## DESCRIPTION -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 +Defines a named task in the build script. +Every script must include +at least one task named 'default'. ## EXAMPLES ### EXAMPLE 1 ```powershell -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" +} ``` -Task default -Depends Test -Task Test -Depends Compile, Clean \{ - "This is a test" -\} +The trailing scriptblock is equivalent to -Action \{ ... +\}. +The 'default' task must exist and should declare no Action of its own. -Task Compile -Depends Clean \{ - "Compile" -\} +## PARAMETERS -Task Clean \{ - "Clean" -\} +### -Action -The 'default' task is required and should not contain an 'Action' parameter. -It uses the 'Depends' parameter to specify that 'Test' is a dependency +A scriptblock containing the statements to execute for the task. -The 'Test' task uses the 'Depends' parameter to specify that 'Compile' and 'Clean' are dependencies -The 'Compile' task depends on the 'Clean' task. +```yaml +Type: System.Management.Automation.ScriptBlock +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: 1 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +- Name: Normal + Position: 1 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` -Note: -The 'Action' parameter is defaulted to the script block following the 'Clean' task. +### -Alias -An equivalent 'Test' task is shown below: +An alternate name for the task. -Task Test -Depends Compile, Clean -Action \{ - $testMessage -\} +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +- Name: Normal + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` -The output for the above sample build script is shown below: +### -ContinueOnError -Executing task, Clean... -Clean -Executing task, Compile... -Compile -Executing task, Test... -This is a test +If this switch parameter is set then the task will not cause the build to +fail when an exception is thrown by the task -Build Succeeded! +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +- Name: Normal + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` ----------------------------------------------------------------------- -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 +### -Definition -## PARAMETERS +Declarative hashtable alternative to named parameters. +Supported keys: Action, PreAction, PostAction, PreCondition, +PostCondition, ContinueOnError, Description, Alias, +RequiredVariables. + +```yaml +Type: System.Collections.Hashtable +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: Declarative + Position: 1 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` -### -name +### -Depends -The name of the task +An array of task names that this task depends on. +These tasks will be executed before the current task is executed. ```yaml -Type: String -Parameter Sets: (All) -Aliases: +Type: System.String[] +DefaultValue: '@()' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +- Name: Normal + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +### -Description + +A description of the task. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +- Name: Normal + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` -### -action +### -FromModule -A scriptblock containing the statements to execute for the task. +Load in the task from the specified PowerShell module. ```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -LessThanVersion + +The version of the PowerShell module to load in the task from that should +not be met or exceeded. +eg -LessThanVersion 2.0.0 will reject anything 2.0.0 +or higher, allowing any module in the 1.x.x series. -Required: False -Position: 2 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` -### -preaction +### -MaximumVersion -A scriptblock to be executed before the 'Action' scriptblock. -Note: This parameter is ignored if the 'Action' scriptblock is not defined. +The maximum (inclusive) version of the PowerShell module to load in the task +from. ```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` -Required: False -Position: 3 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +### -MinimumVersion + +The minimum (inclusive) version of the PowerShell module to load in the task +from. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` -### -postaction +### -Name + +The name of the task + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -PostAction A scriptblock to be executed after the 'Action' scriptblock. Note: This parameter is ignored if the 'Action' scriptblock is not defined. ```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: +Type: System.Management.Automation.ScriptBlock +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +- Name: Normal + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -PostCondition + +A scriptblock that is executed to determine if the task completed its job +correctly. +An exception is thrown if the scriptblock returns $false. -Required: False -Position: 4 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +```yaml +Type: System.Management.Automation.ScriptBlock +DefaultValue: '{ $true }' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +- Name: Normal + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` -### -precondition +### -PreAction -A scriptblock that is executed to determine if the task is executed or skipped. +A scriptblock to be executed before the 'Action' scriptblock. +Note: This parameter is ignored if the 'Action' scriptblock is not defined. + +```yaml +Type: System.Management.Automation.ScriptBlock +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +- Name: Normal + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -PreCondition + +A scriptblock that is executed to determine if the task is executed or +skipped. This scriptblock should return $true or $false ```yaml -Type: ScriptBlock -Parameter Sets: (All) +Type: System.Management.Automation.ScriptBlock +DefaultValue: '{ $true }' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +- Name: Normal + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -RequiredVariables + +An array of names of variables that must be set to run this task. + +```yaml +Type: System.String[] +DefaultValue: '@()' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +- Name: Normal + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -RequiredVersion + +The specific version of a module to load the task from + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false Aliases: +- Version +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS -R +## VERSION +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/TaskSetup.mdx b/docs/commands/TaskSetup.mdx index b8c4bc2..f1e5bc2 100644 --- a/docs/commands/TaskSetup.mdx +++ b/docs/commands/TaskSetup.mdx @@ -22,41 +22,40 @@ Adds a scriptblock that will be executed before each task ## SYNTAX -```powershell -TaskSetup [-setup] [-ProgressAction ] [] +### __AllParameterSets + +``` +TaskSetup [-Setup] [] ``` ## DESCRIPTION -This function will accept a scriptblock that will be executed before each task in the build script. - -The scriptblock accepts an optional parameter which describes the Task being setup. +Use this for per-task setup that applies across all tasks, such as +logging, timing, or environment checks. +The scriptblock receives the +current [PsakeTask] as an optional argument. ## EXAMPLES ### EXAMPLE 1 ```powershell -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" +} ``` -Task default -depends Test - -Task Test -depends Compile, Clean \{ -\} - -Task Compile -depends Clean \{ -\} - -Task Clean \{ -\} - -TaskSetup \{ - "Running 'TaskSetup' for task $context.Peek().currentTaskName" -\} The script above produces the following output: +``` Running 'TaskSetup' for task Clean Executing task, Clean... Running 'TaskSetup' for task Compile @@ -65,32 +64,25 @@ Running 'TaskSetup' for task Test Executing task, Test... Build Succeeded +``` ### EXAMPLE 2 ```powershell -A sample build script showing access to the Task context is shown below: -``` - -Task default -depends Test - -Task Test -depends Compile, Clean \{ -\} - -Task Compile -depends Clean \{ -\} - -Task Clean \{ -\} - -TaskSetup \{ +Task default -Depends Test +Task Test -Depends Compile, Clean {} +Task Compile -Depends Clean {} +Task Clean {} +TaskSetup { param($task) - "Running 'TaskSetup' for task $($task.Name)" -\} +} +``` + The script above produces the following output: +``` Running 'TaskSetup' for task Clean Executing task, Clean... Running 'TaskSetup' for task Compile @@ -99,44 +91,37 @@ Running 'TaskSetup' for task Test Executing task, Test... Build Succeeded +``` ## PARAMETERS -### -setup - -A scriptblock to execute - -```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ProgressAction +### -Setup -\{\{ Fill ProgressAction Description \}\} +Receives the current task as an optional [PsakeTask] argument. ```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: proga - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Management.Automation.ScriptBlock +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -146,26 +131,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Assert](Assert.mdx) - -[Exec](Exec.mdx) - -[FormatTaskName](FormatTaskName.mdx) - -[Framework](Framework.mdx) - -[Get-PSakeScriptTasks](Get-PSakeScriptTasks.mdx) - -[Include](Include.mdx) - -[Invoke-psake](Invoke-psake.mdx) - -[Properties](Properties.mdx) - -[Task](Task.mdx) - -[TaskTearDown](TaskTearDown.mdx) - ## VERSION - -*This page was generated using comment-based help in [Psake 4.9.0](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/TaskTearDown.mdx b/docs/commands/TaskTearDown.mdx index 6e533b6..1d36873 100644 --- a/docs/commands/TaskTearDown.mdx +++ b/docs/commands/TaskTearDown.mdx @@ -22,41 +22,39 @@ Adds a scriptblock to the build that will be executed after each task ## SYNTAX -```powershell -TaskTearDown [-teardown] [-ProgressAction ] [] +### __AllParameterSets + +``` +TaskTearDown [-TearDown] [] ``` ## DESCRIPTION -This function will accept a scriptblock that will be executed after each task in the build script. - -The scriptblock accepts an optional parameter which describes the Task being torn down. +Use this for per-task teardown such as logging duration, checking +postconditions, or cleaning up temporary state. +The completed +[PsakeTask] is passed as an optional argument with success/error info. ## EXAMPLES ### EXAMPLE 1 ```powershell -A sample build script is shown below: -``` - -Task default -depends Test - -Task Test -depends Compile, Clean \{ -\} - -Task Compile -depends Clean \{ -\} - -Task Clean \{ -\} - -TaskTearDown \{ +Task default -Depends Test +Task Test -Depends Compile, Clean { +} +Task Compile -Depends Clean { +} +Task Clean { +} +TaskTearDown { "Running 'TaskTearDown' for task $context.Peek().currentTaskName" -\} - +} The script above produces the following output: +``` + +``` Executing task, Clean... Running 'TaskTearDown' for task Clean Executing task, Compile... @@ -65,36 +63,29 @@ Executing task, Test... Running 'TaskTearDown' for task Test Build Succeeded +``` ### EXAMPLE 2 ```powershell -A sample build script demonstrating access to the task context is shown below: -``` - -Task default -depends Test - -Task Test -depends Compile, Clean \{ -\} - -Task Compile -depends Clean \{ -\} - -Task Clean \{ -\} - -TaskTearDown \{ +Task default -Depends Test +Task Test -Depends Compile, Clean {} +Task Compile -Depends Clean {} +Task Clean {} +TaskTearDown { param($task) - - if ($task.Success) \{ + if ($task.Success) { "Running 'TaskTearDown' for task $($task.Name) - success!" - \} else \{ + } else { "Running 'TaskTearDown' for task $($task.Name) - failed: $($task.ErrorMessage)" - \} -\} + } +} +``` + The script above produces the following output: +``` Executing task, Clean... Running 'TaskTearDown' for task Clean - success! Executing task, Compile... @@ -103,44 +94,37 @@ Executing task, Test... Running 'TaskTearDown' for task Test - success! Build Succeeded +``` ## PARAMETERS -### -teardown +### -TearDown -A scriptblock to execute +Receives the completed task as an optional [PsakeTask] argument. ```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ProgressAction - -\{\{ Fill ProgressAction Description \}\} - -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: proga - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Management.Automation.ScriptBlock +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -150,26 +134,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Assert](Assert.mdx) - -[Exec](Exec.mdx) - -[FormatTaskName](FormatTaskName.mdx) - -[Framework](Framework.mdx) - -[Get-PSakeScriptTasks](Get-PSakeScriptTasks.mdx) - -[Include](Include.mdx) - -[Invoke-psake](Invoke-psake.mdx) - -[Properties](Properties.mdx) - -[Task](Task.mdx) - -[TaskSetup](TaskSetup.mdx) - ## VERSION - -*This page was generated using comment-based help in [Psake 4.9.0](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Test-BuildEnvironment.mdx b/docs/commands/Test-BuildEnvironment.mdx new file mode 100644 index 0000000..2430ceb --- /dev/null +++ b/docs/commands/Test-BuildEnvironment.mdx @@ -0,0 +1,184 @@ +--- +id: Test-BuildEnvironment +title: Test-BuildEnvironment +description: Help page for the PowerShell Psake "Test-BuildEnvironment" command +keywords: + - PowerShell + - Psake + - Help + - Documentation +hide_title: false +hide_table_of_contents: false +custom_edit_url: null +--- + +:::info This page was generated +Contributions are welcome in [Psake-repo](https://github.com/psake/psake). +::: + +:::note Since Psake 5.0 +This command was introduced in Psake 5.0 and is not available in earlier versions. +::: + +## SYNOPSIS + +Tests whether the .NET framework required by a build is available on the +current machine. + +## SYNTAX + +### Framework (Default) + +``` +Test-BuildEnvironment [[-Framework] ] [] +``` + +### BuildFile + +``` +Test-BuildEnvironment -BuildFile [] +``` + +## DESCRIPTION + +Resolves the MSBuild and .NET runtime directories for the specified +framework version and checks that every required directory exists. +Returns $true if the environment is ready, $false otherwise. + +The framework to check is determined in order of precedence: + 1. +The -Framework parameter, if supplied. + 2. +The framework declared in -BuildFile, if supplied. + 3. +The active psake build context (if one is on the stack). + 4. +The psake default framework (4.7.2). + +This is useful in Pester specs to skip tests that require a framework +toolchain that is not installed: + + It 'compiles with MSBuild 4.8' \{ + if (-not (Test-BuildEnvironment -Framework '4.8')) \{ + Set-ItResult -Skipped -Because 'Framework 4.8 not available' + \} + # ... +rest of test + \} + + It 'uses the project framework' \{ + if (-not (Test-BuildEnvironment -BuildFile './psakefile.ps1')) \{ + Set-ItResult -Skipped -Because 'Required framework not available' + \} + # ... +rest of test + \} + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +Test-BuildEnvironment -Framework '4.8' +``` + + +Returns $true when MSBuild 17.0 or 16.0 and the v4.0.30319 runtime +directory are both present. + +### EXAMPLE 2 + +```powershell +Test-BuildEnvironment -BuildFile './psakefile.ps1' +``` + + +Loads the build file, reads its Framework setting, and returns $true if +that framework is installed. + +### EXAMPLE 3 + +```powershell +if (-not (Test-BuildEnvironment)) { + Write-Warning "Build environment not ready for current framework" +} +``` + + +Tests the framework configured in the active psake context. + +## PARAMETERS + +### -BuildFile + +Path to a psake build script. +The framework declared in that file is read +and tested. +Ignored when -Framework is also supplied. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: BuildFile + Position: Named + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Framework + +The .NET framework version string to test (e.g. +'4.8', '3.5', '4.7.2x64'). +Takes precedence over -BuildFile and the active context. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: Framework + Position: 0 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +### System.Boolean + +Returns $true if all required framework directories exist; +$false otherwise. + + +### System.Boolean + + +## NOTES + +## RELATED LINKS + +## VERSION +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Test-PsakeTask.mdx b/docs/commands/Test-PsakeTask.mdx new file mode 100644 index 0000000..43e8fa8 --- /dev/null +++ b/docs/commands/Test-PsakeTask.mdx @@ -0,0 +1,147 @@ +--- +id: Test-PsakeTask +title: Test-PsakeTask +description: Help page for the PowerShell Psake "Test-PsakeTask" command +keywords: + - PowerShell + - Psake + - Help + - Documentation +hide_title: false +hide_table_of_contents: false +custom_edit_url: null +--- + +:::info This page was generated +Contributions are welcome in [Psake-repo](https://github.com/psake/psake). +::: + +:::note Since Psake 5.0 +This command was introduced in Psake 5.0 and is not available in earlier versions. +::: + +## SYNOPSIS + +Runs a single task's Action in isolation, without triggering dependencies. + +## SYNTAX + +### __AllParameterSets + +``` +Test-PsakeTask [[-BuildFile] ] [-TaskName] [[-Variables] ] + [] +``` + +## DESCRIPTION + +Compiles the build file, finds the specified task, and executes only its +Action scriptblock with the provided variables. +Dependencies are NOT +executed.This enables unit-testing individual tasks. + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +$result = Test-PsakeTask -BuildFile './psakefile.ps1' -TaskName 'Build' -Variables @{ + Configuration = 'Debug' + OutputDir = './test-output' +} +$result.Success | Should -BeTrue +``` + + +This example runs the 'Build' task from 'psakefile.ps1' with two variables +injected into the task's scope. +The result object contains details about the +execution, including success status, duration, and any error messages. + +## PARAMETERS + +### -BuildFile + +The path to the psake build script. +Defaults to 'psakefile.ps1'. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -TaskName + +The name of the task to execute. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 1 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Variables + +A hashtable of variables to inject into the task's execution scope. + +```yaml +Type: System.Collections.Hashtable +DefaultValue: '@{}' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 2 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +Dependencies, PreAction, and PostAction are skipped — only the +task's Action scriptblock is executed. + + +## RELATED LINKS + +## VERSION +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Version.mdx b/docs/commands/Version.mdx new file mode 100644 index 0000000..5194a31 --- /dev/null +++ b/docs/commands/Version.mdx @@ -0,0 +1,93 @@ +--- +id: Version +title: Version +description: Help page for the PowerShell Psake "Version" command +keywords: + - PowerShell + - Psake + - Help + - Documentation +hide_title: false +hide_table_of_contents: false +custom_edit_url: null +--- + +:::info This page was generated +Contributions are welcome in [Psake-repo](https://github.com/psake/psake). +::: + +:::note Since Psake 5.0 +This command was introduced in Psake 5.0 and is not available in earlier versions. +::: + +## SYNOPSIS + +Declares the required psake version for the build script. + +## SYNTAX + +### __AllParameterSets + +``` +Version [-RequiredVersion] [] +``` + +## DESCRIPTION + +Use this function at the top of a psake build script to declare which +major version of psake the script requires. +The compile phase will validate +that the running psake version matches. + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +Version 5 +``` + + +Declares that this build script requires psake v5. + +## PARAMETERS + +### -RequiredVersion + +The major version number required (e.g. +5). + +```yaml +Type: System.Int32 +DefaultValue: 0 +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +## VERSION +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/docusaurus.sidebar.js b/docs/commands/docusaurus.sidebar.js index 53b0a0f..80a885a 100644 --- a/docs/commands/docusaurus.sidebar.js +++ b/docs/commands/docusaurus.sidebar.js @@ -1,24 +1,27 @@ /** * Import this file in your Docusaurus `sidebars.js` file. * - * Auto-generated by Alt3.Docusaurus.Powershell 1.0.36. - * - * Copyright (c) 2019-present, ALT3 B.V. - * - * Licensed under the MIT license. + * Auto-generated by New-DocusaurusModuleHelp using Microsoft.PowerShell.PlatyPS. */ module.exports = [ 'commands/Assert', - 'commands/Exec', + 'commands/BuildSetup', + 'commands/BuildTearDown', + 'commands/Clear-PsakeCache', + 'commands/Execute', 'commands/FormatTaskName', 'commands/Framework', + 'commands/Get-PsakeBuildPlan', 'commands/Get-PSakeScriptTasks', 'commands/Include', - 'commands/Invoke-psake', + 'commands/Invoke-Psake', 'commands/Invoke-Task', 'commands/Properties', 'commands/Task', 'commands/TaskSetup', - 'commands/TaskTearDown' -]; + 'commands/TaskTearDown', + 'commands/Test-BuildEnvironment', + 'commands/Test-PsakeTask', + 'commands/Version' +]; \ No newline at end of file diff --git a/docs/intro.md b/docs/intro.md index 2424d94..520996f 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -108,6 +108,6 @@ Ready to start using psake? Here's what to do next: 1. **[Install psake](/docs/tutorial-basics/installing)** - Get psake set up on your system 2. **[Run your first build](/docs/tutorial-basics/run-psake)** - Create and execute your first psake script 3. **[Explore the Guides](/docs/tutorial-basics/default-build-files)** - Learn best practices and advanced techniques -4. **[Check the Command Reference](/docs/commands/Invoke-psake)** - Look up specific commands and their parameters +4. **[Check the Command Reference](/docs/commands/Invoke-Psake)** - Look up specific commands and their parameters Need help? Visit our [Troubleshooting](/docs/troubleshooting/common-errors) section or join the [PowerShell Discord](https://aka.ms/psdiscord) #psake channel. diff --git a/docs/psb-commands/docusaurus.sidebar.js b/docs/psb-commands/docusaurus.sidebar.js new file mode 100644 index 0000000..25f6d15 --- /dev/null +++ b/docs/psb-commands/docusaurus.sidebar.js @@ -0,0 +1,8 @@ +/** + * Import this file in your Docusaurus `sidebars.js` file. + * + * Auto-generated by New-PsakeDocusaurusHelp using Microsoft.PowerShell.PlatyPS. + * Run .\build.ps1 -Task GenerateCommandReferencePSB to populate. + */ + +module.exports = []; diff --git a/docs/tutorial-basics/getting-help.md b/docs/tutorial-basics/getting-help.md index 4c851ff..341abbb 100644 --- a/docs/tutorial-basics/getting-help.md +++ b/docs/tutorial-basics/getting-help.md @@ -95,6 +95,6 @@ Found a bug or have a feature request? For comprehensive guides and reference materials: -- **[Command Reference](/docs/commands/Invoke-psake)** - Detailed documentation for all psake commands +- **[Command Reference](/docs/commands/Invoke-Psake)** - Detailed documentation for all psake commands - **[Troubleshooting](/docs/troubleshooting/common-errors)** - Solutions to common problems - **[FAQ](/docs/troubleshooting/faq)** - Frequently asked questions diff --git a/docusaurus.config.ts b/docusaurus.config.ts index dd50cf5..8b417a6 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -143,7 +143,7 @@ const config: Config = { }, { label: 'Command Reference', - to: '/docs/commands/Invoke-psake', + to: '/docs/commands/Invoke-Psake', }, { label: 'Code of Conduct', diff --git a/psakeFile.ps1 b/psakeFile.ps1 index f12a766..44282d0 100644 --- a/psakeFile.ps1 +++ b/psakeFile.ps1 @@ -1,29 +1,24 @@ -#require -Version 7 +#requires -Version 7 +Version 5 + $ErrorView = 'Detailed' -Version 5 Properties { - $script:OutputPath = $null - $script:OutputFormat = 'Nunit' $script:psakeVersion = (Get-Module psake).Version + $script:PowerShellBuildVersion = (Get-Module PowerShellBuild).Version # ----------------------------------------------------------------------------- # Use below settings to manipulate the rendered MDX files # ----------------------------------------------------------------------------- $script:docusaurusOptions = @{ - Module = "Psake" - DocsFolder = "./docs" - SideBar = "commands" - EditUrl = "null" # prevent the `Edit this Page` button from appearing + Module = 'Psake' + DocsFolder = './docs' + SideBar = 'commands' + EditUrl = 'null' # prevent the `Edit this Page` button from appearing Exclude = @() MetaDescription = 'Help page for the PowerShell Psake "%1" command' - MetaKeywords = @( - "PowerShell" - "Psake" - "Help" - "Documentation" - ) + MetaKeywords = @('PowerShell', 'Psake', 'Help', 'Documentation') PrependMarkdown = @" :::info This page was generated Contributions are welcome in [Psake-repo](https://github.com/psake/psake). @@ -33,8 +28,45 @@ Contributions are welcome in [Psake-repo](https://github.com/psake/psake). ## VERSION *This page was generated using comment-based help in [Psake $($psakeVersion)](https://github.com/psake/psake).* "@ + HelpVersion = "$($script:psakeVersion)" + CommandVersionMap = @{ + 'BuildSetup' = '5.0' + 'BuildTearDown' = '5.0' + 'Clear-PsakeCache' = '5.0' + 'Execute' = '5.0' + 'Get-PsakeBuildPlan' = '5.0' + 'Test-BuildEnvironment' = '5.0' + 'Test-PsakeTask' = '5.0' + 'Version' = '5.0' + } + } + $script:docsOutputFolder = Join-Path $docusaurusOptions.DocsFolder $docusaurusOptions.Sidebar | Join-Path -ChildPath '*.*' + + # ----------------------------------------------------------------------------- + # PowerShellBuild command reference options + # ----------------------------------------------------------------------------- + + $script:psbVersion = (Get-Module PowerShellBuild -ListAvailable | Sort-Object Version -Descending | Select-Object -First 1).Version + $script:psbOptions = @{ + Module = 'PowerShellBuild' + DocsFolder = './docs' + SideBar = 'psb-commands' + EditUrl = 'null' + Exclude = @() + MetaDescription = 'Help page for the PowerShellBuild "%1" command' + MetaKeywords = @('PowerShell', 'PowerShellBuild', 'Help', 'Documentation') + PrependMarkdown = @" +:::info This page was generated +Contributions are welcome in [PowerShellBuild-repo](https://github.com/psake/PowerShellBuild). +::: +"@ + AppendMarkdown = @" +## VERSION +*This page was generated using comment-based help in [PowerShellBuild $($psbVersion)](https://github.com/psake/PowerShellBuild).* +"@ + HelpVersion = "$($script:psbVersion)" } - $script:docsOutputFolder = Join-Path -Path $docusaurusOptions.DocsFolder -ChildPath $docusaurusOptions.Sidebar | Join-Path -ChildPath "*.*" + $script:psbOutputFolder = Join-Path $psbOptions.DocsFolder $psbOptions.Sidebar | Join-Path -ChildPath '*.*' } FormatTaskName { @@ -45,103 +77,127 @@ FormatTaskName { Task Default -Depends Build -Task Init -Description "Initial action to setup the further action." -Action { - Exec { bun install } +Task 'Init' @{ + Description = 'Install Node.js dependencies.' + Inputs = @('package.json', 'bun.lock') + Outputs = 'node_modules' + Action = { Exec { bun install } } } -Task Build -Depends Init, GenerateCommandReference, FrontMatterCMSSync { - Exec { bun run build } +Task 'Build' @{ + Description = 'Full production site build.' + DependsOn = @('Init', 'GenerateCommandReference', 'GenerateCommandReferencePSB', 'FrontMatterCMSSync') + Action = { Exec { bun run build } } } -Task Server -Depends Build -Description "Run the docusaurus server." { - Exec { bun run serve } +Task 'Server' @{ + Description = 'Serve the production build locally.' + DependsOn = 'Build' + Action = { Exec { bun run serve } } } -Task Test { - $configuration = New-PesterConfiguration - $configuration.Output.Verbosity = 'Detailed' - $configuration.Run.PassThru = $true - $configuration.Run.Path = "$PSScriptRoot\tests" +Task 'Test' @{ + Description = 'Run Pester tests to validate sidebar links.' + Action = { + Import-Module Pester -MinimumVersion '5.0' -Force + $configuration = New-PesterConfiguration + $configuration.Output.Verbosity = 'Detailed' + $configuration.Run.PassThru = $true + $configuration.Run.Path = "$PSScriptRoot\tests" - try { $testResult = Invoke-Pester -Configuration $configuration -Verbose - } finally { - } - if ($testResult.FailedCount -gt 0) { - throw 'One or more Pester tests failed' + if ($testResult.FailedCount -gt 0) { + throw 'One or more Pester tests failed' + } } } -(Get-Content ".\package.json" | ConvertFrom-Json -AsHashtable).scripts.Keys | ForEach-Object { - $action = [scriptblock]::create("exec { bun run $($_) }") - $taskSplat = @{ - name = "bun_$($_)" - action = $action - depends = @('Init') - description = "Automatic: A script defined in your package.json" +(Get-Content '.\package.json' | ConvertFrom-Json -AsHashtable).scripts.Keys | ForEach-Object { + Task "bun_$($_)" @{ + Action = [scriptblock]::Create("exec { bun run $($_) }") + DependsOn = @('Init') + Description = 'Automatic: A script defined in your package.json' } - Task @taskSplat } #region Command Reference Generation Tasks -# Copied from the amazing Pester team! https://github.com/pester/docs/blob/main/generate-command-reference.ps1 -$taskSplat = @{ - description = "Use Alt3.Docusaurus.Powershell module to generate our reference docs." - depends = 'GenerateCommandReference-Gen' +Task 'GenerateCommandReference' @{ + Description = 'Use Microsoft.PowerShell.PlatyPS to generate command reference docs.' + DependsOn = 'GenerateCommandReference-Gen' } -Task -Name 'GenerateCommandReference' @taskSplat -Task -Name 'GenerateCommandReference-Clean' -Action { - Write-Host "Removing existing MDX files" -ForegroundColor Magenta - if (Test-Path -Path $script:docsOutputFolder) { - Remove-Item -Path $script:docsOutputFolder +Task 'GenerateCommandReference-Clean' @{ + Action = { + Write-Host 'Removing existing MDX files' -ForegroundColor Magenta + if (Test-Path -Path $script:docsOutputFolder) { + Remove-Item -Path $script:docsOutputFolder + } } } -Task -Name "GenerateCommandReference-Gen" -Depends 'GenerateCommandReference-Clean' { - Write-Host "Generating new MDX files" -ForegroundColor Magenta - New-DocusaurusHelp @docusaurusOptions - - # Fix the links - Get-ChildItem $script:docsOutputFolder | ForEach-Object { - $path = $_.FullName - Write-Host "Fixing relative links for: $path" - (Get-Content $path) | ForEach-Object { - $_ -replace "\[(.+)\]\(\)", '[$1]($1.mdx)' - } | Set-Content $path +Task 'GenerateCommandReference-Gen' @{ + DependsOn = 'GenerateCommandReference-Clean' + Action = { + Write-Host 'Generating new MDX files using Microsoft.PowerShell.PlatyPS' -ForegroundColor Magenta + . "$PSScriptRoot\scripts\New-DocusaurusModuleHelp.ps1" + Import-Module Microsoft.PowerShell.PlatyPS -Force + New-DocusaurusModuleHelp @script:docusaurusOptions } } #endregion Command Reference Generation Tasks -#region Sync Front Matter Data -Task -Name 'FrontMatterCMSSync' { - ( - 'blog/authors.yml', - 'blog/tags.yml' - ) | ForEach-Object { - if (-not (Test-Path $_)) { - Write-Warning "File not found: $_" - return +#region PSB Command Reference Generation Tasks +Task 'GenerateCommandReferencePSB' @{ + Description = 'Use Microsoft.PowerShell.PlatyPS to generate PowerShellBuild command reference docs.' + DependsOn = 'GenerateCommandReferencePSB-Gen' + PreCondition = { $null -ne (Get-Module PowerShellBuild -ListAvailable | Select-Object -First 1) } +} + +Task 'GenerateCommandReferencePSB-Clean' @{ + Action = { + Write-Host 'Removing existing PSB MDX files' -ForegroundColor Magenta + if (Test-Path -Path $script:psbOutputFolder) { + Remove-Item -Path $script:psbOutputFolder } - $name = $_ -replace '\.yml$', '.choices.jsonc' - $outputFile = Join-Path -Path $PSScriptRoot -ChildPath (Split-Path -Path $name -Leaf) + } +} - [array]$output = @( - @{ - "_comment" = "This file is auto-generated from $_ via a psake task" +Task 'GenerateCommandReferencePSB-Gen' @{ + DependsOn = 'GenerateCommandReferencePSB-Clean' + Action = { + Write-Host 'Generating new PSB MDX files using Microsoft.PowerShell.PlatyPS' -ForegroundColor Magenta + New-Item -ItemType Directory -Path (Join-Path $psbOptions.DocsFolder $psbOptions.SideBar) -Force | Out-Null + . "$PSScriptRoot\scripts\New-DocusaurusModuleHelp.ps1" + Import-Module Microsoft.PowerShell.PlatyPS -Force + Import-Module PowerShellBuild -Force + New-DocusaurusModuleHelp @script:psbOptions + } +} +#endregion PSB Command Reference Generation Tasks + +#region Sync Front Matter Data +Task 'FrontMatterCMSSync' @{ + Description = 'Sync Docusaurus YAML data to FrontMatter CMS-friendly choices.jsonc files.' + Inputs = @('blog/authors.yml', 'blog/tags.yml') + Outputs = @('authors.choices.jsonc', 'tags.choices.jsonc') + Action = { + @('blog/authors.yml', 'blog/tags.yml') | ForEach-Object { + if (-not (Test-Path $_)) { + Write-Warning "File not found: $_" + return } - ) - $yaml = Get-Content -Raw $_ | ConvertFrom-Yaml - foreach ($item in $yaml.Keys) { - $value = $yaml[$item] - if (-not $value.Contains('handle')) { - $value.Add('handle', $item) + $outputFile = Join-Path $PSScriptRoot (($_ -replace 'blog/', '') -replace '\.yml$', '.choices.jsonc') + + [array]$output = @(@{ '_comment' = "This file is auto-generated from $_ via a psake task" }) + $yaml = Get-Content -Raw $_ | ConvertFrom-Yaml + foreach ($item in $yaml.Keys) { + $value = $yaml[$item] + if (-not $value.Contains('handle')) { $value.Add('handle', $item) } + $output += $value } - $output += $value + Set-Content -Path $outputFile -Force -Value ($output | ConvertTo-Json -Depth 10) } - Set-Content -Path $outputFile -Force -Value ($output | ConvertTo-Json -Depth 10) } - # TODO: Add support to sync back from FrontMatter CMS to authors.json and tags.json -} -Description "Syncs Docusaurus JSON data from authors.json and tags.json to FrontMatter CMS friendly choices.json files." +} #endregion Sync Front Matter Data diff --git a/requirements.psd1 b/requirements.psd1 index ab180c2..e18ec42 100644 --- a/requirements.psd1 +++ b/requirements.psd1 @@ -7,15 +7,16 @@ Parameters = @{ SkipPublisherCheck = $true } + Import = $false } 'psake' = @{ - Version = '5.0.3' + Version = 'latest' } - 'PlatyPS' = @{ - Version = '0.14.2' + 'Microsoft.PowerShell.PlatyPS' = @{ + Version = 'latest' } - 'Alt3.Docusaurus.Powershell' = @{ - Version = '1.0.36' + 'PowerShellBuild' = @{ + Version = 'latest' } 'Yayaml' = @{ Version = '0.6.0' diff --git a/scripts/New-DocusaurusModuleHelp.ps1 b/scripts/New-DocusaurusModuleHelp.ps1 new file mode 100644 index 0000000..9942769 --- /dev/null +++ b/scripts/New-DocusaurusModuleHelp.ps1 @@ -0,0 +1,286 @@ +function New-DocusaurusModuleHelp { + [CmdletBinding()] + param( + [Parameter(Mandatory)] [string] $Module, + [Parameter(Mandatory)] [string] $DocsFolder, + [Parameter(Mandatory)] [string] $SideBar, + [string] $EditUrl = 'null', + [string[]] $Exclude = @(), + [string] $MetaDescription = 'Help page for the PowerShell %1 command', + [string[]] $MetaKeywords = @('PowerShell', 'Help', 'Documentation'), + [string] $PrependMarkdown = '', + [string] $AppendMarkdown = '', + [string] $HelpVersion = '', + [hashtable] $CommandVersionMap = @{} + ) + + if (-not (Get-Module $Module)) { + Import-Module $Module -Force + } + + $tempDir = Join-Path ([System.IO.Path]::GetTempPath()) "platyps_$(Get-Random)" + New-Item -ItemType Directory -Path $tempDir | Out-Null + + try { + New-MarkdownCommandHelp -ModuleInfo (Get-Module $Module) -OutputFolder $tempDir -Force | Out-Null + + $moduleSubDir = Join-Path $tempDir $Module + $mdFiles = Get-ChildItem -Path $moduleSubDir -Filter '*.md' | + Where-Object { $_.BaseName -notin $Exclude } | + Sort-Object BaseName + + $outputFolder = Join-Path $DocsFolder $SideBar + $allCommandNames = $mdFiles | Select-Object -ExpandProperty BaseName + $sidebarItems = [System.Collections.Generic.List[string]]::new() + + foreach ($mdFile in $mdFiles) { + $commandName = $mdFile.BaseName + + $sinceBadge = '' + if ($CommandVersionMap.ContainsKey($commandName)) { + $sinceVersion = $CommandVersionMap[$commandName] + $sinceBadge = @" +:::note Since $Module $sinceVersion +This command was introduced in $Module $sinceVersion and is not available in earlier versions. +::: +"@ + } + + $mdxSplat = @{ + SourceFile = $mdFile + CommandName = $commandName + MetaDescription = $MetaDescription + MetaKeywords = $MetaKeywords + EditUrl = $EditUrl + PrependMarkdown = $PrependMarkdown + AppendMarkdown = $AppendMarkdown + AllCommandNames = $allCommandNames + SinceBadge = $sinceBadge + SideBar = $SideBar + } + $mdxContent = ConvertTo-DocusaurusMdx @mdxSplat + + $outputPath = Join-Path $outputFolder "$commandName.mdx" + Set-Content -Path $outputPath -Value $mdxContent -Encoding UTF8 -NoNewline + Write-Host " Generated: $commandName.mdx" + + $sidebarItems.Add("'$SideBar/$commandName'") + } + + $sidebarEntries = ($sidebarItems | ForEach-Object { " $_" }) -join ",`n" + $sidebarContent = @" +/** + * Import this file in your Docusaurus ``sidebars.js`` file. + * + * Auto-generated by New-DocusaurusModuleHelp using Microsoft.PowerShell.PlatyPS. + */ + +module.exports = [ +$sidebarEntries +]; +"@ + $sidebarPath = Join-Path $outputFolder 'docusaurus.sidebar.js' + Set-Content -Path $sidebarPath -Value $sidebarContent -Encoding UTF8 -NoNewline + Write-Host " Generated: docusaurus.sidebar.js ($($sidebarItems.Count) commands)" + } + finally { + Remove-Item -Path $tempDir -Recurse -Force -ErrorAction SilentlyContinue + } +} + +function ConvertTo-DocusaurusMdx { + param( + [System.IO.FileInfo] $SourceFile, + [string] $CommandName, + [string] $MetaDescription, + [string[]] $MetaKeywords, + [string] $EditUrl, + [string] $PrependMarkdown, + [string] $AppendMarkdown, + [string[]] $AllCommandNames, + [string] $SinceBadge = '', + [string] $SideBar = 'commands' + ) + + $raw = Get-Content -Path $SourceFile.FullName -Raw + + # Strip PlatyPS v2 frontmatter block + $body = $raw -replace '(?s)^---.*?---\s*', '' + + # Strip the H1 title line PlatyPS emits + $body = $body -replace '(?m)^# .+\r?\n', '' + + # Convert markdown parameter tables to yaml fenced blocks + $body = Convert-ParameterTablesToYamlFences -Body $body + + # Wrap example code in powershell fenced blocks. + # PlatyPS v2 outputs example code as plain text; detect the first paragraph of each + # ### EXAMPLE section (before the first blank line) and wrap it. Skip if already fenced. + $body = [System.Text.RegularExpressions.Regex]::Replace( + $body, + '(?m)^(### EXAMPLE [^\r\n]+)\r?\n\r?\n(?!```)([^\r\n][^\r\n]*(?:\r?\n(?!\r?\n)[^\r\n][^\r\n]*)*)', + { + param($m) + $header = $m.Groups[1].Value + $code = $m.Groups[2].Value.TrimEnd() + "$header`n`n``````powershell`n$code`n```````n" + } + ) + + # Fix RELATED LINKS: [Name]() -> [Name](/docs//Name) for known commands, strip unknown + foreach ($cmd in $AllCommandNames) { + $escaped = [regex]::Escape($cmd) + $body = $body -replace "\[$escaped\]\(\)", "[$cmd](/docs/$SideBar/$cmd)" + } + $body = $body -replace '\[([^\]]+)\]\(\)', '$1' + + # Strip PlatyPS placeholder sections before MDX escaping. + # Remove ## ALIASES section when it contains only the "no aliases" placeholder. + $body = $body -replace '(?ms)^## ALIASES\r?\n\r?\nThis cmdlet has the following aliases,\r?\n \{\{Insert list of aliases\}\}\r?\n(\r?\n)?', '' + # Remove the "Fill in the related links here" placeholder (keep real links if any). + $body = $body -replace '\{\{ Fill in the related links here \}\}\r?\n', '' + # Remove "Fill in the Description" placeholders in INPUTS/OUTPUTS sections (PlatyPS generates + # these when .INPUTS/.OUTPUTS CBH is absent; real content on adjacent lines is preserved). + $body = $body -replace '\{\{ Fill in the Description \}\}\r?\n', '' + + # Warn about any remaining {{...}} placeholders — these indicate unfilled CBH fields. + $remainingPlaceholders = [regex]::Matches($body, '\{\{[^}]+\}\}') + if ($remainingPlaceholders.Count -gt 0) { + $unique = $remainingPlaceholders | ForEach-Object { $_.Value } | Sort-Object -Unique + Write-Warning "$CommandName`: unfilled placeholder(s): $($unique -join ', ')" + } + + # Escape curly braces outside code fences (required for MDX/JSX compatibility) + $body = Escape-CurlyBracesOutsideCodeFences -Body $body + + # Build Docusaurus frontmatter + $description = $MetaDescription -replace '%1', $CommandName + $keywordsYaml = ($MetaKeywords | ForEach-Object { " - $_" }) -join "`n" + $customEditUrl = if ($EditUrl -eq 'null') { 'null' } else { "$EditUrl/$CommandName.ps1" } + + $frontmatter = @" +--- +id: $CommandName +title: $CommandName +description: $description +keywords: +$keywordsYaml +hide_title: false +hide_table_of_contents: false +custom_edit_url: $customEditUrl +--- +"@ + + $parts = [System.Collections.Generic.List[string]]::new() + $parts.Add($frontmatter) + if ($PrependMarkdown) { $parts.Add($PrependMarkdown.Trim()) } + if ($SinceBadge) { $parts.Add($SinceBadge.Trim()) } + $parts.Add($body.Trim()) + if ($AppendMarkdown) { $parts.Add($AppendMarkdown.Trim()) } + + return ($parts -join "`n`n") + "`n" +} + +function Convert-ParameterTablesToYamlFences { + param([string] $Body) + + # PlatyPS v2 emits yaml fenced blocks natively (keys: DefaultValue, ParameterSets, etc.) + # These are already renderable — return body unchanged and skip table conversion. + if ($Body -match '(?ms)^```yaml[\r\n]+(?:Type|DefaultValue):') { + return $Body + } + + # PlatyPS v1: convert markdown tables to yaml fences + $result = [System.Text.RegularExpressions.Regex]::Replace( + $Body, + '(?ms)(### -\w[^\r\n]*\r?\n)(.*?)(?=### -|\z)', + { + param($match) + $header = $match.Groups[1].Value + $content = $match.Groups[2].Value + + # Extract description text (everything before the first table row) + $descText = ($content -split '(?m)^\|')[0].TrimEnd() + + # Helper: extract a value from a markdown table row by property name + function Get-TableValue([string]$text, [string]$prop) { + if ($text -match "(?m)^\|\s*$([regex]::Escape($prop))\s*\|\s*([^|]+)\|") { + return $matches[1].Trim() + } + return $null + } + + $type = Get-TableValue $content 'Type:' + $mandatory = Get-TableValue $content 'Mandatory:' + $position = Get-TableValue $content 'Position:' + $default = Get-TableValue $content 'Default value:' + $pipeline = Get-TableValue $content 'Value from pipeline:' + $wildcard = Get-TableValue $content 'Supports wildcards:' + $aliases = Get-TableValue $content 'Aliases:' + + # Strip System. namespace prefix from types + if ($type) { $type = $type -replace '^System\.', '' } else { $type = 'None' } + + $required = if ($mandatory -eq 'True') { 'True' } else { 'False' } + + # v2 position is 0-based; v1 (target) is 1-based + if ($position -and $position -match '^\d+$') { + $position = [int]$position + 1 + } elseif (-not $position) { + $position = 'Named' + } + + if (-not $default) { $default = 'None' } + if (-not $pipeline) { $pipeline = 'False' } + if (-not $wildcard) { $wildcard = 'False' } + if (-not $aliases) { $aliases = '' } + + # Detect parameter sets - look for "Parameter sets" section in the content + $paramSets = '(All)' + if ($content -match '(?ms)Parameter sets\s*\r?\n\|[^\r\n]+\r?\n\|[^\r\n]+\r?\n\|\s*([^|]+)\|') { + $paramSets = $matches[1].Trim() + } + + $yamlFence = @" + +``````yaml +Type: $type +Parameter Sets: $paramSets +Aliases: $aliases + +Required: $required +Position: $position +Default value: $default +Accept pipeline input: $pipeline +Accept wildcard characters: $wildcard +`````` + +"@ + return $header + $descText + $yamlFence + } + ) + + return $result +} + +function Escape-CurlyBracesOutsideCodeFences { + param([string] $Body) + + # Split on fenced code blocks (``` delimiters), alternating outside/inside + $segments = [System.Text.RegularExpressions.Regex]::Split( + $Body, + '((?ms)^```[^\r\n]*\r?\n.*?^```\r?\n?)' + ) + + $result = for ($i = 0; $i -lt $segments.Count; $i++) { + if ($i % 2 -eq 0) { + # Outside a code fence — escape curly braces + $segments[$i] -replace '\{', '\{' -replace '\}', '\}' + } else { + # Inside a code fence — pass through unchanged + $segments[$i] + } + } + + return $result -join '' +} diff --git a/sidebars.ts b/sidebars.ts index 348039c..b23ed87 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -1,5 +1,6 @@ import type { SidebarsConfig } from '@docusaurus/plugin-content-docs'; import commands from "./docs/commands/docusaurus.sidebar.js"; +import psbCommands from "./docs/psb-commands/docusaurus.sidebar.js"; /** * Creating a sidebar enables you to: @@ -87,6 +88,11 @@ const sidebars: SidebarsConfig = { 'powershellbuild/task-reference', 'powershellbuild/configuration', 'powershellbuild/real-world-example', + ...(psbCommands.length > 0 ? [{ + type: 'category' as const, + label: 'Command Reference', + items: psbCommands, + }] : []), ], // Reference - Command reference, troubleshooting, and lookup materials