API Reference
Command
New-ConfigurationBuild
Allows configuring the build process for a module.
Remarks
This cmdlet emits build configuration that is consumed by Invoke-ModuleBuild / Build-Module. It controls how the module is merged, signed, versioned, installed, and how optional .NET publishing is performed. Dependency-related options in this cmdlet affect the build machine, not artefact packaging. Use InstallMissingModules when the build host needs missing RequiredModule or ExternalModule dependencies installed before merge/import/test steps run. If you want dependencies copied into ZIP/unpacked artefacts, configure that separately with New-ConfigurationArtefact -AddRequiredModules. Build-time installation and artefact packaging are designed as separate decisions because many teams want one without the other. For a broader dependency workflow explanation, see about_ModuleDependencies.
Examples
Enable build and module merge, and keep a few installed versions
New-ConfigurationBuild -Enable -MergeModuleOnBuild -LocalVersioning -VersionedInstallStrategy AutoRevision -VersionedInstallKeep 3
Enable signing and terminate locking processes before install
New-ConfigurationBuild -Enable -SignModule -CertificateThumbprint '0123456789ABCDEF' -KillLockersBeforeInstall -KillLockersForce
Install missing dependencies from PSGallery before the build
New-ConfigurationBuild -Enable -InstallMissingModules -InstallMissingModulesRepository 'PSGallery'
Use this when the build host does not already have the declared RequiredModule or ExternalModule dependencies installed.
Resolve Auto or Latest online without installing first
New-ConfigurationBuild -Enable -ResolveMissingModulesOnline -WarnIfRequiredModulesOutdated
Useful in CI or on clean machines when dependency versions should come from the repository rather than the local module cache.
Install from a private repository with a token stored in a file
New-ConfigurationBuild -Enable -InstallMissingModules -InstallMissingModulesRepository 'MyPrivateFeed' -InstallMissingModulesCredentialUserName 'build' -InstallMissingModulesCredentialSecretFilePath '.secrets\feed-token.txt'
Use the credential parameters only when the repository requires authentication.
Convert the staged script module into a Hybrid binary module
New-ConfigurationBuild -Enable -CompilePowerShell -PowerShellCompilationMode Hybrid -PowerShellCompilationAllowUnreviewedDependencies
Hybrid preserves explicit script fallback. Supply PowerShellCompilationDependencyLock instead of the development opt-out for a reviewed release build.
Common Parameters
This command supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable.
For more information, see about_CommonParameters.
Syntax
New-ConfigurationBuild [-AutoSwitchExactOnPublish] [-CertificatePFXBase64 <String>] [-CertificatePFXPassword <String>] [-CertificatePFXPath <String>] [-CertificateThumbprint <String>] [-CompilePowerShell] [-DeleteTargetModuleBeforeBuild] [-DoNotAttemptToFixRelativePaths] [-DotSourceClasses] [-DotSourceLibraries] [-Enable] [-InstallMissingModules] [-InstallMissingModulesCredentialSecret <String>] [-InstallMissingModulesCredentialSecretFilePath <String>] [-InstallMissingModulesCredentialUserName <String>] [-InstallMissingModulesForce] [-InstallMissingModulesPrerelease] [-InstallMissingModulesRepository <String>] [-KillLockersBeforeInstall] [-KillLockersForce] [-LocalVersioning] [-MergeFunctionsFromApprovedModules] [-MergeModuleOnBuild] [-NETAssemblyLoadContext] [-NETAssemblyTypeAcceleratorAssemblies <String[]>] [-NETAssemblyTypeAcceleratorMode <AllowList|Assembly|Enums>] [-NETAssemblyTypeAccelerators <String[]>] [-NETBinaryModule <String[]>] [-NETBinaryModuleCmdletScanDisabled] [-NETBinaryModuleDocumentation] [-NETConfiguration <Release|Debug>] [-NETDevelopmentBinaries] [-NETDevelopmentBinariesEnvironmentVariable <String>] [-NETDevelopmentBinariesMode <Off|Environment|Auto>] [-NETDevelopmentBinariesPath <String>] [-NETDevelopmentConfigurationEnvironmentVariable <String>] [-NETDevelopmentSourceBootstrapperMode <PreserveSingleFile|ReplaceSingleFile>] [-NETDoNotCopyLibrariesRecursively] [-NETExcludeLibraryFilter <String[]>] [-NETExcludeMainLibrary] [-NETFramework <String[]>] [-NETHandleAssemblyWithSameName] [-NETHandleRuntimes] [-NETIgnoreLibraryOnLoad <String[]>] [-NETLineByLineAddType] [-NETMergeLibraryDebugging] [-NETProjectName <String>] [-NETProjectPath <String>] [-NETResolveBinaryConflicts] [-NETResolveBinaryConflictsName <String>] [-NETSearchClass <String>] [-PowerShellCompilationAllowUnreviewedDependencies] [-PowerShellCompilationBuildCacheDirectory <String>] [-PowerShellCompilationDependencyLock <PowerShellCompilationDependencyGraph>] [-PowerShellCompilationEmitIrSnapshots] [-PowerShellCompilationExcludeResource <String[]>] [-PowerShellCompilationExpectedPublicAbiSha256 <String>] [-PowerShellCompilationIncludeResource <String[]>] [-PowerShellCompilationMode <Hybrid|Strict>] [-PowerShellCompilationResourceMode <Declared|CompleteModule>] [-PowerShellCompilationTargetFramework <String>] [-PowerShellCompilationTimeoutSeconds <Int32>] [-PowerShellCompilationUseBuildCache] [-RefreshPSD1Only] [-ResolveMissingModulesOnline] [-SeparateFileLibraries] [-SignCustomInclude <String[]>] [-SignExcludePaths <String[]>] [-SignIncludeBinaries] [-SignIncludeExe] [-SignIncludeInternals] [-SignModule] [-SignOverwriteSigned] [-SkipBuiltinReplacements] [-SyncNETProjectVersion] [-UseWildcardForFunctions] [-VersionedInstallKeep <Int32>] [-VersionedInstallLegacyFlatHandling <Warn|Convert|Delete|Ignore>] [-VersionedInstallPreserveVersions <String[]>] [-VersionedInstallStrategy <Exact|AutoRevision>] [-WarnIfRequiredModulesOutdated] [<CommonParameters>]Parameter set:
All Parameter SetsParameters
- AutoSwitchExactOnPublish SwitchParameter
- Auto switch VersionedInstallStrategy to Exact when publishing.
- CertificatePFXBase64 String
- Base64 string of a PFX containing a code-signing certificate.
- CertificatePFXPassword String
- Password for the PFX provided via CertificatePFXPath or CertificatePFXBase64.
- CertificatePFXPath String
- Path to a PFX containing a code-signing certificate.
- CertificateThumbprint String
- Thumbprint of a code-signing certificate from the local cert store.
- CompilePowerShell SwitchParameter
- Compile the staged PowerShell module into a generated binary module.
- DeleteTargetModuleBeforeBuild SwitchParameter
- Delete target module before build.
- DoNotAttemptToFixRelativePaths SwitchParameter
- Do not attempt to fix relative paths during merge.
- DotSourceClasses SwitchParameter
- Keep classes in a separate dot-sourced file instead of merging into the main PSM1.
- DotSourceLibraries SwitchParameter
- Keep library-loading code in a separate dot-sourced file.
- Enable SwitchParameter
- Enable build process.
- InstallMissingModules SwitchParameter
- Install missing module dependencies (RequiredModule/ExternalModule) before build. This affects the build host only; it does not bundle modules into artefacts.
- InstallMissingModulesCredentialSecret String
- Credential secret or token for dependency installation. Prefer the file-path form in CI when you do not want the secret value embedded directly in scripts.
- InstallMissingModulesCredentialSecretFilePath String
- Path to a file containing the credential secret or token. This is often the safest option for automation and CI agents.
- InstallMissingModulesCredentialUserName String
- Credential user name for dependency installation. This is usually paired with InstallMissingModulesCredentialSecret or InstallMissingModulesCredentialSecretFilePath.
- InstallMissingModulesForce SwitchParameter
- Force re-install or update even if dependencies are already installed. Useful when you want the build host to re-sync against the repository instead of accepting the current local state.
- InstallMissingModulesPrerelease SwitchParameter
- Allow prerelease versions when installing dependencies. Use this only when the dependency declaration and repository policy intentionally allow prerelease packages.
- InstallMissingModulesRepository String
- Repository name used for dependency installation (defaults to PSGallery). Set this when your build should resolve dependencies from a named private feed or alternate gallery.
- KillLockersBeforeInstall SwitchParameter
- Kill locking processes before install.
- KillLockersForce SwitchParameter
- Force killing locking processes before install.
- LocalVersioning SwitchParameter
- Use local versioning (bump PSD1 version on each build without querying PSGallery).
- MergeFunctionsFromApprovedModules SwitchParameter
- When merging, also include functions from ApprovedModules referenced by the module.
- MergeModuleOnBuild SwitchParameter
- Merge module on build (combine Private/Public/Classes/Enums into one PSM1).
- NETAssemblyLoadContext SwitchParameter
- Load the binary module through a custom AssemblyLoadContext on PowerShell Core.
- NETAssemblyTypeAcceleratorAssemblies String[]
- Assembly simple names whose public types may be exposed as PowerShell type accelerators when assembly mode is enabled.
- NETAssemblyTypeAcceleratorMode AssemblyTypeAcceleratorExportMode
- Controls optional type accelerator exposure for dependency types loaded in the module AssemblyLoadContext.
- Possible values:
AllowList,Assembly,Enums - NETAssemblyTypeAccelerators String[]
- Fully-qualified dependency type names to expose as PowerShell type accelerators from the module AssemblyLoadContext.
- NETBinaryModule String[]
- Binary module names (DLL file names) to import in the module.
- NETBinaryModuleCmdletScanDisabled SwitchParameter
- Disable cmdlet scanning for the binary module.
- NETBinaryModuleDocumentation SwitchParameter
- Enable binary module documentation.
- NETConfiguration String
- Build configuration for .NET projects (Release or Debug).
- Possible values:
Release,Debug - NETDevelopmentBinaries SwitchParameter
- Generate checked-in source bootstrapper logic for local development binary outputs.
- NETDevelopmentBinariesEnvironmentVariable String
- Optional environment variable used by Environment development-binary mode.
- NETDevelopmentBinariesMode ModuleDevelopmentBinaryMode
- Controls when the generated source bootstrapper loads local development binaries.
- Possible values:
Off,Environment,Auto - NETDevelopmentBinariesPath String
- Optional root folder that contains configuration/framework development binary outputs.
- NETDevelopmentConfigurationEnvironmentVariable String
- Optional environment variable that chooses the development build configuration.
- NETDevelopmentSourceBootstrapperMode ModuleDevelopmentSourceBootstrapperMode
- Controls how the source PSM1 is maintained when development binary bootstrapping is enabled.
- Possible values:
PreserveSingleFile,ReplaceSingleFile - NETDoNotCopyLibrariesRecursively SwitchParameter
- Do not copy libraries recursively (legacy option).
- NETExcludeLibraryFilter String[]
- Filters for libraries that should be excluded from build output.
- NETExcludeMainLibrary SwitchParameter
- Exclude main library from build output.
- NETFramework String[]
- Target frameworks for .NET build.
- NETHandleAssemblyWithSameName SwitchParameter
- Handle 'assembly with same name is already loaded' by wrapping Add-Type logic.
- NETHandleRuntimes SwitchParameter
- Handle runtimes folder when copying libraries.
- NETIgnoreLibraryOnLoad String[]
- Exclude libraries from being loaded by PSM1/Libraries.ps1.
- NETLineByLineAddType SwitchParameter
- Add-Type libraries line by line (legacy debugging option).
- NETMergeLibraryDebugging SwitchParameter
- Debug DLL merge (legacy setting).
- NETProjectName String
- Project name for the .NET project (required when NETProjectPath is provided).
- NETProjectPath String
- Path to the .NET project to build (useful when not in Sources folder).
- NETResolveBinaryConflicts SwitchParameter
- Enable resolving binary conflicts.
- NETResolveBinaryConflictsName String
- Project name used when resolving binary conflicts.
- NETSearchClass String
- Search class (legacy option).
- PowerShellCompilationAllowUnreviewedDependencies SwitchParameter
- Explicitly allow dependency resolution without a separately reviewed lock.
- PowerShellCompilationBuildCacheDirectory String
- Optional machine-local root for generated-build cache entries.
- PowerShellCompilationDependencyLock PowerShellCompilationDependencyGraph
- Reviewed dependency graph that the compilation build must reproduce exactly.
- PowerShellCompilationEmitIrSnapshots SwitchParameter
- Publish a redacted semantic-only bound/lowered IR snapshot beside canonical evidence.
- PowerShellCompilationExcludeResource String[]
- Contained module-root resource paths or glob patterns to exclude.
- PowerShellCompilationExpectedPublicAbiSha256 String
- Reviewed public ABI SHA-256 that the generated binary module must match.
- PowerShellCompilationIncludeResource String[]
- Contained module-root resource paths or glob patterns to include.
- PowerShellCompilationMode PowerShellCompilationMode
- Choose Hybrid fallback or require complete Strict compilation.
- Possible values:
Hybrid,Strict - PowerShellCompilationResourceMode PowerShellCompilationResourceMode
- Policy used to select non-code payload for the generated module.
- Possible values:
Declared,CompleteModule - PowerShellCompilationTargetFramework String
- Target framework for the generated binary module.
- PowerShellCompilationTimeoutSeconds Int32
- Maximum seconds allowed for restore and compilation.
- PowerShellCompilationUseBuildCache SwitchParameter
- Enable or disable the content-addressed generated-build cache.
- RefreshPSD1Only SwitchParameter
- Only regenerate the manifest (PSD1) without rebuilding/merging other artefacts.
- ResolveMissingModulesOnline SwitchParameter
- Resolve Auto/Latest dependency versions from the repository without installing. When not explicitly set, this is auto-enabled if any RequiredModules use Auto/Latest/Guid Auto.
- SeparateFileLibraries SwitchParameter
- Write library-loading code into a distinct file and reference it via ScriptsToProcess/DotSource.
- SignCustomInclude String[]
- Override include patterns passed to the signer.
- SignExcludePaths String[]
- Additional path substrings to exclude from signing.
- SignIncludeBinaries SwitchParameter
- When signing is enabled, binaries are signed by default (e.g., .dll, .cat). Use -SignIncludeBinaries:$false to opt out.
- SignIncludeExe SwitchParameter
- When signing is enabled, include .exe files in signing.
- SignIncludeInternals SwitchParameter
- When signing is enabled, also sign scripts that reside under the Internals folder.
- SignModule SwitchParameter
- Enable code-signing for the built module output.
- SignOverwriteSigned SwitchParameter
- When signing is enabled, overwrite existing signatures (re-sign files).
- SkipBuiltinReplacements SwitchParameter
- Disables built-in replacements done by the module builder.
- SyncNETProjectVersion SwitchParameter
- Synchronize the source .NET project version with the resolved module/manifest version before staging. This is opt-in and updates the source .csproj file when a project path can be resolved.
- UseWildcardForFunctions SwitchParameter
- Export all functions/aliases via wildcard in PSD1.
- VersionedInstallKeep Int32
- How many versions to keep per module when using versioned installs.
- VersionedInstallLegacyFlatHandling LegacyFlatModuleHandling
- How to handle legacy flat module installs during install.
- Possible values:
Warn,Convert,Delete,Ignore - VersionedInstallPreserveVersions String[]
- Version folders to preserve during install pruning (for example older major versions).
- VersionedInstallStrategy InstallationStrategy
- Controls how the module is installed into user Module roots after build.
- Possible values:
Exact,AutoRevision - WarnIfRequiredModulesOutdated SwitchParameter
- Warn if RequiredModule entries are older than the latest version available in the repository. This is a reporting hint and does not change the manifest or install anything by itself.