Skip to main content

Configuration Reference

PowerShellBuild exposes all of its settings through a single hashtable called $PSBPreference. Override values in the properties block of your psakeFile.ps1. Task dependency chains can also be customized via separate variables set outside the properties block.

Setting Preferences​

psakeFile.ps1
properties {
    # Override any $PSBPreference keys here
    $PSBPreference.General.ModuleName              = 'MyModule'
    $PSBPreference.Build.OutDir                    = "$PSScriptRoot/build"
    $PSBPreference.Test.ScriptAnalysis.Enabled     = $true
    $PSBPreference.Test.CodeCoverage.Enabled       = $true
    $PSBPreference.Test.CodeCoverage.Threshold     = 0.80
    $PSBPreference.Publish.PSRepositoryApiKey      = $env:PSGALLERY_API_KEY
}

task default -depends Build
task Build   -FromModule PowerShellBuild -Version '0.7.1'

Values not overridden retain their defaults as defined in PowerShellBuild's build.properties.ps1.

General​

SettingDefaultDescription
General.ProjectRoot(auto-detected)Root directory of the project
General.SrcRootDir$ProjectRoot/srcDirectory containing module source files
General.ModuleName(basename of .psd1)Name of the module
General.ModuleVersion(from manifest)Module version number
General.ModuleManifestPath(auto-detected)Path to the .psd1 manifest

Build​

SettingDefaultDescription
Build.OutDir$ProjectRoot/buildRoot output directory
Build.ModuleOutDir$OutDir/$ModuleNameModule-specific output subdirectory (computed)
Build.CompileModule$falseIf $true, concatenate all .ps1 source files into a single .psm1
Build.CompileDirectories'Enum','Classes','Private','Public'Directories whose .ps1 files are merged when compiling
Build.CopyDirectories@()Directories copied as-is (not compiled) to the output
Build.Exclude@()File patterns excluded from the output

Module Compilation​

Setting CompileModule = $true merges all .ps1 files from CompileDirectories into the root .psm1. This can improve module load time and is common for published modules.

properties {
    $PSBPreference.Build.CompileModule       = $true
    $PSBPreference.Build.CompileDirectories  = @('Enum', 'Classes', 'Private', 'Public')
    $PSBPreference.Build.CopyDirectories     = @('data', 'lib')
}

Test​

SettingDefaultDescription
Test.Enabled$trueEnable or disable Pester tests
Test.RootDir$ProjectRoot/testsDirectory containing Pester test files
Test.OutputFile$nullPath to write NUnitXml test results (useful for CI)
Test.OutputFormat'NUnitXml'Test result format
Test.ImportModule$falseImport the built module before running tests
Test.OutputVerbosity'Detailed'Pester output verbosity level
Test.SkipRemainingOnFailure'None'Skip strategy after a test failure

Script Analysis​

SettingDefaultDescription
Test.ScriptAnalysis.Enabled$trueRun PSScriptAnalyzer
Test.ScriptAnalysis.FailBuildOnSeverityLevel'Error'Build fails on violations at or above this severity ('Error', 'Warning', 'Information')
Test.ScriptAnalysis.SettingsPath./PSScriptAnalyzerSettings.psd1Path to a PSScriptAnalyzer settings file. Defaults to PSScriptAnalyzerSettings.psd1 in the project root — if the file exists it is used automatically
properties {
    # Fail on warnings too
    $PSBPreference.Test.ScriptAnalysis.FailBuildOnSeverityLevel = 'Warning'

    # Override the default settings file location
    $PSBPreference.Test.ScriptAnalysis.SettingsPath = "$PSScriptRoot/build/analyzersettings.psd1"
}

Code Coverage​

SettingDefaultDescription
Test.CodeCoverage.Enabled$falseEnable code coverage reporting
Test.CodeCoverage.Threshold0.75Minimum coverage ratio (0.0–1.0); build fails below this
Test.CodeCoverage.Files(staged module files)Files included in coverage analysis
Test.CodeCoverage.OutputFile$nullPath to write the coverage report
Test.CodeCoverage.OutputFileFormat'JaCoCo'Coverage report format
properties {
    $PSBPreference.Test.CodeCoverage.Enabled          = $true
    $PSBPreference.Test.CodeCoverage.Threshold        = 0.80
    $PSBPreference.Test.CodeCoverage.OutputFile       = "$PSScriptRoot/coverage.xml"
    $PSBPreference.Test.CodeCoverage.OutputFileFormat = 'JaCoCo'
}

Help​

SettingDefaultDescription
Help.DefaultLocale'en-US'Locale used when generating MAML and updatable help
Help.UpdatableHelpOutDir$nullDirectory where updatable help .cab files are written
Help.ConvertReadMeToAboutHelp$falseConvert README.md to an about_<ModuleName>.help.txt file

Docs​

SettingDefaultDescription
Docs.RootDir$ProjectRoot/docsDirectory for PlatyPS markdown source files
Docs.Overwrite$falseOverwrite existing markdown files when regenerating
Docs.AlphabeticParamsOrder$falseSort parameters alphabetically in generated markdown
Docs.ExcludeDontShow$falseExclude parameters marked [DontShow]
Docs.UseFullTypeName$falseUse fully-qualified type names instead of short names

Publish​

SettingDefaultDescription
Publish.PSRepository'PSGallery'Name of the PowerShell repository to publish to
Publish.PSRepositoryApiKey$nullAPI key for authenticating with the repository
Publish.PSRepositoryCredential$nullPSCredential for authenticating with the repository
properties {
    $PSBPreference.Publish.PSRepository      = 'PSGallery'
    $PSBPreference.Publish.PSRepositoryApiKey = $env:PSGALLERY_API_KEY
}

Sign​

SettingDefaultDescription
Sign.Enabled$falseEnable Authenticode signing
Sign.CertificateSource'Auto'How to resolve the signing certificate ('Auto', 'CertStore', 'Thumbprint', 'EnvVar', 'PfxFile')
Sign.CertStoreLocation$nullCertificate store path (e.g., 'Cert:\CurrentUser\My')
Sign.Thumbprint$nullSpecific certificate thumbprint
Sign.CertificateEnvVar'SIGNCERTIFICATE'Environment variable containing a Base64-encoded PFX
Sign.CertificatePasswordEnvVar$nullEnvironment variable containing the PFX password
Sign.PfxFilePath$nullPath to a PFX/P12 file
Sign.PfxFilePassword$nullPassword for the PFX file
Sign.SkipCertificateValidation$falseSkip certificate validity checks (not recommended for production)
Sign.TimestampServer$nullRFC 3161 timestamp server URI
Sign.HashAlgorithm'SHA256'Authenticode hash algorithm
Sign.FilesToSign@('*.psd1','*.psm1','*.ps1')File patterns to sign in the output directory

Catalog​

SettingDefaultDescription
Sign.Catalog.Enabled$falseCreate a Windows catalog (.cat) file
Sign.Catalog.Version2Catalog hash version
Sign.Catalog.FileName(module name)Catalog filename (without .cat extension)
properties {
    $PSBPreference.Sign.Enabled          = $true
    $PSBPreference.Sign.CertificateSource = 'EnvVar'
    $PSBPreference.Sign.TimestampServer  = 'http://timestamp.digicert.com'
    $PSBPreference.Sign.Catalog.Enabled  = $true
}

Task Dependency Variables​

To change which tasks a given task depends on, set these variables outside the properties block, before any PowerShellBuild task references:

VariableControls dependencies ofDefault
$PSBCleanDependencyClean'Init'
$PSBStageFilesDependencyStageFiles'Clean'
$PSBBuildHelpDependencyBuildHelp'GenerateMarkdown', 'GenerateMAML'
$PSBGenerateMarkdownDependencyGenerateMarkdown'StageFiles'
$PSBGenerateMAMLDependencyGenerateMAML'GenerateMarkdown'
$PSBGenerateUpdatableHelpDependencyGenerateUpdatableHelp'BuildHelp'
$PSBBuildDependencyBuild'StageFiles', 'BuildHelp'
$PSBAnalyzeDependencyAnalyze'Build'
$PSBPesterDependencyPester'Build'
$PSBTestDependencyTest'Pester', 'Analyze'
$PSBPublishDependencyPublish'Test'
$PSBSignModuleDependencySignModule'Build'
$PSBBuildCatalogDependencyBuildCatalog'SignModule'
$PSBSignCatalogDependencySignCatalog'BuildCatalog'
$PSBSignDependencySign'SignCatalog'

Example: Remove Analyze from the Test pipeline​

psakeFile.ps1
# Set outside properties block
$PSBTestDependency = 'Pester'   # Test only depends on Pester, not Analyze

properties {
    $PSBPreference.Test.ScriptAnalysis.Enabled = $false
}

task default -depends Test
task Test -FromModule PowerShellBuild -Version '0.7.1'

See Also​