Templates¶

A template is a plain text file that defines the structure of the generated output script. PSScriptBuilder replaces {{Token}} placeholders in the template with the collected and dependency-ordered source code from configured collectors.

Template Syntax¶

Placeholders use double curly braces around the collector key:

{{CollectionKey}}

Rules:

Keys are case-insensitive at match time
No whitespace inside the braces — {{ Key }} is invalid and causes a validation error
Each placeholder may appear only once in the template
Only keys matching a registered collector (or {{ORDERED_COMPONENTS}}) are valid

Example Template¶

#region Using Statements
{{UsingStatements}}
#endregion Using Statements

#region Enums
{{EnumDefinitions}}
#endregion Enums

#region Classes
{{ClassDefinitions}}
#endregion Classes

#region Functions
{{FunctionDefinitions}}
#endregion Functions

#region Files
{{FileContents}}
#endregion Files

Each placeholder is replaced with the correctly ordered source code collected by the corresponding collector. Static text before, between, and after placeholders is preserved as-is.

Default Token Names¶

Each collector type has a default CollectionKey, which is also the default placeholder name:

Collector Type	Default `CollectionKey`	Template Token
`Using`	`UsingStatements`	`{{UsingStatements}}`
`Enum`	`EnumDefinitions`	`{{EnumDefinitions}}`
`Class`	`ClassDefinitions`	`{{ClassDefinitions}}`
`Function`	`FunctionDefinitions`	`{{FunctionDefinitions}}`
`File`	`FileContents`	`{{FileContents}}`

Use -CollectionKey on Add-PSScriptBuilderCollector to define a custom token:

$cc = New-PSScriptBuilderContentCollector |
    Add-PSScriptBuilderCollector -Type Class -CollectionKey "DOMAIN_CLASSES" -IncludePath "src\Domain"

Template:

{{DOMAIN_CLASSES}}

Validation Modes¶

PSScriptBuilder automatically determines the validation mode based on dependency analysis.

Free Mode¶

Used when no cross-dependencies exist between classes and functions (a class references only other classes, a function references only classes — not other functions).

In Free Mode:

Each registered collector must have a corresponding placeholder in the template
{{ORDERED_COMPONENTS}} is forbidden
Placeholder order is enforced: Using → Enum → Class/Function

Free Mode template

{{UsingStatements}}
{{EnumDefinitions}}
{{ClassDefinitions}}
{{FunctionDefinitions}}
{{FileContents}}

Cross-Dependencies Mode¶

Activated automatically when classes and functions have dependencies on each other that require them to be interleaved in topological order. In this mode, separate per-type placeholders cannot capture the required order.

In Cross-Dependencies Mode:

{{ORDERED_COMPONENTS}} must be present — all Enum, Class, and Function components are emitted here in topological order
Per-type placeholders for Enum, Class, and Function collectors are forbidden in the template — regardless of their CollectionKey
Per-type placeholders for Using and File collectors remain valid and optional
Using placeholders must appear before {{ORDERED_COMPONENTS}}

Cross-Dependencies Mode template

{{UsingStatements}}
{{ORDERED_COMPONENTS}}

The placeholder name for ordered components defaults to ORDERED_COMPONENTS and can be overridden with the -OrderedComponentsKey parameter on Invoke-PSScriptBuilderBuild and Test-PSScriptBuilderTemplate. To keep the template and the build call in sync, store a custom key in psscriptbuilder.config.json and read it explicitly:

{
    "build": {
        "orderedComponentsKey": "MY_COMPONENTS"
    }
}

$config = Get-PSScriptBuilderConfiguration
Invoke-PSScriptBuilderBuild -ContentCollector $cc `
    -TemplatePath "template.psm1" `
    -OutputPath   "output.psm1" `
    -OrderedComponentsKey $config.Build.OrderedComponentsKey

Template Validation¶

Always validate your template before building. Use Test-PSScriptBuilderTemplate:

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

if (Test-PSScriptBuilderTemplate -ContentCollector $cc -TemplatePath "template.psm1") {
    Invoke-PSScriptBuilderBuild -ContentCollector $cc `
        -TemplatePath "template.psm1" `
        -OutputPath   "output.psm1"
}

Add -Verbose to see detailed validation messages.

For a full analysis result object, use Get-PSScriptBuilderTemplateAnalysis:

$result = Get-PSScriptBuilderTemplateAnalysis -ContentCollector $cc -TemplatePath "template.psm1"

Write-Host "Valid:  $($result.IsValid)"
Write-Host "Mode:   $($result.ValidationMode)"
Write-Host "Found:  $($result.PlaceholdersFound -join ', ')"
Write-Host "Missing: $($result.MissingPlaceholders -join ', ')"
Write-Host "Unknown: $($result.UnknownPlaceholders -join ', ')"

Validation Error Reference¶

Error	Cause	Fix
Whitespace in placeholder	`{{ Key }}` instead of `{{Key}}`	Remove whitespace inside braces
Missing `{{ORDERED_COMPONENTS}}`	Cross-Dependencies Mode but placeholder absent	Add `{{ORDERED_COMPONENTS}}` to template
Forbidden placeholder in CrossDeps Mode	`{{ClassDefinitions}}` etc. present in Cross-Dependencies Mode	Remove per-type placeholders; use only `{{ORDERED_COMPONENTS}}`
Collector placeholder missing	A registered collector has no matching placeholder	Add `{{CollectionKey}}` for each collector
Wrong placeholder order	`{{ClassDefinitions}}` before `{{UsingStatements}}`	Reorder: Using → Enum → Class/Function
Duplicate placeholder	Same `{{Key}}` appears more than once	Remove the duplicate
Unknown placeholder	`{{UNKNOWN}}` has no corresponding collector	Remove it or register a matching collector

Placeholder Analysis Properties¶

Get-PSScriptBuilderTemplateAnalysis returns a PSScriptBuilderTemplateAnalysisResult with:

Property	Description
`IsValid`	Whether the template passed all validation rules
`ValidationErrors`	Array of error messages (empty when valid)
`ValidationMode`	`Free` or `CrossDependencies`
`HasCrossDependencies`	Whether cross-dependencies were detected
`PlaceholdersFound`	All `{{...}}` tokens found in the template (sorted, unique)
`PlaceholdersExpected`	Tokens expected based on collectors and mode
`MissingPlaceholders`	Expected but not found in template
`UnknownPlaceholders`	Found in template but not matching any collector
`TemplatePath`	Resolved absolute path to the template file
`TemplateSize`	Template character count