Skip to content

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.

See Also