Invoke-ModuleBuild.md

external help file	PSPublishModule-help.xml
Module Name	PSPublishModule
online version	https://github.com/EvotecIT/PSPublishModule
schema	2.0.0

Invoke-ModuleBuild

SYNOPSIS

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

SYNTAX

Modern (Default)

Invoke-ModuleBuild [[-Settings] <scriptblock>] -ModuleName <string> [-Path <string>] [-FunctionsToExportFolder <string>] [-AliasesToExportFolder <string>] [-ExcludeFromPackage <string[]>] [-ExcludeDirectories <string[]>] [-ExcludeFiles <string[]>] [-IncludeRoot <string[]>] [-IncludePS1 <string[]>] [-IncludeAll <string[]>] [-IncludeCustomCode <scriptblock>] [-IncludeToArray <IDictionary>] [-LibrariesCore <string>] [-LibrariesDefault <string>] [-LibrariesStandard <string>] [-Legacy] [-NoInteractive] [-StagingPath <string>] [-CsprojPath <string>] [-DotNetConfiguration <string>] [-DotNetFramework <string[]>] [-SkipInstall] [-InstallStrategy <InstallationStrategy>] [-KeepVersions <int>] [-InstallRoots <string[]>] [-LegacyFlatHandling <LegacyFlatModuleHandling>] [-PreserveInstallVersions <string[]>] [-KeepStaging] [-JsonOnly] [-JsonPath <string>] [-DiagnosticsBaselinePath <string>] [-GenerateDiagnosticsBaseline] [-UpdateDiagnosticsBaseline] [-FailOnNewDiagnostics] [-FailOnDiagnosticsSeverity <BuildDiagnosticSeverity>] [-DiagnosticsBinaryConflictSearchRoot <string[]>] [-ExitCode] [<CommonParameters>]

Config

Invoke-ModuleBuild -ConfigPath <string> [-ExcludeDirectories <string[]>] [-ExcludeFiles <string[]>] [-Legacy] [-NoInteractive] [-JsonOnly] [-JsonPath <string>] [-DiagnosticsBaselinePath <string>] [-GenerateDiagnosticsBaseline] [-UpdateDiagnosticsBaseline] [-FailOnNewDiagnostics] [-FailOnDiagnosticsSeverity <BuildDiagnosticSeverity>] [-DiagnosticsBinaryConflictSearchRoot <string[]>] [-ExitCode] [<CommonParameters>]

Configuration

Invoke-ModuleBuild -Configuration <IDictionary> [-ExcludeDirectories <string[]>] [-ExcludeFiles <string[]>] [-Legacy] [-NoInteractive] [-JsonOnly] [-JsonPath <string>] [-DiagnosticsBaselinePath <string>] [-GenerateDiagnosticsBaseline] [-UpdateDiagnosticsBaseline] [-FailOnNewDiagnostics] [-FailOnDiagnosticsSeverity <BuildDiagnosticSeverity>] [-DiagnosticsBinaryConflictSearchRoot <string[]>] [-ExitCode] [<CommonParameters>]

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

EXAMPLE 1

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

EXAMPLE 2

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

EXAMPLE 3

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

EXAMPLE 4

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 }

EXAMPLE 5

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

EXAMPLE 6

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

Folder name containing aliases to export. Default: Public.

Type: String
Parameter Sets: Modern
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-ConfigPath

Path to a module pipeline JSON config generated by Invoke-ModuleBuild -JsonOnly.

Type: String
Parameter Sets: Config
Aliases: None
Possible values:

Required: True
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-Configuration

Legacy configuration dictionary for backwards compatibility.

Type: IDictionary
Parameter Sets: Configuration
Aliases: None
Possible values:

Required: True
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-CsprojPath

Optional path to a .NET project (.csproj) to publish into the module.

Type: String
Parameter Sets: Modern
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-DiagnosticsBaselinePath

Optional path to a diagnostics baseline file used to compare current issues with known issues.

Type: String
Parameter Sets: Modern, Config, Configuration
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-DiagnosticsBinaryConflictSearchRoot

Optional module roots to scan for deterministic binary conflict diagnostics. When provided, conflict findings can participate in diagnostics baselines and policy.

Type: String[]
Parameter Sets: Modern, Config, Configuration
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-DotNetConfiguration

Build configuration for publishing the .NET project (Release or Debug).

Type: String
Parameter Sets: Modern
Aliases: None
Possible values: Release, Debug

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-DotNetFramework

Target frameworks to publish (e.g., net472, net8.0).

Type: String[]
Parameter Sets: Modern
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-ExcludeDirectories

Directory names excluded from staging copy (matched by directory name, not by path).

Type: String[]
Parameter Sets: Modern, Config, Configuration
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-ExcludeFiles

File names excluded from staging copy (matched by file name, not by path).

Type: String[]
Parameter Sets: Modern, Config, Configuration
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-ExcludeFromPackage

Exclude patterns for artefact packaging.

Type: String[]
Parameter Sets: Modern
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-ExitCode

When specified, requests the host to exit with code 0 on success and 1 on failure.

Type: SwitchParameter
Parameter Sets: Modern, Config, Configuration
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-FailOnDiagnosticsSeverity

Fails the build when diagnostics at or above the specified severity are present.

Type: Nullable`1
Parameter Sets: Modern, Config, Configuration
Aliases: None
Possible values: Warning, Error

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-FailOnNewDiagnostics

Fails the build when diagnostics appear that are not present in the loaded baseline.

Type: SwitchParameter
Parameter Sets: Modern, Config, Configuration
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-FunctionsToExportFolder

Folder name containing functions to export. Default: Public.

Type: String
Parameter Sets: Modern
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-GenerateDiagnosticsBaseline

Writes a diagnostics baseline file from the current run.

Type: SwitchParameter
Parameter Sets: Modern, Config, Configuration
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-IncludeAll

Folders from which to include all files in artefacts.

Type: String[]
Parameter Sets: Modern
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-IncludeCustomCode

Optional script block executed during staging that can add custom files/folders to the build.

Type: ScriptBlock
Parameter Sets: Modern
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-IncludePS1

Folders from which to include .ps1 files in artefacts.

Type: String[]
Parameter Sets: Modern
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-IncludeRoot

Include patterns for root files in artefacts.

Type: String[]
Parameter Sets: Modern
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-IncludeToArray

Advanced hashtable form for includes (maps IncludeRoot/IncludePS1/IncludeAll etc).

Type: IDictionary
Parameter Sets: Modern
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-InstallRoots

Destination module roots for install. When omitted, defaults are used.

Type: String[]
Parameter Sets: Modern
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-InstallStrategy

Installation strategy used when installing the module.

Type: InstallationStrategy
Parameter Sets: Modern
Aliases: None
Possible values: Exact, AutoRevision

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-JsonOnly

Generates a PowerForge pipeline JSON file and exits without running the build pipeline. Intended for migrating legacy DSL scripts to powerforge CLI configuration.

Type: SwitchParameter
Parameter Sets: Modern, Config, Configuration
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-JsonPath

Output path for the generated pipeline JSON file (used with JsonOnly). Defaults to powerforge.json in the project root.

Type: String
Parameter Sets: Modern, Config, Configuration
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-KeepStaging

Keep staging directory after build/install.

Type: SwitchParameter
Parameter Sets: Modern
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-KeepVersions

Number of versions to keep per module root when installing.

Type: Int32
Parameter Sets: Modern
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-Legacy

Compatibility switch. Historically forced the PowerShell-script build pipeline; the build now always runs through the C# PowerForge pipeline.

Type: SwitchParameter
Parameter Sets: Modern, Config, Configuration
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-LegacyFlatHandling

How to handle legacy flat installs found under module roots.

Type: LegacyFlatModuleHandling
Parameter Sets: Modern
Aliases: None
Possible values: Warn, Convert, Delete, Ignore

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-LibrariesCore

Alternate relative path for .NET Core-targeted libraries folder. Default: Lib/Core.

Type: String
Parameter Sets: Modern
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-LibrariesDefault

Alternate relative path for .NET Framework-targeted libraries folder. Default: Lib/Default.

Type: String
Parameter Sets: Modern
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-LibrariesStandard

Alternate relative path for .NET Standard-targeted libraries folder. Default: Lib/Standard.

Type: String
Parameter Sets: Modern
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-ModuleName

Name of the module being built.

Type: String
Parameter Sets: Modern
Aliases: ProjectName
Possible values:

Required: True
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-NoInteractive

Disables the interactive progress UI and emits plain log output.

Type: SwitchParameter
Parameter Sets: Modern, Config, Configuration
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-Path

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.

Type: String
Parameter Sets: Modern
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-PreserveInstallVersions

Version folders to preserve when pruning installed versions.

Type: String[]
Parameter Sets: Modern
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-Settings

Provides settings for the module in the form of a script block (DSL).

Type: ScriptBlock
Parameter Sets: Modern
Aliases: None
Possible values:

Required: False
Position: 0
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-SkipInstall

Skips installing the module after build.

Type: SwitchParameter
Parameter Sets: Modern
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-StagingPath

Staging directory for the PowerForge pipeline. When omitted, a temporary folder is generated.

Type: String
Parameter Sets: Modern
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-UpdateDiagnosticsBaseline

Updates a diagnostics baseline file from the current run.

Type: SwitchParameter
Parameter Sets: Modern, Config, Configuration
Aliases: None
Possible values:

Required: False
Position: named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

• None

OUTPUTS

• System.Object

RELATED LINKS

• None