New-ConfigurationModule

Namespace PSPublishModule

Inputs

None

Provides a way to configure required, external, embedded, or approved modules used in the project.

Remarks

Emits module dependency configuration segments. These are later used to patch the module manifest and (optionally) install/package dependencies during a build. Use RequiredModule for dependencies that should appear in the manifest and can also be bundled into build artefacts when New-ConfigurationArtefact -AddRequiredModules is enabled. Use ExternalModule for dependencies that must exist on the target system but should not be bundled into artefacts. Use EmbeddedModule for dependencies that should be bundled under Internals\Modules and installed/imported later by explicit path with Install-ModuleDependency / Import-ModuleDependency. RequiredModule entries are written to the manifest RequiredModules. ExternalModule entries are written to PrivateData.PSData.ExternalModuleDependencies. EmbeddedModule entries are copied into the built module internals and are not emitted as manifest dependencies. ApprovedModule entries are used by merge/missing-function workflows and are not emitted as manifest dependencies. Built-in Microsoft.PowerShell.* modules are ignored during manifest refresh because they are inbox runtime modules, not gallery-resolvable dependencies. Dependencies resolve from installed modules by default. Select -VersionSource PSGallery or -VersionSource PublishRepository when repository state must be authoritative. Select -VersionSource Auto explicitly when an installed-first, repository-fallback policy is desired. Choose only one versioning style per dependency: a minimum version (-Version or -MinimumVersion) or an exact version (-RequiredVersion). Mixing them for the same module is treated as invalid input.

Examples

Authored help example

Add a required module dependency

PS>


New-ConfigurationModule -Type RequiredModule -Name 'Pester' -Version '5.6.1'

Declares a required dependency that is written into the manifest.

Add an external module (required but not packaged)

PS>


New-ConfigurationModule -Type ExternalModule -Name 'Az.Accounts' -Version 'Latest'

Declares a dependency that is expected to be installed separately (not bundled into artefacts).

Pin an exact required version

PS>


New-ConfigurationModule -Type RequiredModule -Name 'PSWriteColor' -RequiredVersion '1.0.0'

Uses RequiredVersion when an exact match is required.

Embed a dependency for explicit private-path import later

PS>


New-ConfigurationModule -Type EmbeddedModule -Name 'Microsoft.Graph.Authentication' -RequiredVersion '2.25.0'

Bundles the dependency under Internals\Modules without adding it to PSD1 RequiredModules.

Declare an approved helper module for merge-time reuse

PS>


New-ConfigurationModule -Type ApprovedModule -Name 'PSSharedGoods','PSWriteColor'

Allows approved helper functions to be copied into the built module when they are actually used.

Declare a dependency whose version can be resolved online later

PS>


New-ConfigurationModule -Type RequiredModule -Name 'Pester' -Version 'Latest' -Guid 'Auto' -VersionSource PSGallery

Resolves repository metadata explicitly instead of allowing an installed local build to win.

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-ConfigurationModule [-Guid <String>] [-MinimumVersion <String>] -Name <String[]> [-RequiredVersion <String>] [-Type <RequiredModule|ExternalModule|ApprovedModule|EmbeddedModule>] [-Version <String>] [-VersionSource <Auto|Installed|PSGallery|PublishRepository>] [<CommonParameters>]

Parameter set: All Parameter Sets

Parameters

Guid String optionalposition: namedpipeline: False: GUID of the dependency module (or Auto). This is most useful when you want manifest validation to lock onto a specific module identity across repositories.
MinimumVersion String optionalposition: namedpipeline: False: Minimum version of the dependency module (preferred over -Version). Use this when any newer compatible version is acceptable.
Name String[] requiredposition: namedpipeline: False: Name of the PowerShell module(s) that your module depends on. Multiple names emit one configuration segment per module using the same dependency settings.
RequiredVersion String optionalposition: namedpipeline: False: Required version of the dependency module (exact match). Use this when consumers and packaging must resolve the exact same version.
Type ModuleDependencyKind optionalposition: namedpipeline: Falsevalues: 4: Choose between RequiredModule, ExternalModule, EmbeddedModule, and ApprovedModule. RequiredModule is used for manifest and optional packaging, ExternalModule is install-only, EmbeddedModule is bundled under Internals for explicit install/import by path, and ApprovedModule is merge-only.; Possible values: RequiredModule, ExternalModule, ApprovedModule, EmbeddedModule
Version String optionalposition: namedpipeline: False: Minimum version of the dependency module (or Auto/Latest). This is treated the same as -MinimumVersion and cannot be combined with -RequiredVersion.
VersionSource ModuleDependencyVersionSource optionalposition: namedpipeline: Falsevalues: 4: Source used when resolving dependency versions. Installed modules are used by default.; Possible values: Auto, Installed, PSGallery, PublishRepository