Command

New-ConfigurationArtefact

Module PSPublishModule

Inputs

None

Tells the module to create an artefact of a specified type.

Syntax

New-ConfigurationArtefact [-AddRequiredModules] [-ArtefactName <String>] [-CopyDirectories <ArtefactCopyMapping[]>] [-CopyDirectoriesRelative] [-CopyFiles <ArtefactCopyMapping[]>] [-CopyFilesRelative] [-DoNotClear] [-Enable] [-ID <String>] [-IncludeTagName] [-ModulesPath <String>] [-Path <String>] [[-PostScriptMerge] <ScriptBlock>] [-PostScriptMergePath <String>] [[-PreScriptMerge] <ScriptBlock>] [-PreScriptMergePath <String>] [-RequiredModulesCredentialSecret <String>] [-RequiredModulesCredentialSecretFilePath <String>] [-RequiredModulesCredentialUserName <String>] [-RequiredModulesExcludeModuleName <String[]>] [-RequiredModulesPath <String>] [-RequiredModulesRepository <String>] [-RequiredModulesSource <Auto|Installed|Download>] [-RequiredModulesTool <Auto|PSResourceGet|PowerShellGet>] [-ScriptName <String>] -Type <Unpacked|Packed|Script|ScriptPacked> [<CommonParameters>]

Parameter set: All Parameter Sets

Description

Artefacts are created after the module is built into staging. Use Packed (ZIP) for distribution and Unpacked (folder) for inspection or offline installation.

When -AddRequiredModules is enabled, required modules are copied from locally available modules (Get-Module -ListAvailable) and, when configured, downloaded (via Save-PSResource/Save-Module) before being copied into the artefact.

Only RequiredModule dependencies participate in artefact bundling. ExternalModule dependencies are intentionally excluded because they represent dependencies that should remain separately installed on the target machine.

RequiredModulesSource controls the packaging strategy: Installed means local-only copy, Auto means prefer local and download when missing, and Download means always download. When omitted, the default is Installed.

Use -ID to link an artefact to a publish step (New-ConfigurationPublish) and publish only a specific artefact.

For a broader dependency workflow explanation, see about_ModuleDependencies.

Examples

Authored help example

Create a packed ZIP artefact

New-ConfigurationArtefact -Type Packed -Enable -Path 'Artefacts\Packed' -ID 'Packed'

Create an unpacked artefact including required modules

New-ConfigurationArtefact -Type Unpacked -Enable -AddRequiredModules -Path 'Artefacts\Unpacked' -RequiredModulesRepository 'PSGallery'

Always download required modules into a packed artefact

New-ConfigurationArtefact -Type Packed -Enable -AddRequiredModules -RequiredModulesSource Download -RequiredModulesRepository 'PSGallery'

Use this when you want packaging to ignore whatever is already installed on the build machine.

Prefer local modules and download only when a dependency is missing

New-ConfigurationArtefact -Type Unpacked -Enable -AddRequiredModules -RequiredModulesSource Auto -RequiredModulesTool Auto

This is a good default for developer machines that may already have some dependencies installed.

Parameters

-AddRequiredModules SwitchParameter optionalaliases: RequiredModules: Add RequiredModule dependencies to the artefact by copying or downloading them. This does not include ExternalModule dependencies.
-ArtefactName String optional: The name of the artefact. If not specified, the default name will be used.
-CopyDirectories ArtefactCopyMapping[] optional: Directories to copy to artefact (Source/Destination). Accepts legacy hashtable (source=>destination) or ArtefactCopyMapping[]
-CopyDirectoriesRelative SwitchParameter optional: Define if destination directories should be relative to artefact root.
-CopyFiles ArtefactCopyMapping[] optional: Files to copy to artefact (Source/Destination). Accepts legacy hashtable (source=>destination) or ArtefactCopyMapping[]
-CopyFilesRelative SwitchParameter optional: Define if destination files should be relative to artefact root.
-DoNotClear SwitchParameter optional: Do not clear artefact output directory before creating artefact.
-Enable SwitchParameter optional: Enable artefact creation. By default artefact creation is disabled.
-ID String optional: Optional ID of the artefact (to be used by New-ConfigurationPublish).
-IncludeTagName SwitchParameter optional: Include tag name in artefact name. By default tag name is not included.
-ModulesPath String optional: Path where main module (or required module) will be copied to.
-Path String optional: Path where artefact will be created.
-PostScriptMerge ScriptBlock optionalposition: 0: ScriptBlock that will be added at the end of the script (Script / ScriptPacked).
-PostScriptMergePath String optional: Path to file that will be added at the end of the script (Script / ScriptPacked).
-PreScriptMerge ScriptBlock optionalposition: 1: ScriptBlock that will be added at the beginning of the script (Script / ScriptPacked).
-PreScriptMergePath String optional: Path to file that will be added at the beginning of the script (Script / ScriptPacked).
-RequiredModulesCredentialSecret String optional: Repository credential secret (password/token) in clear text used when downloading required modules.
-RequiredModulesCredentialSecretFilePath String optional: Repository credential secret (password/token) in a clear-text file used when downloading required modules.
-RequiredModulesCredentialUserName String optional: Repository credential username (basic auth) used when downloading required modules.
-RequiredModulesExcludeModuleName String[] optional: Required module names that should not be copied into this artefact when -AddRequiredModules is enabled. This only affects artefact bundling; it does not remove modules from the generated manifest.
-RequiredModulesPath String optional: Path where required modules will be copied to. When omitted, PowerForge uses the default module layout under the artefact output.
-RequiredModulesRepository String optional: Repository name used when downloading required modules (Save-PSResource / Save-Module). Set this when packaging should resolve from a specific gallery or private feed.
-RequiredModulesSource RequiredModulesSource optional: Source used when resolving required modules (Auto / Installed / Download). When omitted, PowerForge defaults to Installed, which means packaging expects the dependency to already exist on the machine.; Possible values: Auto, Installed, Download
-RequiredModulesTool ModuleSaveTool optional: Tool used when downloading required modules (Save-PSResource / Save-Module). Auto prefers PSResourceGet and falls back to PowerShellGet when necessary.; Possible values: Auto, PSResourceGet, PowerShellGet
-ScriptName String optionalaliases: FileName: The name of the script artefact (alias: FileName).
-Type ArtefactType required: Artefact type to generate.; Possible values: Unpacked, Packed, Script, ScriptPacked

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.