Skip to content

Invoke-ModuleBuild.md

Latest commit

 

History

History
1029 lines (830 loc) · 24.5 KB

Invoke-ModuleBuild.md

File metadata and controls

1029 lines (830 loc) · 24.5 KB
Raw
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>] [-RunMode <ConfigurationGateMode>] [-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] [-Quiet] [-PassThru] [-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> [-RunMode <ConfigurationGateMode>] [-ModuleVersion <string>] [-PreReleaseTag <string>] [-BuildConfiguration <string>] [-BuildFramework <string>] [-NoDotnetBuild] [-NoSign] [-SignModule] [-IncludeProjectPackages <bool>] [-IncludeModulePublishing <bool>] [-PowerForgeUnifiedGitHubRelease] [-CertificateThumbprint <string>] [-SignIncludeBinaries <Boolean>] [-SignIncludeInternals <Boolean>] [-SignIncludeExe <Boolean>] [-ExcludeDirectories <string[]>] [-ExcludeFiles <string[]>] [-Legacy] [-NoInteractive] [-Quiet] [-PassThru] [-StagingPath <string>] [-SkipInstall] [-JsonOnly] [-JsonPath <string>] [-DiagnosticsBaselinePath <string>] [-GenerateDiagnosticsBaseline] [-UpdateDiagnosticsBaseline] [-FailOnNewDiagnostics] [-FailOnDiagnosticsSeverity <BuildDiagnosticSeverity>] [-DiagnosticsBinaryConflictSearchRoot <string[]>] [-ExitCode] [<CommonParameters>]

Configuration

Invoke-ModuleBuild -Configuration <IDictionary> [-RunMode <ConfigurationGateMode>] [-ExcludeDirectories <string[]>] [-ExcludeFiles <string[]>] [-Legacy] [-NoInteractive] [-Quiet] [-PassThru] [-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: False

-BuildConfiguration

Overrides the .NET build configuration declared by a JSON configuration.

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

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

-BuildFramework

Overrides the .NET framework declared by a JSON configuration. Auto preserves the configured framework matrix.

Type: String
Parameter Sets: Config
Aliases: None
Possible values: auto, net10.0, net8.0, net472

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

-CertificateThumbprint

Overrides the signing certificate thumbprint declared by a JSON configuration.

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

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

-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: False

-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: False

-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: False

-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: False

-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: False

-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: False

-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: False

-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: False

-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: False

-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: False

-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: False

-FailOnDiagnosticsSeverity

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

Type: BuildDiagnosticSeverity
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: False

-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: False

-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: False

-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: False

-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: False

-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: False

-IncludeModulePublishing

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.

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

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

-IncludeProjectPackages

Controls whether project/package segments declared by a JSON configuration are included. Unified release orchestration disables them when the outer package lane owns publication.

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

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

-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: False

-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: False

-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: False

-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: False

-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: False

-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: False

-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: False

-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: False

-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: False

-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: False

-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: False

-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: False

-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: False

-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: False

-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: False

-ModuleVersion

Overrides the module version declared by a JSON configuration.

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

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

-NoDotnetBuild

Skips the configured .NET project build and reuses the existing module binary payload.

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

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

-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: False

-NoSign

Disables module signing declared by a JSON configuration.

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

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

-PassThru

Writes the completed module pipeline result to the PowerShell success stream.

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: False

-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: False

-PowerForgeUnifiedGitHubRelease

Indicates that a parent unified release owns GitHub publication and suppresses GitHub publish segments declared by the JSON module configuration.

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

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

-PreReleaseTag

Overrides the prerelease tag declared by a JSON configuration.

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

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

-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: False

-Quiet

Suppresses host rendering and log output. Intended for callers that request structured results.

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: False

-RunMode

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.

Type: ConfigurationGateMode
Parameter Sets: Modern, Config, Configuration
Aliases: ConfigurationGateMode
Possible values: Manifest, Build, Publish, Documentation

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

-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: False

-SignIncludeBinaries

Overrides whether binary files are signed for a JSON configuration.

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

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

-SignIncludeExe

Overrides whether executable files are signed for a JSON configuration.

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

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

-SignIncludeInternals

Overrides whether internal files are signed for a JSON configuration.

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

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

-SignModule

Enables module signing declared by a JSON configuration.

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

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

-SkipInstall

Skips installing the module after build.

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

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

-StagingPath

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

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

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

-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: False

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

  • PowerForge.ModulePipelineResult

RELATED LINKS

  • None