From bdbb8f1d5b799b94391dfe35f3ddb6ef4e34899c Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 3 Sep 2025 18:04:03 -0500 Subject: [PATCH 1/2] Update wildcard support on ExpandProperty parameter (#12335) --- .../Select-Object.md | 69 +++++++++-------- .../Select-Object.md | 77 ++++++++++--------- .../Select-Object.md | 77 ++++++++++--------- .../Select-Object.md | 77 ++++++++++--------- 4 files changed, 160 insertions(+), 140 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Select-Object.md b/reference/5.1/Microsoft.PowerShell.Utility/Select-Object.md index c6d3215cf54..8186ab57afa 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Select-Object.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Select-Object.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 06/19/2024 +ms.date: 09/03/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/select-object?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 aliases: @@ -217,9 +217,9 @@ outputted objects have a specific standard format, the expanded property might n ```powershell # Create a custom object to use for the Select-Object example. -$object = [pscustomobject]@{Name="CustomObject";Expand=@(1,2,3,4,5)} +$object = [pscustomobject]@{Name="CustomObject";List=@(1,2,3,4,5)} # Use the ExpandProperty parameter to Expand the property. -$object | Select-Object -ExpandProperty Expand -Property Name +$object | Select-Object -ExpandProperty List -Property Name ``` ```Output @@ -233,7 +233,7 @@ $object | Select-Object -ExpandProperty Expand -Property Name ```powershell # The output did not contain the Name property, but it was added successfully. # Use Get-Member to confirm the Name property was added and populated. -$object | Select-Object -ExpandProperty Expand -Property Name | Get-Member +$object | Select-Object -ExpandProperty List -Property Name | Get-Member -MemberType Properties ``` ```Output @@ -241,27 +241,6 @@ $object | Select-Object -ExpandProperty Expand -Property Name | Get-Member Name MemberType Definition ---- ---------- ---------- -CompareTo Method int CompareTo(System.Object value), int CompareTo(int value), ... -Equals Method bool Equals(System.Object obj), bool Equals(int obj), bool IEq... -GetHashCode Method int GetHashCode() -GetType Method type GetType() -GetTypeCode Method System.TypeCode GetTypeCode(), System.TypeCode IConvertible.Ge... -ToBoolean Method bool IConvertible.ToBoolean(System.IFormatProvider provider) -ToByte Method byte IConvertible.ToByte(System.IFormatProvider provider) -ToChar Method char IConvertible.ToChar(System.IFormatProvider provider) -ToDateTime Method datetime IConvertible.ToDateTime(System.IFormatProvider provider) -ToDecimal Method decimal IConvertible.ToDecimal(System.IFormatProvider provider) -ToDouble Method double IConvertible.ToDouble(System.IFormatProvider provider) -ToInt16 Method int16 IConvertible.ToInt16(System.IFormatProvider provider) -ToInt32 Method int IConvertible.ToInt32(System.IFormatProvider provider) -ToInt64 Method long IConvertible.ToInt64(System.IFormatProvider provider) -ToSByte Method sbyte IConvertible.ToSByte(System.IFormatProvider provider) -ToSingle Method float IConvertible.ToSingle(System.IFormatProvider provider) -ToString Method string ToString(), string ToString(string format), string ToS... -ToType Method System.Object IConvertible.ToType(type conversionType, System... -ToUInt16 Method uint16 IConvertible.ToUInt16(System.IFormatProvider provider) -ToUInt32 Method uint32 IConvertible.ToUInt32(System.IFormatProvider provider) -ToUInt64 Method uint64 IConvertible.ToUInt64(System.IFormatProvider provider) Name NoteProperty string Name=CustomObject ``` @@ -425,6 +404,30 @@ name children USA @{name=Southwest} ``` +### Example 15: Use wildcards with the -ExpandProperty parameter + +This example demonstrates using wildcards with the **ExpandProperty** parameter. The wildcard +character must resolve to a single property name. If the wildcard character resolves to more than +one property name, `Select-Object` returns an error. + +```powershell +# Create a custom object. +$object = [pscustomobject]@{ + Label = "MyObject" + Names = @("John","Jane","Joe") + Numbers = @(1,2,3,4,5) +} +# Try to expand multiple properties using a wildcard. +$object | Select-Object -ExpandProperty N* +Select-Object: Multiple properties cannot be expanded. + +# Use a wildcard that resolves to a single property. +$object | Select-Object -ExpandProperty Na* +John +Jane +Joe +``` + ## PARAMETERS ### -ExcludeProperty @@ -448,17 +451,19 @@ Accept wildcard characters: True Specifies a property to select, and indicates that an attempt should be made to expand that property. If the input object pipeline doesn't have the property named, `Select-Object` returns an -error. +error. This parameter supports wildcards. However, the wildcard character must resolve to a single +property name. If the wildcard character resolves to more than one property name, `Select-Object` +returns an error. + +When you use **ExpandProperty**, `Select-Object` attempts to expand the specified property for every - If the specified property is an array, each value of the array is included in the output. - If the specified property is an object, the objects properties are expanded for every **InputObject** -In either case, the output objects' **Type** matches the expanded property's **Type**. - -> [!NOTE] -> There is a side-effect when using **ExpandProperty**. The `Select-Object` adds the selected -> properties to the original object as **NoteProperty** members. +In either case, the output objects' **Type** matches the expanded property's **Type**. There is a +side-effect when using **ExpandProperty**. The `Select-Object` adds the selected properties to the +original object as **NoteProperty** members. If the **Property** parameter is specified, `Select-Object` attempts to add each selected property as a **NoteProperty** to every outputted object. @@ -481,7 +486,7 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -First diff --git a/reference/7.4/Microsoft.PowerShell.Utility/Select-Object.md b/reference/7.4/Microsoft.PowerShell.Utility/Select-Object.md index e0996c0c4dc..adcaaa5fcb4 100644 --- a/reference/7.4/Microsoft.PowerShell.Utility/Select-Object.md +++ b/reference/7.4/Microsoft.PowerShell.Utility/Select-Object.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 06/19/2024 +ms.date: 09/03/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/select-object?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 aliases: @@ -240,9 +240,9 @@ outputted objects have a specific standard format, the expanded property might n ```powershell # Create a custom object to use for the Select-Object example. -$object = [pscustomobject]@{Name="CustomObject";Expand=@(1,2,3,4,5)} +$object = [pscustomobject]@{Name="CustomObject";List=@(1,2,3,4,5)} # Use the ExpandProperty parameter to Expand the property. -$object | Select-Object -ExpandProperty Expand -Property Name +$object | Select-Object -ExpandProperty List -Property Name ``` ```Output @@ -256,7 +256,7 @@ $object | Select-Object -ExpandProperty Expand -Property Name ```powershell # The output did not contain the Name property, but it was added successfully. # Use Get-Member to confirm the Name property was added and populated. -$object | Select-Object -ExpandProperty Expand -Property Name | Get-Member +$object | Select-Object -ExpandProperty List -Property Name | Get-Member -MemberType Properties ``` ```Output @@ -264,27 +264,6 @@ $object | Select-Object -ExpandProperty Expand -Property Name | Get-Member Name MemberType Definition ---- ---------- ---------- -CompareTo Method int CompareTo(System.Object value), int CompareTo(int value), ... -Equals Method bool Equals(System.Object obj), bool Equals(int obj), bool IEq... -GetHashCode Method int GetHashCode() -GetType Method type GetType() -GetTypeCode Method System.TypeCode GetTypeCode(), System.TypeCode IConvertible.Ge... -ToBoolean Method bool IConvertible.ToBoolean(System.IFormatProvider provider) -ToByte Method byte IConvertible.ToByte(System.IFormatProvider provider) -ToChar Method char IConvertible.ToChar(System.IFormatProvider provider) -ToDateTime Method datetime IConvertible.ToDateTime(System.IFormatProvider provider) -ToDecimal Method decimal IConvertible.ToDecimal(System.IFormatProvider provider) -ToDouble Method double IConvertible.ToDouble(System.IFormatProvider provider) -ToInt16 Method int16 IConvertible.ToInt16(System.IFormatProvider provider) -ToInt32 Method int IConvertible.ToInt32(System.IFormatProvider provider) -ToInt64 Method long IConvertible.ToInt64(System.IFormatProvider provider) -ToSByte Method sbyte IConvertible.ToSByte(System.IFormatProvider provider) -ToSingle Method float IConvertible.ToSingle(System.IFormatProvider provider) -ToString Method string ToString(), string ToString(string format), string ToS... -ToType Method System.Object IConvertible.ToType(type conversionType, System... -ToUInt16 Method uint16 IConvertible.ToUInt16(System.IFormatProvider provider) -ToUInt32 Method uint32 IConvertible.ToUInt32(System.IFormatProvider provider) -ToUInt64 Method uint64 IConvertible.ToUInt64(System.IFormatProvider provider) Name NoteProperty string Name=CustomObject ``` @@ -377,11 +356,11 @@ This example demonstrates the side-effect of using the **ExpandProperty** parame ```powershell PS> $object = [pscustomobject]@{ - name = 'USA' - children = [pscustomobject]@{ - name = 'Southwest' + name = 'USA' + children = [pscustomobject]@{ + name = 'Southwest' + } } -} PS> $object name children @@ -444,6 +423,30 @@ name children USA @{name=Southwest} ``` +### Example 16: Use wildcards with the -ExpandProperty parameter + +This example demonstrates using wildcards with the **ExpandProperty** parameter. The wildcard +character must resolve to a single property name. If the wildcard character resolves to more than +one property name, `Select-Object` returns an error. + +```powershell +# Create a custom object. +$object = [pscustomobject]@{ + Label = "MyObject" + Names = @("John","Jane","Joe") + Numbers = @(1,2,3,4,5) +} +# Try to expand multiple properties using a wildcard. +$object | Select-Object -ExpandProperty N* +Select-Object: Multiple properties cannot be expanded. + +# Use a wildcard that resolves to a single property. +$object | Select-Object -ExpandProperty Na* +John +Jane +Joe +``` + ## PARAMETERS ### -CaseInsensitive @@ -488,17 +491,19 @@ Accept wildcard characters: True Specifies a property to select, and indicates that an attempt should be made to expand that property. If the input object pipeline doesn't have the property named, `Select-Object` returns an -error. +error. This parameter supports wildcards. However, the wildcard character must resolve to a single +property name. If the wildcard character resolves to more than one property name, `Select-Object` +returns an error. + +When you use **ExpandProperty**, `Select-Object` attempts to expand the specified property for every - If the specified property is an array, each value of the array is included in the output. - If the specified property is an object, the objects properties are expanded for every **InputObject** -In either case, the output objects' **Type** matches the expanded property's **Type**. - -> [!NOTE] -> There is a side-effect when using **ExpandProperty**. The `Select-Object` adds the selected -> properties to the original object as **NoteProperty** members. +In either case, the output objects' **Type** matches the expanded property's **Type**. There is a +side-effect when using **ExpandProperty**. The `Select-Object` adds the selected properties to the +original object as **NoteProperty** members. If the **Property** parameter is specified, `Select-Object` attempts to add each selected property as a **NoteProperty** to every outputted object. @@ -521,7 +526,7 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -First diff --git a/reference/7.5/Microsoft.PowerShell.Utility/Select-Object.md b/reference/7.5/Microsoft.PowerShell.Utility/Select-Object.md index 5c6a43d6f3a..16b4b7df622 100644 --- a/reference/7.5/Microsoft.PowerShell.Utility/Select-Object.md +++ b/reference/7.5/Microsoft.PowerShell.Utility/Select-Object.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 06/19/2024 +ms.date: 09/03/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/select-object?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 aliases: @@ -240,9 +240,9 @@ outputted objects have a specific standard format, the expanded property might n ```powershell # Create a custom object to use for the Select-Object example. -$object = [pscustomobject]@{Name="CustomObject";Expand=@(1,2,3,4,5)} +$object = [pscustomobject]@{Name="CustomObject";List=@(1,2,3,4,5)} # Use the ExpandProperty parameter to Expand the property. -$object | Select-Object -ExpandProperty Expand -Property Name +$object | Select-Object -ExpandProperty List -Property Name ``` ```Output @@ -256,7 +256,7 @@ $object | Select-Object -ExpandProperty Expand -Property Name ```powershell # The output did not contain the Name property, but it was added successfully. # Use Get-Member to confirm the Name property was added and populated. -$object | Select-Object -ExpandProperty Expand -Property Name | Get-Member +$object | Select-Object -ExpandProperty List -Property Name | Get-Member -MemberType Properties ``` ```Output @@ -264,27 +264,6 @@ $object | Select-Object -ExpandProperty Expand -Property Name | Get-Member Name MemberType Definition ---- ---------- ---------- -CompareTo Method int CompareTo(System.Object value), int CompareTo(int value), ... -Equals Method bool Equals(System.Object obj), bool Equals(int obj), bool IEq... -GetHashCode Method int GetHashCode() -GetType Method type GetType() -GetTypeCode Method System.TypeCode GetTypeCode(), System.TypeCode IConvertible.Ge... -ToBoolean Method bool IConvertible.ToBoolean(System.IFormatProvider provider) -ToByte Method byte IConvertible.ToByte(System.IFormatProvider provider) -ToChar Method char IConvertible.ToChar(System.IFormatProvider provider) -ToDateTime Method datetime IConvertible.ToDateTime(System.IFormatProvider provider) -ToDecimal Method decimal IConvertible.ToDecimal(System.IFormatProvider provider) -ToDouble Method double IConvertible.ToDouble(System.IFormatProvider provider) -ToInt16 Method int16 IConvertible.ToInt16(System.IFormatProvider provider) -ToInt32 Method int IConvertible.ToInt32(System.IFormatProvider provider) -ToInt64 Method long IConvertible.ToInt64(System.IFormatProvider provider) -ToSByte Method sbyte IConvertible.ToSByte(System.IFormatProvider provider) -ToSingle Method float IConvertible.ToSingle(System.IFormatProvider provider) -ToString Method string ToString(), string ToString(string format), string ToS... -ToType Method System.Object IConvertible.ToType(type conversionType, System... -ToUInt16 Method uint16 IConvertible.ToUInt16(System.IFormatProvider provider) -ToUInt32 Method uint32 IConvertible.ToUInt32(System.IFormatProvider provider) -ToUInt64 Method uint64 IConvertible.ToUInt64(System.IFormatProvider provider) Name NoteProperty string Name=CustomObject ``` @@ -377,11 +356,11 @@ This example demonstrates the side-effect of using the **ExpandProperty** parame ```powershell PS> $object = [pscustomobject]@{ - name = 'USA' - children = [pscustomobject]@{ - name = 'Southwest' + name = 'USA' + children = [pscustomobject]@{ + name = 'Southwest' + } } -} PS> $object name children @@ -444,6 +423,30 @@ name children USA @{name=Southwest} ``` +### Example 16: Use wildcards with the -ExpandProperty parameter + +This example demonstrates using wildcards with the **ExpandProperty** parameter. The wildcard +character must resolve to a single property name. If the wildcard character resolves to more than +one property name, `Select-Object` returns an error. + +```powershell +# Create a custom object. +$object = [pscustomobject]@{ + Label = "MyObject" + Names = @("John","Jane","Joe") + Numbers = @(1,2,3,4,5) +} +# Try to expand multiple properties using a wildcard. +$object | Select-Object -ExpandProperty N* +Select-Object: Multiple properties cannot be expanded. + +# Use a wildcard that resolves to a single property. +$object | Select-Object -ExpandProperty Na* +John +Jane +Joe +``` + ## PARAMETERS ### -CaseInsensitive @@ -488,17 +491,19 @@ Accept wildcard characters: True Specifies a property to select, and indicates that an attempt should be made to expand that property. If the input object pipeline doesn't have the property named, `Select-Object` returns an -error. +error. This parameter supports wildcards. However, the wildcard character must resolve to a single +property name. If the wildcard character resolves to more than one property name, `Select-Object` +returns an error. + +When you use **ExpandProperty**, `Select-Object` attempts to expand the specified property for every - If the specified property is an array, each value of the array is included in the output. - If the specified property is an object, the objects properties are expanded for every **InputObject** -In either case, the output objects' **Type** matches the expanded property's **Type**. - -> [!NOTE] -> There is a side-effect when using **ExpandProperty**. The `Select-Object` adds the selected -> properties to the original object as **NoteProperty** members. +In either case, the output objects' **Type** matches the expanded property's **Type**. There is a +side-effect when using **ExpandProperty**. The `Select-Object` adds the selected properties to the +original object as **NoteProperty** members. If the **Property** parameter is specified, `Select-Object` attempts to add each selected property as a **NoteProperty** to every outputted object. @@ -521,7 +526,7 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -First diff --git a/reference/7.6/Microsoft.PowerShell.Utility/Select-Object.md b/reference/7.6/Microsoft.PowerShell.Utility/Select-Object.md index ce89bc0c51f..eb1566a9011 100644 --- a/reference/7.6/Microsoft.PowerShell.Utility/Select-Object.md +++ b/reference/7.6/Microsoft.PowerShell.Utility/Select-Object.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 06/19/2024 +ms.date: 09/03/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/select-object?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 aliases: @@ -240,9 +240,9 @@ outputted objects have a specific standard format, the expanded property might n ```powershell # Create a custom object to use for the Select-Object example. -$object = [pscustomobject]@{Name="CustomObject";Expand=@(1,2,3,4,5)} +$object = [pscustomobject]@{Name="CustomObject";List=@(1,2,3,4,5)} # Use the ExpandProperty parameter to Expand the property. -$object | Select-Object -ExpandProperty Expand -Property Name +$object | Select-Object -ExpandProperty List -Property Name ``` ```Output @@ -256,7 +256,7 @@ $object | Select-Object -ExpandProperty Expand -Property Name ```powershell # The output did not contain the Name property, but it was added successfully. # Use Get-Member to confirm the Name property was added and populated. -$object | Select-Object -ExpandProperty Expand -Property Name | Get-Member +$object | Select-Object -ExpandProperty List -Property Name | Get-Member -MemberType Properties ``` ```Output @@ -264,27 +264,6 @@ $object | Select-Object -ExpandProperty Expand -Property Name | Get-Member Name MemberType Definition ---- ---------- ---------- -CompareTo Method int CompareTo(System.Object value), int CompareTo(int value), ... -Equals Method bool Equals(System.Object obj), bool Equals(int obj), bool IEq... -GetHashCode Method int GetHashCode() -GetType Method type GetType() -GetTypeCode Method System.TypeCode GetTypeCode(), System.TypeCode IConvertible.Ge... -ToBoolean Method bool IConvertible.ToBoolean(System.IFormatProvider provider) -ToByte Method byte IConvertible.ToByte(System.IFormatProvider provider) -ToChar Method char IConvertible.ToChar(System.IFormatProvider provider) -ToDateTime Method datetime IConvertible.ToDateTime(System.IFormatProvider provider) -ToDecimal Method decimal IConvertible.ToDecimal(System.IFormatProvider provider) -ToDouble Method double IConvertible.ToDouble(System.IFormatProvider provider) -ToInt16 Method int16 IConvertible.ToInt16(System.IFormatProvider provider) -ToInt32 Method int IConvertible.ToInt32(System.IFormatProvider provider) -ToInt64 Method long IConvertible.ToInt64(System.IFormatProvider provider) -ToSByte Method sbyte IConvertible.ToSByte(System.IFormatProvider provider) -ToSingle Method float IConvertible.ToSingle(System.IFormatProvider provider) -ToString Method string ToString(), string ToString(string format), string ToS... -ToType Method System.Object IConvertible.ToType(type conversionType, System... -ToUInt16 Method uint16 IConvertible.ToUInt16(System.IFormatProvider provider) -ToUInt32 Method uint32 IConvertible.ToUInt32(System.IFormatProvider provider) -ToUInt64 Method uint64 IConvertible.ToUInt64(System.IFormatProvider provider) Name NoteProperty string Name=CustomObject ``` @@ -377,11 +356,11 @@ This example demonstrates the side-effect of using the **ExpandProperty** parame ```powershell PS> $object = [pscustomobject]@{ - name = 'USA' - children = [pscustomobject]@{ - name = 'Southwest' + name = 'USA' + children = [pscustomobject]@{ + name = 'Southwest' + } } -} PS> $object name children @@ -444,6 +423,30 @@ name children USA @{name=Southwest} ``` +### Example 16: Use wildcards with the -ExpandProperty parameter + +This example demonstrates using wildcards with the **ExpandProperty** parameter. The wildcard +character must resolve to a single property name. If the wildcard character resolves to more than +one property name, `Select-Object` returns an error. + +```powershell +# Create a custom object. +$object = [pscustomobject]@{ + Label = "MyObject" + Names = @("John","Jane","Joe") + Numbers = @(1,2,3,4,5) +} +# Try to expand multiple properties using a wildcard. +$object | Select-Object -ExpandProperty N* +Select-Object: Multiple properties cannot be expanded. + +# Use a wildcard that resolves to a single property. +$object | Select-Object -ExpandProperty Na* +John +Jane +Joe +``` + ## PARAMETERS ### -CaseInsensitive @@ -488,17 +491,19 @@ Accept wildcard characters: True Specifies a property to select, and indicates that an attempt should be made to expand that property. If the input object pipeline doesn't have the property named, `Select-Object` returns an -error. +error. This parameter supports wildcards. However, the wildcard character must resolve to a single +property name. If the wildcard character resolves to more than one property name, `Select-Object` +returns an error. + +When you use **ExpandProperty**, `Select-Object` attempts to expand the specified property for every - If the specified property is an array, each value of the array is included in the output. - If the specified property is an object, the objects properties are expanded for every **InputObject** -In either case, the output objects' **Type** matches the expanded property's **Type**. - -> [!NOTE] -> There is a side-effect when using **ExpandProperty**. The `Select-Object` adds the selected -> properties to the original object as **NoteProperty** members. +In either case, the output objects' **Type** matches the expanded property's **Type**. There is a +side-effect when using **ExpandProperty**. The `Select-Object` adds the selected properties to the +original object as **NoteProperty** members. If the **Property** parameter is specified, `Select-Object` attempts to add each selected property as a **NoteProperty** to every outputted object. @@ -521,7 +526,7 @@ Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -First From 33e837972d49fe6bd520a0fd8399790703995545 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 4 Sep 2025 13:09:20 -0500 Subject: [PATCH 2/2] Update information about external dependencies (#12336) --- .../About/about_Module_Manifests.md | 12 +++-- .../New-ModuleManifest.md | 21 +++++--- .../About/about_Module_Manifests.md | 12 +++-- .../New-ModuleManifest.md | 53 ++++++++++++------- .../About/about_Module_Manifests.md | 12 +++-- .../New-ModuleManifest.md | 28 ++++++---- .../About/about_Module_Manifests.md | 12 +++-- .../New-ModuleManifest.md | 53 ++++++++++++------- ...w-to-write-a-powershell-module-manifest.md | 46 ++++++++-------- 9 files changed, 154 insertions(+), 95 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifests.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifests.md index ecd3c4b9d8c..e50f9b04ec7 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifests.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifests.md @@ -1,7 +1,7 @@ --- description: Describes the settings and practices for writing module manifest files. Locale: en-US -ms.date: 07/07/2023 +ms.date: 09/04/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_module_manifests?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Module_Manifests @@ -64,6 +64,7 @@ PrivateData = @{ # ProjectUri = '' # IconUri = '' # ReleaseNotes = '' + # ExternalModuleDependencies = @() } # End of PSData hashtable } # End of PrivateData hashtable # HelpInfoURI = '' @@ -1470,15 +1471,18 @@ The **PSData** child property is used for the following scenarios: - PowerShell Gallery - When you create a module manifest using `New-ModuleManifest` the cmdlet prepopulates the **PSData** hashtable with - place holder keys that are needed when publishing the module to the - PowerShell Gallery. For more information on module manifests and the - publishing to the PowerShell Gallery, see + placeholder keys needed when publishing the module to the PowerShell Gallery. + For more information on module manifests and the publishing to the PowerShell + Gallery, see [Package manifest values that impact the PowerShell Gallery UI][03]. - Crescendo modules - When you export a Crescendo manifest to create a new module, `Export-CrescendoModule` adds the value `CrescendoBuilt` to the **PSData.Tags** property. You can use this tag to find modules in the PowerShell Gallery that were created using Crescendo. For more information, see [Export-CrescendoModule][15]. +- The **PSData.ExternalModuleDependencies** property is an array of module names + that are dependencies for this module. This property is informational only and + doesn't affect module installation or loading. ### HelpInfoURI diff --git a/reference/5.1/Microsoft.PowerShell.Core/New-ModuleManifest.md b/reference/5.1/Microsoft.PowerShell.Core/New-ModuleManifest.md index cbec9150ce8..027433033d4 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/New-ModuleManifest.md +++ b/reference/5.1/Microsoft.PowerShell.Core/New-ModuleManifest.md @@ -252,8 +252,9 @@ $moduleSettings = @{ New-ModuleManifest @moduleSettings ``` -For information about Updatable Help, see [about_Updatable_Help](./About/about_Updatable_Help.md). -For information about the HelpInfo XML file, see [Supporting Updatable Help](/powershell/scripting/developer/module/supporting-updatable-help). +For information about Updatable Help, see [about_Updatable_Help](About/about_Updatable_Help.md). +For information about the HelpInfo XML file, see +[Supporting Updatable Help](/powershell/scripting/developer/module/supporting-updatable-help). ### Example 5 - Getting module information @@ -951,8 +952,9 @@ Enter each module name as a string or as a hash table with **ModuleName** and ** keys. The hash table can also have an optional **GUID** key. You can combine strings and hash tables in the parameter value. -In PowerShell 2.0, `Import-Module` doesn't import required modules automatically. It just verifies -that the required modules are in the global session state. +When you install a module using the `Install-Module` or `Install-PSResource` commands, these +commands check this list. If the required modules aren't installed, the commands attempt to install +required modules. ```yaml Type: System.Object[] @@ -1139,10 +1141,6 @@ that is installed in the global assembly cache. To add or change files in the `$PSHOME\Modules` directory, start PowerShell with the **Run as administrator** option. -In PowerShell 2.0, many parameters of `New-ModuleManifest` were mandatory, even though they weren't -required in a module manifest. Beginning in PowerShell 3.0, only the **Path** parameter is -mandatory. - A session is an instance of the PowerShell execution environment. A session can have one or more session states. By default, a session has only a global session state, but each imported module has its own session state. Session states allow the commands in a module to run without affecting the @@ -1152,6 +1150,13 @@ The caller's session state is the session state into which a module is imported. refers to the global session state, but when a module imports nested modules, the caller is the module and the caller's session state is the module's session state. +In PowerShell 2.0, many parameters of `New-ModuleManifest` were mandatory, even though they weren't +required in a module manifest. Beginning in PowerShell 3.0, only the **Path** parameter is +mandatory. + +In PowerShell 2.0, `Import-Module` doesn't import required modules automatically. It just verifies +that the required modules are in the global session state. + ## RELATED LINKS [Export-ModuleMember](Export-ModuleMember.md) diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Module_Manifests.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Module_Manifests.md index 567cfbadca1..afb418ecce6 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Module_Manifests.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Module_Manifests.md @@ -1,7 +1,7 @@ --- description: Describes the settings and practices for writing module manifest files. Locale: en-US -ms.date: 07/07/2023 +ms.date: 09/04/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_module_manifests?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Module_Manifests @@ -64,6 +64,7 @@ PrivateData = @{ # ProjectUri = '' # IconUri = '' # ReleaseNotes = '' + # ExternalModuleDependencies = @() } # End of PSData hashtable } # End of PrivateData hashtable # HelpInfoURI = '' @@ -1470,9 +1471,9 @@ The **PSData** child property is used for the following scenarios: - PowerShell Gallery - When you create a module manifest using `New-ModuleManifest` the cmdlet prepopulates the **PSData** hashtable with - place holder keys that are needed when publishing the module to the - PowerShell Gallery. For more information on module manifests and the - publishing to the PowerShell Gallery, see + placeholder keys needed when publishing the module to the PowerShell Gallery. + For more information on module manifests and the publishing to the PowerShell + Gallery, see [Package manifest values that impact the PowerShell Gallery UI][03]. - Experimental features - Metadata about an experimental feature is kept in the **ExperimentalFeatures** property of **PSData**. The **ExperimentalFeatures** @@ -1484,6 +1485,9 @@ The **PSData** child property is used for the following scenarios: **PSData.Tags** property. You can use this tag to find modules in the PowerShell Gallery that were created using Crescendo. For more information, see [Export-CrescendoModule][15]. +- The **PSData.ExternalModuleDependencies** property is an array of module names + that are dependencies for this module. This property is informational only and + doesn't affect module installation or loading. ### HelpInfoURI diff --git a/reference/7.4/Microsoft.PowerShell.Core/New-ModuleManifest.md b/reference/7.4/Microsoft.PowerShell.Core/New-ModuleManifest.md index 2fb759c2159..73af918cccc 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/New-ModuleManifest.md +++ b/reference/7.4/Microsoft.PowerShell.Core/New-ModuleManifest.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 12/09/2022 +ms.date: 09/04/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/new-modulemanifest?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: New-ModuleManifest @@ -121,10 +121,12 @@ Copyright = '(c) ContosoAdmin. All rights reserved.' # Minimum version of the PowerShell host required by this module # PowerShellHostVersion = '' -# Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only. +# Minimum version of Microsoft .NET Framework required by this module. This prerequisite +# is valid for the PowerShell Desktop edition only. # DotNetFrameworkVersion = '' -# Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only. +# Minimum version of the common language runtime (CLR) required by this module. This +# prerequisite is valid for the PowerShell Desktop edition only. # CLRVersion = '' # Processor architecture (None, X86, Amd64) required by this module @@ -136,7 +138,8 @@ Copyright = '(c) ContosoAdmin. All rights reserved.' # Assemblies that must be loaded prior to importing this module # RequiredAssemblies = @() -# Script files (.ps1) that are run in the caller's environment prior to importing this module. +# Script files (.ps1) that are run in the caller's environment prior to importing this +# module. # ScriptsToProcess = @() # Type files (.ps1xml) to be loaded when importing this module @@ -148,16 +151,19 @@ Copyright = '(c) ContosoAdmin. All rights reserved.' # Modules to import as nested modules of the module specified in RootModule/ModuleToProcess # NestedModules = @() -# Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export. +# Functions to export from this module, for best performance, do not use wildcards and do +# not delete the entry, use an empty array if there are no functions to export. FunctionsToExport = @() -# Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export. +# Cmdlets to export from this module, for best performance, do not use wildcards and do +# not delete the entry, use an empty array if there are no cmdlets to export. CmdletsToExport = @() # Variables to export from this module VariablesToExport = '*' -# Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export. +# Aliases to export from this module, for best performance, do not use wildcards and do +# not delete the entry, use an empty array if there are no aliases to export. AliasesToExport = @() # DSC resources to export from this module @@ -169,7 +175,8 @@ AliasesToExport = @() # List of all files packaged with this module # FileList = @() -# Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell. +# Private data to pass to the module specified in RootModule/ModuleToProcess. This may +also contain a PSData hashtable with additional module metadata used by PowerShell. PrivateData = @{ PSData = @{ @@ -205,7 +212,8 @@ PrivateData = @{ # HelpInfo URI of this module # HelpInfoURI = '' -# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix. +# Default prefix for commands exported from this module. Override the default prefix +# using Import-Module -Prefix. # DefaultCommandPrefix = '' } @@ -265,8 +273,9 @@ $moduleSettings = @{ New-ModuleManifest @moduleSettings ``` -For information about Updatable Help, see [about_Updatable_Help](./About/about_Updatable_Help.md). -For information about the HelpInfo XML file, see [Supporting Updatable Help](/powershell/scripting/developer/module/supporting-updatable-help). +For information about Updatable Help, see [about_Updatable_Help](About/about_Updatable_Help.md). +For information about the HelpInfo XML file, see +[Supporting Updatable Help](/powershell/scripting/developer/module/supporting-updatable-help). ### Example 5 - Getting module information @@ -549,7 +558,9 @@ Accept wildcard characters: True ### -ExternalModuleDependencies -A list of external modules that this module is depends on. +A list of external modules that this module is depends on. This list is only used to document the +module's dependencies and is not enforced by PowerShell. It's not used by the PowerShellGet or +PSResourceGet commands, or by the PowerShell Gallery. ```yaml Type: System.String[] @@ -608,7 +619,7 @@ Specifies the functions that the module exports. Wildcards are permitted. You can use this parameter to restrict the functions that are exported by the module. It can remove functions from the list of exported aliases, but it can't add functions to the list. -If you omit this parameter, `New-ModuleManifest` creates an **FunctionsToExport** key with a value +If you omit this parameter, `New-ModuleManifest` creates a **FunctionsToExport** key with a value of `*` (all), meaning that all functions defined in the module are exported by the manifest. ```yaml @@ -1000,8 +1011,9 @@ Enter each module name as a string or as a hash table with **ModuleName** and ** keys. The hash table can also have an optional **GUID** key. You can combine strings and hash tables in the parameter value. -In PowerShell 2.0, `Import-Module` doesn't import required modules automatically. It just verifies -that the required modules are in the global session state. +When you install a module using the `Install-Module` or `Install-PSResource` commands, these +commands check this list. If the required modules aren't installed, the commands attempt to install +required modules. ```yaml Type: System.Object[] @@ -1211,10 +1223,6 @@ administrator** option. > and the error is ignored. All managed DLLs are loaded in the process. This behavior was removed in > PowerShell 7.1. -In PowerShell 2.0, many parameters of `New-ModuleManifest` were mandatory, even though they weren't -required in a module manifest. Beginning in PowerShell 3.0, only the **Path** parameter is -mandatory. - A session is an instance of the PowerShell execution environment. A session can have one or more session states. By default, a session has only a global session state, but each imported module has its own session state. Session states allow the commands in a module to run without affecting the @@ -1224,6 +1232,13 @@ The caller's session state is the session state into which a module is imported. refers to the global session state, but when a module imports nested modules, the caller is the module and the caller's session state is the module's session state. +In PowerShell 2.0, many parameters of `New-ModuleManifest` were mandatory, even though they weren't +required in a module manifest. Beginning in PowerShell 3.0, only the **Path** parameter is +mandatory. + +In PowerShell 2.0, `Import-Module` doesn't import required modules automatically. It just verifies +that the required modules are in the global session state. + ## RELATED LINKS [Export-ModuleMember](Export-ModuleMember.md) diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Module_Manifests.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Module_Manifests.md index 2ecb0f02600..687286857b0 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Module_Manifests.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Module_Manifests.md @@ -1,7 +1,7 @@ --- description: Describes the settings and practices for writing module manifest files. Locale: en-US -ms.date: 07/07/2023 +ms.date: 09/04/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_module_manifests?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Module_Manifests @@ -64,6 +64,7 @@ PrivateData = @{ # ProjectUri = '' # IconUri = '' # ReleaseNotes = '' + # ExternalModuleDependencies = @() } # End of PSData hashtable } # End of PrivateData hashtable # HelpInfoURI = '' @@ -1470,9 +1471,9 @@ The **PSData** child property is used for the following scenarios: - PowerShell Gallery - When you create a module manifest using `New-ModuleManifest` the cmdlet prepopulates the **PSData** hashtable with - place holder keys that are needed when publishing the module to the - PowerShell Gallery. For more information on module manifests and the - publishing to the PowerShell Gallery, see + placeholder keys needed when publishing the module to the PowerShell Gallery. + For more information on module manifests and the publishing to the PowerShell + Gallery, see [Package manifest values that impact the PowerShell Gallery UI][03]. - Experimental features - Metadata about an experimental feature is kept in the **ExperimentalFeatures** property of **PSData**. The **ExperimentalFeatures** @@ -1484,6 +1485,9 @@ The **PSData** child property is used for the following scenarios: **PSData.Tags** property. You can use this tag to find modules in the PowerShell Gallery that were created using Crescendo. For more information, see [Export-CrescendoModule][15]. +- The **PSData.ExternalModuleDependencies** property is an array of module names + that are dependencies for this module. This property is informational only and + doesn't affect module installation or loading. ### HelpInfoURI diff --git a/reference/7.5/Microsoft.PowerShell.Core/New-ModuleManifest.md b/reference/7.5/Microsoft.PowerShell.Core/New-ModuleManifest.md index 14806325b96..e9d38b242b2 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/New-ModuleManifest.md +++ b/reference/7.5/Microsoft.PowerShell.Core/New-ModuleManifest.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 12/09/2022 +ms.date: 09/04/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/new-modulemanifest?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: New-ModuleManifest @@ -558,7 +558,9 @@ Accept wildcard characters: True ### -ExternalModuleDependencies -A list of external modules that this module is depends on. +A list of external modules that this module is depends on. This list is only used to document the +module's dependencies and is not enforced by PowerShell. It's not used by the PowerShellGet or +PSResourceGet commands, or by the PowerShell Gallery. ```yaml Type: System.String[] @@ -617,7 +619,7 @@ Specifies the functions that the module exports. Wildcards are permitted. You can use this parameter to restrict the functions that are exported by the module. It can remove functions from the list of exported aliases, but it can't add functions to the list. -If you omit this parameter, `New-ModuleManifest` creates an **FunctionsToExport** key with a value +If you omit this parameter, `New-ModuleManifest` creates a **FunctionsToExport** key with a value of `*` (all), meaning that all functions defined in the module are exported by the manifest. ```yaml @@ -663,7 +665,7 @@ The HelpInfo XML file supports the Updatable Help feature that was introduced in contains information about the location of downloadable help files for the module and the version numbers of the newest help files for each supported locale. -For information about Updatable Help, see [about_Updatable_Help](About/about_Updatable_Help.md). +For information about Updatable Help, see [about_Updatable_Help](./About/about_Updatable_Help.md). For information about the HelpInfo XML file, see [Supporting Updatable Help](/powershell/scripting/developer/module/supporting-updatable-help). @@ -1009,8 +1011,9 @@ Enter each module name as a string or as a hash table with **ModuleName** and ** keys. The hash table can also have an optional **GUID** key. You can combine strings and hash tables in the parameter value. -In PowerShell 2.0, `Import-Module` doesn't import required modules automatically. It just verifies -that the required modules are in the global session state. +When you install a module using the `Install-Module` or `Install-PSResource` commands, these +commands check this list. If the required modules aren't installed, the commands attempt to install +required modules. ```yaml Type: System.Object[] @@ -1220,10 +1223,6 @@ administrator** option. > and the error is ignored. All managed DLLs are loaded in the process. This behavior was removed in > PowerShell 7.1. -In PowerShell 2.0, many parameters of `New-ModuleManifest` were mandatory, even though they weren't -required in a module manifest. Beginning in PowerShell 3.0, only the **Path** parameter is -mandatory. - A session is an instance of the PowerShell execution environment. A session can have one or more session states. By default, a session has only a global session state, but each imported module has its own session state. Session states allow the commands in a module to run without affecting the @@ -1233,6 +1232,13 @@ The caller's session state is the session state into which a module is imported. refers to the global session state, but when a module imports nested modules, the caller is the module and the caller's session state is the module's session state. +In PowerShell 2.0, many parameters of `New-ModuleManifest` were mandatory, even though they weren't +required in a module manifest. Beginning in PowerShell 3.0, only the **Path** parameter is +mandatory. + +In PowerShell 2.0, `Import-Module` doesn't import required modules automatically. It just verifies +that the required modules are in the global session state. + ## RELATED LINKS [Export-ModuleMember](Export-ModuleMember.md) @@ -1247,4 +1253,4 @@ module and the caller's session state is the module's session state. [Test-ModuleManifest](Test-ModuleManifest.md) -[about_Modules](About/about_Modules.md) +[about_Modules](./About/about_Modules.md) diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Module_Manifests.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Module_Manifests.md index 76b1160e355..39688a9499f 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Module_Manifests.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Module_Manifests.md @@ -1,7 +1,7 @@ --- description: Describes the settings and practices for writing module manifest files. Locale: en-US -ms.date: 07/07/2023 +ms.date: 09/04/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_module_manifests?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Module_Manifests @@ -64,6 +64,7 @@ PrivateData = @{ # ProjectUri = '' # IconUri = '' # ReleaseNotes = '' + # ExternalModuleDependencies = @() } # End of PSData hashtable } # End of PrivateData hashtable # HelpInfoURI = '' @@ -1470,9 +1471,9 @@ The **PSData** child property is used for the following scenarios: - PowerShell Gallery - When you create a module manifest using `New-ModuleManifest` the cmdlet prepopulates the **PSData** hashtable with - place holder keys that are needed when publishing the module to the - PowerShell Gallery. For more information on module manifests and the - publishing to the PowerShell Gallery, see + placeholder keys needed when publishing the module to the PowerShell Gallery. + For more information on module manifests and the publishing to the PowerShell + Gallery, see [Package manifest values that impact the PowerShell Gallery UI][03]. - Experimental features - Metadata about an experimental feature is kept in the **ExperimentalFeatures** property of **PSData**. The **ExperimentalFeatures** @@ -1484,6 +1485,9 @@ The **PSData** child property is used for the following scenarios: **PSData.Tags** property. You can use this tag to find modules in the PowerShell Gallery that were created using Crescendo. For more information, see [Export-CrescendoModule][15]. +- The **PSData.ExternalModuleDependencies** property is an array of module names + that are dependencies for this module. This property is informational only and + doesn't affect module installation or loading. ### HelpInfoURI diff --git a/reference/7.6/Microsoft.PowerShell.Core/New-ModuleManifest.md b/reference/7.6/Microsoft.PowerShell.Core/New-ModuleManifest.md index 270e9624758..3d2c3988d42 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/New-ModuleManifest.md +++ b/reference/7.6/Microsoft.PowerShell.Core/New-ModuleManifest.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 12/09/2022 +ms.date: 09/04/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/new-modulemanifest?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: New-ModuleManifest @@ -121,10 +121,12 @@ Copyright = '(c) ContosoAdmin. All rights reserved.' # Minimum version of the PowerShell host required by this module # PowerShellHostVersion = '' -# Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only. +# Minimum version of Microsoft .NET Framework required by this module. This prerequisite +# is valid for the PowerShell Desktop edition only. # DotNetFrameworkVersion = '' -# Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only. +# Minimum version of the common language runtime (CLR) required by this module. This +# prerequisite is valid for the PowerShell Desktop edition only. # CLRVersion = '' # Processor architecture (None, X86, Amd64) required by this module @@ -136,7 +138,8 @@ Copyright = '(c) ContosoAdmin. All rights reserved.' # Assemblies that must be loaded prior to importing this module # RequiredAssemblies = @() -# Script files (.ps1) that are run in the caller's environment prior to importing this module. +# Script files (.ps1) that are run in the caller's environment prior to importing this +# module. # ScriptsToProcess = @() # Type files (.ps1xml) to be loaded when importing this module @@ -148,16 +151,19 @@ Copyright = '(c) ContosoAdmin. All rights reserved.' # Modules to import as nested modules of the module specified in RootModule/ModuleToProcess # NestedModules = @() -# Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export. +# Functions to export from this module, for best performance, do not use wildcards and do +# not delete the entry, use an empty array if there are no functions to export. FunctionsToExport = @() -# Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export. +# Cmdlets to export from this module, for best performance, do not use wildcards and do +# not delete the entry, use an empty array if there are no cmdlets to export. CmdletsToExport = @() # Variables to export from this module VariablesToExport = '*' -# Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export. +# Aliases to export from this module, for best performance, do not use wildcards and do +# not delete the entry, use an empty array if there are no aliases to export. AliasesToExport = @() # DSC resources to export from this module @@ -169,7 +175,8 @@ AliasesToExport = @() # List of all files packaged with this module # FileList = @() -# Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell. +# Private data to pass to the module specified in RootModule/ModuleToProcess. This may +also contain a PSData hashtable with additional module metadata used by PowerShell. PrivateData = @{ PSData = @{ @@ -205,7 +212,8 @@ PrivateData = @{ # HelpInfo URI of this module # HelpInfoURI = '' -# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix. +# Default prefix for commands exported from this module. Override the default prefix +# using Import-Module -Prefix. # DefaultCommandPrefix = '' } @@ -265,8 +273,9 @@ $moduleSettings = @{ New-ModuleManifest @moduleSettings ``` -For information about Updatable Help, see [about_Updatable_Help](./About/about_Updatable_Help.md). -For information about the HelpInfo XML file, see [Supporting Updatable Help](/powershell/scripting/developer/module/supporting-updatable-help). +For information about Updatable Help, see [about_Updatable_Help](About/about_Updatable_Help.md). +For information about the HelpInfo XML file, see +[Supporting Updatable Help](/powershell/scripting/developer/module/supporting-updatable-help). ### Example 5 - Getting module information @@ -549,7 +558,9 @@ Accept wildcard characters: True ### -ExternalModuleDependencies -A list of external modules that this module is depends on. +A list of external modules that this module is depends on. This list is only used to document the +module's dependencies and is not enforced by PowerShell. It's not used by the PowerShellGet or +PSResourceGet commands, or by the PowerShell Gallery. ```yaml Type: System.String[] @@ -608,7 +619,7 @@ Specifies the functions that the module exports. Wildcards are permitted. You can use this parameter to restrict the functions that are exported by the module. It can remove functions from the list of exported aliases, but it can't add functions to the list. -If you omit this parameter, `New-ModuleManifest` creates an **FunctionsToExport** key with a value +If you omit this parameter, `New-ModuleManifest` creates a **FunctionsToExport** key with a value of `*` (all), meaning that all functions defined in the module are exported by the manifest. ```yaml @@ -1000,8 +1011,9 @@ Enter each module name as a string or as a hash table with **ModuleName** and ** keys. The hash table can also have an optional **GUID** key. You can combine strings and hash tables in the parameter value. -In PowerShell 2.0, `Import-Module` doesn't import required modules automatically. It just verifies -that the required modules are in the global session state. +When you install a module using the `Install-Module` or `Install-PSResource` commands, these +commands check this list. If the required modules aren't installed, the commands attempt to install +required modules. ```yaml Type: System.Object[] @@ -1211,10 +1223,6 @@ administrator** option. > and the error is ignored. All managed DLLs are loaded in the process. This behavior was removed in > PowerShell 7.1. -In PowerShell 2.0, many parameters of `New-ModuleManifest` were mandatory, even though they weren't -required in a module manifest. Beginning in PowerShell 3.0, only the **Path** parameter is -mandatory. - A session is an instance of the PowerShell execution environment. A session can have one or more session states. By default, a session has only a global session state, but each imported module has its own session state. Session states allow the commands in a module to run without affecting the @@ -1224,6 +1232,13 @@ The caller's session state is the session state into which a module is imported. refers to the global session state, but when a module imports nested modules, the caller is the module and the caller's session state is the module's session state. +In PowerShell 2.0, many parameters of `New-ModuleManifest` were mandatory, even though they weren't +required in a module manifest. Beginning in PowerShell 3.0, only the **Path** parameter is +mandatory. + +In PowerShell 2.0, `Import-Module` doesn't import required modules automatically. It just verifies +that the required modules are in the global session state. + ## RELATED LINKS [Export-ModuleMember](Export-ModuleMember.md) diff --git a/reference/docs-conceptual/developer/module/how-to-write-a-powershell-module-manifest.md b/reference/docs-conceptual/developer/module/how-to-write-a-powershell-module-manifest.md index 468146bedcc..e657d9fb4da 100644 --- a/reference/docs-conceptual/developer/module/how-to-write-a-powershell-module-manifest.md +++ b/reference/docs-conceptual/developer/module/how-to-write-a-powershell-module-manifest.md @@ -25,17 +25,17 @@ required to export an assembly that is installed in the [Global Assembly Cache][ manifest is also required for modules that support the Updatable Help feature. Updatable Help uses the **HelpInfoUri** key in the module manifest to find the Help information (HelpInfo XML) file that contains the location of the updated help files for the module. For more information about Updatable -Help, see [Supporting Updatable Help][06]. +Help, see [Supporting Updatable Help][07]. ### To create and use a module manifest -1. The best practice to create a module manifest is to use the [New-ModuleManifest][09] cmdlet. You +1. The best practice to create a module manifest is to use the [New-ModuleManifest][10] cmdlet. You can use parameters to specify one or more of the manifest's default keys and values. The only requirement is to name the file. `New-ModuleManifest` creates a module manifest with your specified values, and includes the remaining keys and their default values. If you need to create multiple modules, use `New-ModuleManifest` to create a module manifest template that can be modified for your different modules. For an example of a default module manifest, see the - [Sample module manifest][05]. + [Sample module manifest][06]. `New-ModuleManifest -Path C:\myModuleName.psd1 -ModuleVersion "2.0" -Author "YourNameHere"` @@ -52,8 +52,8 @@ Help, see [Supporting Updatable Help][06]. **ModuleVersion** number. For descriptions of the keys and values you can include in a module manifest, see the - [Module manifest elements][04] table. For more information, see the parameter descriptions in the - [New-ModuleManifest][09] cmdlet. + [Module manifest elements][05] table. For more information, see the parameter descriptions in the + [New-ModuleManifest][10] cmdlet. 1. To address any scenarios that might not be covered by the base module manifest elements, you have the option to add additional code to your module manifest. @@ -63,7 +63,7 @@ Help, see [Supporting Updatable Help][06]. operators, and the basic PowerShell data types. 1. After you've created your module manifest, you can test it to confirm that any paths described in - the manifest are correct. To test your module manifest, use [Test-ModuleManifest][10]. + the manifest are correct. To test your module manifest, use [Test-ModuleManifest][11]. `Test-ModuleManifest myModuleName.psd1` @@ -73,14 +73,15 @@ Help, see [Supporting Updatable Help][06]. When you copy your module onto a system and import it, PowerShell uses the module manifest to import your module. -1. Optionally, you can directly test your module manifest with a call to [Import-Module][08] by +1. Optionally, you can directly test your module manifest with a call to [Import-Module][09] by dot-sourcing the manifest itself. `Import-Module .\myModuleName.psd1` ## Module manifest elements -The following table describes the elements you can include in a module manifest. +The following table describes the elements you can include in a module manifest. For more detailed +information, see [about_Module_Manifests][04]. | Element | Default | Description | | ------------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -118,7 +119,7 @@ The following table describes the elements you can include in a module manifest. | **ReleaseNotes**
Type: `String` | `` | Specifies the module's release notes.
Example: `ReleaseNotes = 'The release notes provide information about the module.` | | **PreRelease**
Type: `String` | `` | This parameter was added in PowerShellGet 1.6.6. A **PreRelease** string that identifies the module as a prerelease version in online galleries.
Example: `PreRelease = 'alpha'` | | **RequireLicenseAcceptance**
Type: `Boolean` | `$false` | This parameter was added in PowerShellGet 1.5. Flag to indicate whether the module requires explicit user acceptance for install, update, or save.
Example: `RequireLicenseAcceptance = $false` | -| **ExternalModuleDependencies**
Type: `String[]` | `@()` | This parameter was added in PowerShellGet v2. A list of external modules that this module is dependent upon.
Example: `ExternalModuleDependencies = @("ExtModule1", "ExtModule2", "ExtModule3")` | +| **ExternalModuleDependencies**
Type: `String[]` | `@()` | This parameter was added in PowerShellGet v2. A list of external modules that this module is dependent upon.
Example: `ExternalModuleDependencies = @("ExtModule1", "ExtModule2", "ExtModule3")`. This list is informational only. Unlike **RequiredModules**, it isn't used to enforce dependencies. | | **HelpInfoURI**
Type: `String` | `` | HelpInfo URI of this module.
Example: `HelpInfoURI = 'https://www.contoso.com/help'` | | **DefaultCommandPrefix**
Type: `String` | `` | Default prefix for commands exported from this module. Override the default prefix using `Import-Module -Prefix`.
Example: `DefaultCommandPrefix = 'My'` | @@ -266,21 +267,22 @@ PrivateData = @{ - [about_Comparison_Operators][02] - [about_If][03] - [Global Assembly Cache][01] -- [Import-Module][08] -- [New-ModuleManifest][09] -- [Test-ModuleManifest][10] -- [Update-ModuleManifest][11] -- [Writing a Windows PowerShell Module][07] +- [Import-Module][09] +- [New-ModuleManifest][10] +- [Test-ModuleManifest][11] +- [Update-ModuleManifest][12] +- [Writing a Windows PowerShell Module][08] [01]: /dotnet/framework/app-domains/gac [02]: /powershell/module/microsoft.powershell.core/about/about_comparison_operators [03]: /powershell/module/microsoft.powershell.core/about/about_if -[04]: #module-manifest-elements -[05]: #sample-module-manifest -[06]: supporting-updatable-help.md -[07]: writing-a-windows-powershell-module.md -[08]: xref:Microsoft.PowerShell.Core.Import-Module -[09]: xref:Microsoft.PowerShell.Core.New-ModuleManifest -[10]: xref:Microsoft.PowerShell.Core.Test-ModuleManifest -[11]: xref:PowerShellGet.Update-ModuleManifest +[04]: /powershell/module/microsoft.powershell.core/about/about_module_manifests +[05]: #module-manifest-elements +[06]: #sample-module-manifest +[07]: supporting-updatable-help.md +[08]: writing-a-windows-powershell-module.md +[09]: xref:Microsoft.PowerShell.Core.Import-Module +[10]: xref:Microsoft.PowerShell.Core.New-ModuleManifest +[11]: xref:Microsoft.PowerShell.Core.Test-ModuleManifest +[12]: xref:PowerShellGet.Update-ModuleManifest