### Invoke-Build Automatic Bootstrapping

Source: https://github.com/nightroman/invoke-build/blob/main/Tasks/README.md

Covers the process of automatic bootstrapping for the Invoke-Build module. This typically involves ensuring the module is installed and available before build scripts are executed, simplifying setup for users.

```APIDOC
Feature: Automatic Bootstrapping
  Description: Describes the mechanism for automatically installing or ensuring the availability of the Invoke-Build module. This simplifies the initial setup for projects using Invoke-Build, as users may not need to manually install the module.
  Mechanism:
    Often involves a script or command that checks for the module's presence and installs it if necessary, potentially using package managers like PowerShellGet or Paket.
  Usage:
    Typically executed once per environment or project setup.
    Example (conceptual):
      Invoke-Build --bootstrap
  Benefits:
    - Reduces friction for new users.
    - Ensures a consistent build environment.
```

--------------------------------

### Invoke-Build Bootstrapping and Installation

Source: https://github.com/nightroman/invoke-build/blob/main/Tasks/Bootstrap/README.md

This PowerShell script demonstrates how to bootstrap Invoke-Build. It checks if the Invoke-Build module is installed and installs it if necessary, then executes the build tasks. This ensures the build environment is set up correctly before running build tasks.

```powershell
param(
    [Parameter(Position=0)]
    [string[]]$Tasks,
    #... other script parameters
)

# bootstrap
if (!$MyInvocation.ScriptName.EndsWith('Invoke-Build.ps1')) {
    $ErrorActionPreference = 1
    if (!(Get-Command Invoke-Build -ErrorAction 0)) {
        Write-Host InvokeBuild installing...
        Install-Module InvokeBuild -Scope CurrentUser -Force
        Import-Module InvokeBuild
    }
    return Invoke-Build $Tasks $MyInvocation.MyCommand.Path @PSBoundParameters
}

# the usual build script
task ...
```

--------------------------------

### Hello World Example

Source: https://github.com/nightroman/invoke-build/wiki/Script-Tutorial

A basic example demonstrating the 'Hello World' task in Invoke-Build. This task simply outputs the string 'Hello, World!'. It shows how to define a task and how Invoke-Build executes it.

```powershell
task Hello {
    'Hello, World!'
}
```

--------------------------------

### Install Paket and Add to Manifest

Source: https://github.com/nightroman/invoke-build/blob/main/Tasks/Paket/README.md

This command installs the paket tool and adds it to the local dotnet tool manifest.

```bash
dotnet tool install paket
```

--------------------------------

### Invoke-Build Execution Examples

Source: https://github.com/nightroman/invoke-build/blob/main/Tasks/SubCases/README.md

Provides examples of how to execute Invoke-Build with different parameters to target specific cases and configurations.

```powershell
# case1, default task with default parameters
Invoke-Build -Case case1

# case2, common task with custom parameters
Invoke-Build root1 -Case case2 -Configuration Debug
```

--------------------------------

### Install and Update Show-BuildGraph

Source: https://github.com/nightroman/invoke-build/wiki/Show-Build-Graph

Demonstrates how to install and update the Show-BuildGraph script from the PowerShell Gallery.

```powershell
Install-Script Show-BuildGraph
Update-Script Show-BuildGraph
```

--------------------------------

### Install Invoke-Build as .NET Tool

Source: https://github.com/nightroman/invoke-build/blob/main/README.md

Instructions for installing the Invoke-Build .NET tool globally or locally. This involves using the `dotnet tool install` command. For local installation, a tool manifest must be created first.

```bash
dotnet tool install --global ib
```

```bash
dotnet new tool-manifest
dotnet tool install --local ib
```

--------------------------------

### Install Invoke-Build .NET Global Tool

Source: https://github.com/nightroman/invoke-build/blob/main/ib/README.md

Installs the Invoke-Build .NET tool globally, making the 'ib' command available system-wide.

```bash
dotnet tool install --global ib
```

--------------------------------

### Getting Help for InvokeBuild

Source: https://github.com/nightroman/invoke-build/blob/main/InvokeBuild/about_InvokeBuild.help.txt

Provides instructions on how to access help documentation for the InvokeBuild engine and its associated commands and tasks.

```powershell
help <path>\Invoke-Build.ps1 -full
```

```powershell
. <path>\Invoke-Build.ps1
help task -full
help exec -full
```

--------------------------------

### Initialization with Enter-Build

Source: https://github.com/nightroman/invoke-build/wiki/Build-Scripts-Guidelines

Demonstrates using the Enter-Build block for script initialization, which is executed before any tasks. This is useful for setup operations that should occur once at the beginning of the build process.

```powershell
Enter-Build {
    'Prepare for tasks...'
}

task Task1 {
    'Doing Task1...'
}
```

--------------------------------

### Invoke-Build Dynamic Parameters Example

Source: https://github.com/nightroman/invoke-build/wiki/V2-Release-Notes

Demonstrates the new dynamic parameter syntax for Invoke-Build, simplifying command-line arguments for build configurations and platforms.

```powershell
Invoke-Build -Configuration Release -Platform x64
```

```powershell
Invoke-Build -Parameters @{Configuration = 'Release'; Platform = 'x64'}
```

--------------------------------

### Install Invoke-Build Module

Source: https://github.com/nightroman/invoke-build/blob/main/README.md

Installs the Invoke-Build module from the PowerShell Gallery. This is the recommended way to install and use Invoke-Build.

```powershell
Install-Module InvokeBuild
```

--------------------------------

### Invoke-Build Build Script with Paket Integration

Source: https://github.com/nightroman/invoke-build/blob/main/Tasks/README.md

Demonstrates how to create an Invoke-Build script that integrates with Paket for automatic bootstrapping. This implies using Paket to manage dependencies required for the build process itself.

```APIDOC
Feature: Paket Integration for Bootstrapping
  Description: Shows how to configure an Invoke-Build project to use Paket for automatically bootstrapping dependencies required by the build process. This ensures that all necessary tools and libraries are available before the build starts.
  Mechanism:
    Typically involves a `paket.dependencies` file and potentially a `build.fsx` or `build.ps1` script that invokes Paket commands to restore dependencies.
  Usage:
    1. Define dependencies in `paket.dependencies`.
    2. Ensure Paket is installed or bootstrapped.
    3. In the build script (e.g., `build.ps1`):
       `paket install`
       `Invoke-Build ...`
  Benefits:
    - Robust dependency management for the build environment.
    - Ensures consistency across different development and CI/CD environments.
```

--------------------------------

### Invoke-Build Task Ordering Example

Source: https://github.com/nightroman/invoke-build/wiki/V2-Release-Notes

Demonstrates the fix for task ordering in Invoke-Build, specifically how '-After' and '-Before' tasks are handled. This example illustrates the expected task reference order after preprocessing.

```PowerShell
task Task1
task After -After Task1
task Before -Before Task1
```

--------------------------------

### Invoke-Build .build.ps1 Script Examples

Source: https://github.com/nightroman/invoke-build/wiki/Build-Scripts-in-Projects

Examples of .build.ps1 scripts used in various PowerShell projects. These scripts automate tasks such as cleaning, testing, building help files, converting markdown to HTML, and creating packages.

```PowerShell
# Example from Helps/.build.ps1
# Clean the project directory
# Run tests and compare results with expected
# Build the help file (PowerShell MAML format)
# Convert markdown files to HTML for packages
# Create packages
```

```PowerShell
# Example from PowerShellTraps/.build.ps1
# Build script for testing, generating the index, and other routine tasks.
```

```PowerShell
# Example from PSReadline.build.ps1
# A bash inspired readline implementation for PowerShell.
```

```PowerShell
# Example from vscode-powershell.build.ps1
# PowerShell extension for Visual Studio Code.
```

```PowerShell
# Example from PowerShellEditorServices.build.ps1
# A common platform for PowerShell development support in any editor or application.
```

```PowerShell
# Example from pipeline.build.ps1 (PSRule)
# Validate infrastructure as code (IaC) and objects using PowerShell rules.
```

```PowerShell
# Example from pode.build.ps1 (Pode)
# PowerShell web framework for creating REST APIs, Web Sites, and TCP/SMTP servers.
```

```PowerShell
# Example from JiraPS.build.ps1 (JiraPS)
# PowerShell module to interact with Atlassian JIRA.
```

```PowerShell
# Example from build-script-template/build.ps1 (red-gate)
# Build script template.
```

```PowerShell
# Example from XmlDoc2CmdletDoc/build.ps1 (red-gate)
# Build script for XmlDoc2CmdletDoc.
```

```PowerShell
# Example from zloeber/FormatPowershellCode/.build.ps1
# Puts together a lot of typical project tasks with complex relations.
```

```PowerShell
# Example from PSCodeHealth.build.ps1
# PowerShell module gathering PowerShell code quality and maintainability metrics.
```

--------------------------------

### Initialization with $WhatIf

Source: https://github.com/nightroman/invoke-build/wiki/Build-Scripts-Guidelines

Shows how to conditionally execute initialization code based on the $WhatIf build variable. If $WhatIf is false, the initialization block runs, allowing for dynamic setup.

```powershell
if (!$WhatIf) {
    'Prepare for tasks...'
}

task Task1 {
    'Doing Task1...'
}
```

--------------------------------

### red-gate/build-script-template - Example Build Script

Source: https://github.com/nightroman/invoke-build/wiki/Related-Projects

This repository provides an example template for a PowerShell build script that utilizes Invoke-Build. The script handles dependency gathering, versioning, compilation, testing, and packaging.

```PowerShell
# build.ps1 - Main build script
# This script orchestrates the entire build process using Invoke-Build.

# Load Invoke-Build module
# Add-Type -Path "$PSScriptRoot\InvokeBuild\InvokeBuild.psm1"

# Define tasks
Function Invoke-Task-Clean {
    Write-Host "Cleaning build artifacts..."
    # Add clean logic here
}

Function Invoke-Task-Build {
    Write-Host "Compiling project..."
    # Add build logic here
}

Function Invoke-Task-Test {
    Write-Host "Running tests..."
    # Add test logic here
}

# Entry point script (build_init.ps1)
# This script defines the entry points for PowerShell commands.
# It typically calls the main build.ps1 script.
# Example: .uild_init.ps1 -Task Build
```

--------------------------------

### Realistic Build Example

Source: https://github.com/nightroman/invoke-build/wiki/Script-Tutorial

A more comprehensive example showcasing three tasks: 'Build' for compiling a C# project using MSBuild, 'Clean' for removing temporary files, and '.' as a default task that orchestrates 'Build' and 'Clean'. It highlights the 'use', 'exec', and 'remove' aliases.

```powershell
use 15.0x86 MSBuild

# Synopsis: Build the project.
task Build {
    exec { MSBuild Project.csproj /t:Build /p:Configuration=Release }
}

# Synopsis: Remove temp files.
task Clean {
    remove bin, obj
}

# Synopsis: Build and clean.
task . Build, Clean
```

--------------------------------

### Invoke-Build Module Installation

Source: https://github.com/nightroman/invoke-build/wiki/Design-Notes

Shows how to install Invoke-Build as a PowerShell module using PowerShellGet. This is the recommended method for PowerShell 5.0 and later.

```powershell
Install-Module InvokeBuild
```

--------------------------------

### Build Parameters Example

Source: https://github.com/nightroman/invoke-build/blob/main/Tasks/SubCases/README.md

Defines mandatory and optional parameters for an Invoke-Build script, illustrating how to handle case selection and configuration.

```powershell
param(
    [Parameter(Mandatory=1)]
    [string]$Case
    ,
    [string]$Configuration = 'Release'
)
```

--------------------------------

### Install Invoke-Build Argument Completers

Source: https://github.com/nightroman/invoke-build/wiki/Argument-Completers

Installs the Invoke-Build argument completers script from the PowerShell Gallery. This allows for enhanced code completion within PowerShell sessions.

```powershell
Install-Script Invoke-Build.ArgumentCompleters
```

--------------------------------

### Full Example: Markdown to HTML Conversion

Source: https://github.com/nightroman/invoke-build/wiki/Partial-Incremental-Tasks

A complete example of a partial incremental task that converts Markdown files (`.md`, `.markdown`) to HTML files (`.htm`) using `pandoc.exe`. It demonstrates the use of the alternative task syntax with a hashtable for parameters.

```powershell
# Synopsis: Converts *.md and *.markdown files to *.htm
task ConvertMarkdown @{
    Partial = $true
    Inputs = {
        Get-Item *.md, *.markdown
    }
    Outputs = {
        process{
            [System.IO.Path]::ChangeExtension($_, 'htm')
        }
    }
    Jobs = {
        process{
            exec { pandoc.exe $_ --standalone --quiet --from=gfm "--output=$2" }
        }
    }
}
```

--------------------------------

### Invoke-Build Task Condition and Targets Example

Source: https://github.com/nightroman/invoke-build/wiki/Comparison-with-MSBuild

Demonstrates the behavior of Invoke-Build's `-After` and `-Before` parameters with the `-If` condition, contrasting it with MSBuild's behavior.

```powershell
# script 1
task Task1 {...}
task Task2 -If {...} Task1, {...}

# script 2
task Task1 -Before Task2 {...}
task Task2 -If {...} {...}
```

--------------------------------

### Invoke-Build Sharing and Importing Tasks

Source: https://github.com/nightroman/invoke-build/blob/main/Tasks/README.md

Explains the mechanism for sharing and importing tasks from external task scripts and modules in Invoke-Build. This promotes modularity and reusability of build logic.

```APIDOC
Feature: Sharing and Importing Tasks
  Description: Describes how to define tasks in separate scripts and import them into other build scripts or modules. This facilitates code reuse and organization of build logic.
  Mechanism:
    - Dot-sourcing (`. 'path/to/tasks.ps1'`) to load tasks from external files.
    - Importing tasks from installed PowerShell modules.
  Usage:
    # Import tasks from a file:
    . "./tasks/common-tasks.ps1"
    # Import tasks from a module:
    Import-Module MyBuildTasks
  Benefits:
    - Encourages modular design of build processes.
    - Allows teams to share common build tasks.
    - Simplifies maintenance by centralizing task definitions.
```

--------------------------------

### Invoke-Build Parameterized Tasks

Source: https://github.com/nightroman/invoke-build/blob/main/Tasks/README.md

Explains how to create tasks in Invoke-Build that accept parameters. This allows tasks to perform similar actions with variations defined by input values, promoting flexibility and reducing code duplication.

```APIDOC
Feature: Parameterized Tasks
  Description: Describes how to define tasks in Invoke-Build that accept parameters. This allows for reusable tasks that can be customized at runtime with different values.
  Syntax:
    task "task-with-params" -Parameters @{
        "Param1" = "DefaultValue1"
        "Param2" = "DefaultValue2"
    } {
        param($Param1, $Param2)
        Write-Host "Param1: $Param1"
        Write-Host "Param2: $Param2"
    }
  Usage:
    Invoke-Build -Task "task-with-params" -Parameters @{"Param1" = "CustomValue1"}
  Benefits:
    - Increases task reusability.
    - Reduces the need for multiple similar tasks.
    - Enhances flexibility in build configurations.
```

--------------------------------

### Full Incremental Task Example (Powershell)

Source: https://github.com/nightroman/invoke-build/wiki/Incremental-Tasks

A complete example of an incremental task in Invoke-Build that compiles C# files into a Library.dll. It demonstrates the use of 'use' for compiler version and the task definition with inputs, outputs, and the build script.

```powershell
# Use the .NET 4.0 compiler
use 4.0 csc

# Build the Library.dll if it is missing or out-of-date
task Build -Inputs { Get-Item *.cs } -Outputs Library.dll {
    exec { csc /optimize /target:library /out:Library.dll *.cs }
}
```

--------------------------------

### Invoke-Build Inline Build Assembly

Source: https://github.com/nightroman/invoke-build/blob/main/Tasks/README.md

Covers the technique of assembling an entire build inline as a script block within Invoke-Build, without needing separate script files. This is useful for simple or self-contained build processes.

```APIDOC
Feature: Inline Build Assembly
  Description: Allows the definition of an entire build process within a single script block, without requiring separate `.ps1` files for tasks. This is suitable for simpler or self-contained build definitions.
  Usage:
    Invoke-Build -ScriptBlock @"`n    task "hello" { Write-Host "Hello, World!" }`n    task "goodbye" { Write-Host "Goodbye!" }`n    "@ -Task "hello"
  Parameters:
    ScriptBlock: A string containing the PowerShell script defining the tasks.
  Benefits:
    - Simplifies the creation of small, self-contained build scripts.
    - Useful for examples or quick build tasks.
```

--------------------------------

### Create Dotnet Tool Manifest

Source: https://github.com/nightroman/invoke-build/blob/main/Tasks/Paket/README.md

This command creates a new dotnet tool manifest file, which is used to manage local tool installations.

```bash
dotnet new tool-manifest
```

--------------------------------

### Add Before/After Tasks to Build Script

Source: https://github.com/nightroman/invoke-build/blob/main/Tasks/Inline/README.md

This script block demonstrates how to add tasks that run before and after the main build process using Invoke-Build. It utilizes the 'Before' and 'After' methods to define these tasks.

```powershell
# app1.ps1

# Add tasks to run before the build
Before(InvokeBuild, { Write-Host "Starting build..." })

# Add tasks to run after the build
After(InvokeBuild, { Write-Host "Build finished." })

# Invoke the build process
InvokeBuild
```

--------------------------------

### Importing the InvokeBuild Module

Source: https://github.com/nightroman/invoke-build/blob/main/InvokeBuild/about_InvokeBuild.help.txt

Demonstrates how to import the InvokeBuild module into a PowerShell session, either from the installed location or a specific directory.

```powershell
Import-Module InvokeBuild
```

```powershell
Import-Module <path>\InvokeBuild.psd1
```

--------------------------------

### Save Invoke-Build Argument Completers

Source: https://github.com/nightroman/invoke-build/wiki/Argument-Completers

Downloads the Invoke-Build argument completers script to a specified local path. This is an alternative to installing from the PowerShell Gallery.

```powershell
Save-Script Invoke-Build.ArgumentCompleters -Path .
```

--------------------------------

### Invoke-Build Dynamic Script with Dynamic Tasks

Source: https://github.com/nightroman/invoke-build/blob/main/Tasks/README.md

Covers the concept of using dynamic scripts and dynamic tasks within Invoke-Build. This implies the ability to generate or modify build logic at runtime, offering high flexibility.

```APIDOC
Feature: Dynamic Scripts and Tasks
  Description: Explains how to create and execute build logic dynamically within Invoke-Build. This involves generating script content or task definitions at runtime based on certain conditions or data.
  Techniques:
    - Using PowerShell's `Invoke-Expression` or script blocks to build and execute code dynamically.
    - Programmatically defining tasks based on configuration files, environment variables, or other inputs.
  Usage Example (Conceptual):
    $taskName = "dynamic-task-$((Get-Date).Ticks)"
    $scriptContent = "task '$taskName' { Write-Host 'This task was generated dynamically!' }"
    Invoke-Expression $scriptContent
    Invoke-Build -Task $taskName
  Benefits:
    - High degree of flexibility in defining build processes.
    - Ability to adapt build logic based on runtime conditions.
```

--------------------------------

### Create and Invoke Test Tasks

Source: https://github.com/nightroman/invoke-build/blob/main/Tasks/Inline/README.md

This script block illustrates how to create and invoke test tasks within an Invoke-Build script. It's useful for setting up and running tests as part of the build process.

```powershell
# app3.ps1

# Define a test task
New-BuildTask -Name "RunTests" -ScriptBlock {
    Write-Host "Executing tests..."
    # Add your test execution commands here
}

# Invoke the test task
InvokeBuild -Task "RunTests"
```

--------------------------------

### Invoke-Build Custom Task: Check

Source: https://github.com/nightroman/invoke-build/blob/main/Tasks/README.md

Demonstrates the custom task 'check' in Invoke-Build, which executes only once even when a build (like 'check list') is invoked multiple times. This is useful for setup or initialization tasks that should not be repeated within a single build session.

```APIDOC
Custom Task: check
  Description: Executes a task only once per build session, even if the build is invoked multiple times.
  Usage:
    Invoke-Build -Task check
    Invoke-Build -Task "check list"
  Parameters:
    None explicitly mentioned, but implies internal state management by Invoke-Build.
  Example Scenario:
    Useful for tasks like setting up a temporary directory or initializing a connection that should only happen at the start of a build.
```

--------------------------------

### Set-BuildHeader and Set-BuildFooter Help

Source: https://github.com/nightroman/invoke-build/blob/main/Release-Notes.md

Adds help documentation for the Set-BuildHeader and Set-BuildFooter commands.

```powershell
Get-Help Set-BuildHeader
Get-Help Set-BuildFooter
```

--------------------------------

### Example 'check list' Build Script

Source: https://github.com/nightroman/invoke-build/blob/main/Tasks/Check/README.md

This snippet provides an example of a build script 'Check.build.ps1' that utilizes the custom 'check' task. It demonstrates how a build script might invoke this task as part of its execution flow.

```powershell
param($context)

# Invoke the custom check task
Invoke-Task -Name 'check' -Context $context

# Other build steps
Write-Host "Running other build steps..."
```

--------------------------------

### Resolve-MSBuild Path Resolution Logic

Source: https://github.com/nightroman/invoke-build/wiki/DEV-Public-Functions

Illustrates the logic used by Resolve-MSBuild to determine MSBuild installation folders based on the Visual Studio version and whether a prerelease version is installed. It handles different versioning schemes and installation paths.

```PowerShell
$folders = switch($Version) {
    * {if ($Prerelease) {'2019\Preview\*', 'Preview\*'} else {'2019\*', '2017\*'} }
    '16.0' {if ($Prerelease) {'2019\Preview\*'} else {'2019\*'} }
    default {if ($Prerelease) {'Preview\*'} else {'2017\*'} }
}
```

--------------------------------

### Task Discovery and Preview

Source: https://github.com/nightroman/invoke-build/wiki/Concepts

Demonstrates how to discover available tasks and preview their execution using Invoke-Build's command-line interface. This helps in understanding the build process and potential side effects.

```powershell
Invoke-Build ?
Invoke-Build ... -WhatIf
```

--------------------------------

### Invoke-Build CLI Usage and Help

Source: https://github.com/nightroman/invoke-build/blob/main/ib/README.md

Demonstrates how to invoke the Invoke-Build command-line tool and access its help documentation. Includes options for showing general help, task-specific help, and running with PowerShell.

```bash
ib -h|--help
ib -h|--help task|exec|assert|...
ib -?
ib /?
ib [--pwsh] [arguments]
```

--------------------------------

### Initialize Paket Dependencies

Source: https://github.com/nightroman/invoke-build/blob/main/Tasks/Paket/README.md

This command initializes a new paket file named 'paket.dependencies' for managing project dependencies.

```bash
dotnet paket init
```

--------------------------------

### Install Invoke-Build with Chocolatey

Source: https://github.com/nightroman/invoke-build/blob/main/README.md

Installs the Invoke-Build package using the Chocolatey package manager. Note that the Chocolatey package is maintained by its owner.

```powershell
choco install invoke-build
```

--------------------------------

### Executing Directly Invokable Build Scripts

Source: https://github.com/nightroman/invoke-build/blob/main/Tasks/Direct-2/README.md

Provides examples of how to execute a directly invokable build script. Demonstrates running all tasks, passing script parameters, and displaying task descriptions.

```powershell
# run all tasks (because $Tasks default is set to '*')
./Build.ps1

# run with parameters
./Build.ps1 -Param1 testing

# run specified tasks
./Build.ps1 ScriptParameters, ScriptVariables

# show task descriptions
./Build.ps1 ?
```

--------------------------------

### Basic Usage of Visualization Scripts

Source: https://github.com/nightroman/invoke-build/wiki/Show-Build-Graph

Shows the basic commands to generate and display build graphs using Show-BuildGraph and Show-BuildMermaid.

```powershell
Show-BuildGraph
Show-BuildMermaid
```

--------------------------------

### Install Invoke-Build .NET Local Tool

Source: https://github.com/nightroman/invoke-build/blob/main/ib/README.md

Installs the Invoke-Build .NET tool locally within a project's manifest. This is useful for project-specific tool management.

```bash
dotnet new tool-manifest
dotnet tool install --local ib
```

--------------------------------

### Install Invoke-Build with Scoop

Source: https://github.com/nightroman/invoke-build/blob/main/README.md

Installs the Invoke-Build package using the Scoop package manager. This command downloads the scripts and adds their directory to the system's PATH.

```powershell
scoop install invoke-build
```

--------------------------------

### Improved product selection logic in `Resolve-MSBuild`

Source: https://github.com/nightroman/invoke-build/blob/main/Release-Notes.md

Enhances the product selection logic within `Resolve-MSBuild` to better handle various MSBuild installations, referencing issue #77. Users of the `VSSetup` module should ensure it supports `-Product *`.

```PowerShell
# Improved product selection logic in `Resolve-MSBuild` (#77).
# If you use the module `VSSetup` make sure it is not too old.
# It should support `-Product *`.
```

--------------------------------

### Custom Task 'retry' Example

Source: https://github.com/nightroman/invoke-build/wiki/V2-Release-Notes

Demonstrates a custom task 'retry' that allows tasks to be retried with configurable timeouts and intervals. The underlying function 'Invoke-RetryAction' can be used independently, as shown in the 'Retry.build.ps1' example.

```powershell
# Sample custom task 'retry'
# Special parameters: RetryTimeout, RetryInterval
# ... implementation details ...
```

--------------------------------

### Demo Case Tasks/Steps

Source: https://github.com/nightroman/invoke-build/blob/main/Release-Notes.md

A new demo case named 'Tasks/Steps' has been added, likely showcasing a specific build workflow or feature.

```PowerShell
# New demo case [Tasks/Steps](https://github.com/nightroman/Invoke-Build/tree/main/Tasks/Steps).
```

--------------------------------

### Build Script Example (Powershell)

Source: https://github.com/nightroman/invoke-build/wiki/Incremental-Tasks

Provides an example of the script block within an Invoke-Build task that generates output files from input files. It utilizes automatic variables like $Inputs and $Outputs.

```powershell
{
    exec { csc /optimize /target:library /out:Library.dll *.cs }
}
```

--------------------------------

### Custom Task 'file' Example

Source: https://github.com/nightroman/invoke-build/wiki/V2-Release-Notes

Provides a sample custom task named 'file' that demonstrates rake-like functionality and examples of incremental tasks. This task is intended as a utility and showcases how to implement custom build logic.

```powershell
# Sample custom task 'file'
# ... implementation details ...
```

--------------------------------

### Invoke-Build Engine Differences

Source: https://github.com/nightroman/invoke-build/wiki/Comparison-with-psake

Details the core engine differences between Invoke-Build and other build tools, highlighting its script-based nature, parameter handling, state management, and support for incremental, parallel, and persistent builds.

```PowerShell
# Invoke-Build is implemented as a script, not a module function.
# Tasks naturally share build script parameters, variables, functions, and aliases.
# Build script parameters are defined using the usual `param` syntax.
# Invoke-Build maintains its state in its script scope, and all data and service functions are gone when a build completes.
# Supports incremental tasks with inputs processed or skipped based on timestamps.
# Supports parallel builds in the same process using *Build-Parallel*.
# Supports persistent builds for long running or interactive processes with expected interruptions.
# Can invoke all tasks (`*`) and all tasks in all `*.test.ps1` files (`**`).
# Can optionally return result tasks, errors, warnings, and other details about the current and nested builds.
# Resolves default tasks and scripts differently ('.' task, first `*.build.ps1`).
# Does not use a single *Framework*; uses `use` command to create aliases for various tools.
# Allows task redefinitions with messages about each case.
# Replaces `TaskSetup` and `TaskTearDown` with `Enter-*` and `Exit-*`.
# Custom task headers and footers defined by `Set-BuildHeader` and `Set-BuildFooters`.
# Hides its variables from user code.
# Allows definition of new tasks with specific features and new parameters (e.g., `check`, `repeat`, `retry`).
```

--------------------------------

### Starting Persistent Builds

Source: https://github.com/nightroman/invoke-build/wiki/Persistent-Builds

Starts a persistent build by specifying a checkpoint file. The file is updated after each successful task and deleted on overall success. If the build fails or is interrupted, the checkpoint file is preserved for resuming.

```powershell
# with the default task and script
Build-Checkpoint temp.clixml

# with the specified tasks and script
Build-Checkpoint temp.clixml @{Task = 'Build', 'Clean'; File = '../Project.build.ps1'}
```

--------------------------------

### Custom Attributes with Init and Kill in Invoke-Build

Source: https://github.com/nightroman/invoke-build/blob/main/Tasks/Attributes/README.md

This example defines custom attributes with 'Init' and 'Kill' methods and applies them to a task action job. The build blocks 'Enter-BuildJob' and 'Exit-BuildJob' are used to retrieve these attributes and invoke their custom actions, simulating resource initialization and disposal.

```powershell
# Requires PowerShell v5+ and Invoke-Build v5.8.4+

# Define custom attributes with Init and Kill methods
[AttributeUsage(AttributeTargets.Method)]
class InitKillAttribute : Attribute {
    [string]$ResourceName

    InitKillAttribute([string]$resourceName) {
        $this.ResourceName = $resourceName
    }

    [void]Init() {
        Write-Host "Initializing resource: $($this.ResourceName)"
        # Simulate resource initialization
    }

    [void]Kill() {
        Write-Host "Disposing resource: $($this.ResourceName)"
        # Simulate resource disposal
    }
}

# Define a task that uses the custom attributes
function Task-CustomActions {
    [InitKill('Foo1')]
    [InitKill('Foo2')]
    param() 
    
    # Task logic here
    Write-Host "Executing task with custom actions."
}

# Build blocks to manage custom actions
function Enter-BuildJob {
    param(
        [Parameter(Mandatory=$true)]
        [InvokeBuild.BuildJob]$BuildJob
    )

    $buildJob.Attributes | ForEach-Object {
        if ($_ -is [InitKillAttribute]) {
            $_.Init()
        }
    }
}

function Exit-BuildJob {
    param(
        [Parameter(Mandatory=$true)]
        [InvokeBuild.BuildJob]$BuildJob
    )

    $buildJob.Attributes | ForEach-Object {
        if ($_ -is [InitKillAttribute]) {
            $_.Kill()
        }
    }
}

# Example of how to run this with Invoke-Build (assuming this is in a build.ps1 file)
# Invoke-Build -Task Task-CustomActions
```

--------------------------------

### Custom Task Headers and Footers Example

Source: https://github.com/nightroman/invoke-build/blob/main/Tasks/Header/README.md

This snippet demonstrates how to set custom headers and footers for tasks in Invoke-Build. It utilizes `Set-BuildHeader` and `Set-BuildFooter` to include task synopses and locations, providing more context during the build process. The example also shows how these settings are inherited by called scripts.

```powershell
# Example of setting custom headers and footers in Invoke-Build

# Define a task with a synopsis
# Synopsis: This is a sample task
function MyTask {
    Write-Host "Executing MyTask..."
    Start-Sleep -Seconds 1
}

# Set custom header format to include synopsis and location
Set-BuildHeader -Format @(
    "Task `"$($Task.Name)`" - $($Task.Synopsis)",
    "Location: $($Task.Location)"
)

# Set custom footer format to include elapsed time
Set-BuildFooter -Format @(
    "Done `"$($Task.Name)`" - Elapsed: $($Task.ElapsedTime.TotalSeconds)s"
)

# Register the task
Register-BuildTask -Name "MySampleTask" -ScriptBlock { MyTask }

# Example of calling another script that inherits headers/footers
# .path	oanotheruild.ps1
```

--------------------------------

### Invoke-Build Task Listing Details

Source: https://github.com/nightroman/invoke-build/wiki/V2-Release-Notes

Describes enhancements to task listings, including logging task starts with 'Task X:'.

```powershell
Task X:
```

--------------------------------

### Build Graph Tooltips

Source: https://github.com/nightroman/invoke-build/blob/main/Release-Notes.md

Enhancements to Show-BuildGraph.ps1 to display node and edge tooltips, including synopses and names, for better graph visualization.

```PowerShell
# `Show-BuildGraph.ps1`
# - shows node and edge tooltips (synopses, names)
```

--------------------------------

### Show-TaskHelp.ps1 Input/Output Processing

Source: https://github.com/nightroman/invoke-build/blob/main/Release-Notes.md

Enhances Show-TaskHelp.ps1 to process 'Inputs', 'Outputs', 'If', and 'Jobs' sections for more comprehensive task help.

```powershell
Show-TaskHelp -Task "MyTask"
```

--------------------------------

### VSCode Keybindings Configuration

Source: https://github.com/nightroman/invoke-build/wiki/Generate-VSCode-Tasks

Example of how to configure custom keyboard shortcuts in VSCode's keybindings.json to run specific tasks.

```json
{
    "key": "ctrl+k k",
    "command": "workbench.action.tasks.runTask"
}

```

--------------------------------

### Use-BuildEnv Helper Function

Source: https://github.com/nightroman/invoke-build/blob/main/Release-Notes.md

Introduction of a new helper function, Use-BuildEnv, likely for managing and setting up the build environment.

```PowerShell
# New helper function `Use-BuildEnv`.
```

--------------------------------

### Confirm-Build Helper

Source: https://github.com/nightroman/invoke-build/blob/main/Release-Notes.md

Introduces the Confirm-Build helper script for build processes, replacing the older Ask script. See Tasks/Confirm for a demo.

```powershell
Confirm-Build -Message "Are you sure you want to proceed?"
```

--------------------------------

### Invoke-Build Reserved Names

Source: https://github.com/nightroman/invoke-build/wiki/V2-Release-Notes

Functions and variables starting with `*` are reserved for the Invoke-Build engine. Scripts should avoid using names with this prefix to prevent conflicts.

```PowerShell
# Avoid using function or variable names starting with '*'.
# Example of reserved naming convention:
# *InternalFunction
# *BuildState
```

--------------------------------

### Get Invoke-Build Task Information

Source: https://github.com/nightroman/invoke-build/wiki/VSCode-Tips

Retrieves information about available tasks within an Invoke-Build project. This command is executed in the PowerShell terminal.

```powershell
ib ?
```

--------------------------------

### PowerShell Alias for Invoke-Build

Source: https://github.com/nightroman/invoke-build/blob/main/ib/README.md

Shows how to create a PowerShell alias 'ib' to easily invoke Invoke-Build, either when installed as a module or as scripts.

```powershell
# installed as module
Set-Alias ib Invoke-Build

# installed as scripts
Set-Alias ib .../Invoke-Build.ps1
```

--------------------------------

### Show Build Graph Commands

Source: https://github.com/nightroman/invoke-build/wiki/Building-FarNet-Showcase

Commands to visualize the build script dependencies. The first command shows a simple task graph, while the second includes task clusters for a more detailed view.

```powershell
PS> Show-BuildGraph
```

```powershell
PS> Show-BuildGraph -Cluster
```

--------------------------------

### Invoke-Build Task Differences

Source: https://github.com/nightroman/invoke-build/wiki/Comparison-with-psake

Outlines the differences in task parameters and functionality between Invoke-Build and other build tools, focusing on new parameters for incremental tasks, dependency management, conditional execution, and error handling.

```PowerShell
# New parameters for incremental tasks: `Inputs`, `Outputs`, and `Partial`.
# Parameters `Before` and `After` for alteration of other tasks.
# Parameters `Data`, `Done`, and `Source` for extensions.
# `Depends`, `PreAction`, `Action`, and `PostAction` replaced with `Jobs` (list of referenced tasks and own actions).
# `PostCondition` is not used; similar code is an `assert` in an extra action.
# Parameter `If` used instead of `PreCondition`; accepts script blocks or expression results.
# `ContinueOnError` not used; caller uses `?` to decide if failure is safe.
# `RequiredVariables` not used; uses `requires` and `property` commands.
# Documentation comment `# Synopsis: ...` used instead of `Description`.
# `Alias` not used but alias tasks are possible: `task MyAlias MyTaskName`.
```

--------------------------------

### Configurable Build Parameters

Source: https://github.com/nightroman/invoke-build/wiki/Script-Tutorial

Demonstrates how to use PowerShell script parameters within an Invoke-Build script to make build configurations dynamic. The example shows how to parameterize the build configuration (e.g., 'Release' or 'Debug') and pass it via the Invoke-Build command.

```powershell
param(
    $Configuration = 'Release'
)

use 15.0x86 MSBuild

task Build {
    exec { MSBuild Project.csproj /t:Build /p:Configuration=$Configuration }
}
```

--------------------------------

### Multilevel Inheritance Example

Source: https://github.com/nightroman/invoke-build/blob/main/Tasks/Extends/README.md

Demonstrates multilevel inheritance in Invoke-Build scripts. Shows how parameters and tasks are inherited and resolved from parent build scripts.

```powershell
param(
    # Replaced with parameters from "Base.build.ps1" and "More.build.ps1" recursively.
    [ValidateScript({"More\More.build.ps1"})]
    $Extends,

    # Own parameters.
    $Test1,
    $Test2 = 'test2'
)

# Own task.
task TestTask1 MoreTask1, {
    ...
}

# Redefined dot.
task . TestTask1
```

```powershell
param(
    # from "Base.build.ps1" (but "Release" comes from "More.build.ps1")
    $Configuration = "Release",
    $Base1,
    $Base2 = 'base2'

    # from "More.build.ps1"
    $More1,
    $More2 = 'more2'

    # from "Test.build.ps1"
    $Test1,
    $Test2 = 'test2'
)

# from "Base.build.ps1"
task BaseTask1 {
    ...
}
task . BaseTask1

# from "More.build.ps1"
task MoreTask1 BaseTask1, {
    ...
}

# from "Test.build.ps1"
task TestTask1 MoreTask1, {
    ...
}
task . TestTask1
```

--------------------------------

### Demo Tasks/Repeat2

Source: https://github.com/nightroman/invoke-build/blob/main/Release-Notes.md

A new demo case named 'Tasks/Repeat2' has been added, possibly demonstrating repeated task execution or a related concept.

```PowerShell
# Minor tweaks, new demo Tasks/Repeat2, etc.
```

--------------------------------

### Explicitly Running Multiple Tasks

Source: https://github.com/nightroman/invoke-build/wiki/Script-Tutorial

Shows how to explicitly invoke multiple tasks in a specific order using the Invoke-Build command. This allows for manual control over the build process.

```powershell
# This explicitly runs both tasks, "Clean" and "Build"
Invoke-Build Clean, Build
```

--------------------------------

### New internal tool `Show-TaskHelp.ps1`

Source: https://github.com/nightroman/invoke-build/blob/main/Release-Notes.md

Introduces a new internal tool, `Show-TaskHelp.ps1`, which is included in packages. This tool is used by `Invoke-Build -WhatIf`.

```PowerShell
# The new tool *Show-TaskHelp.ps1* is included to packages.
# `Invoke-Build ... -WhatIf` uses the new `Show-TaskHelp`.
```