API Reference
Command
Invoke-ModuleBuild
Creates/updates a module structure and triggers the build pipeline (legacy DSL compatible).
Remarks
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
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
}
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
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:
ModernParameters
- AliasesToExportFolder String
- Folder name containing aliases to export. Default: Public.
- CsprojPath String
- Optional path to a .NET project (.csproj) to publish into the module.
- DiagnosticsBaselinePath String
- Optional path to a diagnostics baseline file used to compare current issues with known issues.
- DiagnosticsBinaryConflictSearchRoot String[]
- Optional module roots to scan for deterministic binary conflict diagnostics. When provided, conflict findings can participate in diagnostics baselines and policy.
- DotNetConfiguration String
- Build configuration for publishing the .NET project (Release or Debug).
- Possible values:
Release,Debug - DotNetFramework String[]
- Target frameworks to publish (e.g., net472, net8.0).
- ExcludeDirectories String[]
- Directory names excluded from staging copy (matched by directory name, not by path).
- ExcludeFiles String[]
- File names excluded from staging copy (matched by file name, not by path).
- ExcludeFromPackage String[]
- Exclude patterns for artefact packaging.
- ExitCode SwitchParameter
- When specified, requests the host to exit with code 0 on success and 1 on failure.
- FailOnDiagnosticsSeverity BuildDiagnosticSeverity
- Fails the build when diagnostics at or above the specified severity are present.
- Possible values:
Warning,Error - FailOnNewDiagnostics SwitchParameter
- Fails the build when diagnostics appear that are not present in the loaded baseline.
- FunctionsToExportFolder String
- Folder name containing functions to export. Default: Public.
- GenerateDiagnosticsBaseline SwitchParameter
- Writes a diagnostics baseline file from the current run.
- IncludeAll String[]
- Folders from which to include all files in artefacts.
- IncludeCustomCode ScriptBlock
- Optional script block executed during staging that can add custom files/folders to the build.
- IncludePS1 String[]
- Folders from which to include .ps1 files in artefacts.
- IncludeRoot String[]
- Include patterns for root files in artefacts.
- IncludeToArray IDictionary
- Advanced hashtable form for includes (maps IncludeRoot/IncludePS1/IncludeAll etc).
- InstallRoots String[]
- Destination module roots for install. When omitted, defaults are used.
- InstallStrategy InstallationStrategy
- Installation strategy used when installing the module.
- Possible values:
Exact,AutoRevision - JsonOnly SwitchParameter
- 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
- Output path for the generated pipeline JSON file (used with JsonOnly). Defaults to powerforge.json in the project root.
- KeepStaging SwitchParameter
- Keep staging directory after build/install.
- KeepVersions Int32
- Number of versions to keep per module root when installing.
- Legacy SwitchParameter
- Compatibility switch. Historically forced the PowerShell-script build pipeline; the build now always runs through the C# PowerForge pipeline.
- LegacyFlatHandling LegacyFlatModuleHandling
- How to handle legacy flat installs found under module roots.
- Possible values:
Warn,Convert,Delete,Ignore - LibrariesCore String
- Alternate relative path for .NET Core-targeted libraries folder. Default: Lib/Core.
- LibrariesDefault String
- Alternate relative path for .NET Framework-targeted libraries folder. Default: Lib/Default.
- LibrariesStandard String
- Alternate relative path for .NET Standard-targeted libraries folder. Default: Lib/Standard.
- ModuleName String
- Name of the module being built.
- NoInteractive SwitchParameter
- Disables the interactive progress UI and emits plain log output.
- PassThru SwitchParameter
- Writes the completed module pipeline result to the PowerShell success stream.
- Path String
- 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[]
- Version folders to preserve when pruning installed versions.
- Quiet SwitchParameter
- Suppresses host rendering and log output. Intended for callers that request structured results.
- RunMode 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
- Provides settings for the module in the form of a script block (DSL).
- SkipInstall SwitchParameter
- Skips installing the module after build.
- StagingPath String
- Staging directory for the PowerForge pipeline. When omitted, a temporary folder is generated.
- UpdateDiagnosticsBaseline SwitchParameter
- Updates a diagnostics baseline file from the current run.
Outputs
PowerForge.ModulePipelineResult
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:
ConfigParameters
- BuildConfiguration String
- Overrides the .NET build configuration declared by a JSON configuration.
- Possible values:
Release,Debug - BuildFramework String
- 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
- Overrides the signing certificate thumbprint declared by a JSON configuration.
- ConfigPath String
- Path to a module pipeline JSON config generated by Invoke-ModuleBuild -JsonOnly.
- DiagnosticsBaselinePath String
- Optional path to a diagnostics baseline file used to compare current issues with known issues.
- DiagnosticsBinaryConflictSearchRoot String[]
- Optional module roots to scan for deterministic binary conflict diagnostics. When provided, conflict findings can participate in diagnostics baselines and policy.
- ExcludeDirectories String[]
- Directory names excluded from staging copy (matched by directory name, not by path).
- ExcludeFiles String[]
- File names excluded from staging copy (matched by file name, not by path).
- ExitCode SwitchParameter
- When specified, requests the host to exit with code 0 on success and 1 on failure.
- FailOnDiagnosticsSeverity BuildDiagnosticSeverity
- Fails the build when diagnostics at or above the specified severity are present.
- Possible values:
Warning,Error - FailOnNewDiagnostics SwitchParameter
- Fails the build when diagnostics appear that are not present in the loaded baseline.
- GenerateDiagnosticsBaseline SwitchParameter
- Writes a diagnostics baseline file from the current run.
- IncludeModulePublishing Boolean
- 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
- Controls whether project/package segments declared by a JSON configuration are included. Unified release orchestration disables them when the outer package lane owns publication.
- JsonOnly SwitchParameter
- 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
- Output path for the generated pipeline JSON file (used with JsonOnly). Defaults to powerforge.json in the project root.
- Legacy SwitchParameter
- Compatibility switch. Historically forced the PowerShell-script build pipeline; the build now always runs through the C# PowerForge pipeline.
- ModuleVersion String
- Overrides the module version declared by a JSON configuration.
- NoDotnetBuild SwitchParameter
- Skips the configured .NET project build and reuses the existing module binary payload.
- NoInteractive SwitchParameter
- Disables the interactive progress UI and emits plain log output.
- NoSign SwitchParameter
- Disables module signing declared by a JSON configuration.
- PassThru SwitchParameter
- Writes the completed module pipeline result to the PowerShell success stream.
- PowerForgeUnifiedGitHubRelease SwitchParameter
- Indicates that a parent unified release owns GitHub publication and suppresses GitHub publish segments declared by the JSON module configuration.
- PreReleaseTag String
- Overrides the prerelease tag declared by a JSON configuration.
- Quiet SwitchParameter
- Suppresses host rendering and log output. Intended for callers that request structured results.
- RunMode 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 - SignIncludeBinaries Boolean
- Overrides whether binary files are signed for a JSON configuration.
- SignIncludeExe Boolean
- Overrides whether executable files are signed for a JSON configuration.
- SignIncludeInternals Boolean
- Overrides whether internal files are signed for a JSON configuration.
- SignModule SwitchParameter
- Enables module signing declared by a JSON configuration.
- SkipInstall SwitchParameter
- Skips installing the module after build.
- StagingPath String
- Staging directory for the PowerForge pipeline. When omitted, a temporary folder is generated.
- UpdateDiagnosticsBaseline SwitchParameter
- Updates a diagnostics baseline file from the current run.
Outputs
PowerForge.ModulePipelineResult
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:
ConfigurationParameters
- Configuration IDictionary
- Legacy configuration dictionary for backwards compatibility.
- DiagnosticsBaselinePath String
- Optional path to a diagnostics baseline file used to compare current issues with known issues.
- DiagnosticsBinaryConflictSearchRoot String[]
- Optional module roots to scan for deterministic binary conflict diagnostics. When provided, conflict findings can participate in diagnostics baselines and policy.
- ExcludeDirectories String[]
- Directory names excluded from staging copy (matched by directory name, not by path).
- ExcludeFiles String[]
- File names excluded from staging copy (matched by file name, not by path).
- ExitCode SwitchParameter
- When specified, requests the host to exit with code 0 on success and 1 on failure.
- FailOnDiagnosticsSeverity BuildDiagnosticSeverity
- Fails the build when diagnostics at or above the specified severity are present.
- Possible values:
Warning,Error - FailOnNewDiagnostics SwitchParameter
- Fails the build when diagnostics appear that are not present in the loaded baseline.
- GenerateDiagnosticsBaseline SwitchParameter
- Writes a diagnostics baseline file from the current run.
- JsonOnly SwitchParameter
- 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
- Output path for the generated pipeline JSON file (used with JsonOnly). Defaults to powerforge.json in the project root.
- Legacy SwitchParameter
- Compatibility switch. Historically forced the PowerShell-script build pipeline; the build now always runs through the C# PowerForge pipeline.
- NoInteractive SwitchParameter
- Disables the interactive progress UI and emits plain log output.
- PassThru SwitchParameter
- Writes the completed module pipeline result to the PowerShell success stream.
- Quiet SwitchParameter
- Suppresses host rendering and log output. Intended for callers that request structured results.
- RunMode 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 - UpdateDiagnosticsBaseline SwitchParameter
- Updates a diagnostics baseline file from the current run.
Outputs
PowerForge.ModulePipelineResult