New-ConfigurationArtefact

Namespace PSPublishModule

Inputs

None

Outputs

System.Object

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

Remarks

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.

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

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>] [-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

Parameters

AddRequiredModules SwitchParameter optionalposition: namedpipeline: Falsealiases: RequiredModules: Add RequiredModule dependencies to the artefact by copying or downloading them. This does not include ExternalModule dependencies.
ArtefactName String optionalposition: namedpipeline: False: The name of the artefact. If not specified, the default name will be used.
CopyDirectories ArtefactCopyMapping[] optionalposition: namedpipeline: False: Directories to copy to artefact (Source/Destination). Accepts legacy hashtable (source=>destination) or ArtefactCopyMapping[]
CopyDirectoriesRelative SwitchParameter optionalposition: namedpipeline: False: Define if destination directories should be relative to artefact root.
CopyFiles ArtefactCopyMapping[] optionalposition: namedpipeline: False: Files to copy to artefact (Source/Destination). Accepts legacy hashtable (source=>destination) or ArtefactCopyMapping[]
CopyFilesRelative SwitchParameter optionalposition: namedpipeline: False: Define if destination files should be relative to artefact root.
DoNotClear SwitchParameter optionalposition: namedpipeline: False: Do not clear artefact output directory before creating artefact.
Enable SwitchParameter optionalposition: namedpipeline: False: Enable artefact creation. By default artefact creation is disabled.
ID String optionalposition: namedpipeline: False: Optional ID of the artefact (to be used by New-ConfigurationPublish).
IncludeTagName SwitchParameter optionalposition: namedpipeline: False: Include tag name in artefact name. By default tag name is not included.
ModulesPath String optionalposition: namedpipeline: False: Path where main module (or required module) will be copied to.
Path String optionalposition: namedpipeline: False: Path where artefact will be created.
PostScriptMerge ScriptBlock optionalposition: 0pipeline: False: ScriptBlock that will be added at the end of the script (Script / ScriptPacked).
PostScriptMergePath String optionalposition: namedpipeline: False: Path to file that will be added at the end of the script (Script / ScriptPacked).
PreScriptMerge ScriptBlock optionalposition: 1pipeline: False: ScriptBlock that will be added at the beginning of the script (Script / ScriptPacked).
PreScriptMergePath String optionalposition: namedpipeline: False: Path to file that will be added at the beginning of the script (Script / ScriptPacked).
RequiredModulesCredentialSecret String optionalposition: namedpipeline: False: Repository credential secret (password/token) in clear text used when downloading required modules.
RequiredModulesCredentialSecretFilePath String optionalposition: namedpipeline: False: Repository credential secret (password/token) in a clear-text file used when downloading required modules.
RequiredModulesCredentialUserName String optionalposition: namedpipeline: False: Repository credential username (basic auth) used when downloading required modules.
RequiredModulesPath String optionalposition: namedpipeline: False: Path where required modules will be copied to. When omitted, PowerForge uses the default module layout under the artefact output.
RequiredModulesRepository String optionalposition: namedpipeline: False: 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 optionalposition: namedpipeline: Falsevalues: 3: 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 optionalposition: namedpipeline: Falsevalues: 3: 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 optionalposition: namedpipeline: Falsealiases: FileName: The name of the script artefact (alias: FileName).
Type ArtefactType requiredposition: namedpipeline: Falsevalues: 4: Artefact type to generate.; Possible values: Unpacked, Packed, Script, ScriptPacked

Outputs

System.Object