Test-PSScriptBuilderTemplate

SYNOPSIS

Validates a PSScriptBuilder template file without performing a build.

SYNTAX

Test-PSScriptBuilderTemplate [-ContentCollector] <PSScriptBuilderContentCollector> [-TemplatePath] <String>
 [[-OrderedComponentsKey] <String>] [<CommonParameters>]

DESCRIPTION

The Test-PSScriptBuilderTemplate cmdlet validates template content against the current collector configuration. It checks:

• Placeholder format (no whitespace in placeholders)
• Placeholder existence (all collectors have placeholders in template)
• Unknown placeholders (no placeholders that don't map to collectors)
• Duplicate placeholders (no duplicate placeholder keys)
• Placeholder ordering (Using first, then Enum before Class/Function)

In Cross-Dependencies Mode (when Class \<-> Function dependencies exist):

• Only ORDERED_COMPONENTS placeholder allowed
• Individual collector placeholders forbidden (CLASS, FUNCTION, etc.)

In Free Mode (when no cross-dependencies):

• Individual collector placeholders allowed
• ORDERED_COMPONENTS placeholder forbidden

This cmdlet is useful for:

• Validating template changes before building
• CI/CD pipeline template checks
• Development workflow validation
• Template troubleshooting

EXAMPLES

EXAMPLE 1

$isValid = New-PSScriptBuilderContentCollector |
    Add-PSScriptBuilderCollector -Type Class -IncludePath "src\Classes" |
    Add-PSScriptBuilderCollector -Type Function -IncludePath "src\Public" |
    Test-PSScriptBuilderTemplate -TemplatePath "template.psm1"
if ($isValid) {
    Write-Host "Template is valid" -ForegroundColor Green
}

Fluent pipeline validation with conditional output.

EXAMPLE 2

$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" -Verbose) {
    Invoke-PSScriptBuilderBuild -ContentCollector $cc `
        -TemplatePath "template.psm1" `
        -OutputPath "build\output\MyModule.psm1"
} else {
    Write-Warning "Template validation failed. Build skipped."
}

Pre-flight validation before build. Use -Verbose to see detailed validation steps.

EXAMPLE 3

$cc = New-PSScriptBuilderContentCollector |
    Add-PSScriptBuilderCollector -Type Using -IncludePath "src" |
    Add-PSScriptBuilderCollector -Type Enum -IncludePath "src\Enums" |
    Add-PSScriptBuilderCollector -Type Class -IncludePath "src\Classes" |
    Add-PSScriptBuilderCollector -Type Function -IncludePath "src\Public"
Test-PSScriptBuilderTemplate -ContentCollector $cc `
    -TemplatePath "template.psm1" `
    -OrderedComponentsKey "ALL_COMPONENTS"

Validates template with custom placeholder key for ordered components.

PARAMETERS

-ContentCollector

The PSScriptBuilderContentCollector instance containing all configured collectors. Can be passed via pipeline from New-PSScriptBuilderContentCollector or Add-PSScriptBuilderCollector.

Type: PSScriptBuilderContentCollector
Parameter Sets: (All)
Aliases:

Required: True
Position: 1
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False

-TemplatePath

Path to the template file to validate. Supports both absolute paths and paths relative to the project root (as set via Set-PSScriptBuilderProjectRoot).

The path is resolved using FileSystemHelper.GetProjectRootedPath(), which means:

• Absolute paths are used as-is
• Relative paths are resolved from the project root

Example paths:

• "build\templates\module.template"
• "C:\Projects\MyModule\templates\script.template"

Type: String
Parameter Sets: (All)
Aliases:

Required: True
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-OrderedComponentsKey

The placeholder key used in the template for dependency-ordered components. Default is "ORDERED_COMPONENTS" (resulting in {{ORDERED_COMPONENTS}} in template).

This is used in Cross-Dependencies Mode where all components must be merged in dependency order.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 3
Default value: ORDERED_COMPONENTS
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

OUTPUTS

System.Boolean

NOTES

The cmdlet performs dependency analysis to determine the validation mode:

• Cross-Dependencies Mode: Class \<-> Function dependencies detected
• Free Mode: No cross-dependencies between component types

Validation is comprehensive and catches common template issues early:

• Missing placeholders for configured collectors
• Extra placeholders that don't map to collectors
• Incorrect placeholder ordering (e.g., Class before Using)
• Mode violations (e.g., individual placeholders in cross-dependencies mode)

Template validation failures return $false (not an error):

• Validation failures are expected outcomes and logged via Write-Verbose
• Use -Verbose to see detailed validation failure messages
• Only unexpected errors (file not found, parameter errors) are terminating errors

This is a lightweight validation-only operation. No files are modified and no output is generated. For detailed analysis results, use Get-PSScriptBuilderTemplateAnalysis.

All validation details are logged by the worker classes when -Verbose is specified:

• TemplateFileManager logs template loading
• ContentCollector logs collection execution
• DependencyAnalyzer logs dependency analysis
• TemplateValidator logs validation steps

RELATED LINKS