Quick Start¶

PSScriptBuilder solves a specific problem: you write your PowerShell classes, enums, and functions in separate, focused files but a deployable script needs everything in a single file, in the correct dependency order. PSScriptBuilder handles the assembly automatically.

This guide gets you from zero to a working, dependency-ordered script in three steps: scaffold a project, run the build, and run the generated output.

Step 1 Scaffold a New Project¶

Open a PowerShell session, load the module with using module PSScriptBuilder (see Installation), and run:

New-PSScriptBuilderProject -Name "MyProject"

By default, the project folder is created in the current working directory. To create it somewhere else, pass -Path:

New-PSScriptBuilderProject -Name "MyProject" -Path "C:\Projects"

Either way, the command creates the complete directory structure, a configuration file, a template, and a build script in one step. It also creates three sample source files that are deliberately chosen to demonstrate dependency resolution:

WorkStatus.ps1 an enum with three values
Employee.ps1 a class that uses WorkStatus as a property type
Get-EmployeeInfo.ps1 a function that accepts an Employee parameter

These files depend on each other. PSScriptBuilder analyses the dependencies and determines the correct output order automatically regardless of how the files are arranged on disk. They are included by default to demonstrate this behaviour. For a real project without sample files, pass -NoSampleFiles:

New-PSScriptBuilderProject -Name "MyProject" -NoSampleFiles

Step 2 Run the Build¶

Build-MyProject.ps1 was generated by the scaffold command. It configures the collectors, points them at the source directories, and triggers the build:

cd MyProject
.\Build-MyProject.ps1

The build output is written to build\Output\MyProject.ps1.

Step 3 Run the Generated Script¶

Open build\Output\MyProject.ps1 and you will see WorkStatus, Employee, and Get-EmployeeInfo appear in exactly that sequence resolved from the actual dependencies, not from the file names. At the bottom of the generated script you will find a sample invocation that was included in the template:

Sample invocation (inside MyProject.ps1)

$employee = [Employee]::new("Alice", [WorkStatus]::Active)
Get-EmployeeInfo -Employee $employee

Run the generated script to see it in action:

.\build\Output\MyProject.ps1

Output

Alice [Active]

That is all it takes to go from source files to a working, dependency-ordered script.

Want to understand what's happening under the hood?

See Building Your First Project for a step-by-step walkthrough that explains each part of the pipeline.

What Gets Created¶

MyProject/
 psscriptbuilder.config.json        build and release settings
 Build-MyProject.ps1                run this to build
 src/
    Enums/
       WorkStatus.ps1             sample: enum with Active, OnLeave, Terminated
    Classes/
       Employee.ps1               sample: class referencing WorkStatus
    Public/
        Get-EmployeeInfo.ps1       sample: function referencing Employee
 build/
     Templates/
        MyProject.ps1.template     defines the output structure
     Output/                        generated files go here

Replace the sample files with your own source files and run Build-MyProject.ps1 again. PSScriptBuilder will resolve the dependency order of whatever you put there.

With Release Management¶

If your project needs version tracking bumping a version number before each build and recording when it was built add -IncludeReleaseManagement to the scaffold command:

New-PSScriptBuilderProject -Name "MyProject" -IncludeReleaseManagement

This creates a build\Release\ directory with two configuration files, plus a dedicated release script in the project root:

build\Release\psscriptbuilder.releasedata.json stores the current version number and build timestamp. You edit this file (or let PSScriptBuilder update it) when preparing a release.
build\Release\psscriptbuilder.bumpconfig.json defines which files receive version updates and how. Pre-configured for the generated template.
Release-MyProject.ps1 a dedicated release script that runs the full release workflow in a single command. It accepts -Major, -Minor, or -Patch to bump the version, updates the release data file, replaces the tokens in the template, and then triggers the build:

.\Release-MyProject.ps1 -Minor

The generated psscriptbuilder.bumpconfig.json is pre-configured for repeatable releases: the first run replaces the {{VERSION}} and {{BUILD_TIMESTAMP}} placeholders in the template; every subsequent run uses regex patterns to find and replace the actual values. See Release Management for the full picture.

The build script Build-MyProject.ps1 remains unchanged it always produces an output from whatever state the template is currently in. The separation keeps the build concern and the release concern distinct: you build as often as you like, and you release when you are ready.