DEV Community: Tim Hartling

When PowerShell Classes and Functions Depend on Each Other — How PSScriptBuilder Handles It

Tim Hartling — Mon, 04 May 2026 09:22:18 +0000

When you build a PowerShell project from multiple files, the natural structure is clear: enums first, then classes, then functions. Each group has its own place, and as long as dependencies only flow in one direction, that structure works perfectly.

But sometimes a function depends on a class, and that class calls the function. There is no longer a clean boundary between the two groups — they need to be interleaved in the output. That's a cross-dependency, and handling it manually is where things get fragile.

What a Cross-Dependency Looks Like

Consider this scenario:

# New-Report.ps1
function New-Report([ReportConfig] $config) {
    # uses ReportConfig as a parameter type
}

# ReportConfig.ps1
class ReportConfig {
    [string] $Title

    [void] Generate() {
        New-Report $this  # calls New-Report
    }
}

New-Report references ReportConfig as a parameter type — so ReportConfig must be defined before New-Report is loaded. But ReportConfig calls New-Report — so New-Report must appear before ReportConfig.

There is no single clean boundary between classes and functions anymore — they need to be interleaved in the output. That's exactly what PSScriptBuilder's Ordered Mode handles.

PSScriptBuilder Detects It Automatically

PSScriptBuilder analyzes the full dependency graph of your project and detects whether classes and functions need to be interleaved in the output. You can check this before building:

$contentCollector = New-PSScriptBuilderContentCollector |
    Add-PSScriptBuilderCollector -Type Class    -IncludePath "src/Classes"    |
    Add-PSScriptBuilderCollector -Type Function -IncludePath "src/Functions"

$analysis = Get-PSScriptBuilderDependencyAnalysis -ContentCollector $contentCollector

Write-Host "Has cross-dependencies: $($analysis.HasCrossDependencies)"

Output:

Has cross-dependencies: True

Free Mode, Ordered Mode, and Hybrid Mode

PSScriptBuilder selects a build mode based on the actual dependency structure of your project.

Free Mode applies when all enums, classes, and functions can be cleanly separated in the output — all enums first, then all classes in dependency order, then all functions. Each component type maps to its own placeholder in the template:

{{ENUM_DEFINITIONS}}

{{CLASS_DEFINITIONS}}

{{FUNCTION_DEFINITIONS}}

Ordered Mode applies when cross-dependencies exist and classes and functions must be interleaved. A separate placeholder per component type is no longer sufficient — the output order cannot be determined until all dependencies are resolved globally. The template must use a single placeholder instead:

{{ORDERED_COMPONENTS}}

PSScriptBuilder then outputs all enums, classes, and functions in a single topologically-sorted block in the correct order.

Hybrid Mode applies when the template already uses {{ORDERED_COMPONENTS}} but no cross-dependencies exist. This is an opt-in configuration — useful when you anticipate future cross-dependencies, or simply prefer a single unified component block. PSScriptBuilder handles Hybrid Mode and Ordered Mode identically.

Adapting the Template

When PSScriptBuilder detects cross-dependencies and the template still uses separate placeholders, the build fails with a clear error pointing to the required change.

The fix is straightforward — replace the separate placeholders with a single one:

# Before
{{ENUM_DEFINITIONS}}

{{CLASS_DEFINITIONS}}

{{FUNCTION_DEFINITIONS}}

# After
{{ORDERED_COMPONENTS}}

PSScriptBuilder takes care of the rest. The output will contain all components in the correct interleaved order — automatically, on every build.

You can also check the detected mode before building:

$templateAnalysis = Get-PSScriptBuilderTemplateAnalysis `
    -ContentCollector $contentCollector `
    -TemplatePath     "build/Templates/MyScript.ps1.template"

Write-Host "Template mode: $($templateAnalysis.ValidationMode)"

Output:

Template mode: Ordered

No manual reordering, no fragile concatenation scripts — PSScriptBuilder resolves the interleaving and produces a correctly ordered output file on every run.

Whether your project has only a few components or over a hundred — like PSScriptBuilder itself — PSScriptBuilder figures out the correct structure and tells you immediately when the template needs to be adapted.

For the full reference, see the Templates Guide and the Dependency Analysis Guide.

Get Started

Install-Module -Name PSScriptBuilder

Docs: docs.psscriptbuilder.com
GitHub: github.com/PSScriptBuilder/PSScriptBuilder

New to PSScriptBuilder? Start here: Stop Manually Sorting PowerShell Class Files — PSScriptBuilder Does It For You

Have you run into cross-dependency issues in your PowerShell projects? I'd be curious to hear how you've been handling them — or whether PSScriptBuilder covers your use case.

How PSScriptBuilder Analyzes PowerShell Dependencies — and What Happens When They Form a Cycle

Tim Hartling — Thu, 30 Apr 2026 11:17:35 +0000

If you've read the first article in this series, you already know that PSScriptBuilder resolves PowerShell class load order automatically. This article goes one level deeper: what exactly does PSScriptBuilder analyze, how does it build a dependency graph, and what happens when that graph contains a cycle?

What PSScriptBuilder Extracts

When PSScriptBuilder processes your source files, it runs AST analysis on every collected component and extracts the following dependency information:

Component	Dependencies extracted
Class	Base class, type references (properties, method parameters), static initializer references, called functions
Function	Called functions, type references
Enum	None — enums have no outgoing dependencies and always appear first

Built-in types (string, int, bool, System.*, etc.) are automatically excluded — only types that are part of your project create graph edges.

The Dependency Graph

The extracted dependencies form a directed graph where each node is a component and each edge represents a dependency. An edge from Employee to Person means: Employee depends on Person, so Person must appear first in the output.

Consider this example:

class Employee : Person {
    [Address] $Address
    [decimal] $Salary
}

PSScriptBuilder extracts two edges from this class:

Employee --[inherits]--> Person
Employee --[type reference]--> Address

Both Person and Address must appear before Employee in the output. PSScriptBuilder applies topological sorting to the full graph and determines the correct order for all components automatically — regardless of file or directory order.

You can inspect the dependency graph at any time:

$contentCollector = New-PSScriptBuilderContentCollector |
    Add-PSScriptBuilderCollector -Type Class -IncludePath "src/Classes"

$analysis = Get-PSScriptBuilderDependencyAnalysis -ContentCollector $contentCollector

Write-Host "Components : $($analysis.TotalComponents)"
Write-Host "Has cycles : $($analysis.HasCycles)"

Not All Cycles Are Equal

PSScriptBuilder distinguishes two fundamentally different types of cycles — and only one of them is a problem.

Fatal Cycles

A cycle is fatal when it creates an unresolvable ordering constraint at PowerShell load time. PowerShell processes type definitions from top to bottom before any code runs. Two dependency types create this hard constraint:

Inheritance — a base class must be fully defined before any class that inherits from it can be loaded. If two classes inherit from each other — directly or through a chain — there is no valid order:

class ServiceA : ServiceB { }  # requires ServiceB first
class ServiceB : ServiceC { }  # requires ServiceC first
class ServiceC : ServiceA { }  # requires ServiceA first — impossible

Static property initializers — static initializers run immediately when a class is loaded, not when a method is called. A type referenced in a static initializer must already be defined at load time — the same hard requirement as inheritance:

class ClassA {
    static [ClassB] $Default = [ClassB]::new()  # runs when ClassA loads
}

class ClassB {
    static [ClassA] $Default = [ClassA]::new()  # runs when ClassB loads
}

Neither class can be loaded first. PSScriptBuilder catches both cycle types before writing any output.

Type Reference Cycles — Not Fatal

A type reference cycle occurs when two classes reference each other inside method bodies:

class ClassA {
    [void] Process() { $b = [ClassB]::new() }
}

class ClassB {
    [void] Process() { $a = [ClassA]::new() }
}

This looks like a cycle — but it isn't a problem. Method bodies are not executed when the class is loaded; they only run when the method is called. By that time, all class definitions in the script have already been loaded. PSScriptBuilder recognizes this and handles it automatically — no error, no manual intervention required.

When a Fatal Cycle Is Detected

When the $contentCollector points at classes that form a fatal cycle, Get-PSScriptBuilderDependencyAnalysis reports it immediately:

$analysis = Get-PSScriptBuilderDependencyAnalysis -ContentCollector $contentCollector

if ($analysis.HasCycles) {
    Write-Host "Cycle path: $($analysis.CyclePath -join ' -> ')"
}

Output:

Cycle path: ServiceA -> ServiceB -> ServiceC -> ServiceA

If you call Invoke-PSScriptBuilderBuild directly, it fails fast with the same information:

Build failed: Circular dependency detected: ServiceA -> ServiceB -> ServiceC -> ServiceA

The full cycle path tells you exactly where to look. A fatal cycle always represents a structural problem in the code — PSScriptBuilder surfaces it clearly so you can fix it at the source.

Whether your project has only a few components or over a hundred — like PSScriptBuilder itself — PSScriptBuilder figures out the correct order and tells you immediately when a cycle makes that impossible.

For the full reference, see the Dependency Analysis Guide.

Get Started

Install-Module -Name PSScriptBuilder

Docs: docs.psscriptbuilder.com
GitHub: github.com/PSScriptBuilder/PSScriptBuilder

New to PSScriptBuilder? Start here: Stop Manually Sorting PowerShell Class Files — PSScriptBuilder Does It For You

Have you run into dependency issues in your PowerShell projects? I'd be curious to hear how you've been handling them — or whether PSScriptBuilder covers your use case.

Stop Manually Updating Version Numbers in PowerShell Projects — PSScriptBuilder Does It For You

Tim Hartling — Mon, 20 Apr 2026 17:13:39 +0000

If you maintain a PowerShell project, you've probably done this before:

Bump the version in MyScript.ps1 or MyModule.psd1
Update the version comment in your script header
Add the date to CHANGELOG.md
Forget one of the three — and push anyway

Manual version management is error-prone by nature. The more files you need to update, the more likely something falls out of sync. And "just use a script" sounds simple until that script breaks six months later because a filename changed.

PSScriptBuilder includes a full release management pipeline that solves this with two JSON files and two cmdlets — whether you're building a deployable script, a module, or anything in between.

How It Works

PSScriptBuilder separates release management into two concerns:

Release data — a single source of truth for your current version and build metadata:

{
    "version": {
        "major": 1,
        "minor": 0,
        "patch": 3,
        "prerelease": "",
        "buildmetadata": "",
        "full": "1.0.3"
    },
    "build": {
        "number": 42,
        "date": "2026-04-20",
        "time": "14:23:11",
        "timestamp": "2026-04-20T14:23:11Z",
        "year": 2026,
        "month": 4,
        "day": 20,
        "hour": 14,
        "minute": 23,
        "second": 11
    },
    "git": {
        "commit": "a3f1c2987d4e5f6b",
        "commitShort": "a3f1c29",
        "branch": "main",
        "tag": "v1.0.3"
    }
}

Bump configuration — a declaration of which files get updated and how. Here is a real-world example covering a module manifest, a script header, and a CHANGELOG — all in Mixed Bump Mode:

{
    "bumpFiles": [
        {
            "description": "Module manifest - Mixed bump mode",
            "path": "build\\Output\\MyModule.psd1",
            "items": [
                {
                    "pattern": "{{VERSION}}",
                    "tokens": ["VERSION"]
                },
                {
                    "pattern": "ModuleVersion\\s*=\\s*'({REGEX_VERSION})'",
                    "tokens": ["VERSION"]
                }
            ]
        },
        {
            "description": "Script header - Mixed bump mode",
            "path": "build\\Templates\\MyScript.psm1.template",
            "items": [
                {
                    "pattern": "{{VERSION}}",
                    "tokens": ["VERSION"]
                },
                {
                    "pattern": "# MyScript v({REGEX_VERSION})",
                    "tokens": ["VERSION"]
                }
            ]
        },
        {
            "description": "CHANGELOG - Mixed bump mode with VERSION and BUILD_DATE",
            "path": "CHANGELOG.md",
            "items": [
                {
                    "pattern": "{{VERSION}}",
                    "tokens": ["VERSION"]
                },
                {
                    "pattern": "{{BUILD_DATE}}",
                    "tokens": ["BUILD_DATE"]
                },
                {
                    "pattern": "Release: ({REGEX_VERSION})",
                    "tokens": ["VERSION"]
                },
                {
                    "pattern": "Date: (\\d{4}-\\d{2}-\\d{2})",
                    "tokens": ["BUILD_DATE"]
                }
            ]
        }
    ]
}

PSScriptBuilder automatically substitutes {REGEX_VERSION} and similar placeholders with the appropriate regex pattern for the token — no manual regex writing required.

A Release in Two Cmdlets

Step 1 — Update the release data:

Update-PSScriptBuilderReleaseData -Patch -UpdateBuildDetails

This bumps the patch version, increments the build number, and refreshes date, time, and timestamp — all in one call. -WhatIf shows you the changes before committing them.

Step 2 — Apply the new version to your files:

Update-PSScriptBuilderBumpFiles

PSScriptBuilder reads the bump configuration, locates each file, applies the patterns, substitutes the tokens with current values, and writes the results. Every configured file is updated atomically — either all succeed or nothing is written.

That's it. No fragile find-and-replace scripts. No forgotten files.

Mixed Bump Mode

The first time you run Update-PSScriptBuilderBumpFiles on a new file, there is no existing version to match — only a placeholder token like {{VERSION}}. On every subsequent run, the file already contains a real version string that needs to be matched by regex.

PSScriptBuilder handles this with Mixed Bump Mode: each bump entry can contain both a simple token replacement (first run) and a regex replacement (all subsequent runs) within the same file entry.

First run: the simple item "pattern": "{{VERSION}}" matches the placeholder and replaces it with 1.0.3.

All subsequent runs: the regex item "pattern": "ModuleVersion\\s*=\\s*'({REGEX_VERSION})'" matches the existing value and updates it to 1.0.4.

PSScriptBuilder tries each item in order — whichever matches wins. No config change needed between the first and second run. Multiple tokens per entry are fully supported — the CHANGELOG example above updates both VERSION and BUILD_DATE from a single file entry.

Available Tokens (excerpt)

Token	Example value
`{{VERSION}}`	`1.0.3`
`{{VERSION_FULL}}`	`1.0.3-beta.1`
`{{BUILD_TIMESTAMP}}`	`2026-04-20T14:23:11Z`
`{{BUILD_DATE}}`	`2026-04-20`
`{{GIT_COMMIT_SHORT}}`	`a3f1c29`

All available tokens — including build number, time components, and full Git metadata — are listed in the Release Management Guide. You can also inspect the current values at any time:

Get-PSScriptBuilderReleaseDataTokens | Format-Table -AutoSize

Fitting Into a Full Build Pipeline

Release management is designed to run before your build (adjust -Patch, -Minor, or -Major to your needs):

# Step 1 — Bump version and refresh metadata
Update-PSScriptBuilderReleaseData -Patch -UpdateBuildDetails -UpdateGitDetails

# Step 2 — Propagate version into manifest, script header, CHANGELOG
Update-PSScriptBuilderBumpFiles

# Step 3 — Build the script
$buildResult = Invoke-PSScriptBuilderBuild `
    -ContentCollector $contentCollector `
    -TemplatePath "build/Templates/MyScript.psm1.template" `
    -OutputPath "build/Output/MyScript.psm1"

The version flows from the release data file through your project files all the way into the built output — automatically, every time.

Get Started

Install-Module -Name PSScriptBuilder

Full guide: docs.psscriptbuilder.com/guides/release-management
Docs: docs.psscriptbuilder.com
GitHub: github.com/PSScriptBuilder/PSScriptBuilder

New to PSScriptBuilder? Start here: Stop Manually Sorting PowerShell Class Files — PSScriptBuilder Does It For You

Do you currently manage version numbers manually across your PowerShell projects? I'd be curious to hear what your current process looks like — or whether this covers your use case.

Stop Manually Sorting PowerShell Class Files — PSScriptBuilder Does It For You

Tim Hartling — Fri, 17 Apr 2026 15:36:44 +0000

If you've ever written a PowerShell module with classes, you know the pain:

Unable to find type [Employee].

PowerShell requires class definitions to appear in the correct order — base classes before derived classes, dependencies before dependents. In a single file with only a few classes, that's manageable. In a multi-file project with dozens of classes? It becomes a maintenance nightmare that only grows as the project does.

PSScriptBuilder solves this. It's a dependency-aware build tool that combines your multi-file PowerShell project into a single, deployable script — with class definitions automatically sorted into the correct load order using AST analysis.

Installation

Install-Module -Name PSScriptBuilder -Scope CurrentUser

PSScriptBuilder requires using module instead of Import-Module to make classes and enums available. The using statement must appear at the very top of your script, before any other code.

PSScriptBuilder runs on Windows PowerShell 5.1 and PowerShell 7+ (Windows, Linux, macOS). Generated output is fully PS 5.1 compatible — ideal for enterprise environments.

Core Concepts

PSScriptBuilder has two building blocks:

Collectors define where your source files live. You configure one collector per source location and point it at a directory. Multiple collectors of the same type are fully supported — useful when your classes are spread across several directories that each need different filter rules.

Templates define the output structure. You create a template file with {{Token}} placeholders, and each placeholder is replaced by the collected, dependency-ordered source code of the corresponding collector.

A Complete Example

Given this project structure:

MyModule/
├── src/
│   ├── Enums/
│   ├── Classes/
│   └── Public/
└── build/
    ├── Templates/
    │   └── MyModule.psm1.template
    └── Output/

Step 1 — Generate the configuration file:

New-PSScriptBuilderConfiguration

This creates psscriptbuilder.config.json in your project root. PSScriptBuilder searches for it automatically starting from the current directory upward.

Step 2 — Create a template:

{{ENUM_DEFINITIONS}}

{{CLASS_DEFINITIONS}}

{{FUNCTION_DEFINITIONS}}

Step 3 — Configure collectors and build:

using module PSScriptBuilder

$contentCollector = New-PSScriptBuilderContentCollector |
    Add-PSScriptBuilderCollector -Type Enum     -IncludePath "src/Enums"   |
    Add-PSScriptBuilderCollector -Type Class    -IncludePath "src/Classes" |
    Add-PSScriptBuilderCollector -Type Function -IncludePath "src/Public"

Invoke-PSScriptBuilderBuild `
    -ContentCollector $contentCollector `
    -TemplatePath     "build/Templates/MyModule.psm1.template" `
    -OutputPath       "build/Output/MyModule.psm1"

PSScriptBuilder reads every source file, resolves all type dependencies via AST analysis, and writes a correctly ordered output file. If Employee inherits from Person, Person will always appear first — regardless of file or directory order.

More Features

Cycle detection — Circular inheritance dependencies are caught before any output is written, with a clear error message showing the full cycle path.

Cross-dependency handling — When classes and functions have mutual dependencies, PSScriptBuilder detects this situation and reports it. You resolve it by replacing the separate {{CLASS_DEFINITIONS}} and {{FUNCTION_DEFINITIONS}} placeholders in your template with a single {{ORDERED_COMPONENTS}} token — PSScriptBuilder then outputs all components interleaved in the correct dependency order.

Using statement deduplication — If multiple source files contain the same using namespace or using assembly statements, PSScriptBuilder collects them via a dedicated Using collector and outputs each statement exactly once at the top of the script.

Flexible filtering — Collectors support include/exclude patterns, recursive or flat scanning, and custom file extensions:

Add-PSScriptBuilderCollector -Type Class `
    -IncludePath   "src/Classes" `
    -ExcludeFile   "*.Tests.ps1" `
    -FileExtension ".ps1", ".psm1"

Release management — PSScriptBuilder includes a full release pipeline beyond simple version bumping. A release data file tracks your current SemVer version, build details, and Git metadata. You update it with Update-PSScriptBuilderReleaseData, which offers granular control over what gets refreshed — version bumping (-Major, -Minor, -Patch), build details (-UpdateBuildDetails), Git metadata (-UpdateGitDetails), or any combination in a single call.

A separate bump configuration file defines which files get updated and how. Each file can have multiple replacement rules — each rule uses a regex pattern to locate the value and a release data token (e.g. {{VERSION_FULL}}) to inject the new value. This means a single Update-PSScriptBuilderReleaseData call can update your .psd1, README, and version header simultaneously, each with its own pattern.

Consider this pattern: on the first bump, a static placeholder like {{BUILD_TIMESTAMP}} is replaced with the actual timestamp. On every subsequent bump, the regex matches the existing timestamp value and replaces it with the new one — no manual intervention, no config change between runs.

Get Started

PSGallery: Install-Module -Name PSScriptBuilder
Docs: docs.psscriptbuilder.com
GitHub: github.com/PSScriptBuilder/PSScriptBuilder

Have you run into load-order issues in your PowerShell projects? I'd love to hear how you've been handling it — or if PSScriptBuilder covers your use case.