Command

Invoke-ModuleBuild

Module PSPublishModule

Inputs

None

Outputs

PowerForge.ModulePipelineResult

Creates/updates a module structure and triggers the build pipeline (legacy DSL compatible).

Syntax

Invoke-ModuleBuild [-AliasesToExportFolder <String>] [-CsprojPath <String>] [-DiagnosticsBaselinePath <String>] [-DiagnosticsBinaryConflictSearchRoot <String[]>] [-DotNetConfiguration <Release|Debug>] [-DotNetFramework <String[]>] [-ExcludeDirectories <String[]>] [-ExcludeFiles <String[]>] [-ExcludeFromPackage <String[]>] [-ExitCode] [-FailOnDiagnosticsSeverity <Warning|Error>] [-FailOnNewDiagnostics] [-FunctionsToExportFolder <String>] [-GenerateDiagnosticsBaseline] [-IncludeAll <String[]>] [-IncludeCustomCode <ScriptBlock>] [-IncludePS1 <String[]>] [-IncludeRoot <String[]>] [-IncludeToArray <IDictionary>] [-InstallRoots <String[]>] [-InstallStrategy <Exact|AutoRevision>] [-JsonOnly] [-JsonPath <String>] [-KeepStaging] [-KeepVersions <Int32>] [-Legacy] [-LegacyFlatHandling <Warn|Convert|Delete|Ignore>] [-LibrariesCore <String>] [-LibrariesDefault <String>] [-LibrariesStandard <String>] -ModuleName <String> [-NoInteractive] [-PassThru] [-Path <String>] [-PreserveInstallVersions <String[]>] [-Quiet] [-RunMode <Manifest|Build|Publish|Documentation>] [[-Settings] <ScriptBlock>] [-SkipInstall] [-StagingPath <String>] [-UpdateDiagnosticsBaseline] [<CommonParameters>]

Parameter set: Modern

Invoke-ModuleBuild [-BuildConfiguration <Release|Debug>] [-BuildFramework <auto|net10.0|net8.0|net472>] [-CertificateThumbprint <String>] -ConfigPath <String> [-DiagnosticsBaselinePath <String>] [-DiagnosticsBinaryConflictSearchRoot <String[]>] [-ExcludeDirectories <String[]>] [-ExcludeFiles <String[]>] [-ExitCode] [-FailOnDiagnosticsSeverity <Warning|Error>] [-FailOnNewDiagnostics] [-GenerateDiagnosticsBaseline] [-IncludeModulePublishing <Boolean>] [-IncludeProjectPackages <Boolean>] [-JsonOnly] [-JsonPath <String>] [-Legacy] [-ModuleVersion <String>] [-NoDotnetBuild] [-NoInteractive] [-NoSign] [-PassThru] [-PowerForgeUnifiedGitHubRelease] [-PreReleaseTag <String>] [-Quiet] [-RunMode <Manifest|Build|Publish|Documentation>] [-SignIncludeBinaries <Boolean>] [-SignIncludeExe <Boolean>] [-SignIncludeInternals <Boolean>] [-SignModule] [-SkipInstall] [-StagingPath <String>] [-UpdateDiagnosticsBaseline] [<CommonParameters>]

Parameter set: Config

Invoke-ModuleBuild -Configuration <IDictionary> [-DiagnosticsBaselinePath <String>] [-DiagnosticsBinaryConflictSearchRoot <String[]>] [-ExcludeDirectories <String[]>] [-ExcludeFiles <String[]>] [-ExitCode] [-FailOnDiagnosticsSeverity <Warning|Error>] [-FailOnNewDiagnostics] [-GenerateDiagnosticsBaseline] [-JsonOnly] [-JsonPath <String>] [-Legacy] [-NoInteractive] [-PassThru] [-Quiet] [-RunMode <Manifest|Build|Publish|Documentation>] [-UpdateDiagnosticsBaseline] [<CommonParameters>]

Parameter set: Configuration

Description

This is the primary entry point for building a PowerShell module using PSPublishModule. Configuration is provided via a DSL using New-Configuration* cmdlets (typically inside the -Settings scriptblock) and then executed by the PowerForge pipeline runner.

To generate a reusable powerforge.json configuration file (for the PowerForge CLI) without running any build steps, use -JsonOnly with -JsonPath.

When running in an interactive terminal, pipeline execution uses a Spectre.Console progress UI. Redirect output or use -Verbose to force plain, line-by-line output (useful for CI logs).

Dependency behavior is composed from the configuration segments you emit. Typically this means: New-ConfigurationModule declares dependencies, New-ConfigurationBuild decides whether the build host should install missing ones, and New-ConfigurationArtefact decides whether required modules should be bundled into the output artefact.

Examples

Authored help example

Build a module (DSL) and keep docs in sync

Invoke-ModuleBuild -ModuleName 'MyModule' -Path 'C:\Git' -Settings {
    New-ConfigurationDocumentation -Enable -Path 'Docs' -PathReadme 'Docs\Readme.md'
}

Generate a PowerForge JSON pipeline without running the build

Invoke-ModuleBuild -ModuleName 'MyModule' -Path 'C:\Git' -JsonOnly -JsonPath 'C:\Git\MyModule\powerforge.json'

Enforce consistency and compatibility during build (fail CI on issues)

Invoke-ModuleBuild -ModuleName 'MyModule' -Path 'C:\Git' -ExitCode -Settings {
    New-ConfigurationFileConsistency -Enable -FailOnInconsistency -AutoFix -CreateBackups -ExportReport
    New-ConfigurationCompatibility -Enable -RequireCrossCompatibility -FailOnIncompatibility -ExportReport
}

Publish a .NET project into the module as part of the build

Invoke-ModuleBuild -ModuleName 'MyModule' -Path 'C:\Git' `
    -CsprojPath 'C:\Git\MyModule\src\MyModule\MyModule.csproj' -DotNetFramework net8.0 -DotNetConfiguration Release `
    -Settings { New-ConfigurationBuild -Enable -MergeModuleOnBuild }

Fail CI only on new diagnostics compared to a committed baseline

Invoke-ModuleBuild -ModuleName 'MyModule' -Path 'C:\Git' `
    -DiagnosticsBaselinePath 'C:\Git\MyModule\.powerforge\module-diagnostics-baseline.json' `
    -FailOnNewDiagnostics -FailOnDiagnosticsSeverity Warning

Install missing dependencies during the build and bundle required modules into the package

Invoke-ModuleBuild -ModuleName 'MyModule' -Path 'C:\Git' -Settings {
    New-ConfigurationModule -Type RequiredModule -Name 'Pester' -Version 'Latest' -Guid 'Auto'
    New-ConfigurationBuild -Enable -InstallMissingModules -ResolveMissingModulesOnline
    New-ConfigurationArtefact -Type Packed -Enable -AddRequiredModules -RequiredModulesSource Auto
}

Parameters

-AliasesToExportFolder String optionalsets: Modern: Folder name containing aliases to export. Default: Public.
-CsprojPath String optionalsets: Modern: Optional path to a .NET project (.csproj) to publish into the module.
-DiagnosticsBaselinePath String optional: Optional path to a diagnostics baseline file used to compare current issues with known issues.
-DiagnosticsBinaryConflictSearchRoot String[] optional: Optional module roots to scan for deterministic binary conflict diagnostics. When provided, conflict findings can participate in diagnostics baselines and policy.
-DotNetConfiguration String optionalsets: Modern: Build configuration for publishing the .NET project (Release or Debug).; Possible values: Release, Debug
-DotNetFramework String[] optionalsets: Modern: Target frameworks to publish (e.g., net472, net8.0).
-ExcludeDirectories String[] optional: Directory names excluded from staging copy (matched by directory name, not by path).
-ExcludeFiles String[] optional: File names excluded from staging copy (matched by file name, not by path).
-ExcludeFromPackage String[] optionalsets: Modern: Exclude patterns for artefact packaging.
-ExitCode SwitchParameter optional: When specified, requests the host to exit with code 0 on success and 1 on failure.
-FailOnDiagnosticsSeverity BuildDiagnosticSeverity optional: Fails the build when diagnostics at or above the specified severity are present.; Possible values: Warning, Error
-FailOnNewDiagnostics SwitchParameter optional: Fails the build when diagnostics appear that are not present in the loaded baseline.
-FunctionsToExportFolder String optionalsets: Modern: Folder name containing functions to export. Default: Public.
-GenerateDiagnosticsBaseline SwitchParameter optional: Writes a diagnostics baseline file from the current run.
-IncludeAll String[] optionalsets: Modern: Folders from which to include all files in artefacts.
-IncludeCustomCode ScriptBlock optionalsets: Modern: Optional script block executed during staging that can add custom files/folders to the build.
-IncludePS1 String[] optionalsets: Modern: Folders from which to include .ps1 files in artefacts.
-IncludeRoot String[] optionalsets: Modern: Include patterns for root files in artefacts.
-IncludeToArray IDictionary optionalsets: Modern: Advanced hashtable form for includes (maps IncludeRoot/IncludePS1/IncludeAll etc).
-InstallRoots String[] optionalsets: Modern: Destination module roots for install. When omitted, defaults are used.
-InstallStrategy InstallationStrategy optionalsets: Modern: Installation strategy used when installing the module.; Possible values: Exact, AutoRevision
-JsonOnly SwitchParameter optional: Generates a PowerForge pipeline JSON file and exits without running the build pipeline. Intended for migrating legacy DSL scripts to powerforge CLI configuration.
-JsonPath String optional: Output path for the generated pipeline JSON file (used with JsonOnly). Defaults to powerforge.json in the project root.
-KeepStaging SwitchParameter optionalsets: Modern: Keep staging directory after build/install.
-KeepVersions Int32 optionalsets: Modern: Number of versions to keep per module root when installing.
-Legacy SwitchParameter optional: Compatibility switch. Historically forced the PowerShell-script build pipeline; the build now always runs through the C# PowerForge pipeline.
-LegacyFlatHandling LegacyFlatModuleHandling optionalsets: Modern: How to handle legacy flat installs found under module roots.; Possible values: Warn, Convert, Delete, Ignore
-LibrariesCore String optionalsets: Modern: Alternate relative path for .NET Core-targeted libraries folder. Default: Lib/Core.
-LibrariesDefault String optionalsets: Modern: Alternate relative path for .NET Framework-targeted libraries folder. Default: Lib/Default.
-LibrariesStandard String optionalsets: Modern: Alternate relative path for .NET Standard-targeted libraries folder. Default: Lib/Standard.
-ModuleName String requiredaliases: ProjectNamesets: Modern: Name of the module being built.
-NoInteractive SwitchParameter optional: Disables the interactive progress UI and emits plain log output.
-PassThru SwitchParameter optional: Writes the completed module pipeline result to the PowerShell success stream.
-Path String optionalsets: Modern: Path to the parent folder where the project exists or should be created. The module project resolves to Path\ModuleName. When omitted, uses the parent of the calling script directory.
-PreserveInstallVersions String[] optionalsets: Modern: Version folders to preserve when pruning installed versions.
-Quiet SwitchParameter optional: Suppresses host rendering and log output. Intended for callers that request structured results.
-RunMode ConfigurationGateMode optionalaliases: ConfigurationGateMode: High-level module build lane. Manifest refreshes PSD1 metadata only, Documentation regenerates command Markdown and external help without validation/tests/signing/package/install phases, Build runs local build/package lanes, and Publish enables configured publish destinations.; Possible values: Manifest, Build, Publish, Documentation
-Settings ScriptBlock optionalposition: 0sets: Modern: Provides settings for the module in the form of a script block (DSL).
-SkipInstall SwitchParameter optionalsets: Modern, Config: Skips installing the module after build.
-StagingPath String optionalsets: Modern, Config: Staging directory for the PowerForge pipeline. When omitted, a temporary folder is generated.
-UpdateDiagnosticsBaseline SwitchParameter optional: Updates a diagnostics baseline file from the current run.
-BuildConfiguration String optionalsets: Config: Overrides the .NET build configuration declared by a JSON configuration.; Possible values: Release, Debug
-BuildFramework String optionalsets: Config: Overrides the .NET framework declared by a JSON configuration. Auto preserves the configured framework matrix.; Possible values: auto, net10.0, net8.0, net472
-CertificateThumbprint String optionalsets: Config: Overrides the signing certificate thumbprint declared by a JSON configuration.
-ConfigPath String requiredsets: Config: Path to a module pipeline JSON config generated by Invoke-ModuleBuild -JsonOnly.
-IncludeModulePublishing Boolean optionalsets: Config: Controls whether module repository and GitHub publish segments declared by a JSON configuration are included. Parent release hosts disable them when publishing signed checkpointed module artifacts directly.
-IncludeProjectPackages Boolean optionalsets: Config: Controls whether project/package segments declared by a JSON configuration are included. Unified release orchestration disables them when the outer package lane owns publication.
-ModuleVersion String optionalsets: Config: Overrides the module version declared by a JSON configuration.
-NoDotnetBuild SwitchParameter optionalsets: Config: Skips the configured .NET project build and reuses the existing module binary payload.
-NoSign SwitchParameter optionalsets: Config: Disables module signing declared by a JSON configuration.
-PowerForgeUnifiedGitHubRelease SwitchParameter optionalsets: Config: Indicates that a parent unified release owns GitHub publication and suppresses GitHub publish segments declared by the JSON module configuration.
-PreReleaseTag String optionalsets: Config: Overrides the prerelease tag declared by a JSON configuration.
-SignIncludeBinaries Boolean optionalsets: Config: Overrides whether binary files are signed for a JSON configuration.
-SignIncludeExe Boolean optionalsets: Config: Overrides whether executable files are signed for a JSON configuration.
-SignIncludeInternals Boolean optionalsets: Config: Overrides whether internal files are signed for a JSON configuration.
-SignModule SwitchParameter optionalsets: Config: Enables module signing declared by a JSON configuration.
-Configuration IDictionary requiredsets: Configuration: Legacy configuration dictionary for backwards compatibility.

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.