Skip to content

Quick Start

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 resolves the dependencies and assembles that file automatically.

This guide gets you from zero to a working, dependency-ordered script in three steps:

  • Scaffold a new project
  • Run the build
  • Run the generated output

Prerequisites:

Step 1 — Scaffold a New Project

Open a PowerShell session, then import the module — none of the cmdlets work without it:

using module PSScriptBuilder

With the module imported, scaffold a new project:

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. 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 runs the build:

cd MyProject
.\Build-MyProject.ps1
Expected output
WARNING: 2 cross-collector dependency(s) detected. Verify template placeholder order. Run with -Verbose for details.

Build Summary
  Output : ...\build\Output\MyProject.ps1
  Size   : 734 bytes
  Time   : 1.05 s

Components
  Enums     : 1
  Classes   : 1
  Functions : 1
  Total     : 3

The warning is expected — Employee references WorkStatus and Get-EmployeeInfo references Employee, spanning three different collectors. It's a feature, not a problem to fix: see Building Your First Project for the full explanation.

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]

With the project scaffolded, built, and run, all three steps are complete.

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

Now that it works, here is the complete project layout for reference:

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 everything Scaffold a New Project does, plus a build\Release\ directory with two configuration files and a dedicated release script in the project root, and two extra lines in the generated template:

  • build\Release\psscriptbuilder.releasedata.json — stores the full release state: version, build metadata, and Git details. 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, updates the version and timestamp already written into the template, and then runs the build.
  • # Version: and # Timestamp: — two lines near the top of the generated template, holding placeholder values until the first release.

The full project layout, with release management included:

MyProject/
├── psscriptbuilder.config.json
├── Build-MyProject.ps1
├── Release-MyProject.ps1                     ← run this to release
├── src/
│   ├── Enums/
│   │   └── WorkStatus.ps1
│   ├── Classes/
│   │   └── Employee.ps1
│   └── Public/
│       └── Get-EmployeeInfo.ps1
└── build/
    ├── Templates/
    │   └── MyProject.ps1.template            ← now includes # Version: and # Timestamp: lines
    ├── Output/
    └── Release/
        ├── psscriptbuilder.releasedata.json  ← version, build metadata, Git details
        └── psscriptbuilder.bumpconfig.json   ← which files get version updates, and how

Run Release-MyProject.ps1 to see the release workflow in action. Any of -Major, -Minor, or -Patch works for a demo like this — -Patch is used here simply as the smallest bump:

.\Release-MyProject.ps1 -Patch
Expected output
Category : Version

  Property  : patch
  Old Value : 0
  New Value : 1

  Property  : full
  Old Value : 0.1.0
  New Value : 0.1.1

...

The release script also builds the project — producing the same warning and Build Summary shown in Run the Build.

The generated psscriptbuilder.bumpconfig.json is pre-configured for repeatable releases: it finds the # Version: and # Timestamp: lines already written into the template and updates them with the real values, on every run. See Release Management for how this mechanism works in full.

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.

Summary

You now have a working PSScriptBuilder project — from scaffold to a deployable, dependency-ordered script — without writing any ordering logic yourself.

In short: PSScriptBuilder resolves the order of your components for you, regardless of how the source files are arranged on disk.

See Also