Command

New-ConfigurationBuild

Module PSPublishModule

Inputs

None

Allows configuring the build process for a module.

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 Sets

Description

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

Authored help example

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.

Parameters

-AutoSwitchExactOnPublish SwitchParameter optional: Auto switch VersionedInstallStrategy to Exact when publishing.
-CertificatePFXBase64 String optional: Base64 string of a PFX containing a code-signing certificate.
-CertificatePFXPassword String optional: Password for the PFX provided via CertificatePFXPath or CertificatePFXBase64.
-CertificatePFXPath String optional: Path to a PFX containing a code-signing certificate.
-CertificateThumbprint String optional: Thumbprint of a code-signing certificate from the local cert store.
-CompilePowerShell SwitchParameter optionalaliases: Compile: Compile the staged PowerShell module into a generated binary module.
-DeleteTargetModuleBeforeBuild SwitchParameter optional: Delete target module before build.
-DoNotAttemptToFixRelativePaths SwitchParameter optional: Do not attempt to fix relative paths during merge.
-DotSourceClasses SwitchParameter optional: Keep classes in a separate dot-sourced file instead of merging into the main PSM1.
-DotSourceLibraries SwitchParameter optional: Keep library-loading code in a separate dot-sourced file.
-Enable SwitchParameter optional: Enable build process.
-InstallMissingModules SwitchParameter optional: Install missing module dependencies (RequiredModule/ExternalModule) before build. This affects the build host only; it does not bundle modules into artefacts.
-InstallMissingModulesCredentialSecret String optional: 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 optional: Path to a file containing the credential secret or token. This is often the safest option for automation and CI agents.
-InstallMissingModulesCredentialUserName String optional: Credential user name for dependency installation. This is usually paired with InstallMissingModulesCredentialSecret or InstallMissingModulesCredentialSecretFilePath.
-InstallMissingModulesForce SwitchParameter optional: 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 optional: Allow prerelease versions when installing dependencies. Use this only when the dependency declaration and repository policy intentionally allow prerelease packages.
-InstallMissingModulesRepository String optional: 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 optional: Kill locking processes before install.
-KillLockersForce SwitchParameter optional: Force killing locking processes before install.
-LocalVersioning SwitchParameter optional: Use local versioning (bump PSD1 version on each build without querying PSGallery).
-MergeFunctionsFromApprovedModules SwitchParameter optional: When merging, also include functions from ApprovedModules referenced by the module.
-MergeModuleOnBuild SwitchParameter optional: Merge module on build (combine Private/Public/Classes/Enums into one PSM1).
-NETAssemblyLoadContext SwitchParameter optionalaliases: UseAssemblyLoadContext: Load the binary module through a custom AssemblyLoadContext on PowerShell Core.
-NETAssemblyTypeAcceleratorAssemblies String[] optionalaliases: AssemblyTypeAcceleratorAssemblies: Assembly simple names whose public types may be exposed as PowerShell type accelerators when assembly mode is enabled.
-NETAssemblyTypeAcceleratorMode AssemblyTypeAcceleratorExportMode optionalaliases: AssemblyTypeAcceleratorMode: Controls optional type accelerator exposure for dependency types loaded in the module AssemblyLoadContext.; Possible values: AllowList, Assembly, Enums
-NETAssemblyTypeAccelerators String[] optionalaliases: AssemblyTypeAccelerators: Fully-qualified dependency type names to expose as PowerShell type accelerators from the module AssemblyLoadContext.
-NETBinaryModule String[] optional: Binary module names (DLL file names) to import in the module.
-NETBinaryModuleCmdletScanDisabled SwitchParameter optional: Disable cmdlet scanning for the binary module.
-NETBinaryModuleDocumentation SwitchParameter optionalaliases: NETBinaryModuleDocumenation, NETDocumentation: Enable binary module documentation.
-NETConfiguration String optional: Build configuration for .NET projects (Release or Debug).; Possible values: Release, Debug
-NETDevelopmentBinaries SwitchParameter optional: Generate checked-in source bootstrapper logic for local development binary outputs.
-NETDevelopmentBinariesEnvironmentVariable String optional: Optional environment variable used by Environment development-binary mode.
-NETDevelopmentBinariesMode ModuleDevelopmentBinaryMode optional: Controls when the generated source bootstrapper loads local development binaries.; Possible values: Off, Environment, Auto
-NETDevelopmentBinariesPath String optional: Optional root folder that contains configuration/framework development binary outputs.
-NETDevelopmentConfigurationEnvironmentVariable String optional: Optional environment variable that chooses the development build configuration.
-NETDevelopmentSourceBootstrapperMode ModuleDevelopmentSourceBootstrapperMode optional: Controls how the source PSM1 is maintained when development binary bootstrapping is enabled.; Possible values: PreserveSingleFile, ReplaceSingleFile
-NETDoNotCopyLibrariesRecursively SwitchParameter optional: Do not copy libraries recursively (legacy option).
-NETExcludeLibraryFilter String[] optional: Filters for libraries that should be excluded from build output.
-NETExcludeMainLibrary SwitchParameter optional: Exclude main library from build output.
-NETFramework String[] optional: Target frameworks for .NET build.
-NETHandleAssemblyWithSameName SwitchParameter optionalaliases: HandleAssemblyWithSameName: Handle 'assembly with same name is already loaded' by wrapping Add-Type logic.
-NETHandleRuntimes SwitchParameter optional: Handle runtimes folder when copying libraries.
-NETIgnoreLibraryOnLoad String[] optional: Exclude libraries from being loaded by PSM1/Libraries.ps1.
-NETLineByLineAddType SwitchParameter optional: Add-Type libraries line by line (legacy debugging option).
-NETMergeLibraryDebugging SwitchParameter optionalaliases: MergeLibraryDebugging: Debug DLL merge (legacy setting).
-NETProjectName String optional: Project name for the .NET project (required when NETProjectPath is provided).
-NETProjectPath String optional: Path to the .NET project to build (useful when not in Sources folder).
-NETResolveBinaryConflicts SwitchParameter optionalaliases: ResolveBinaryConflicts: Enable resolving binary conflicts.
-NETResolveBinaryConflictsName String optionalaliases: ResolveBinaryConflictsName: Project name used when resolving binary conflicts.
-NETSearchClass String optional: Search class (legacy option).
-PowerShellCompilationAllowUnreviewedDependencies SwitchParameter optional: Explicitly allow dependency resolution without a separately reviewed lock.
-PowerShellCompilationBuildCacheDirectory String optional: Optional machine-local root for generated-build cache entries.
-PowerShellCompilationDependencyLock PowerShellCompilationDependencyGraph optional: Reviewed dependency graph that the compilation build must reproduce exactly.
-PowerShellCompilationEmitIrSnapshots SwitchParameter optional: Publish a redacted semantic-only bound/lowered IR snapshot beside canonical evidence.
-PowerShellCompilationExcludeResource String[] optional: Contained module-root resource paths or glob patterns to exclude.
-PowerShellCompilationExpectedPublicAbiSha256 String optional: Reviewed public ABI SHA-256 that the generated binary module must match.
-PowerShellCompilationIncludeResource String[] optional: Contained module-root resource paths or glob patterns to include.
-PowerShellCompilationMode PowerShellCompilationMode optional: Choose Hybrid fallback or require complete Strict compilation.; Possible values: Hybrid, Strict
-PowerShellCompilationResourceMode PowerShellCompilationResourceMode optional: Policy used to select non-code payload for the generated module.; Possible values: Declared, CompleteModule
-PowerShellCompilationTargetFramework String optional: Target framework for the generated binary module.
-PowerShellCompilationTimeoutSeconds Int32 optional: Maximum seconds allowed for restore and compilation.
-PowerShellCompilationUseBuildCache SwitchParameter optional: Enable or disable the content-addressed generated-build cache.
-RefreshPSD1Only SwitchParameter optional: Only regenerate the manifest (PSD1) without rebuilding/merging other artefacts.
-ResolveMissingModulesOnline SwitchParameter optional: 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 optional: Write library-loading code into a distinct file and reference it via ScriptsToProcess/DotSource.
-SignCustomInclude String[] optional: Override include patterns passed to the signer.
-SignExcludePaths String[] optional: Additional path substrings to exclude from signing.
-SignIncludeBinaries SwitchParameter optional: When signing is enabled, binaries are signed by default (e.g., .dll, .cat). Use -SignIncludeBinaries:$false to opt out.
-SignIncludeExe SwitchParameter optional: When signing is enabled, include .exe files in signing.
-SignIncludeInternals SwitchParameter optional: When signing is enabled, also sign scripts that reside under the Internals folder.
-SignModule SwitchParameter optional: Enable code-signing for the built module output.
-SignOverwriteSigned SwitchParameter optional: When signing is enabled, overwrite existing signatures (re-sign files).
-SkipBuiltinReplacements SwitchParameter optional: Disables built-in replacements done by the module builder.
-SyncNETProjectVersion SwitchParameter optional: 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 optional: Export all functions/aliases via wildcard in PSD1.
-VersionedInstallKeep Int32 optional: How many versions to keep per module when using versioned installs.
-VersionedInstallLegacyFlatHandling LegacyFlatModuleHandling optional: How to handle legacy flat module installs during install.; Possible values: Warn, Convert, Delete, Ignore
-VersionedInstallPreserveVersions String[] optional: Version folders to preserve during install pruning (for example older major versions).
-VersionedInstallStrategy InstallationStrategy optional: Controls how the module is installed into user Module roots after build.; Possible values: Exact, AutoRevision
-WarnIfRequiredModulesOutdated SwitchParameter optional: 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.

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.