Collectors¶

Collectors are the core building block of PSScriptBuilder. Each collector scans a set of source files, extracts a specific type of PowerShell component, and makes the collected data available for template processing and dependency analysis.

Collector Types¶

PSScriptBuilder provides five collector types:

Type	Collects	Default Token
`Using`	`using` statements	`{{UsingStatements}}`
`Enum`	Enum definitions	`{{EnumDefinitions}}`
`Class`	Class definitions (with dependency order)	`{{ClassDefinitions}}`
`Function`	Standalone function definitions	`{{FunctionDefinitions}}`
`File`	Complete file contents as-is	`{{FileContents}}`

Note

The Class collector uses PowerShell AST analysis to detect inheritance (BaseClass) and type references, enabling automatic topological sorting. The Function collector similarly detects called functions and type references.

Creating a Collector¶

Use New-PSScriptBuilderCollector to create a standalone collector:

$classCollector = New-PSScriptBuilderCollector -Type Class -IncludePath "src\Classes"

Or use Add-PSScriptBuilderCollector to create and register a collector in one fluent step — this is the recommended approach:

$cc = New-PSScriptBuilderContentCollector |
    Add-PSScriptBuilderCollector -Type Class    -IncludePath "src\Classes" |
    Add-PSScriptBuilderCollector -Type Function -IncludePath "src\Public"

ContentCollector¶

A PSScriptBuilderContentCollector manages all collectors for a build. It maintains the registered collectors in CollectorType order (Using → Enum → Class → Function → File) and validates that all collection keys are unique.

Create an empty ContentCollector and add collectors later:

$cc = New-PSScriptBuilderContentCollector
$cc = $cc | Add-PSScriptBuilderCollector -Type Class -IncludePath "src\Classes"

Or pass pre-built collectors at creation time:

$collectors = @(
    New-PSScriptBuilderCollector -Type Using    -IncludePath "src"
    New-PSScriptBuilderCollector -Type Class    -IncludePath "src\Classes"
    New-PSScriptBuilderCollector -Type Function -IncludePath "src\Public"
)
$cc = New-PSScriptBuilderContentCollector -Collector $collectors

Parameters Reference¶

All collector parameters are available on both New-PSScriptBuilderCollector and Add-PSScriptBuilderCollector:

Parameter	Type	Description
`-Type`	`string`	Required. One of: `Using`, `Enum`, `Class`, `Function`, `File`
`-CollectionKey`	`string`	Custom token key for use in templates. Defaults to the type's default key
`-IncludePath`	`string[]`	Directories to scan. Relative to project root or absolute
`-IncludeFile`	`string[]`	Specific files or glob patterns to include explicitly
`-ExcludePath`	`string[]`	Directories to exclude. Takes precedence over `-IncludePath`
`-ExcludeFile`	`string[]`	File patterns to exclude (e.g., `"*.Tests.ps1"`)

File Resolution Rules¶

Paths can be relative (resolved against $Global:PSScriptBuilderProjectRoot) or absolute
-IncludeFile entries take highest priority — they bypass path exclusion filters
By default, collectors scan all .ps1 files recursively (-Recurse: $true)
Non-existent paths produce a warning, not an error — the collector continues with valid paths

Custom Collection Keys¶

The CollectionKey maps a collector to a {{Token}} placeholder in your template. Use a custom key when you need multiple collectors of the same type or want more descriptive names. Multiple collectors of the same type are supported for all collector types, including Using and File:

$cc = New-PSScriptBuilderContentCollector |
    Add-PSScriptBuilderCollector -Type Class -CollectionKey "DOMAIN_CLASSES"    -IncludePath "src\Domain" |
    Add-PSScriptBuilderCollector -Type Class -CollectionKey "INFRA_CLASSES"     -IncludePath "src\Infrastructure" |
    Add-PSScriptBuilderCollector -Type Function -CollectionKey "PUBLIC_CMDLETS" -IncludePath "src\Public"

The template would then use:

{{DOMAIN_CLASSES}}
{{INFRA_CLASSES}}
{{PUBLIC_CMDLETS}}

Keys must be unique

Adding two collectors with the same CollectionKey throws an InvalidOperationException.

Default Collection Keys¶

Collector Type	Default CollectionKey
`Using`	`UsingStatements`
`Enum`	`EnumDefinitions`
`Class`	`ClassDefinitions`
`Function`	`FunctionDefinitions`
`File`	`FileContents`

Inspecting Collectors¶

Use Get-PSScriptBuilderCollector to retrieve registered collectors from a ContentCollector:

# All collectors (sorted by CollectorType)
Get-PSScriptBuilderCollector -ContentCollector $cc

# Single collector by key (case-insensitive)
$classCollector = Get-PSScriptBuilderCollector -ContentCollector $cc -CollectionKey "ClassDefinitions"

# All collectors of a specific type
Get-PSScriptBuilderCollector -ContentCollector $cc -CollectorType Class

Inspecting Collected Data¶

After a build or explicit Collect() call, use Get-PSScriptBuilderCollectorContent to inspect what was collected:

$classCollector = Get-PSScriptBuilderCollector -ContentCollector $cc -CollectionKey "ClassDefinitions"
$classes = Get-PSScriptBuilderCollectorContent -Collector $classCollector

# Display name, base class, and source file for all collected classes
$classes | Format-Table Name, BaseClass, SourceFile

Each data object exposes type-specific properties:

Collector Type	Data Properties
`Class`	`Name`, `SourceCode`, `SourceFile`, `BaseClass`, `TypeReferences`
`Function`	`Name`, `SourceCode`, `SourceFile`, `CalledFunctions`, `TypeReferences`
`Enum`	`Name`, `SourceCode`, `SourceFile`
`Using`	`Statement`, `SourceFiles`
`File`	`FileName`, `FilePath`, `Content`

Filter collected items by name:

# Get a single class by name
$data = Get-PSScriptBuilderCollectorContent -Collector $classCollector -ItemName "MyBaseClass"
Write-Host $data.SourceCode

Removing Collectors¶

Use Remove-PSScriptBuilderCollector to remove a collector from a ContentCollector by key. The operation is idempotent — removing a non-existent key produces a warning, not an error:

$cc = $cc | Remove-PSScriptBuilderCollector -CollectionKey "TEMP_CLASSES"

Fluent chaining with remove and add:

$cc = $cc |
    Remove-PSScriptBuilderCollector -CollectionKey "OLD_FUNCTIONS" |
    Add-PSScriptBuilderCollector -Type Function -CollectionKey "NEW_FUNCTIONS" -IncludePath "src\v2"

Execution Order¶

Collectors are always executed in CollectorType enum order, regardless of registration order:

Order	CollectorType
1	`Using`
2	`Enum`
3	`Class`
4	`Function`
5	`File`

This defines the order in which collectors run during the collection phase. The position of each collector's output in the final script is controlled by the template — see the Templates Guide for details on how tokens and build modes determine the final output.