Service | Microsoft Docs article | Related commit history on GitHub | Change details |
---|---|---|---|
Microsoft.PowerShell.Core | About Module Manifests (5.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifests.md | +--- +description: Describes the settings and practices for writing module manifest files. +Locale: en-US Last updated : 03/30/2022+online version: https://docs.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 +--- +# about_Module_Manifests ++## Short description +Describes the settings and practices for writing module manifest files. ++## Long description ++A module manifest is a PowerShell data file (`.psd1`) containing a hash table. +The keys/value pairs in the hash table describe the contents and attributes of +the module, define the prerequisites, and control how the components are +processed. ++Manifests aren't required to load a module but they are required to publish a +module to the PowerShell Gallery. Manifests also enable you to separate your +module's implementation from how it loads. With a manifest, you can define +requirements, compatibility, loading order, and more. ++When you use `New-ModuleManifest` without specifying any parameters for the +manifest's settings it writes a minimal manifest file. The snippet below shows +you this default output, snipped of commentary and spacing for brevity: ++```powershell +@{ +# RootModule = '' +ModuleVersion = '1.0' +# CompatiblePSEditions = @() +GUID = 'e7184b71-2527-469f-a50e-166b612dfb3b' +Author = 'username' +CompanyName = 'Unknown' +Copyright = '(c) 2022 username. All rights reserved.' +# Description = '' +# PowerShellVersion = '' +# PowerShellHostName = '' +# PowerShellHostVersion = '' +# DotNetFrameworkVersion = '' +# CLRVersion = '' +# ProcessorArchitecture = '' +# RequiredModules = @() +# RequiredAssemblies = @() +# ScriptsToProcess = @() +# TypesToProcess = @() +# FormatsToProcess = @() +# NestedModules = @() +FunctionsToExport = @() +CmdletsToExport = @() +VariablesToExport = '*' +AliasesToExport = @() +# DscResourcesToExport = @() +# ModuleList = @() +# FileList = @() +PrivateData = @{ + PSData = @{ + # Tags = @() + # LicenseUri = '' + # ProjectUri = '' + # IconUri = '' + # ReleaseNotes = '' + } # End of PSData hashtable +} # End of PrivateData hashtable +# HelpInfoURI = '' +# DefaultCommandPrefix = '' +} +``` ++You can use `Test-ModuleManifest` to validate a module manifest before you +publish your module. `Test-ModuleManifest` returns an error if the manifest is +invalid or the module can't be imported into the current session because the +session does not meet requirements set in the manifest. ++## Manifest settings ++The following sections detail every available setting in a module manifest and +how you can use them. They start with a synopsis of the setting and are followed +by a matrix which lists: ++- **Input type**: The object type that you can specify for this setting in the + manifest. +- **Required**: If this value is `Yes`, the setting is required both to import + the module and to publish it to the PowerShell Gallery. If it is `No`, it is + required for neither. If it is `PowerShell Gallery`, it is only required for + publishing to the PowerShell Gallery. +- **Value if unset**: The value this setting has when imported and not + explicitly set. +- **Accepts wildcards**: Whether this setting can take a wildcard + value or not. ++### RootModule ++This setting specifies the primary or root file of the module. When the module +is imported, the members exported by the root module file are imported into the +caller's session state. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++The value must be the file path to one of the following: ++- a script (`.ps1`) +- a script module (`.psm1`) +- a module manifest (`.psd1`) +- an assembly (`.dll`) +- a cmdlet definition XML file (`.cdxml`) +- a Windows PowerShell 5.1 Workflow (`.xaml`) ++The file path should be relative to the module manifest. ++If a module has a manifest file and no root file was designated in the +**RootModule** key, the manifest becomes the primary file for the module, and +the module becomes a manifest module (ModuleType = Manifest). When +**RootModule** is defined, the module's type is determined from the file +extension used: ++- a `.ps1` or `.psm1` file makes the module type **Script** +- a `.psd1` file makes the module type **Manifest** +- a `.dll` file makes the module type **Binary** +- a `.cdxml` file makes the module type **CIM** +- a `.xaml` file makes the module type **Workflow** ++By default, all module members in the **RootModule** are exported. ++> [!TIP] +> Module loading speed differs between **Binary**, **Script**, and **CIM** +> module types. For more information, see +> [PowerShell module authoring considerations](/powershell/scripting/dev-cross-plat/performance/module-authoring-considerations) ++For example, this module's **ModuleType** is **Manifest**. The only module +members this module can export are those defined in the modules specified with +the **NestedModules** setting. ++```powershell +@{ + RootModule = '' +} +``` ++> [!NOTE] +> This setting may also be specified in module manifests as **ModuleToProcess**. +> While that name for this setting is valid, it is best practice to use +> **RootModule** instead. ++### ModuleVersion ++This setting specifies the version of the module. When multiple versions of a +module exist on a system, the latest version is loaded by default when you run +`Import-Module`. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | Yes | +| **Value if unset** | None | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to `System.Version` when you run +`Import-Module`. ++For example, this manifest declares the module's version as `'1.2.3'`. ++```powershell +@{ + ModuleVersion = '1.2.3' +} +``` ++When you import the module and inspect the **Version** property, note that it is +a **System.Version** object and not a string: ++```powershell +$ExampleModule = Import-Module example.psd1 +$ExampleModule.Version +$ExampleModule.Version.GetType().Name +``` ++```Output +Major Minor Build Revision +----- ----- ----- -------- +1 2 3 -1 ++Version +``` ++### CompatiblePSEditions ++This setting specifies the module's compatible PSEditions. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Accepted Values** | `Desktop`, `Core` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++If the value of this setting is `$null`, the module can be imported regardless +of the PSEdition of the session. You can set it to one or more of the accepted +values. ++For information about PSEdition, see: ++- [about_PowerShell_Editions](/powershell/module/microsoft.powershell.core/about/about_powershell_editions) +- [Modules with compatible PowerShell Editions](/powershell/scripting/gallery/concepts/module-psedition-support). ++When this setting is defined, the module can only be imported into a session +where the `$PSEdition` automatic variable's value is included in the setting. ++> [!NOTE] +> Because the `$PSEdition` automatic variable was introduced in version 5.1, +> older versions of Windows PowerShell can't load a module that uses the +> **CompatiblePSEditions** setting. ++For example, you can import this module manifest in any session: ++```powershell +@{ + # CompatiblePSEditions = @() +} +``` ++With the setting specified, this module can only be imported in sessions where +the `$PSEdition` automatic variable's value is `Core`. ++```powershell +@{ + CompatiblePSEditions = @('Core') +} +``` ++### GUID ++This setting specifies a unique identifier for the module. The **GUID** is used +to distinguish between modules with the same name. ++| | Value | +| --------------------- | -------------------------------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `00000000-0000-0000-0000-000000000000` | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to `System.Guid` when you run +`Import-Module`. ++> [!CAUTION] +> While it is not a required setting, not specifying a **GUID** in a manifest +> has no benefits and may lead to name collisions for modules. ++You can create a new guid to use in your manifest: ++```powershell +New-Guid | Select-Object -ExpandProperty Guid +``` ++```Output +8456b025-2fa5-4034-ae47-e6305f3917ca +``` ++```powershell +@{ + GUID = '8456b025-2fa5-4034-ae47-e6305f3917ca' +} +``` ++If there is another module on the machine with the same name, you can still +import the one you want by specifying the module's fully qualified name: ++```powershell +Import-Module -FullyQualifiedName @{ + ModuleName = 'Example' + GUID = '8456b025-2fa5-4034-ae47-e6305f3917ca' + ModuleVersion = '1.0.0' +} +``` ++### Author ++This setting identifies the module author. ++| | Value | +| --------------------- | ------------------ | +| **Input Type** | `System.String` | +| **Required** | PowerShell Gallery | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This manifest declares that the module's author is the Contoso Developer +Experience Team. ++```powershell +@{ + Author = 'Contoso Developer Experience Team' +} +``` ++### CompanyName ++This setting identifies the company or vendor who created the module. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This manifest declares that the module was created by Contoso, Ltd. ++```powershell +@{ + CompanyName = 'Contoso, Ltd.' +} +``` ++### Copyright ++This setting specifies a copyright statement for the module. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This manifest declares a copyright statement reserving all rights to Contoso, +Ltd. as of 2022. ++```powershell +@{ + Copyright = '(c) 2022 Contoso, Ltd. All rights reserved.' +} +``` ++### Description ++This setting describes the module at a high level. ++| | Value | +| --------------------- | ------------------ | +| **Input Type** | `System.String` | +| **Required** | PowerShell Gallery | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This manifest includes a short description. You can also use a here-string to +write a longer or multi-line description. ++```powershell +@{ + Description = 'Provides example commands to show a valid module manifest' +} +``` ++### PowerShellVersion ++This setting specifies the minimum version of PowerShell this module requires. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to `System.Version` when you run +`Import-Module`. ++If this setting is not set, PowerShell does not restrict the module's import +based on the current version. ++For example, this manifest declares that the module is compatible with every +version of PowerShell and Windows PowerShell. ++```powershell +@{ + # PowerShellVersion = '' +} +``` ++With **PowerShellVersion** set to `7.2`, you can only import the module in +PowerShell 7.2 or higher. ++```powershell +@{ + PowerShellVersion = '7.2' +} +``` ++### PowerShellHostName ++This setting specifies the name of the PowerShell host program that the module +requires, such as **Windows PowerShell ISE Host** or **ConsoleHost**. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++You can find the name of the host for a session with the `$Host.Name` statement. +For example, you can see that the host for a remote session is +**ServerRemoteHost** instead of **ConsoleHost**: ++```powershell +$Host.Name +Enter-PSSession -ComputerName localhost +$Host.Name +``` ++```Output +ConsoleHost +[localhost]: PS C:\Users\username\Documents> $Host.Name +ServerRemoteHost +``` ++This module can be imported into any host. ++```powershell +@{ + # PowerShellHostName = '' +} +``` ++With **PowerShellHostName** set to `ServerRemoteHost`, you can only import the +module in a remote PowerShell session. ++```powershell +@{ + PowerShellHostName = 'ServerRemoteHost' +} +``` ++### PowerShellHostVersion ++This setting specifies the minimum version of a PowerShell host program that the +module requires. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to `System.Version` when you run +`Import-Module`. ++> [!CAUTION] +> While this setting can be used without the **PowerShellHostName** setting, it +> increases the odds of unexpected behavior. Only use this setting when you are +> also using the **PowerShellHostName** setting. ++For example, this manifest's module can be imported from any PowerShell session +running in **ConsoleHost**, regardless of the host's version. ++```powershell +@{ + PowerShellHostName = 'ConsoleHost' + # PowerShellHostVersion = '' +} +``` ++With the **PowerShellHostVersion** set to `5.1`, you can only import the module +from any PowerShell session running in **ConsoleHost** where the host's version +is 5.1 or higher. ++```powershell +@{ + PowerShellHostName = 'ConsoleHost' + PowerShellHostVersion = '5.1' +} +``` ++### DotNetFrameworkVersion ++This setting specifies the minimum version of the Microsoft .NET Framework that +the module requires. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This setting only applies to Windows PowerShell. The value of this setting must +be convertible to `System.Version` when you run `Import-Module`. ++For example, this manifest declares that its module can be imported in any +PowerShell or Windows PowerShell session, regardless of the version of the +Microsoft .NET Framework. ++```powershell +@{ + # DotNetFrameworkVersion = '' +} +``` ++With **DotNetFrameworkVersion** set to `4.0`, you can import this module in any +session of Windows PowerShell where the latest available version of the +Microsoft .NET Framework is at least 4.0. You can also import it in any +PowerShell session. ++```powershell +@{ + DotNetFrameworkVersion = '4.0' +} +``` ++### CLRVersion ++This setting specifies the minimum version of the Common Language Runtime (CLR) +of the Microsoft .NET Framework that the module requires. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This setting only applies to Windows PowerShell. The value of this setting must +be convertible to `System.Version` when you run `Import-Module`. ++For example, this manifest declares that its module can be imported in any +PowerShell or Windows PowerShell session, regardless of the version of the +Microsoft .NET Framework's CLR version. ++```powershell +@{ + # CLRVersion = '' +} +``` ++With **CLRVersion** set to `4.0`, you can import this module in any session of +Windows PowerShell where the latest available version of the CLR is at least +4.0. You can also import it in any PowerShell session. ++```powershell +@{ + CLRVersion = '4.0' +} +``` ++### ProcessorArchitecture ++This setting specifies the processor architecture that the module requires. ++| | Value | +| --------------------- | --------------------------------------------- | +| **Input Type** | `System.String` | +| **Accepted Values** | `None`, `MSIL`, `X86`, `IA64`, `Amd64`, `Arm` | +| **Required** | No | +| **Value if unset** | `None` | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to +`System.Reflection.ProcessorArchitecture` when you run `Import-Module`. ++For example, this manifest declares that its module can be imported in any +session, regardless of the system's processor architecture. ++```powershell +@{ + # ProcessorArchitecture = '' +} +``` ++With **ProcessorArchitecture** set to `Amd64`, you can only import this module +in a session running on a machine with a matching architecture. ++```powershell +@{ + ProcessorArchitecture = 'Amd64' +} +``` ++### RequiredModules ++This setting specifies modules that must be in the global session state. If the +required modules aren't in the global session state, PowerShell imports them. If +the required modules aren't available, the `Import-Module` command fails. ++| | Value | +| --------------------- | --------------------------------------------------- | +| **Input Type** | `System.String[]`, `System.Collections.Hashtable[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Entries for this setting can be a module name, a full module specification, or a +path to a module file. ++When the value is a path, the path can be fully qualified or relative. ++When the value is a name or module specification, PowerShell searches the +**PSModulePath** for the specified module. ++A module specification is a hash table that has the following keys. ++- `ModuleName` - **Required**. Specifies the module name. +- `GUID` - **Optional**. Specifies the GUID of the module. +- It's also **Required** to specify at least one of the three below keys. The + `RequiredVersion` key can't be used with the `ModuleVersion` or + `MaximumVersion` keys. You can define an acceptable version range for the + module by specifying the `ModuleVersion` and `MaximumVersion` keys together. + - `ModuleVersion` - Specifies a minimum acceptable version of the module. + - `RequiredVersion` - Specifies an exact, required version of the module. + - `MaximumVersion` - Specifies the maximum acceptable version of the module. ++> [!NOTE] +> `RequiredVersion` was added in Windows PowerShell 5.0. +> `MaximumVersion` was added in Windows PowerShell 5.1. ++For example, this manifest declares that its module does not require any other +modules for its functionality. ++```powershell +@{ + # RequiredModules = @() +} +``` ++This manifest declares that it requires the PSReadLine module. When you run +`Import-Module` on this manifest, PowerShell imports the latest version of +PSReadline that is available to the session. If no version is available, the +import returns an error. ++```powershell +@{ + RequiredModules = @( + 'PSReadLine' + ) +} +``` ++> [!TIP] +> In PowerShell 2.0, `Import-Module` doesn't import required modules +> automatically. It only verifies that the required modules are in the global +> session state. ++This manifest declares that it requires a version of the PSReadLine module +vendored in it's own module folder. When you run `Import-Module` on this +manifest, PowerShell imports the vendored PSReadLine from the specified path. ++```powershell +@{ + RequiredModules = @( + 'Vendored\PSReadline\PSReadline.psd1' + ) +} +``` ++This manifest declares that it specifically requires version 2.0.0 of the +PSReadLine module. When you run `Import-Module` on this manifest, PowerShell +imports version 2.0.0 of PSReadline if it is available. If it is not available, +`Import-Module` returns an error. ++```powershell +@{ + RequiredModules = @( + @{ + ModuleName = 'PSReadLine' + RequiredVersion = '2.0.0' + } + ) +} +``` ++This manifest declares that it requires the PSReadLine module to be imported at +version 2.0.0 or higher. ++```powershell +@{ + RequiredModules = @( + @{ + ModuleName = 'PSReadLine' + ModuleVersion = '2.0.0' + } + ) +} +``` ++This manifest declares that it requires the PSReadLine module to be imported at +version 2.0.0 or lower. ++```powershell +@{ + RequiredModules = @( + @{ + ModuleName = 'PSReadLine' + MaximumVersion = '2.0.0' + } + ) +} +``` ++This manifest declares that it requires the PSDesiredStateConfiguration module +to be imported at a version equal to or higher than 2.0.0 but no higher than +2.99.99. ++```powershell +@{ + RequiredModules = @( + @{ + ModuleName = 'PSDesiredStateConfiguration' + ModuleVersion = '2.0.0' + MaximumVersion = '2.99.99' + } + ) +} +``` ++### RequiredAssemblies ++This setting specifies the assembly (`.dll`) files that the module requires. +PowerShell loads the specified assemblies before updating types or formats, +importing nested modules, or importing the module file that is specified in the +value of the **RootModule** key. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Entries for this setting can be the filename of an assembly or the path to one. +List all required assemblies, even if they are also listed as binary modules in +the **NestedModules** setting. ++This manifest requires the `example.dll` assembly. Before loading any formatting +or type files specified in this manifest, PowerShell loads `example.dll` from +the `Assemblies` folder located in the same directory as the module manifest. ++```powershell +@{ + RequiredAssemblies = @( + 'Assemblies\Example.dll' + ) +} +``` ++### ScriptsToProcess ++This setting specifies script (`.ps1`) files that run in the caller's session +state when the module is imported. You can use these scripts to prepare an +environment, just as you might use a login script. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++To specify scripts that run in the module's session state, use the +**NestedModules** key. ++When you import this manifest, PowerShell runs the `Initialize.ps1` in your +current session. ++```powershell +@{ + ScriptsToProcess = @( + 'Scripts\Initialize.ps1' + ) +} +``` ++For example, if `Initialize.ps1` writes informational messages and sets the +`$ExampleState` variable: ++```powershell +if ([string]::IsNullOrEmpty($ExampleState)) { + Write-Information "Example not initialized." + Write-Information "Initializing now..." + $ExampleState = 'Initialized' +} else { + Write-Information "Example already initialized." +} +``` ++When you import the module, the script runs, writing those messages and setting +`$ExampleState` in your session. ++```powershell +$InformationPreference = 'Continue' +"Example State is: $ExampleState" +Import-Module .\example7x.psd1 +"Example State is: $ExampleState" +Import-Module .\example7x.psd1 -Force +``` ++```Output +Example State is: ++Example not initialized. +Initializing now... ++Example State is: Initialized ++Example already initialized. +``` ++### TypesToProcess ++This setting specifies the type files (`.ps1xml`) that run when the module is +imported. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++When you import the module, PowerShell runs the `Update-TypeData` cmdlet with +the specified files. Because type files aren't scoped, they affect all session +states in the session. ++For more information on type files, see +[about_Types.ps1xml](about_Types.ps1xml.md) ++For example, when you import this manifest, PowerShell loads the types specified +in the `Example.ps1xml` file from the `Types` folder located in the same +directory as the module manifest. ++```powershell +@{ + TypesToProcess = @( + 'Types\Example.ps1xml' + ) +} +``` ++### FormatsToProcess ++This setting specifies the formatting files (`.ps1xml`) that run when the module +is imported. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++When you import a module, PowerShell runs the `Update-FormatData` cmdlet with +the specified files. Because formatting files aren't scoped, they affect all +session states in the session. ++For more information on type files, see +[about_Format.ps1xml](about_Format.ps1xml.md) ++For example, when you import this module, PowerShell loads the formats specified +in the `Example.ps1xml` file from the `Formats` folder located in the same +directory as the module manifest. ++```powershell +@{ + FormatsToProcess = @( + 'Formats\Example.ps1xml' + ) +} +``` ++### NestedModules ++This setting specifies script modules (`.psm1`) and binary modules (`.dll`) that +are imported into the module's session state. You can also specify script files +(`.ps1`). The files in this setting run in the order in which they're listed. ++| | Value | +| --------------------- | --------------------------------------------------- | +| **Input Type** | `System.String[]`, `System.Collections.Hashtable[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Entries for this setting can be a module name, a full module specification, or a +path to a module or script file. ++When the value is a path, the path can be fully qualified or relative. ++When the value is a module name or specification, PowerShell searches the +**PSModulePath** for the specified module. ++A module specification is a hash table that has the following keys. ++- `ModuleName` - **Required**. Specifies the module name. +- `GUID` - **Optional**. Specifies the GUID of the module. +- It's also **Required** to specify at least one of the three below keys. The + `RequiredVersion` key can't be used with the `ModuleVersion` or + `MaximumVersion` keys. You can define an acceptable version range for the + module by specifying the `ModuleVersion` and `MaximumVersion` keys together. + - `ModuleVersion` - Specifies a minimum acceptable version of the module. + - `RequiredVersion` - Specifies an exact, required version of the module. + - `MaximumVersion` - Specifies the maximum acceptable version of the module. ++> [!NOTE] +> `RequiredVersion` was added in Windows PowerShell 5.0. +> `MaximumVersion` was added in Windows PowerShell 5.1. ++Any items that need to be exported from a nested module must exported by the +nested module using the `Export-ModuleMember` cmdlet or be listed in one of the +export properties: ++- **FunctionsToExport** +- **CmdletsToExport** +- **VariablesToExport** +- **AliasesToExport** ++Nested modules in the module session state are available to the root module, but +they aren't returned by a `Get-Module` command in the caller's session state. ++Scripts (`.ps1`) that are listed in this setting are run in the module's session +state, not in the caller's session state. To run a script in the caller's +session state, list the script filename in the **ScriptsToProcess** setting. ++For example, when you import this manifest, the `Helpers.psm1` module is loaded +into the root module's session state. Any cmdlets declared in the nested module +are exported unless otherwise restricted. ++```powershell +@{ + NestedModules = @( + 'Helpers\Helpers.psm1' + ) +} +``` ++### FunctionsToExport ++This setting specifies the functions that the module exports. You can use this +setting to restrict the functions that are exported by the module. It can remove +functions from the list of exported functions, but it can't add functions to the +list. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++You can specify entries in this setting with wildcards. All matching functions +in the list of exported functions are exported. ++> [!TIP] +> For performance and discoverability, you should always explicitly list the +> functions you want your module to export in this setting without using any +> wildcards. ++For example, when you import a module with the setting commented out, all +functions in the root module and any nested modules are exported. ++```powershell +@{ + # FunctionsToExport = @() +} +``` ++This manifest is functionally identical to not specifying the setting at all. ++```powershell +@{ + FunctionsToExport = '*' +} +``` ++With **FunctionsToExport** set as an empty array, when you import this module no +functions the root module or any nested modules export are available. ++```powershell +@{ + FunctionsToExport = @() +} +``` ++> [!NOTE] +> If you create your module manifest with the `New-ModuleManifest` command and +> do not specify the **FunctionsToExport** parameter, the created manifest has +> this setting specified as an empty array. Unless you edit the manifest, no +> functions from the module are exported. ++With **FunctionsToExport** set to only include the `Get-Example` function, when +you import this module only the `Get-Example` function is made available, even +if other functions were exported by the root module or any nested modules. ++```powershell +@{ + FunctionsToExport = @( + 'Get-Example' + ) +} +``` ++With **FunctionsToExport** set with a wildcard string, when you import this +module any function whose name ends with `Example` is made available, even if +other functions were exported as module members by the root module or any nested +modules. ++```powershell +@{ + FunctionsToExport = @( + '*Example' + ) +} +``` ++### CmdletsToExport ++This setting specifies the cmdlets that the module exports. You can use this +setting to restrict the cmdlets that are exported by the module. It can remove +cmdlets from the list of exported module members, but it can't add cmdlets to +the list. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++You can specify entries in this setting with wildcards. All matching cmdlets +in the list of exported cmdlets is exported. ++> [!TIP] +> For performance and discoverability, you should always explicitly list the +> cmdlets you want your module to export in this setting without using any +> wildcards. ++For example, when you import a module with this setting commented out, all +cmdlets in the root module and any nested modules are exported. ++```powershell +@{ + # CmdletsToExport = @() +} +``` ++This manifest is functionally identical to not specifying the setting at all. ++```powershell +@{ + CmdletsToExport = '*' +} +``` ++With **CmdletsToExport** set as an empty array, when you import this module no +cmdlets the root module or any nested modules export are available. ++```powershell +@{ + CmdletsToExport = @() +} +``` ++> [!NOTE] +> If you create your module manifest with the `New-ModuleManifest` command and +> do not specify the **CmdletsToExport** parameter, the created manifest has +> this setting specified as an empty array. Unless you edit the manifest, no +> cmdlets from the module is exported. ++With **CmdletsToExport** set to only include the `Get-Example` cmdlet, when +you import this module only the `Get-Example` cmdlet is made available, even +if other cmdlets were exported by the root module or any nested modules. ++```powershell +@{ + CmdletsToExport = @( + 'Get-Example' + ) +} +``` ++With **CmdletsToExport** set with a wildcard string, when you import this +module any cmdlet whose name ends with `Example` is made available, even if +other cmdlets were exported as module members by the root module or any nested +modules. ++```powershell +@{ + CmdletsToExport = @( + '*Example' + ) +} +``` ++### VariablesToExport ++This setting specifies the variables that the module exports. You can use this +setting to restrict the variables that are exported by the module. It can remove +variables from the list of exported module members, but it can't add variables +to the list. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++You can specify entries in this setting with wildcards. All matching variables +in the list of exported module members is exported. ++> [!TIP] +> For performance and discoverability, you should always explicitly list the +> variables you want your module to export in this setting without using any +> wildcards. ++For example, when you import a module with this setting commented out, all +variables in the root module and any nested modules are exported. ++```powershell +@{ + # VariablesToExport = @() +} +``` ++This manifest is functionally identical to not specifying the setting at all. ++```powershell +@{ + VariablesToExport = '*' +} +``` ++> [!NOTE] +> If you create your module manifest with the `New-ModuleManifest` command and +> do not specify the **VariablesToExport** parameter, the created manifest has +> this setting specified as `'*'`. Unless you edit the manifest, all variables +> from the module is exported. ++With **VariablesToExport** set as an empty array, when you import this module no +variables the root module or any nested modules export are available. ++```powershell +@{ + VariablesToExport = @() +} +``` ++With **VariablesToExport** set to only include the `SomeExample` variable, when +you import this module only the `$SomeExample` variable is made available, even +if other variables were exported by the root module or any nested modules. ++```powershell +@{ + VariablesToExport = @( + 'SomeExample' + ) +} +``` ++With **VariablesToExport** set with a wildcard string, when you import this +module any variable whose name ends with `Example` is made available, even if +other variables were exported as module members by the root module or any nested +modules. ++```powershell +@{ + VariablesToExport = @( + '*Example' + ) +} +``` ++### DscResourcesToExport ++This setting specifies the DSC Resources that the module exports. You can use +this setting to restrict the class-based DSC Resources that are exported by the +module. It can remove DSC Resources from the list of exported module members, +but it can't add DSC Resources to the list. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++You can specify entries in this setting with wildcards. All matching class-based +DSC Resources in the module are exported. ++> [!TIP] +> For discoverability, you should always explicitly list all of the DSC +> Resources your module module exports. ++For more information on authoring and using DSC Resources, see the +[documentation for DSC](/powershell/dsc/overview). ++This manifest exports all of the class-based and MOF-based DSC Resources defined +in the root module and any nested modules. ++```powershell +@{ + # DscResourcesToExport = @() +} +``` ++This manifest exports all of the MOF-based DSC Resources defined in the root +module and any nested modules, but only one class-based DSC Resource, +`ExampleClassResource`. ++```powershell +@{ + DscResourcesToExport = @( + 'ExampleClassResource' + ) +} +``` ++This manifest exports all of the DSC Resources it includes. Even if the +MOF-Based resource was not listed, the module would still export it. ++```powershell +@{ + DscResourcesToExport = @( + 'ExampleClassResource' + 'ExampleMofResourceFirst' + ) +} +``` ++### ModuleList ++This setting is an informational inventory list of the modules included in this +one. This list does not affect the behavior of the module. ++| | Value | +| --------------------- | --------------------------------------------------- | +| **Input Type** | `System.String[]`, `System.Collections.Hashtable[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Entries for this setting can be a module name, a full module specification, or a +path to a module or script file. ++When the value is a path, the path can be fully qualified or relative. ++When the value is a module name or specification, PowerShell searches the +**PSModulePath** for the specified module. ++A module specification is a hash table that has the following keys. ++- `ModuleName` - **Required**. Specifies the module name. +- `GUID` - **Optional**. Specifies the GUID of the module. +- It's also **Required** to specify at least one of the three below keys. The + `RequiredVersion` key can't be used with the `ModuleVersion` or + `MaximumVersion` keys. You can define an acceptable version range for the + module by specifying the `ModuleVersion` and `MaximumVersion` keys together. + - `ModuleVersion` - Specifies a minimum acceptable version of the module. + - `RequiredVersion` - Specifies an exact, required version of the module. + - `MaximumVersion` - Specifies the maximum acceptable version of the module. ++> [!NOTE] +> `RequiredVersion` was added in Windows PowerShell 5.0. +> `MaximumVersion` was added in Windows PowerShell 5.1. ++This manifest does not provide an informational list of the modules it includes. +It may or may not have modules. Even though this setting is not specified, any +modules listed in the **RootModule**, **ScriptsToProcess**, or **NestedModules** +settings will still behave as normal. ++```powershell +@{ + # ModuleList = @() +} +``` ++This manifest declares that the only modules it includes are `Example.psm1` and +the submodules `First.psm1` and `Second.psm1` in the `Submodules` folder. ++```powershell +@{ + ModuleList = @( + 'Example.psm1' + 'Submodules\First.psm1' + 'Submodules\Second.psm1' + ) +} +``` ++### FileList ++This setting is an informational inventory list of the files included in this +module. This list does not affect the behavior of the module. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++Entries for this setting should be the relative path to a file from the folder +containing the module manifest. ++When a user calls `Get-Module` against a manifest with this setting defined, the +**FileList** property of the returned object will be the full path to these +files, joining the module's path with each entry's relative path. ++This manifest does not include a list of its files. ++```powershell +@{ + # FileList = @() +} +``` ++This manifest declares that the only files it includes are listed in this +setting. ++```powershell +@{ + Filelist = @( + 'Example.psd1' + 'Example.psm1' + 'Assemblies\Example.dll' + 'Scripts\Initialize.ps1' + 'Submodules\First.psm1' + 'Submodules\Second.psm1' + ) +} +``` ++### PrivateData ++This setting defines a hash table of data that is available to any commands or +functions in the root module's scope. ++| | Value | +| --------------------- | ------------------------------ | +| **Input Type** | `System.Collections.Hashtable` | +| **Required** | PowerShell Gallery | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This setting has two primary effects: ++1. Any keys added to this setting are available to functions and cmdlets in the + root module with `$MyInvocation.MyCommand.Module.PrivateData`. The hash table + is not available in the module scope itself, only in cmdlets you define in + the module. +1. You can add the **PSData** key with a hash table for metadata needed when + publishing 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](/powershell/scripting/gallery/concepts/package-manifest-affecting-ui) ++For example, this manifest defines the **PublishedDate** key in **PrivateData**. ++```powershell +@{ + PrivateData = @{ + PublishedDate = '2022-06-01' + } +} +``` ++Cmdlets in the module can access this value with the `$MyInvocation` variable. ++```powershell +Function Get-Stale { + [CmdletBinding()] + param() ++ $PublishedDate = $MyInvocation.MyCommand.Module.PrivateData.PublishedDate + $CurrentDate = Get-Date ++ try { + $PublishedDate = Get-Date -Date $PublishedDate -ErrorAction Stop + } catch { + # The date was set in the manifest, set to an invalid value, or the + # script module was directly imported without the manifest. + Throw "Unable to determine published date. Check the module manifest." + } ++ if ($CurrentDate -gt $PublishedDate.AddDays(30)) { + Write-Warning "This module version was published more than 30 days ago." + } else { + $TimeUntilStale = $PublishedDate.AddDays(30) - $CurrentDate + "This module will be stale in $($TimeUntilStale.Days) days" + } +} +``` ++Once the module is imported, the function uses the value from **PrivateData** +to determine when the module was published. ++```powershell +Get-Stale -TestDate '2022-06-15' +Get-Stale -TestDate '2022-08-01' +``` ++```Output +This module will be stale in 16 days ++WARNING: This module version was published more than 30 days ago. +``` ++### HelpInfoURI ++This setting specifies the internet address of the HelpInfo XML file for the +module. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This setting's value must be a Uniform Resource Identifier (URI) that begins +with **http** or **https**. ++The HelpInfo XML file supports the Updatable Help feature that was introduced in +PowerShell 3.0. It 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_Updatable_Help.md). For information about +the HelpInfo XML file, see +[Supporting Updatable Help](/powershell/scripting/developer/module/supporting-updatable-help). ++For example, this module supports updatable help. ++```powershell +@{ + HelpInfoUri = 'http://https://go.microsoft.com/fwlink/?LinkID=603' +} +``` ++### DefaultCommandPrefix ++This setting specifies a prefix that is prepended to the nouns of all commands +in the module when they're imported into a session. Prefixes help prevent +command name conflicts in a user's session. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Module users can override this prefix by specifying the **Prefix** parameter of +the `Import-Module` cmdlet. ++This setting was introduced in PowerShell 3.0. ++When this manifest is imported, any cmdlets imported from this module have +`Example` prepended to the noun in their name. For example, `Get-Item` is +imported as `Get-ExampleItem`. ++```powershell +@{ + DefaultCommandPrefix = 'Example' +} +``` ++## See also ++- [about_PowerShell_Editions](/powershell/module/microsoft.powershell.core/about/about_powershell_editions) +- [New-ModuleManifest](xref:Microsoft.PowerShell.Core.New-ModuleManifest) +- [Test-ModuleManifest](xref:Microsoft.PowerShell.Core.Test-ModuleManifest) +- [Modules with compatible PowerShell Editions](/powershell/scripting/gallery/concepts/module-psedition-support). +- [Package manifest values that impact the PowerShell Gallery UI](/powershell/scripting/gallery/concepts/package-manifest-affecting-ui) +- [PowerShell module authoring considerations](/powershell/scripting/dev-cross-plat/performance/module-authoring-considerations) |
PackageManagement | Packagemanagement (5.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/5.1/PackageManagement/PackageManagement.md | Help Version: 5.2.0.0 Locale: en-US Module Guid: 4ae9fd46-338a-459c-8186-07f910774cb8 Module Name: PackageManagement Previously updated : 06/09/2017 Last updated : 04/21/2022 schema: 2.0.0 Title: PackageManagement --- Title: PackageManagement ## Description -This topic displays help topics for the Package Management Cmdlets. +This topic displays help topics for the Package Management Cmdlets. The cmdlet reference +documentation on this site documents the latest version of the module. > [!IMPORTANT] > As of April 2020, the PowerShell Gallery no longer supports Transport Layer Security (TLS) This topic displays help topics for the Package Management Cmdlets. > trying to access the PowerShell Gallery. Use the following command to ensure you are using TLS > 1.2: >-> `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` +> `[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12` > > For more information, see the > [announcement](https://devblogs.microsoft.com/powershell/powershell-gallery-tls-support/) in the |
PowershellGet | Powershellget (5.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/5.1/PowershellGet/PowerShellGet.md | Help Version: 5.2.0.0 Locale: en-US Module Guid: 1d73a601-4a6c-43c5-ba3f-619b18bbb404 Module Name: PowerShellGet Previously updated : 06/09/2017 Last updated : 04/21/2022 schema: 2.0.0 Title: PowerShellGet --- Title: PowerShellGet PowerShellGet is a module with commands for discovering, installing, updating and publishing PowerShell artifacts like Modules, DSC Resources, Role Capabilities, and Scripts. +The cmdlet reference documentation on this site documents the latest version of the module. + > [!IMPORTANT] > As of April 2020, the PowerShell Gallery no longer supports Transport Layer Security (TLS) > versions 1.0 and 1.1. If you are not using TLS 1.2 or higher, you will receive an error when > trying to access the PowerShell Gallery. Use the following command to ensure you are using TLS > 1.2: >-> `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` +> `[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12` > > For more information, see the > [announcement](https://devblogs.microsoft.com/powershell/powershell-gallery-tls-support/) in the Uninstalls a script. Unregisters a repository. ### [Update-Module](Update-Module.md)-Downloads and installs the newest version of specified modules from an online gallery to the local -computer. +Downloads and installs the newest version of specified modules from an online gallery to the local computer. ### [Update-ModuleManifest](Update-ModuleManifest.md) Updates a module manifest file. |
Microsoft.PowerShell.Core | About Module Manifests (7.0) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/Microsoft.PowerShell.Core/About/about_Module_Manifests.md | +--- +description: Describes the settings and practices for writing module manifest files. +Locale: en-US Last updated : 03/30/2022+online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_module_manifests?view=powershell-7&WT.mc_id=ps-gethelp +schema: 2.0.0 + Title: about Module Manifests +--- +# about_Module_Manifests ++## Short description +Describes the settings and practices for writing module manifest files. ++## Long description ++A module manifest is a PowerShell data file (`.psd1`) containing a hash table. +The keys/value pairs in the hash table describe the contents and attributes of +the module, define the prerequisites, and control how the components are +processed. ++Manifests aren't required to load a module but they are required to publish a +module to the PowerShell Gallery. Manifests also enable you to separate your +module's implementation from how it loads. With a manifest, you can define +requirements, compatibility, loading order, and more. ++When you use `New-ModuleManifest` without specifying any parameters for the +manifest's settings it writes a minimal manifest file. The snippet below shows +you this default output, snipped of commentary and spacing for brevity: ++```powershell +@{ +# RootModule = '' +ModuleVersion = '1.0' +# CompatiblePSEditions = @() +GUID = 'e7184b71-2527-469f-a50e-166b612dfb3b' +Author = 'username' +CompanyName = 'Unknown' +Copyright = '(c) 2022 username. All rights reserved.' +# Description = '' +# PowerShellVersion = '' +# PowerShellHostName = '' +# PowerShellHostVersion = '' +# DotNetFrameworkVersion = '' +# CLRVersion = '' +# ProcessorArchitecture = '' +# RequiredModules = @() +# RequiredAssemblies = @() +# ScriptsToProcess = @() +# TypesToProcess = @() +# FormatsToProcess = @() +# NestedModules = @() +FunctionsToExport = @() +CmdletsToExport = @() +VariablesToExport = '*' +AliasesToExport = @() +# DscResourcesToExport = @() +# ModuleList = @() +# FileList = @() +PrivateData = @{ + PSData = @{ + # Tags = @() + # LicenseUri = '' + # ProjectUri = '' + # IconUri = '' + # ReleaseNotes = '' + } # End of PSData hashtable +} # End of PrivateData hashtable +# HelpInfoURI = '' +# DefaultCommandPrefix = '' +} +``` ++You can use `Test-ModuleManifest` to validate a module manifest before you +publish your module. `Test-ModuleManifest` returns an error if the manifest is +invalid or the module can't be imported into the current session because the +session does not meet requirements set in the manifest. ++## Manifest settings ++The following sections detail every available setting in a module manifest and +how you can use them. They start with a synopsis of the setting and are followed +by a matrix which lists: ++- **Input type**: The object type that you can specify for this setting in the + manifest. +- **Required**: If this value is `Yes`, the setting is required both to import + the module and to publish it to the PowerShell Gallery. If it is `No`, it is + required for neither. If it is `PowerShell Gallery`, it is only required for + publishing to the PowerShell Gallery. +- **Value if unset**: The value this setting has when imported and not + explicitly set. +- **Accepts wildcards**: Whether this setting can take a wildcard + value or not. ++### RootModule ++This setting specifies the primary or root file of the module. When the module +is imported, the members exported by the root module file are imported into the +caller's session state. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++The value must be the file path to one of the following: ++- a script (`.ps1`) +- a script module (`.psm1`) +- a module manifest (`.psd1`) +- an assembly (`.dll`) +- a cmdlet definition XML file (`.cdxml`) +- a Windows PowerShell 5.1 Workflow (`.xaml`) ++The file path should be relative to the module manifest. ++If a module has a manifest file and no root file was designated in the +**RootModule** key, the manifest becomes the primary file for the module, and +the module becomes a manifest module (ModuleType = Manifest). When +**RootModule** is defined, the module's type is determined from the file +extension used: ++- a `.ps1` or `.psm1` file makes the module type **Script** +- a `.psd1` file makes the module type **Manifest** +- a `.dll` file makes the module type **Binary** +- a `.cdxml` file makes the module type **CIM** +- a `.xaml` file makes the module type **Workflow** ++By default, all module members in the **RootModule** are exported. ++> [!TIP] +> Module loading speed differs between **Binary**, **Script**, and **CIM** +> module types. For more information, see +> [PowerShell module authoring considerations](/powershell/scripting/dev-cross-plat/performance/module-authoring-considerations) ++For example, this module's **ModuleType** is **Manifest**. The only module +members this module can export are those defined in the modules specified with +the **NestedModules** setting. ++```powershell +@{ + RootModule = '' +} +``` ++> [!NOTE] +> This setting may also be specified in module manifests as **ModuleToProcess**. +> While that name for this setting is valid, it is best practice to use +> **RootModule** instead. ++### ModuleVersion ++This setting specifies the version of the module. When multiple versions of a +module exist on a system, the latest version is loaded by default when you run +`Import-Module`. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | Yes | +| **Value if unset** | None | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to `System.Version` when you run +`Import-Module`. ++For example, this manifest declares the module's version as `'1.2.3'`. ++```powershell +@{ + ModuleVersion = '1.2.3' +} +``` ++When you import the module and inspect the **Version** property, note that it is +a **System.Version** object and not a string: ++```powershell +$ExampleModule = Import-Module example.psd1 +$ExampleModule.Version +$ExampleModule.Version.GetType().Name +``` ++```Output +Major Minor Build Revision +----- ----- ----- -------- +1 2 3 -1 ++Version +``` ++### CompatiblePSEditions ++This setting specifies the module's compatible PSEditions. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Accepted Values** | `Desktop`, `Core` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++If the value of this setting is `$null`, the module can be imported regardless +of the PSEdition of the session. You can set it to one or more of the accepted +values. ++For information about PSEdition, see: ++- [about_PowerShell_Editions](/powershell/module/microsoft.powershell.core/about/about_powershell_editions) +- [Modules with compatible PowerShell Editions](/powershell/scripting/gallery/concepts/module-psedition-support). ++When this setting is defined, the module can only be imported into a session +where the `$PSEdition` automatic variable's value is included in the setting. ++> [!NOTE] +> Because the `$PSEdition` automatic variable was introduced in version 5.1, +> older versions of Windows PowerShell can't load a module that uses the +> **CompatiblePSEditions** setting. ++For example, you can import this module manifest in any session: ++```powershell +@{ + # CompatiblePSEditions = @() +} +``` ++With the setting specified, this module can only be imported in sessions where +the `$PSEdition` automatic variable's value is `Core`. ++```powershell +@{ + CompatiblePSEditions = @('Core') +} +``` ++### GUID ++This setting specifies a unique identifier for the module. The **GUID** is used +to distinguish between modules with the same name. ++| | Value | +| --------------------- | -------------------------------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `00000000-0000-0000-0000-000000000000` | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to `System.Guid` when you run +`Import-Module`. ++> [!CAUTION] +> While it is not a required setting, not specifying a **GUID** in a manifest +> has no benefits and may lead to name collisions for modules. ++You can create a new guid to use in your manifest: ++```powershell +New-Guid | Select-Object -ExpandProperty Guid +``` ++```Output +8456b025-2fa5-4034-ae47-e6305f3917ca +``` ++```powershell +@{ + GUID = '8456b025-2fa5-4034-ae47-e6305f3917ca' +} +``` ++If there is another module on the machine with the same name, you can still +import the one you want by specifying the module's fully qualified name: ++```powershell +Import-Module -FullyQualifiedName @{ + ModuleName = 'Example' + GUID = '8456b025-2fa5-4034-ae47-e6305f3917ca' + ModuleVersion = '1.0.0' +} +``` ++### Author ++This setting identifies the module author. ++| | Value | +| --------------------- | ------------------ | +| **Input Type** | `System.String` | +| **Required** | PowerShell Gallery | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This manifest declares that the module's author is the Contoso Developer +Experience Team. ++```powershell +@{ + Author = 'Contoso Developer Experience Team' +} +``` ++### CompanyName ++This setting identifies the company or vendor who created the module. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This manifest declares that the module was created by Contoso, Ltd. ++```powershell +@{ + CompanyName = 'Contoso, Ltd.' +} +``` ++### Copyright ++This setting specifies a copyright statement for the module. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This manifest declares a copyright statement reserving all rights to Contoso, +Ltd. as of 2022. ++```powershell +@{ + Copyright = '(c) 2022 Contoso, Ltd. All rights reserved.' +} +``` ++### Description ++This setting describes the module at a high level. ++| | Value | +| --------------------- | ------------------ | +| **Input Type** | `System.String` | +| **Required** | PowerShell Gallery | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This manifest includes a short description. You can also use a here-string to +write a longer or multi-line description. ++```powershell +@{ + Description = 'Provides example commands to show a valid module manifest' +} +``` ++### PowerShellVersion ++This setting specifies the minimum version of PowerShell this module requires. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to `System.Version` when you run +`Import-Module`. ++If this setting is not set, PowerShell does not restrict the module's import +based on the current version. ++For example, this manifest declares that the module is compatible with every +version of PowerShell and Windows PowerShell. ++```powershell +@{ + # PowerShellVersion = '' +} +``` ++With **PowerShellVersion** set to `7.2`, you can only import the module in +PowerShell 7.2 or higher. ++```powershell +@{ + PowerShellVersion = '7.2' +} +``` ++### PowerShellHostName ++This setting specifies the name of the PowerShell host program that the module +requires, such as **Windows PowerShell ISE Host** or **ConsoleHost**. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++You can find the name of the host for a session with the `$Host.Name` statement. +For example, you can see that the host for a remote session is +**ServerRemoteHost** instead of **ConsoleHost**: ++```powershell +$Host.Name +Enter-PSSession -ComputerName localhost +$Host.Name +``` ++```Output +ConsoleHost +[localhost]: PS C:\Users\username\Documents> $Host.Name +ServerRemoteHost +``` ++This module can be imported into any host. ++```powershell +@{ + # PowerShellHostName = '' +} +``` ++With **PowerShellHostName** set to `ServerRemoteHost`, you can only import the +module in a remote PowerShell session. ++```powershell +@{ + PowerShellHostName = 'ServerRemoteHost' +} +``` ++### PowerShellHostVersion ++This setting specifies the minimum version of a PowerShell host program that the +module requires. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to `System.Version` when you run +`Import-Module`. ++> [!CAUTION] +> While this setting can be used without the **PowerShellHostName** setting, it +> increases the odds of unexpected behavior. Only use this setting when you are +> also using the **PowerShellHostName** setting. ++For example, this manifest's module can be imported from any PowerShell session +running in **ConsoleHost**, regardless of the host's version. ++```powershell +@{ + PowerShellHostName = 'ConsoleHost' + # PowerShellHostVersion = '' +} +``` ++With the **PowerShellHostVersion** set to `5.1`, you can only import the module +from any PowerShell session running in **ConsoleHost** where the host's version +is 5.1 or higher. ++```powershell +@{ + PowerShellHostName = 'ConsoleHost' + PowerShellHostVersion = '5.1' +} +``` ++### DotNetFrameworkVersion ++This setting specifies the minimum version of the Microsoft .NET Framework that +the module requires. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This setting only applies to Windows PowerShell. The value of this setting must +be convertible to `System.Version` when you run `Import-Module`. ++For example, this manifest declares that its module can be imported in any +PowerShell or Windows PowerShell session, regardless of the version of the +Microsoft .NET Framework. ++```powershell +@{ + # DotNetFrameworkVersion = '' +} +``` ++With **DotNetFrameworkVersion** set to `4.0`, you can import this module in any +session of Windows PowerShell where the latest available version of the +Microsoft .NET Framework is at least 4.0. You can also import it in any +PowerShell session. ++```powershell +@{ + DotNetFrameworkVersion = '4.0' +} +``` ++### CLRVersion ++This setting specifies the minimum version of the Common Language Runtime (CLR) +of the Microsoft .NET Framework that the module requires. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This setting only applies to Windows PowerShell. The value of this setting must +be convertible to `System.Version` when you run `Import-Module`. ++For example, this manifest declares that its module can be imported in any +PowerShell or Windows PowerShell session, regardless of the version of the +Microsoft .NET Framework's CLR version. ++```powershell +@{ + # CLRVersion = '' +} +``` ++With **CLRVersion** set to `4.0`, you can import this module in any session of +Windows PowerShell where the latest available version of the CLR is at least +4.0. You can also import it in any PowerShell session. ++```powershell +@{ + CLRVersion = '4.0' +} +``` ++### ProcessorArchitecture ++This setting specifies the processor architecture that the module requires. ++| | Value | +| --------------------- | --------------------------------------------- | +| **Input Type** | `System.String` | +| **Accepted Values** | `None`, `MSIL`, `X86`, `IA64`, `Amd64`, `Arm` | +| **Required** | No | +| **Value if unset** | `None` | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to +`System.Reflection.ProcessorArchitecture` when you run `Import-Module`. ++For example, this manifest declares that its module can be imported in any +session, regardless of the system's processor architecture. ++```powershell +@{ + # ProcessorArchitecture = '' +} +``` ++With **ProcessorArchitecture** set to `Amd64`, you can only import this module +in a session running on a machine with a matching architecture. ++```powershell +@{ + ProcessorArchitecture = 'Amd64' +} +``` ++### RequiredModules ++This setting specifies modules that must be in the global session state. If the +required modules aren't in the global session state, PowerShell imports them. If +the required modules aren't available, the `Import-Module` command fails. ++| | Value | +| --------------------- | --------------------------------------------------- | +| **Input Type** | `System.String[]`, `System.Collections.Hashtable[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Entries for this setting can be a module name, a full module specification, or a +path to a module file. ++When the value is a path, the path can be fully qualified or relative. ++When the value is a name or module specification, PowerShell searches the +**PSModulePath** for the specified module. ++A module specification is a hash table that has the following keys. ++- `ModuleName` - **Required**. Specifies the module name. +- `GUID` - **Optional**. Specifies the GUID of the module. +- It's also **Required** to specify at least one of the three below keys. The + `RequiredVersion` key can't be used with the `ModuleVersion` or + `MaximumVersion` keys. You can define an acceptable version range for the + module by specifying the `ModuleVersion` and `MaximumVersion` keys together. + - `ModuleVersion` - Specifies a minimum acceptable version of the module. + - `RequiredVersion` - Specifies an exact, required version of the module. + - `MaximumVersion` - Specifies the maximum acceptable version of the module. ++> [!NOTE] +> `RequiredVersion` was added in Windows PowerShell 5.0. +> `MaximumVersion` was added in Windows PowerShell 5.1. ++For example, this manifest declares that its module does not require any other +modules for its functionality. ++```powershell +@{ + # RequiredModules = @() +} +``` ++This manifest declares that it requires the PSReadLine module. When you run +`Import-Module` on this manifest, PowerShell imports the latest version of +PSReadline that is available to the session. If no version is available, the +import returns an error. ++```powershell +@{ + RequiredModules = @( + 'PSReadLine' + ) +} +``` ++> [!TIP] +> In PowerShell 2.0, `Import-Module` doesn't import required modules +> automatically. It only verifies that the required modules are in the global +> session state. ++This manifest declares that it requires a version of the PSReadLine module +vendored in it's own module folder. When you run `Import-Module` on this +manifest, PowerShell imports the vendored PSReadLine from the specified path. ++```powershell +@{ + RequiredModules = @( + 'Vendored\PSReadline\PSReadline.psd1' + ) +} +``` ++This manifest declares that it specifically requires version 2.0.0 of the +PSReadLine module. When you run `Import-Module` on this manifest, PowerShell +imports version 2.0.0 of PSReadline if it is available. If it is not available, +`Import-Module` returns an error. ++```powershell +@{ + RequiredModules = @( + @{ + ModuleName = 'PSReadLine' + RequiredVersion = '2.0.0' + } + ) +} +``` ++This manifest declares that it requires the PSReadLine module to be imported at +version 2.0.0 or higher. ++```powershell +@{ + RequiredModules = @( + @{ + ModuleName = 'PSReadLine' + ModuleVersion = '2.0.0' + } + ) +} +``` ++This manifest declares that it requires the PSReadLine module to be imported at +version 2.0.0 or lower. ++```powershell +@{ + RequiredModules = @( + @{ + ModuleName = 'PSReadLine' + MaximumVersion = '2.0.0' + } + ) +} +``` ++This manifest declares that it requires the PSDesiredStateConfiguration module +to be imported at a version equal to or higher than 2.0.0 but no higher than +2.99.99. ++```powershell +@{ + RequiredModules = @( + @{ + ModuleName = 'PSDesiredStateConfiguration' + ModuleVersion = '2.0.0' + MaximumVersion = '2.99.99' + } + ) +} +``` ++### RequiredAssemblies ++This setting specifies the assembly (`.dll`) files that the module requires. +PowerShell loads the specified assemblies before updating types or formats, +importing nested modules, or importing the module file that is specified in the +value of the **RootModule** key. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Entries for this setting can be the filename of an assembly or the path to one. +List all required assemblies, even if they are also listed as binary modules in +the **NestedModules** setting. ++This manifest requires the `example.dll` assembly. Before loading any formatting +or type files specified in this manifest, PowerShell loads `example.dll` from +the `Assemblies` folder located in the same directory as the module manifest. ++```powershell +@{ + RequiredAssemblies = @( + 'Assemblies\Example.dll' + ) +} +``` ++### ScriptsToProcess ++This setting specifies script (`.ps1`) files that run in the caller's session +state when the module is imported. You can use these scripts to prepare an +environment, just as you might use a login script. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++To specify scripts that run in the module's session state, use the +**NestedModules** key. ++When you import this manifest, PowerShell runs the `Initialize.ps1` in your +current session. ++```powershell +@{ + ScriptsToProcess = @( + 'Scripts\Initialize.ps1' + ) +} +``` ++For example, if `Initialize.ps1` writes informational messages and sets the +`$ExampleState` variable: ++```powershell +if ([string]::IsNullOrEmpty($ExampleState)) { + Write-Information "Example not initialized." + Write-Information "Initializing now..." + $ExampleState = 'Initialized' +} else { + Write-Information "Example already initialized." +} +``` ++When you import the module, the script runs, writing those messages and setting +`$ExampleState` in your session. ++```powershell +$InformationPreference = 'Continue' +"Example State is: $ExampleState" +Import-Module .\example7x.psd1 +"Example State is: $ExampleState" +Import-Module .\example7x.psd1 -Force +``` ++```Output +Example State is: ++Example not initialized. +Initializing now... ++Example State is: Initialized ++Example already initialized. +``` ++### TypesToProcess ++This setting specifies the type files (`.ps1xml`) that run when the module is +imported. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++When you import the module, PowerShell runs the `Update-TypeData` cmdlet with +the specified files. Because type files aren't scoped, they affect all session +states in the session. ++For more information on type files, see +[about_Types.ps1xml](about_Types.ps1xml.md) ++For example, when you import this manifest, PowerShell loads the types specified +in the `Example.ps1xml` file from the `Types` folder located in the same +directory as the module manifest. ++```powershell +@{ + TypesToProcess = @( + 'Types\Example.ps1xml' + ) +} +``` ++### FormatsToProcess ++This setting specifies the formatting files (`.ps1xml`) that run when the module +is imported. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++When you import a module, PowerShell runs the `Update-FormatData` cmdlet with +the specified files. Because formatting files aren't scoped, they affect all +session states in the session. ++For more information on type files, see +[about_Format.ps1xml](about_Format.ps1xml.md) ++For example, when you import this module, PowerShell loads the formats specified +in the `Example.ps1xml` file from the `Formats` folder located in the same +directory as the module manifest. ++```powershell +@{ + FormatsToProcess = @( + 'Formats\Example.ps1xml' + ) +} +``` ++### NestedModules ++This setting specifies script modules (`.psm1`) and binary modules (`.dll`) that +are imported into the module's session state. You can also specify script files +(`.ps1`). The files in this setting run in the order in which they're listed. ++| | Value | +| --------------------- | --------------------------------------------------- | +| **Input Type** | `System.String[]`, `System.Collections.Hashtable[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Entries for this setting can be a module name, a full module specification, or a +path to a module or script file. ++When the value is a path, the path can be fully qualified or relative. ++When the value is a module name or specification, PowerShell searches the +**PSModulePath** for the specified module. ++A module specification is a hash table that has the following keys. ++- `ModuleName` - **Required**. Specifies the module name. +- `GUID` - **Optional**. Specifies the GUID of the module. +- It's also **Required** to specify at least one of the three below keys. The + `RequiredVersion` key can't be used with the `ModuleVersion` or + `MaximumVersion` keys. You can define an acceptable version range for the + module by specifying the `ModuleVersion` and `MaximumVersion` keys together. + - `ModuleVersion` - Specifies a minimum acceptable version of the module. + - `RequiredVersion` - Specifies an exact, required version of the module. + - `MaximumVersion` - Specifies the maximum acceptable version of the module. ++> [!NOTE] +> `RequiredVersion` was added in Windows PowerShell 5.0. +> `MaximumVersion` was added in Windows PowerShell 5.1. ++Any items that need to be exported from a nested module must exported by the +nested module using the `Export-ModuleMember` cmdlet or be listed in one of the +export properties: ++- **FunctionsToExport** +- **CmdletsToExport** +- **VariablesToExport** +- **AliasesToExport** ++Nested modules in the module session state are available to the root module, but +they aren't returned by a `Get-Module` command in the caller's session state. ++Scripts (`.ps1`) that are listed in this setting are run in the module's session +state, not in the caller's session state. To run a script in the caller's +session state, list the script filename in the **ScriptsToProcess** setting. ++For example, when you import this manifest, the `Helpers.psm1` module is loaded +into the root module's session state. Any cmdlets declared in the nested module +are exported unless otherwise restricted. ++```powershell +@{ + NestedModules = @( + 'Helpers\Helpers.psm1' + ) +} +``` ++### FunctionsToExport ++This setting specifies the functions that the module exports. You can use this +setting to restrict the functions that are exported by the module. It can remove +functions from the list of exported functions, but it can't add functions to the +list. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++You can specify entries in this setting with wildcards. All matching functions +in the list of exported functions are exported. ++> [!TIP] +> For performance and discoverability, you should always explicitly list the +> functions you want your module to export in this setting without using any +> wildcards. ++For example, when you import a module with the setting commented out, all +functions in the root module and any nested modules are exported. ++```powershell +@{ + # FunctionsToExport = @() +} +``` ++This manifest is functionally identical to not specifying the setting at all. ++```powershell +@{ + FunctionsToExport = '*' +} +``` ++With **FunctionsToExport** set as an empty array, when you import this module no +functions the root module or any nested modules export are available. ++```powershell +@{ + FunctionsToExport = @() +} +``` ++> [!NOTE] +> If you create your module manifest with the `New-ModuleManifest` command and +> do not specify the **FunctionsToExport** parameter, the created manifest has +> this setting specified as an empty array. Unless you edit the manifest, no +> functions from the module are exported. ++With **FunctionsToExport** set to only include the `Get-Example` function, when +you import this module only the `Get-Example` function is made available, even +if other functions were exported by the root module or any nested modules. ++```powershell +@{ + FunctionsToExport = @( + 'Get-Example' + ) +} +``` ++With **FunctionsToExport** set with a wildcard string, when you import this +module any function whose name ends with `Example` is made available, even if +other functions were exported as module members by the root module or any nested +modules. ++```powershell +@{ + FunctionsToExport = @( + '*Example' + ) +} +``` ++### CmdletsToExport ++This setting specifies the cmdlets that the module exports. You can use this +setting to restrict the cmdlets that are exported by the module. It can remove +cmdlets from the list of exported module members, but it can't add cmdlets to +the list. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++You can specify entries in this setting with wildcards. All matching cmdlets +in the list of exported cmdlets is exported. ++> [!TIP] +> For performance and discoverability, you should always explicitly list the +> cmdlets you want your module to export in this setting without using any +> wildcards. ++For example, when you import a module with this setting commented out, all +cmdlets in the root module and any nested modules are exported. ++```powershell +@{ + # CmdletsToExport = @() +} +``` ++This manifest is functionally identical to not specifying the setting at all. ++```powershell +@{ + CmdletsToExport = '*' +} +``` ++With **CmdletsToExport** set as an empty array, when you import this module no +cmdlets the root module or any nested modules export are available. ++```powershell +@{ + CmdletsToExport = @() +} +``` ++> [!NOTE] +> If you create your module manifest with the `New-ModuleManifest` command and +> do not specify the **CmdletsToExport** parameter, the created manifest has +> this setting specified as an empty array. Unless you edit the manifest, no +> cmdlets from the module is exported. ++With **CmdletsToExport** set to only include the `Get-Example` cmdlet, when +you import this module only the `Get-Example` cmdlet is made available, even +if other cmdlets were exported by the root module or any nested modules. ++```powershell +@{ + CmdletsToExport = @( + 'Get-Example' + ) +} +``` ++With **CmdletsToExport** set with a wildcard string, when you import this +module any cmdlet whose name ends with `Example` is made available, even if +other cmdlets were exported as module members by the root module or any nested +modules. ++```powershell +@{ + CmdletsToExport = @( + '*Example' + ) +} +``` ++### VariablesToExport ++This setting specifies the variables that the module exports. You can use this +setting to restrict the variables that are exported by the module. It can remove +variables from the list of exported module members, but it can't add variables +to the list. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++You can specify entries in this setting with wildcards. All matching variables +in the list of exported module members is exported. ++> [!TIP] +> For performance and discoverability, you should always explicitly list the +> variables you want your module to export in this setting without using any +> wildcards. ++For example, when you import a module with this setting commented out, all +variables in the root module and any nested modules are exported. ++```powershell +@{ + # VariablesToExport = @() +} +``` ++This manifest is functionally identical to not specifying the setting at all. ++```powershell +@{ + VariablesToExport = '*' +} +``` ++> [!NOTE] +> If you create your module manifest with the `New-ModuleManifest` command and +> do not specify the **VariablesToExport** parameter, the created manifest has +> this setting specified as `'*'`. Unless you edit the manifest, all variables +> from the module is exported. ++With **VariablesToExport** set as an empty array, when you import this module no +variables the root module or any nested modules export are available. ++```powershell +@{ + VariablesToExport = @() +} +``` ++With **VariablesToExport** set to only include the `SomeExample` variable, when +you import this module only the `$SomeExample` variable is made available, even +if other variables were exported by the root module or any nested modules. ++```powershell +@{ + VariablesToExport = @( + 'SomeExample' + ) +} +``` ++With **VariablesToExport** set with a wildcard string, when you import this +module any variable whose name ends with `Example` is made available, even if +other variables were exported as module members by the root module or any nested +modules. ++```powershell +@{ + VariablesToExport = @( + '*Example' + ) +} +``` ++### DscResourcesToExport ++This setting specifies the DSC Resources that the module exports. You can use +this setting to restrict the class-based DSC Resources that are exported by the +module. It can remove DSC Resources from the list of exported module members, +but it can't add DSC Resources to the list. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++You can specify entries in this setting with wildcards. All matching class-based +DSC Resources in the module are exported. ++> [!TIP] +> For discoverability, you should always explicitly list all of the DSC +> Resources your module module exports. ++For more information on authoring and using DSC Resources, see the +[documentation for DSC](/powershell/dsc/overview). ++This manifest exports all of the class-based and MOF-based DSC Resources defined +in the root module and any nested modules. ++```powershell +@{ + # DscResourcesToExport = @() +} +``` ++This manifest exports all of the MOF-based DSC Resources defined in the root +module and any nested modules, but only one class-based DSC Resource, +`ExampleClassResource`. ++```powershell +@{ + DscResourcesToExport = @( + 'ExampleClassResource' + ) +} +``` ++This manifest exports all of the DSC Resources it includes. Even if the +MOF-Based resource was not listed, the module would still export it. ++```powershell +@{ + DscResourcesToExport = @( + 'ExampleClassResource' + 'ExampleMofResourceFirst' + ) +} +``` ++### ModuleList ++This setting is an informational inventory list of the modules included in this +one. This list does not affect the behavior of the module. ++| | Value | +| --------------------- | --------------------------------------------------- | +| **Input Type** | `System.String[]`, `System.Collections.Hashtable[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Entries for this setting can be a module name, a full module specification, or a +path to a module or script file. ++When the value is a path, the path can be fully qualified or relative. ++When the value is a module name or specification, PowerShell searches the +**PSModulePath** for the specified module. ++A module specification is a hash table that has the following keys. ++- `ModuleName` - **Required**. Specifies the module name. +- `GUID` - **Optional**. Specifies the GUID of the module. +- It's also **Required** to specify at least one of the three below keys. The + `RequiredVersion` key can't be used with the `ModuleVersion` or + `MaximumVersion` keys. You can define an acceptable version range for the + module by specifying the `ModuleVersion` and `MaximumVersion` keys together. + - `ModuleVersion` - Specifies a minimum acceptable version of the module. + - `RequiredVersion` - Specifies an exact, required version of the module. + - `MaximumVersion` - Specifies the maximum acceptable version of the module. ++> [!NOTE] +> `RequiredVersion` was added in Windows PowerShell 5.0. +> `MaximumVersion` was added in Windows PowerShell 5.1. ++This manifest does not provide an informational list of the modules it includes. +It may or may not have modules. Even though this setting is not specified, any +modules listed in the **RootModule**, **ScriptsToProcess**, or **NestedModules** +settings will still behave as normal. ++```powershell +@{ + # ModuleList = @() +} +``` ++This manifest declares that the only modules it includes are `Example.psm1` and +the submodules `First.psm1` and `Second.psm1` in the `Submodules` folder. ++```powershell +@{ + ModuleList = @( + 'Example.psm1' + 'Submodules\First.psm1' + 'Submodules\Second.psm1' + ) +} +``` ++### FileList ++This setting is an informational inventory list of the files included in this +module. This list does not affect the behavior of the module. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++Entries for this setting should be the relative path to a file from the folder +containing the module manifest. ++When a user calls `Get-Module` against a manifest with this setting defined, the +**FileList** property of the returned object will be the full path to these +files, joining the module's path with each entry's relative path. ++This manifest does not include a list of its files. ++```powershell +@{ + # FileList = @() +} +``` ++This manifest declares that the only files it includes are listed in this +setting. ++```powershell +@{ + Filelist = @( + 'Example.psd1' + 'Example.psm1' + 'Assemblies\Example.dll' + 'Scripts\Initialize.ps1' + 'Submodules\First.psm1' + 'Submodules\Second.psm1' + ) +} +``` ++### PrivateData ++This setting defines a hash table of data that is available to any commands or +functions in the root module's scope. ++| | Value | +| --------------------- | ------------------------------ | +| **Input Type** | `System.Collections.Hashtable` | +| **Required** | PowerShell Gallery | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This setting has two primary effects: ++1. Any keys added to this setting are available to functions and cmdlets in the + root module with `$MyInvocation.MyCommand.Module.PrivateData`. The hash table + is not available in the module scope itself, only in cmdlets you define in + the module. +1. You can add the **PSData** key with a hash table for metadata needed when + publishing 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](/powershell/scripting/gallery/concepts/package-manifest-affecting-ui) ++For example, this manifest defines the **PublishedDate** key in **PrivateData**. ++```powershell +@{ + PrivateData = @{ + PublishedDate = '2022-06-01' + } +} +``` ++Cmdlets in the module can access this value with the `$MyInvocation` variable. ++```powershell +Function Get-Stale { + [CmdletBinding()] + param() ++ $PublishedDate = $MyInvocation.MyCommand.Module.PrivateData.PublishedDate + $CurrentDate = Get-Date ++ try { + $PublishedDate = Get-Date -Date $PublishedDate -ErrorAction Stop + } catch { + # The date was set in the manifest, set to an invalid value, or the + # script module was directly imported without the manifest. + Throw "Unable to determine published date. Check the module manifest." + } ++ if ($CurrentDate -gt $PublishedDate.AddDays(30)) { + Write-Warning "This module version was published more than 30 days ago." + } else { + $TimeUntilStale = $PublishedDate.AddDays(30) - $CurrentDate + "This module will be stale in $($TimeUntilStale.Days) days" + } +} +``` ++Once the module is imported, the function uses the value from **PrivateData** +to determine when the module was published. ++```powershell +Get-Stale -TestDate '2022-06-15' +Get-Stale -TestDate '2022-08-01' +``` ++```Output +This module will be stale in 16 days ++WARNING: This module version was published more than 30 days ago. +``` ++### HelpInfoURI ++This setting specifies the internet address of the HelpInfo XML file for the +module. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This setting's value must be a Uniform Resource Identifier (URI) that begins +with **http** or **https**. ++The HelpInfo XML file supports the Updatable Help feature that was introduced in +PowerShell 3.0. It 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_Updatable_Help.md). For information about +the HelpInfo XML file, see +[Supporting Updatable Help](/powershell/scripting/developer/module/supporting-updatable-help). ++For example, this module supports updatable help. ++```powershell +@{ + HelpInfoUri = 'http://https://go.microsoft.com/fwlink/?LinkID=603' +} +``` ++### DefaultCommandPrefix ++This setting specifies a prefix that is prepended to the nouns of all commands +in the module when they're imported into a session. Prefixes help prevent +command name conflicts in a user's session. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Module users can override this prefix by specifying the **Prefix** parameter of +the `Import-Module` cmdlet. ++This setting was introduced in PowerShell 3.0. ++When this manifest is imported, any cmdlets imported from this module have +`Example` prepended to the noun in their name. For example, `Get-Item` is +imported as `Get-ExampleItem`. ++```powershell +@{ + DefaultCommandPrefix = 'Example' +} +``` ++## See also ++- [about_PowerShell_Editions](/powershell/module/microsoft.powershell.core/about/about_powershell_editions) +- [New-ModuleManifest](xref:Microsoft.PowerShell.Core.New-ModuleManifest) +- [Test-ModuleManifest](xref:Microsoft.PowerShell.Core.Test-ModuleManifest) +- [Modules with compatible PowerShell Editions](/powershell/scripting/gallery/concepts/module-psedition-support). +- [Package manifest values that impact the PowerShell Gallery UI](/powershell/scripting/gallery/concepts/package-manifest-affecting-ui) +- [PowerShell module authoring considerations](/powershell/scripting/dev-cross-plat/performance/module-authoring-considerations) |
PackageManagement | Packagemanagement (7.0) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/PackageManagement/PackageManagement.md | Help Version: 7.0.1.0 Locale: en-US Module Guid: 4ae9fd46-338a-459c-8186-07f910774cb8 Module Name: PackageManagement Previously updated : 06/09/2017 Last updated : 04/21/2022 schema: 2.0.0 Title: PackageManagement --- Title: PackageManagement ## Description -This topic displays help topics for the Package Management Cmdlets. +This topic displays help topics for the Package Management Cmdlets. The cmdlet reference +documentation on this site documents the latest version of the module. > [!IMPORTANT] > As of April 2020, the PowerShell Gallery no longer supports Transport Layer Security (TLS) This topic displays help topics for the Package Management Cmdlets. > trying to access the PowerShell Gallery. Use the following command to ensure you are using TLS > 1.2: >-> `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` +> `[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12` > > For more information, see the > [announcement](https://devblogs.microsoft.com/powershell/powershell-gallery-tls-support/) in the |
PowerShellGet | Powershellget (7.0) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/PowerShellGet/PowerShellGet.md | Help Version: 7.0.1.0 Locale: en-US Module Guid: 1d73a601-4a6c-43c5-ba3f-619b18bbb404 Module Name: PowerShellGet Previously updated : 06/09/2017 Last updated : 04/21/2022 schema: 2.0.0 Title: PowerShellGet --- Title: PowerShellGet PowerShellGet is a module with commands for discovering, installing, updating and publishing PowerShell artifacts like Modules, DSC Resources, Role Capabilities, and Scripts. +The cmdlet reference documentation on this site documents the latest version of the module. + > [!IMPORTANT] > As of April 2020, the PowerShell Gallery no longer supports Transport Layer Security (TLS) > versions 1.0 and 1.1. If you are not using TLS 1.2 or higher, you will receive an error when > trying to access the PowerShell Gallery. Use the following command to ensure you are using TLS > 1.2: >-> `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` +> `[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12` > > For more information, see the > [announcement](https://devblogs.microsoft.com/powershell/powershell-gallery-tls-support/) in the PowerShell artifacts like Modules, DSC Resources, Role Capabilities, and Scripts Finds PowerShell commands in modules. ### [Find-DscResource](Find-DscResource.md)-Finds Desired State Configuration (DSC) resources. +Finds a DSC resource. ### [Find-Module](Find-Module.md) Finds modules in a repository that match specified criteria. Updates a script. ### [Update-ScriptFileInfo](Update-ScriptFileInfo.md) Updates information for a script.- |
Microsoft.PowerShell.Core | About Module Manifests (7.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/Microsoft.PowerShell.Core/About/about_Module_Manifests.md | +--- +description: Describes the settings and practices for writing module manifest files. +Locale: en-US Last updated : 03/30/2022+online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_module_manifests?view=powershell-7.1&WT.mc_id=ps-gethelp +schema: 2.0.0 + Title: about Module Manifests +--- +# about_Module_Manifests ++## Short description +Describes the settings and practices for writing module manifest files. ++## Long description ++A module manifest is a PowerShell data file (`.psd1`) containing a hash table. +The keys/value pairs in the hash table describe the contents and attributes of +the module, define the prerequisites, and control how the components are +processed. ++Manifests aren't required to load a module but they are required to publish a +module to the PowerShell Gallery. Manifests also enable you to separate your +module's implementation from how it loads. With a manifest, you can define +requirements, compatibility, loading order, and more. ++When you use `New-ModuleManifest` without specifying any parameters for the +manifest's settings it writes a minimal manifest file. The snippet below shows +you this default output, snipped of commentary and spacing for brevity: ++```powershell +@{ +# RootModule = '' +ModuleVersion = '1.0' +# CompatiblePSEditions = @() +GUID = 'e7184b71-2527-469f-a50e-166b612dfb3b' +Author = 'username' +CompanyName = 'Unknown' +Copyright = '(c) 2022 username. All rights reserved.' +# Description = '' +# PowerShellVersion = '' +# PowerShellHostName = '' +# PowerShellHostVersion = '' +# DotNetFrameworkVersion = '' +# CLRVersion = '' +# ProcessorArchitecture = '' +# RequiredModules = @() +# RequiredAssemblies = @() +# ScriptsToProcess = @() +# TypesToProcess = @() +# FormatsToProcess = @() +# NestedModules = @() +FunctionsToExport = @() +CmdletsToExport = @() +VariablesToExport = '*' +AliasesToExport = @() +# DscResourcesToExport = @() +# ModuleList = @() +# FileList = @() +PrivateData = @{ + PSData = @{ + # Tags = @() + # LicenseUri = '' + # ProjectUri = '' + # IconUri = '' + # ReleaseNotes = '' + } # End of PSData hashtable +} # End of PrivateData hashtable +# HelpInfoURI = '' +# DefaultCommandPrefix = '' +} +``` ++You can use `Test-ModuleManifest` to validate a module manifest before you +publish your module. `Test-ModuleManifest` returns an error if the manifest is +invalid or the module can't be imported into the current session because the +session does not meet requirements set in the manifest. ++## Manifest settings ++The following sections detail every available setting in a module manifest and +how you can use them. They start with a synopsis of the setting and are followed +by a matrix which lists: ++- **Input type**: The object type that you can specify for this setting in the + manifest. +- **Required**: If this value is `Yes`, the setting is required both to import + the module and to publish it to the PowerShell Gallery. If it is `No`, it is + required for neither. If it is `PowerShell Gallery`, it is only required for + publishing to the PowerShell Gallery. +- **Value if unset**: The value this setting has when imported and not + explicitly set. +- **Accepts wildcards**: Whether this setting can take a wildcard + value or not. ++### RootModule ++This setting specifies the primary or root file of the module. When the module +is imported, the members exported by the root module file are imported into the +caller's session state. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++The value must be the file path to one of the following: ++- a script (`.ps1`) +- a script module (`.psm1`) +- a module manifest (`.psd1`) +- an assembly (`.dll`) +- a cmdlet definition XML file (`.cdxml`) +- a Windows PowerShell 5.1 Workflow (`.xaml`) ++The file path should be relative to the module manifest. ++If a module has a manifest file and no root file was designated in the +**RootModule** key, the manifest becomes the primary file for the module, and +the module becomes a manifest module (ModuleType = Manifest). When +**RootModule** is defined, the module's type is determined from the file +extension used: ++- a `.ps1` or `.psm1` file makes the module type **Script** +- a `.psd1` file makes the module type **Manifest** +- a `.dll` file makes the module type **Binary** +- a `.cdxml` file makes the module type **CIM** +- a `.xaml` file makes the module type **Workflow** ++By default, all module members in the **RootModule** are exported. ++> [!TIP] +> Module loading speed differs between **Binary**, **Script**, and **CIM** +> module types. For more information, see +> [PowerShell module authoring considerations](/powershell/scripting/dev-cross-plat/performance/module-authoring-considerations) ++For example, this module's **ModuleType** is **Manifest**. The only module +members this module can export are those defined in the modules specified with +the **NestedModules** setting. ++```powershell +@{ + RootModule = '' +} +``` ++> [!NOTE] +> This setting may also be specified in module manifests as **ModuleToProcess**. +> While that name for this setting is valid, it is best practice to use +> **RootModule** instead. ++### ModuleVersion ++This setting specifies the version of the module. When multiple versions of a +module exist on a system, the latest version is loaded by default when you run +`Import-Module`. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | Yes | +| **Value if unset** | None | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to `System.Version` when you run +`Import-Module`. ++For example, this manifest declares the module's version as `'1.2.3'`. ++```powershell +@{ + ModuleVersion = '1.2.3' +} +``` ++When you import the module and inspect the **Version** property, note that it is +a **System.Version** object and not a string: ++```powershell +$ExampleModule = Import-Module example.psd1 +$ExampleModule.Version +$ExampleModule.Version.GetType().Name +``` ++```Output +Major Minor Build Revision +----- ----- ----- -------- +1 2 3 -1 ++Version +``` ++### CompatiblePSEditions ++This setting specifies the module's compatible PSEditions. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Accepted Values** | `Desktop`, `Core` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++If the value of this setting is `$null`, the module can be imported regardless +of the PSEdition of the session. You can set it to one or more of the accepted +values. ++For information about PSEdition, see: ++- [about_PowerShell_Editions](/powershell/module/microsoft.powershell.core/about/about_powershell_editions) +- [Modules with compatible PowerShell Editions](/powershell/scripting/gallery/concepts/module-psedition-support). ++When this setting is defined, the module can only be imported into a session +where the `$PSEdition` automatic variable's value is included in the setting. ++> [!NOTE] +> Because the `$PSEdition` automatic variable was introduced in version 5.1, +> older versions of Windows PowerShell can't load a module that uses the +> **CompatiblePSEditions** setting. ++For example, you can import this module manifest in any session: ++```powershell +@{ + # CompatiblePSEditions = @() +} +``` ++With the setting specified, this module can only be imported in sessions where +the `$PSEdition` automatic variable's value is `Core`. ++```powershell +@{ + CompatiblePSEditions = @('Core') +} +``` ++### GUID ++This setting specifies a unique identifier for the module. The **GUID** is used +to distinguish between modules with the same name. ++| | Value | +| --------------------- | -------------------------------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `00000000-0000-0000-0000-000000000000` | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to `System.Guid` when you run +`Import-Module`. ++> [!CAUTION] +> While it is not a required setting, not specifying a **GUID** in a manifest +> has no benefits and may lead to name collisions for modules. ++You can create a new guid to use in your manifest: ++```powershell +New-Guid | Select-Object -ExpandProperty Guid +``` ++```Output +8456b025-2fa5-4034-ae47-e6305f3917ca +``` ++```powershell +@{ + GUID = '8456b025-2fa5-4034-ae47-e6305f3917ca' +} +``` ++If there is another module on the machine with the same name, you can still +import the one you want by specifying the module's fully qualified name: ++```powershell +Import-Module -FullyQualifiedName @{ + ModuleName = 'Example' + GUID = '8456b025-2fa5-4034-ae47-e6305f3917ca' + ModuleVersion = '1.0.0' +} +``` ++### Author ++This setting identifies the module author. ++| | Value | +| --------------------- | ------------------ | +| **Input Type** | `System.String` | +| **Required** | PowerShell Gallery | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This manifest declares that the module's author is the Contoso Developer +Experience Team. ++```powershell +@{ + Author = 'Contoso Developer Experience Team' +} +``` ++### CompanyName ++This setting identifies the company or vendor who created the module. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This manifest declares that the module was created by Contoso, Ltd. ++```powershell +@{ + CompanyName = 'Contoso, Ltd.' +} +``` ++### Copyright ++This setting specifies a copyright statement for the module. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This manifest declares a copyright statement reserving all rights to Contoso, +Ltd. as of 2022. ++```powershell +@{ + Copyright = '(c) 2022 Contoso, Ltd. All rights reserved.' +} +``` ++### Description ++This setting describes the module at a high level. ++| | Value | +| --------------------- | ------------------ | +| **Input Type** | `System.String` | +| **Required** | PowerShell Gallery | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This manifest includes a short description. You can also use a here-string to +write a longer or multi-line description. ++```powershell +@{ + Description = 'Provides example commands to show a valid module manifest' +} +``` ++### PowerShellVersion ++This setting specifies the minimum version of PowerShell this module requires. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to `System.Version` when you run +`Import-Module`. ++If this setting is not set, PowerShell does not restrict the module's import +based on the current version. ++For example, this manifest declares that the module is compatible with every +version of PowerShell and Windows PowerShell. ++```powershell +@{ + # PowerShellVersion = '' +} +``` ++With **PowerShellVersion** set to `7.2`, you can only import the module in +PowerShell 7.2 or higher. ++```powershell +@{ + PowerShellVersion = '7.2' +} +``` ++### PowerShellHostName ++This setting specifies the name of the PowerShell host program that the module +requires, such as **Windows PowerShell ISE Host** or **ConsoleHost**. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++You can find the name of the host for a session with the `$Host.Name` statement. +For example, you can see that the host for a remote session is +**ServerRemoteHost** instead of **ConsoleHost**: ++```powershell +$Host.Name +Enter-PSSession -ComputerName localhost +$Host.Name +``` ++```Output +ConsoleHost +[localhost]: PS C:\Users\username\Documents> $Host.Name +ServerRemoteHost +``` ++This module can be imported into any host. ++```powershell +@{ + # PowerShellHostName = '' +} +``` ++With **PowerShellHostName** set to `ServerRemoteHost`, you can only import the +module in a remote PowerShell session. ++```powershell +@{ + PowerShellHostName = 'ServerRemoteHost' +} +``` ++### PowerShellHostVersion ++This setting specifies the minimum version of a PowerShell host program that the +module requires. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to `System.Version` when you run +`Import-Module`. ++> [!CAUTION] +> While this setting can be used without the **PowerShellHostName** setting, it +> increases the odds of unexpected behavior. Only use this setting when you are +> also using the **PowerShellHostName** setting. ++For example, this manifest's module can be imported from any PowerShell session +running in **ConsoleHost**, regardless of the host's version. ++```powershell +@{ + PowerShellHostName = 'ConsoleHost' + # PowerShellHostVersion = '' +} +``` ++With the **PowerShellHostVersion** set to `5.1`, you can only import the module +from any PowerShell session running in **ConsoleHost** where the host's version +is 5.1 or higher. ++```powershell +@{ + PowerShellHostName = 'ConsoleHost' + PowerShellHostVersion = '5.1' +} +``` ++### DotNetFrameworkVersion ++This setting specifies the minimum version of the Microsoft .NET Framework that +the module requires. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This setting only applies to Windows PowerShell. The value of this setting must +be convertible to `System.Version` when you run `Import-Module`. ++For example, this manifest declares that its module can be imported in any +PowerShell or Windows PowerShell session, regardless of the version of the +Microsoft .NET Framework. ++```powershell +@{ + # DotNetFrameworkVersion = '' +} +``` ++With **DotNetFrameworkVersion** set to `4.0`, you can import this module in any +session of Windows PowerShell where the latest available version of the +Microsoft .NET Framework is at least 4.0. You can also import it in any +PowerShell session. ++```powershell +@{ + DotNetFrameworkVersion = '4.0' +} +``` ++### CLRVersion ++This setting specifies the minimum version of the Common Language Runtime (CLR) +of the Microsoft .NET Framework that the module requires. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This setting only applies to Windows PowerShell. The value of this setting must +be convertible to `System.Version` when you run `Import-Module`. ++For example, this manifest declares that its module can be imported in any +PowerShell or Windows PowerShell session, regardless of the version of the +Microsoft .NET Framework's CLR version. ++```powershell +@{ + # CLRVersion = '' +} +``` ++With **CLRVersion** set to `4.0`, you can import this module in any session of +Windows PowerShell where the latest available version of the CLR is at least +4.0. You can also import it in any PowerShell session. ++```powershell +@{ + CLRVersion = '4.0' +} +``` ++### ProcessorArchitecture ++This setting specifies the processor architecture that the module requires. ++| | Value | +| --------------------- | --------------------------------------------- | +| **Input Type** | `System.String` | +| **Accepted Values** | `None`, `MSIL`, `X86`, `IA64`, `Amd64`, `Arm` | +| **Required** | No | +| **Value if unset** | `None` | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to +`System.Reflection.ProcessorArchitecture` when you run `Import-Module`. ++For example, this manifest declares that its module can be imported in any +session, regardless of the system's processor architecture. ++```powershell +@{ + # ProcessorArchitecture = '' +} +``` ++With **ProcessorArchitecture** set to `Amd64`, you can only import this module +in a session running on a machine with a matching architecture. ++```powershell +@{ + ProcessorArchitecture = 'Amd64' +} +``` ++### RequiredModules ++This setting specifies modules that must be in the global session state. If the +required modules aren't in the global session state, PowerShell imports them. If +the required modules aren't available, the `Import-Module` command fails. ++| | Value | +| --------------------- | --------------------------------------------------- | +| **Input Type** | `System.String[]`, `System.Collections.Hashtable[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Entries for this setting can be a module name, a full module specification, or a +path to a module file. ++When the value is a path, the path can be fully qualified or relative. ++When the value is a name or module specification, PowerShell searches the +**PSModulePath** for the specified module. ++A module specification is a hash table that has the following keys. ++- `ModuleName` - **Required**. Specifies the module name. +- `GUID` - **Optional**. Specifies the GUID of the module. +- It's also **Required** to specify at least one of the three below keys. The + `RequiredVersion` key can't be used with the `ModuleVersion` or + `MaximumVersion` keys. You can define an acceptable version range for the + module by specifying the `ModuleVersion` and `MaximumVersion` keys together. + - `ModuleVersion` - Specifies a minimum acceptable version of the module. + - `RequiredVersion` - Specifies an exact, required version of the module. + - `MaximumVersion` - Specifies the maximum acceptable version of the module. ++> [!NOTE] +> `RequiredVersion` was added in Windows PowerShell 5.0. +> `MaximumVersion` was added in Windows PowerShell 5.1. ++For example, this manifest declares that its module does not require any other +modules for its functionality. ++```powershell +@{ + # RequiredModules = @() +} +``` ++This manifest declares that it requires the PSReadLine module. When you run +`Import-Module` on this manifest, PowerShell imports the latest version of +PSReadline that is available to the session. If no version is available, the +import returns an error. ++```powershell +@{ + RequiredModules = @( + 'PSReadLine' + ) +} +``` ++> [!TIP] +> In PowerShell 2.0, `Import-Module` doesn't import required modules +> automatically. It only verifies that the required modules are in the global +> session state. ++This manifest declares that it requires a version of the PSReadLine module +vendored in it's own module folder. When you run `Import-Module` on this +manifest, PowerShell imports the vendored PSReadLine from the specified path. ++```powershell +@{ + RequiredModules = @( + 'Vendored\PSReadline\PSReadline.psd1' + ) +} +``` ++This manifest declares that it specifically requires version 2.0.0 of the +PSReadLine module. When you run `Import-Module` on this manifest, PowerShell +imports version 2.0.0 of PSReadline if it is available. If it is not available, +`Import-Module` returns an error. ++```powershell +@{ + RequiredModules = @( + @{ + ModuleName = 'PSReadLine' + RequiredVersion = '2.0.0' + } + ) +} +``` ++This manifest declares that it requires the PSReadLine module to be imported at +version 2.0.0 or higher. ++```powershell +@{ + RequiredModules = @( + @{ + ModuleName = 'PSReadLine' + ModuleVersion = '2.0.0' + } + ) +} +``` ++This manifest declares that it requires the PSReadLine module to be imported at +version 2.0.0 or lower. ++```powershell +@{ + RequiredModules = @( + @{ + ModuleName = 'PSReadLine' + MaximumVersion = '2.0.0' + } + ) +} +``` ++This manifest declares that it requires the PSDesiredStateConfiguration module +to be imported at a version equal to or higher than 2.0.0 but no higher than +2.99.99. ++```powershell +@{ + RequiredModules = @( + @{ + ModuleName = 'PSDesiredStateConfiguration' + ModuleVersion = '2.0.0' + MaximumVersion = '2.99.99' + } + ) +} +``` ++### RequiredAssemblies ++This setting specifies the assembly (`.dll`) files that the module requires. +PowerShell loads the specified assemblies before updating types or formats, +importing nested modules, or importing the module file that is specified in the +value of the **RootModule** key. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Entries for this setting can be the filename of an assembly or the path to one. +List all required assemblies, even if they are also listed as binary modules in +the **NestedModules** setting. ++This manifest requires the `example.dll` assembly. Before loading any formatting +or type files specified in this manifest, PowerShell loads `example.dll` from +the `Assemblies` folder located in the same directory as the module manifest. ++```powershell +@{ + RequiredAssemblies = @( + 'Assemblies\Example.dll' + ) +} +``` ++### ScriptsToProcess ++This setting specifies script (`.ps1`) files that run in the caller's session +state when the module is imported. You can use these scripts to prepare an +environment, just as you might use a login script. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++To specify scripts that run in the module's session state, use the +**NestedModules** key. ++When you import this manifest, PowerShell runs the `Initialize.ps1` in your +current session. ++```powershell +@{ + ScriptsToProcess = @( + 'Scripts\Initialize.ps1' + ) +} +``` ++For example, if `Initialize.ps1` writes informational messages and sets the +`$ExampleState` variable: ++```powershell +if ([string]::IsNullOrEmpty($ExampleState)) { + Write-Information "Example not initialized." + Write-Information "Initializing now..." + $ExampleState = 'Initialized' +} else { + Write-Information "Example already initialized." +} +``` ++When you import the module, the script runs, writing those messages and setting +`$ExampleState` in your session. ++```powershell +$InformationPreference = 'Continue' +"Example State is: $ExampleState" +Import-Module .\example7x.psd1 +"Example State is: $ExampleState" +Import-Module .\example7x.psd1 -Force +``` ++```Output +Example State is: ++Example not initialized. +Initializing now... ++Example State is: Initialized ++Example already initialized. +``` ++### TypesToProcess ++This setting specifies the type files (`.ps1xml`) that run when the module is +imported. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++When you import the module, PowerShell runs the `Update-TypeData` cmdlet with +the specified files. Because type files aren't scoped, they affect all session +states in the session. ++For more information on type files, see +[about_Types.ps1xml](about_Types.ps1xml.md) ++For example, when you import this manifest, PowerShell loads the types specified +in the `Example.ps1xml` file from the `Types` folder located in the same +directory as the module manifest. ++```powershell +@{ + TypesToProcess = @( + 'Types\Example.ps1xml' + ) +} +``` ++### FormatsToProcess ++This setting specifies the formatting files (`.ps1xml`) that run when the module +is imported. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++When you import a module, PowerShell runs the `Update-FormatData` cmdlet with +the specified files. Because formatting files aren't scoped, they affect all +session states in the session. ++For more information on type files, see +[about_Format.ps1xml](about_Format.ps1xml.md) ++For example, when you import this module, PowerShell loads the formats specified +in the `Example.ps1xml` file from the `Formats` folder located in the same +directory as the module manifest. ++```powershell +@{ + FormatsToProcess = @( + 'Formats\Example.ps1xml' + ) +} +``` ++### NestedModules ++This setting specifies script modules (`.psm1`) and binary modules (`.dll`) that +are imported into the module's session state. You can also specify script files +(`.ps1`). The files in this setting run in the order in which they're listed. ++| | Value | +| --------------------- | --------------------------------------------------- | +| **Input Type** | `System.String[]`, `System.Collections.Hashtable[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Entries for this setting can be a module name, a full module specification, or a +path to a module or script file. ++When the value is a path, the path can be fully qualified or relative. ++When the value is a module name or specification, PowerShell searches the +**PSModulePath** for the specified module. ++A module specification is a hash table that has the following keys. ++- `ModuleName` - **Required**. Specifies the module name. +- `GUID` - **Optional**. Specifies the GUID of the module. +- It's also **Required** to specify at least one of the three below keys. The + `RequiredVersion` key can't be used with the `ModuleVersion` or + `MaximumVersion` keys. You can define an acceptable version range for the + module by specifying the `ModuleVersion` and `MaximumVersion` keys together. + - `ModuleVersion` - Specifies a minimum acceptable version of the module. + - `RequiredVersion` - Specifies an exact, required version of the module. + - `MaximumVersion` - Specifies the maximum acceptable version of the module. ++> [!NOTE] +> `RequiredVersion` was added in Windows PowerShell 5.0. +> `MaximumVersion` was added in Windows PowerShell 5.1. ++Any items that need to be exported from a nested module must exported by the +nested module using the `Export-ModuleMember` cmdlet or be listed in one of the +export properties: ++- **FunctionsToExport** +- **CmdletsToExport** +- **VariablesToExport** +- **AliasesToExport** ++Nested modules in the module session state are available to the root module, but +they aren't returned by a `Get-Module` command in the caller's session state. ++Scripts (`.ps1`) that are listed in this setting are run in the module's session +state, not in the caller's session state. To run a script in the caller's +session state, list the script filename in the **ScriptsToProcess** setting. ++For example, when you import this manifest, the `Helpers.psm1` module is loaded +into the root module's session state. Any cmdlets declared in the nested module +are exported unless otherwise restricted. ++```powershell +@{ + NestedModules = @( + 'Helpers\Helpers.psm1' + ) +} +``` ++### FunctionsToExport ++This setting specifies the functions that the module exports. You can use this +setting to restrict the functions that are exported by the module. It can remove +functions from the list of exported functions, but it can't add functions to the +list. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++You can specify entries in this setting with wildcards. All matching functions +in the list of exported functions are exported. ++> [!TIP] +> For performance and discoverability, you should always explicitly list the +> functions you want your module to export in this setting without using any +> wildcards. ++For example, when you import a module with the setting commented out, all +functions in the root module and any nested modules are exported. ++```powershell +@{ + # FunctionsToExport = @() +} +``` ++This manifest is functionally identical to not specifying the setting at all. ++```powershell +@{ + FunctionsToExport = '*' +} +``` ++With **FunctionsToExport** set as an empty array, when you import this module no +functions the root module or any nested modules export are available. ++```powershell +@{ + FunctionsToExport = @() +} +``` ++> [!NOTE] +> If you create your module manifest with the `New-ModuleManifest` command and +> do not specify the **FunctionsToExport** parameter, the created manifest has +> this setting specified as an empty array. Unless you edit the manifest, no +> functions from the module are exported. ++With **FunctionsToExport** set to only include the `Get-Example` function, when +you import this module only the `Get-Example` function is made available, even +if other functions were exported by the root module or any nested modules. ++```powershell +@{ + FunctionsToExport = @( + 'Get-Example' + ) +} +``` ++With **FunctionsToExport** set with a wildcard string, when you import this +module any function whose name ends with `Example` is made available, even if +other functions were exported as module members by the root module or any nested +modules. ++```powershell +@{ + FunctionsToExport = @( + '*Example' + ) +} +``` ++### CmdletsToExport ++This setting specifies the cmdlets that the module exports. You can use this +setting to restrict the cmdlets that are exported by the module. It can remove +cmdlets from the list of exported module members, but it can't add cmdlets to +the list. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++You can specify entries in this setting with wildcards. All matching cmdlets +in the list of exported cmdlets is exported. ++> [!TIP] +> For performance and discoverability, you should always explicitly list the +> cmdlets you want your module to export in this setting without using any +> wildcards. ++For example, when you import a module with this setting commented out, all +cmdlets in the root module and any nested modules are exported. ++```powershell +@{ + # CmdletsToExport = @() +} +``` ++This manifest is functionally identical to not specifying the setting at all. ++```powershell +@{ + CmdletsToExport = '*' +} +``` ++With **CmdletsToExport** set as an empty array, when you import this module no +cmdlets the root module or any nested modules export are available. ++```powershell +@{ + CmdletsToExport = @() +} +``` ++> [!NOTE] +> If you create your module manifest with the `New-ModuleManifest` command and +> do not specify the **CmdletsToExport** parameter, the created manifest has +> this setting specified as an empty array. Unless you edit the manifest, no +> cmdlets from the module is exported. ++With **CmdletsToExport** set to only include the `Get-Example` cmdlet, when +you import this module only the `Get-Example` cmdlet is made available, even +if other cmdlets were exported by the root module or any nested modules. ++```powershell +@{ + CmdletsToExport = @( + 'Get-Example' + ) +} +``` ++With **CmdletsToExport** set with a wildcard string, when you import this +module any cmdlet whose name ends with `Example` is made available, even if +other cmdlets were exported as module members by the root module or any nested +modules. ++```powershell +@{ + CmdletsToExport = @( + '*Example' + ) +} +``` ++### VariablesToExport ++This setting specifies the variables that the module exports. You can use this +setting to restrict the variables that are exported by the module. It can remove +variables from the list of exported module members, but it can't add variables +to the list. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++You can specify entries in this setting with wildcards. All matching variables +in the list of exported module members is exported. ++> [!TIP] +> For performance and discoverability, you should always explicitly list the +> variables you want your module to export in this setting without using any +> wildcards. ++For example, when you import a module with this setting commented out, all +variables in the root module and any nested modules are exported. ++```powershell +@{ + # VariablesToExport = @() +} +``` ++This manifest is functionally identical to not specifying the setting at all. ++```powershell +@{ + VariablesToExport = '*' +} +``` ++> [!NOTE] +> If you create your module manifest with the `New-ModuleManifest` command and +> do not specify the **VariablesToExport** parameter, the created manifest has +> this setting specified as `'*'`. Unless you edit the manifest, all variables +> from the module is exported. ++With **VariablesToExport** set as an empty array, when you import this module no +variables the root module or any nested modules export are available. ++```powershell +@{ + VariablesToExport = @() +} +``` ++With **VariablesToExport** set to only include the `SomeExample` variable, when +you import this module only the `$SomeExample` variable is made available, even +if other variables were exported by the root module or any nested modules. ++```powershell +@{ + VariablesToExport = @( + 'SomeExample' + ) +} +``` ++With **VariablesToExport** set with a wildcard string, when you import this +module any variable whose name ends with `Example` is made available, even if +other variables were exported as module members by the root module or any nested +modules. ++```powershell +@{ + VariablesToExport = @( + '*Example' + ) +} +``` ++### DscResourcesToExport ++This setting specifies the DSC Resources that the module exports. You can use +this setting to restrict the class-based DSC Resources that are exported by the +module. It can remove DSC Resources from the list of exported module members, +but it can't add DSC Resources to the list. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++You can specify entries in this setting with wildcards. All matching class-based +DSC Resources in the module are exported. ++> [!TIP] +> For discoverability, you should always explicitly list all of the DSC +> Resources your module module exports. ++For more information on authoring and using DSC Resources, see the +[documentation for DSC](/powershell/dsc/overview). ++This manifest exports all of the class-based and MOF-based DSC Resources defined +in the root module and any nested modules. ++```powershell +@{ + # DscResourcesToExport = @() +} +``` ++This manifest exports all of the MOF-based DSC Resources defined in the root +module and any nested modules, but only one class-based DSC Resource, +`ExampleClassResource`. ++```powershell +@{ + DscResourcesToExport = @( + 'ExampleClassResource' + ) +} +``` ++This manifest exports all of the DSC Resources it includes. Even if the +MOF-Based resource was not listed, the module would still export it. ++```powershell +@{ + DscResourcesToExport = @( + 'ExampleClassResource' + 'ExampleMofResourceFirst' + ) +} +``` ++### ModuleList ++This setting is an informational inventory list of the modules included in this +one. This list does not affect the behavior of the module. ++| | Value | +| --------------------- | --------------------------------------------------- | +| **Input Type** | `System.String[]`, `System.Collections.Hashtable[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Entries for this setting can be a module name, a full module specification, or a +path to a module or script file. ++When the value is a path, the path can be fully qualified or relative. ++When the value is a module name or specification, PowerShell searches the +**PSModulePath** for the specified module. ++A module specification is a hash table that has the following keys. ++- `ModuleName` - **Required**. Specifies the module name. +- `GUID` - **Optional**. Specifies the GUID of the module. +- It's also **Required** to specify at least one of the three below keys. The + `RequiredVersion` key can't be used with the `ModuleVersion` or + `MaximumVersion` keys. You can define an acceptable version range for the + module by specifying the `ModuleVersion` and `MaximumVersion` keys together. + - `ModuleVersion` - Specifies a minimum acceptable version of the module. + - `RequiredVersion` - Specifies an exact, required version of the module. + - `MaximumVersion` - Specifies the maximum acceptable version of the module. ++> [!NOTE] +> `RequiredVersion` was added in Windows PowerShell 5.0. +> `MaximumVersion` was added in Windows PowerShell 5.1. ++This manifest does not provide an informational list of the modules it includes. +It may or may not have modules. Even though this setting is not specified, any +modules listed in the **RootModule**, **ScriptsToProcess**, or **NestedModules** +settings will still behave as normal. ++```powershell +@{ + # ModuleList = @() +} +``` ++This manifest declares that the only modules it includes are `Example.psm1` and +the submodules `First.psm1` and `Second.psm1` in the `Submodules` folder. ++```powershell +@{ + ModuleList = @( + 'Example.psm1' + 'Submodules\First.psm1' + 'Submodules\Second.psm1' + ) +} +``` ++### FileList ++This setting is an informational inventory list of the files included in this +module. This list does not affect the behavior of the module. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++Entries for this setting should be the relative path to a file from the folder +containing the module manifest. ++When a user calls `Get-Module` against a manifest with this setting defined, the +**FileList** property of the returned object will be the full path to these +files, joining the module's path with each entry's relative path. ++This manifest does not include a list of its files. ++```powershell +@{ + # FileList = @() +} +``` ++This manifest declares that the only files it includes are listed in this +setting. ++```powershell +@{ + Filelist = @( + 'Example.psd1' + 'Example.psm1' + 'Assemblies\Example.dll' + 'Scripts\Initialize.ps1' + 'Submodules\First.psm1' + 'Submodules\Second.psm1' + ) +} +``` ++### PrivateData ++This setting defines a hash table of data that is available to any commands or +functions in the root module's scope. ++| | Value | +| --------------------- | ------------------------------ | +| **Input Type** | `System.Collections.Hashtable` | +| **Required** | PowerShell Gallery | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This setting has two primary effects: ++1. Any keys added to this setting are available to functions and cmdlets in the + root module with `$MyInvocation.MyCommand.Module.PrivateData`. The hash table + is not available in the module scope itself, only in cmdlets you define in + the module. +1. You can add the **PSData** key with a hash table for metadata needed when + publishing 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](/powershell/scripting/gallery/concepts/package-manifest-affecting-ui) ++For example, this manifest defines the **PublishedDate** key in **PrivateData**. ++```powershell +@{ + PrivateData = @{ + PublishedDate = '2022-06-01' + } +} +``` ++Cmdlets in the module can access this value with the `$MyInvocation` variable. ++```powershell +Function Get-Stale { + [CmdletBinding()] + param() ++ $PublishedDate = $MyInvocation.MyCommand.Module.PrivateData.PublishedDate + $CurrentDate = Get-Date ++ try { + $PublishedDate = Get-Date -Date $PublishedDate -ErrorAction Stop + } catch { + # The date was set in the manifest, set to an invalid value, or the + # script module was directly imported without the manifest. + Throw "Unable to determine published date. Check the module manifest." + } ++ if ($CurrentDate -gt $PublishedDate.AddDays(30)) { + Write-Warning "This module version was published more than 30 days ago." + } else { + $TimeUntilStale = $PublishedDate.AddDays(30) - $CurrentDate + "This module will be stale in $($TimeUntilStale.Days) days" + } +} +``` ++Once the module is imported, the function uses the value from **PrivateData** +to determine when the module was published. ++```powershell +Get-Stale -TestDate '2022-06-15' +Get-Stale -TestDate '2022-08-01' +``` ++```Output +This module will be stale in 16 days ++WARNING: This module version was published more than 30 days ago. +``` ++### HelpInfoURI ++This setting specifies the internet address of the HelpInfo XML file for the +module. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This setting's value must be a Uniform Resource Identifier (URI) that begins +with **http** or **https**. ++The HelpInfo XML file supports the Updatable Help feature that was introduced in +PowerShell 3.0. It 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_Updatable_Help.md). For information about +the HelpInfo XML file, see +[Supporting Updatable Help](/powershell/scripting/developer/module/supporting-updatable-help). ++For example, this module supports updatable help. ++```powershell +@{ + HelpInfoUri = 'http://https://go.microsoft.com/fwlink/?LinkID=603' +} +``` ++### DefaultCommandPrefix ++This setting specifies a prefix that is prepended to the nouns of all commands +in the module when they're imported into a session. Prefixes help prevent +command name conflicts in a user's session. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Module users can override this prefix by specifying the **Prefix** parameter of +the `Import-Module` cmdlet. ++This setting was introduced in PowerShell 3.0. ++When this manifest is imported, any cmdlets imported from this module have +`Example` prepended to the noun in their name. For example, `Get-Item` is +imported as `Get-ExampleItem`. ++```powershell +@{ + DefaultCommandPrefix = 'Example' +} +``` ++## See also ++- [about_PowerShell_Editions](/powershell/module/microsoft.powershell.core/about/about_powershell_editions) +- [New-ModuleManifest](xref:Microsoft.PowerShell.Core.New-ModuleManifest) +- [Test-ModuleManifest](xref:Microsoft.PowerShell.Core.Test-ModuleManifest) +- [Modules with compatible PowerShell Editions](/powershell/scripting/gallery/concepts/module-psedition-support). +- [Package manifest values that impact the PowerShell Gallery UI](/powershell/scripting/gallery/concepts/package-manifest-affecting-ui) +- [PowerShell module authoring considerations](/powershell/scripting/dev-cross-plat/performance/module-authoring-considerations) |
PackageManagement | Packagemanagement (7.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/PackageManagement/PackageManagement.md | Help Version: 7.1.0.0 Locale: en-US Module Guid: 4ae9fd46-338a-459c-8186-07f910774cb8 Module Name: PackageManagement Previously updated : 06/09/2017 Last updated : 04/21/2022 schema: 2.0.0 Title: PackageManagement --- Title: PackageManagement ## Description -This topic displays help topics for the Package Management Cmdlets. +This topic displays help topics for the Package Management Cmdlets. The cmdlet reference +documentation on this site documents the latest version of the module. > [!IMPORTANT] > As of April 2020, the PowerShell Gallery no longer supports Transport Layer Security (TLS) This topic displays help topics for the Package Management Cmdlets. > trying to access the PowerShell Gallery. Use the following command to ensure you are using TLS > 1.2: >-> `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` +> `[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12` > > For more information, see the > [announcement](https://devblogs.microsoft.com/powershell/powershell-gallery-tls-support/) in the Uninstalls one or more software packages. ### [Unregister-PackageSource](Unregister-PackageSource.md) Removes a registered package source.- |
PowerShellGet | Powershellget (7.1) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/PowerShellGet/PowerShellGet.md | Help Version: 7.1.0.0 Locale: en-US Module Guid: 1d73a601-4a6c-43c5-ba3f-619b18bbb404 Module Name: PowerShellGet Previously updated : 06/09/2017 Last updated : 04/21/2022 schema: 2.0.0 Title: PowerShellGet --- Title: PowerShellGet PowerShellGet is a module with commands for discovering, installing, updating and publishing PowerShell artifacts like Modules, DSC Resources, Role Capabilities, and Scripts. +The cmdlet reference documentation on this site documents the latest version of the module. + > [!IMPORTANT] > As of April 2020, the PowerShell Gallery no longer supports Transport Layer Security (TLS) > versions 1.0 and 1.1. If you are not using TLS 1.2 or higher, you will receive an error when > trying to access the PowerShell Gallery. Use the following command to ensure you are using TLS > 1.2: >-> `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` +> `[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12` > > For more information, see the > [announcement](https://devblogs.microsoft.com/powershell/powershell-gallery-tls-support/) in the PowerShell artifacts like Modules, DSC Resources, Role Capabilities, and Scripts Finds PowerShell commands in modules. ### [Find-DscResource](Find-DscResource.md)-Finds Desired State Configuration (DSC) resources. +Finds a DSC resource. ### [Find-Module](Find-Module.md) Finds modules in a repository that match specified criteria. |
Microsoft.PowerShell.Core | About Module Manifests (7.2) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Core/About/about_Module_Manifests.md | +--- +description: Describes the settings and practices for writing module manifest files. +Locale: en-US Last updated : 03/30/2022+online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_module_manifests?view=powershell-7.2&WT.mc_id=ps-gethelp +schema: 2.0.0 + Title: about Module Manifests +--- +# about_Module_Manifests ++## Short description +Describes the settings and practices for writing module manifest files. ++## Long description ++A module manifest is a PowerShell data file (`.psd1`) containing a hash table. +The keys/value pairs in the hash table describe the contents and attributes of +the module, define the prerequisites, and control how the components are +processed. ++Manifests aren't required to load a module but they are required to publish a +module to the PowerShell Gallery. Manifests also enable you to separate your +module's implementation from how it loads. With a manifest, you can define +requirements, compatibility, loading order, and more. ++When you use `New-ModuleManifest` without specifying any parameters for the +manifest's settings it writes a minimal manifest file. The snippet below shows +you this default output, snipped of commentary and spacing for brevity: ++```powershell +@{ +# RootModule = '' +ModuleVersion = '1.0' +# CompatiblePSEditions = @() +GUID = 'e7184b71-2527-469f-a50e-166b612dfb3b' +Author = 'username' +CompanyName = 'Unknown' +Copyright = '(c) 2022 username. All rights reserved.' +# Description = '' +# PowerShellVersion = '' +# PowerShellHostName = '' +# PowerShellHostVersion = '' +# DotNetFrameworkVersion = '' +# CLRVersion = '' +# ProcessorArchitecture = '' +# RequiredModules = @() +# RequiredAssemblies = @() +# ScriptsToProcess = @() +# TypesToProcess = @() +# FormatsToProcess = @() +# NestedModules = @() +FunctionsToExport = @() +CmdletsToExport = @() +VariablesToExport = '*' +AliasesToExport = @() +# DscResourcesToExport = @() +# ModuleList = @() +# FileList = @() +PrivateData = @{ + PSData = @{ + # Tags = @() + # LicenseUri = '' + # ProjectUri = '' + # IconUri = '' + # ReleaseNotes = '' + } # End of PSData hashtable +} # End of PrivateData hashtable +# HelpInfoURI = '' +# DefaultCommandPrefix = '' +} +``` ++You can use `Test-ModuleManifest` to validate a module manifest before you +publish your module. `Test-ModuleManifest` returns an error if the manifest is +invalid or the module can't be imported into the current session because the +session does not meet requirements set in the manifest. ++## Manifest settings ++The following sections detail every available setting in a module manifest and +how you can use them. They start with a synopsis of the setting and are followed +by a matrix which lists: ++- **Input type**: The object type that you can specify for this setting in the + manifest. +- **Required**: If this value is `Yes`, the setting is required both to import + the module and to publish it to the PowerShell Gallery. If it is `No`, it is + required for neither. If it is `PowerShell Gallery`, it is only required for + publishing to the PowerShell Gallery. +- **Value if unset**: The value this setting has when imported and not + explicitly set. +- **Accepts wildcards**: Whether this setting can take a wildcard + value or not. ++### RootModule ++This setting specifies the primary or root file of the module. When the module +is imported, the members exported by the root module file are imported into the +caller's session state. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++The value must be the file path to one of the following: ++- a script (`.ps1`) +- a script module (`.psm1`) +- a module manifest (`.psd1`) +- an assembly (`.dll`) +- a cmdlet definition XML file (`.cdxml`) +- a Windows PowerShell 5.1 Workflow (`.xaml`) ++The file path should be relative to the module manifest. ++If a module has a manifest file and no root file was designated in the +**RootModule** key, the manifest becomes the primary file for the module, and +the module becomes a manifest module (ModuleType = Manifest). When +**RootModule** is defined, the module's type is determined from the file +extension used: ++- a `.ps1` or `.psm1` file makes the module type **Script** +- a `.psd1` file makes the module type **Manifest** +- a `.dll` file makes the module type **Binary** +- a `.cdxml` file makes the module type **CIM** +- a `.xaml` file makes the module type **Workflow** ++By default, all module members in the **RootModule** are exported. ++> [!TIP] +> Module loading speed differs between **Binary**, **Script**, and **CIM** +> module types. For more information, see +> [PowerShell module authoring considerations](/powershell/scripting/dev-cross-plat/performance/module-authoring-considerations) ++For example, this module's **ModuleType** is **Manifest**. The only module +members this module can export are those defined in the modules specified with +the **NestedModules** setting. ++```powershell +@{ + RootModule = '' +} +``` ++> [!NOTE] +> This setting may also be specified in module manifests as **ModuleToProcess**. +> While that name for this setting is valid, it is best practice to use +> **RootModule** instead. ++### ModuleVersion ++This setting specifies the version of the module. When multiple versions of a +module exist on a system, the latest version is loaded by default when you run +`Import-Module`. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | Yes | +| **Value if unset** | None | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to `System.Version` when you run +`Import-Module`. ++For example, this manifest declares the module's version as `'1.2.3'`. ++```powershell +@{ + ModuleVersion = '1.2.3' +} +``` ++When you import the module and inspect the **Version** property, note that it is +a **System.Version** object and not a string: ++```powershell +$ExampleModule = Import-Module example.psd1 +$ExampleModule.Version +$ExampleModule.Version.GetType().Name +``` ++```Output +Major Minor Build Revision +----- ----- ----- -------- +1 2 3 -1 ++Version +``` ++### CompatiblePSEditions ++This setting specifies the module's compatible PSEditions. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Accepted Values** | `Desktop`, `Core` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++If the value of this setting is `$null`, the module can be imported regardless +of the PSEdition of the session. You can set it to one or more of the accepted +values. ++For information about PSEdition, see: ++- [about_PowerShell_Editions](/powershell/module/microsoft.powershell.core/about/about_powershell_editions) +- [Modules with compatible PowerShell Editions](/powershell/scripting/gallery/concepts/module-psedition-support). ++When this setting is defined, the module can only be imported into a session +where the `$PSEdition` automatic variable's value is included in the setting. ++> [!NOTE] +> Because the `$PSEdition` automatic variable was introduced in version 5.1, +> older versions of Windows PowerShell can't load a module that uses the +> **CompatiblePSEditions** setting. ++For example, you can import this module manifest in any session: ++```powershell +@{ + # CompatiblePSEditions = @() +} +``` ++With the setting specified, this module can only be imported in sessions where +the `$PSEdition` automatic variable's value is `Core`. ++```powershell +@{ + CompatiblePSEditions = @('Core') +} +``` ++### GUID ++This setting specifies a unique identifier for the module. The **GUID** is used +to distinguish between modules with the same name. ++| | Value | +| --------------------- | -------------------------------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `00000000-0000-0000-0000-000000000000` | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to `System.Guid` when you run +`Import-Module`. ++> [!CAUTION] +> While it is not a required setting, not specifying a **GUID** in a manifest +> has no benefits and may lead to name collisions for modules. ++You can create a new guid to use in your manifest: ++```powershell +New-Guid | Select-Object -ExpandProperty Guid +``` ++```Output +8456b025-2fa5-4034-ae47-e6305f3917ca +``` ++```powershell +@{ + GUID = '8456b025-2fa5-4034-ae47-e6305f3917ca' +} +``` ++If there is another module on the machine with the same name, you can still +import the one you want by specifying the module's fully qualified name: ++```powershell +Import-Module -FullyQualifiedName @{ + ModuleName = 'Example' + GUID = '8456b025-2fa5-4034-ae47-e6305f3917ca' + ModuleVersion = '1.0.0' +} +``` ++### Author ++This setting identifies the module author. ++| | Value | +| --------------------- | ------------------ | +| **Input Type** | `System.String` | +| **Required** | PowerShell Gallery | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This manifest declares that the module's author is the Contoso Developer +Experience Team. ++```powershell +@{ + Author = 'Contoso Developer Experience Team' +} +``` ++### CompanyName ++This setting identifies the company or vendor who created the module. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This manifest declares that the module was created by Contoso, Ltd. ++```powershell +@{ + CompanyName = 'Contoso, Ltd.' +} +``` ++### Copyright ++This setting specifies a copyright statement for the module. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This manifest declares a copyright statement reserving all rights to Contoso, +Ltd. as of 2022. ++```powershell +@{ + Copyright = '(c) 2022 Contoso, Ltd. All rights reserved.' +} +``` ++### Description ++This setting describes the module at a high level. ++| | Value | +| --------------------- | ------------------ | +| **Input Type** | `System.String` | +| **Required** | PowerShell Gallery | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This manifest includes a short description. You can also use a here-string to +write a longer or multi-line description. ++```powershell +@{ + Description = 'Provides example commands to show a valid module manifest' +} +``` ++### PowerShellVersion ++This setting specifies the minimum version of PowerShell this module requires. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to `System.Version` when you run +`Import-Module`. ++If this setting is not set, PowerShell does not restrict the module's import +based on the current version. ++For example, this manifest declares that the module is compatible with every +version of PowerShell and Windows PowerShell. ++```powershell +@{ + # PowerShellVersion = '' +} +``` ++With **PowerShellVersion** set to `7.2`, you can only import the module in +PowerShell 7.2 or higher. ++```powershell +@{ + PowerShellVersion = '7.2' +} +``` ++### PowerShellHostName ++This setting specifies the name of the PowerShell host program that the module +requires, such as **Windows PowerShell ISE Host** or **ConsoleHost**. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++You can find the name of the host for a session with the `$Host.Name` statement. +For example, you can see that the host for a remote session is +**ServerRemoteHost** instead of **ConsoleHost**: ++```powershell +$Host.Name +Enter-PSSession -ComputerName localhost +$Host.Name +``` ++```Output +ConsoleHost +[localhost]: PS C:\Users\username\Documents> $Host.Name +ServerRemoteHost +``` ++This module can be imported into any host. ++```powershell +@{ + # PowerShellHostName = '' +} +``` ++With **PowerShellHostName** set to `ServerRemoteHost`, you can only import the +module in a remote PowerShell session. ++```powershell +@{ + PowerShellHostName = 'ServerRemoteHost' +} +``` ++### PowerShellHostVersion ++This setting specifies the minimum version of a PowerShell host program that the +module requires. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to `System.Version` when you run +`Import-Module`. ++> [!CAUTION] +> While this setting can be used without the **PowerShellHostName** setting, it +> increases the odds of unexpected behavior. Only use this setting when you are +> also using the **PowerShellHostName** setting. ++For example, this manifest's module can be imported from any PowerShell session +running in **ConsoleHost**, regardless of the host's version. ++```powershell +@{ + PowerShellHostName = 'ConsoleHost' + # PowerShellHostVersion = '' +} +``` ++With the **PowerShellHostVersion** set to `5.1`, you can only import the module +from any PowerShell session running in **ConsoleHost** where the host's version +is 5.1 or higher. ++```powershell +@{ + PowerShellHostName = 'ConsoleHost' + PowerShellHostVersion = '5.1' +} +``` ++### DotNetFrameworkVersion ++This setting specifies the minimum version of the Microsoft .NET Framework that +the module requires. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This setting only applies to Windows PowerShell. The value of this setting must +be convertible to `System.Version` when you run `Import-Module`. ++For example, this manifest declares that its module can be imported in any +PowerShell or Windows PowerShell session, regardless of the version of the +Microsoft .NET Framework. ++```powershell +@{ + # DotNetFrameworkVersion = '' +} +``` ++With **DotNetFrameworkVersion** set to `4.0`, you can import this module in any +session of Windows PowerShell where the latest available version of the +Microsoft .NET Framework is at least 4.0. You can also import it in any +PowerShell session. ++```powershell +@{ + DotNetFrameworkVersion = '4.0' +} +``` ++### CLRVersion ++This setting specifies the minimum version of the Common Language Runtime (CLR) +of the Microsoft .NET Framework that the module requires. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This setting only applies to Windows PowerShell. The value of this setting must +be convertible to `System.Version` when you run `Import-Module`. ++For example, this manifest declares that its module can be imported in any +PowerShell or Windows PowerShell session, regardless of the version of the +Microsoft .NET Framework's CLR version. ++```powershell +@{ + # CLRVersion = '' +} +``` ++With **CLRVersion** set to `4.0`, you can import this module in any session of +Windows PowerShell where the latest available version of the CLR is at least +4.0. You can also import it in any PowerShell session. ++```powershell +@{ + CLRVersion = '4.0' +} +``` ++### ProcessorArchitecture ++This setting specifies the processor architecture that the module requires. ++| | Value | +| --------------------- | --------------------------------------------- | +| **Input Type** | `System.String` | +| **Accepted Values** | `None`, `MSIL`, `X86`, `IA64`, `Amd64`, `Arm` | +| **Required** | No | +| **Value if unset** | `None` | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to +`System.Reflection.ProcessorArchitecture` when you run `Import-Module`. ++For example, this manifest declares that its module can be imported in any +session, regardless of the system's processor architecture. ++```powershell +@{ + # ProcessorArchitecture = '' +} +``` ++With **ProcessorArchitecture** set to `Amd64`, you can only import this module +in a session running on a machine with a matching architecture. ++```powershell +@{ + ProcessorArchitecture = 'Amd64' +} +``` ++### RequiredModules ++This setting specifies modules that must be in the global session state. If the +required modules aren't in the global session state, PowerShell imports them. If +the required modules aren't available, the `Import-Module` command fails. ++| | Value | +| --------------------- | --------------------------------------------------- | +| **Input Type** | `System.String[]`, `System.Collections.Hashtable[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Entries for this setting can be a module name, a full module specification, or a +path to a module file. ++When the value is a path, the path can be fully qualified or relative. ++When the value is a name or module specification, PowerShell searches the +**PSModulePath** for the specified module. ++A module specification is a hash table that has the following keys. ++- `ModuleName` - **Required**. Specifies the module name. +- `GUID` - **Optional**. Specifies the GUID of the module. +- It's also **Required** to specify at least one of the three below keys. The + `RequiredVersion` key can't be used with the `ModuleVersion` or + `MaximumVersion` keys. You can define an acceptable version range for the + module by specifying the `ModuleVersion` and `MaximumVersion` keys together. + - `ModuleVersion` - Specifies a minimum acceptable version of the module. + - `RequiredVersion` - Specifies an exact, required version of the module. + - `MaximumVersion` - Specifies the maximum acceptable version of the module. ++> [!NOTE] +> `RequiredVersion` was added in Windows PowerShell 5.0. +> `MaximumVersion` was added in Windows PowerShell 5.1. ++For example, this manifest declares that its module does not require any other +modules for its functionality. ++```powershell +@{ + # RequiredModules = @() +} +``` ++This manifest declares that it requires the PSReadLine module. When you run +`Import-Module` on this manifest, PowerShell imports the latest version of +PSReadline that is available to the session. If no version is available, the +import returns an error. ++```powershell +@{ + RequiredModules = @( + 'PSReadLine' + ) +} +``` ++> [!TIP] +> In PowerShell 2.0, `Import-Module` doesn't import required modules +> automatically. It only verifies that the required modules are in the global +> session state. ++This manifest declares that it requires a version of the PSReadLine module +vendored in it's own module folder. When you run `Import-Module` on this +manifest, PowerShell imports the vendored PSReadLine from the specified path. ++```powershell +@{ + RequiredModules = @( + 'Vendored\PSReadline\PSReadline.psd1' + ) +} +``` ++This manifest declares that it specifically requires version 2.0.0 of the +PSReadLine module. When you run `Import-Module` on this manifest, PowerShell +imports version 2.0.0 of PSReadline if it is available. If it is not available, +`Import-Module` returns an error. ++```powershell +@{ + RequiredModules = @( + @{ + ModuleName = 'PSReadLine' + RequiredVersion = '2.0.0' + } + ) +} +``` ++This manifest declares that it requires the PSReadLine module to be imported at +version 2.0.0 or higher. ++```powershell +@{ + RequiredModules = @( + @{ + ModuleName = 'PSReadLine' + ModuleVersion = '2.0.0' + } + ) +} +``` ++This manifest declares that it requires the PSReadLine module to be imported at +version 2.0.0 or lower. ++```powershell +@{ + RequiredModules = @( + @{ + ModuleName = 'PSReadLine' + MaximumVersion = '2.0.0' + } + ) +} +``` ++This manifest declares that it requires the PSDesiredStateConfiguration module +to be imported at a version equal to or higher than 2.0.0 but no higher than +2.99.99. ++```powershell +@{ + RequiredModules = @( + @{ + ModuleName = 'PSDesiredStateConfiguration' + ModuleVersion = '2.0.0' + MaximumVersion = '2.99.99' + } + ) +} +``` ++### RequiredAssemblies ++This setting specifies the assembly (`.dll`) files that the module requires. +PowerShell loads the specified assemblies before updating types or formats, +importing nested modules, or importing the module file that is specified in the +value of the **RootModule** key. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Entries for this setting can be the filename of an assembly or the path to one. +List all required assemblies, even if they are also listed as binary modules in +the **NestedModules** setting. ++This manifest requires the `example.dll` assembly. Before loading any formatting +or type files specified in this manifest, PowerShell loads `example.dll` from +the `Assemblies` folder located in the same directory as the module manifest. ++```powershell +@{ + RequiredAssemblies = @( + 'Assemblies\Example.dll' + ) +} +``` ++### ScriptsToProcess ++This setting specifies script (`.ps1`) files that run in the caller's session +state when the module is imported. You can use these scripts to prepare an +environment, just as you might use a login script. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++To specify scripts that run in the module's session state, use the +**NestedModules** key. ++When you import this manifest, PowerShell runs the `Initialize.ps1` in your +current session. ++```powershell +@{ + ScriptsToProcess = @( + 'Scripts\Initialize.ps1' + ) +} +``` ++For example, if `Initialize.ps1` writes informational messages and sets the +`$ExampleState` variable: ++```powershell +if ([string]::IsNullOrEmpty($ExampleState)) { + Write-Information "Example not initialized." + Write-Information "Initializing now..." + $ExampleState = 'Initialized' +} else { + Write-Information "Example already initialized." +} +``` ++When you import the module, the script runs, writing those messages and setting +`$ExampleState` in your session. ++```powershell +$InformationPreference = 'Continue' +"Example State is: $ExampleState" +Import-Module .\example7x.psd1 +"Example State is: $ExampleState" +Import-Module .\example7x.psd1 -Force +``` ++```Output +Example State is: ++Example not initialized. +Initializing now... ++Example State is: Initialized ++Example already initialized. +``` ++### TypesToProcess ++This setting specifies the type files (`.ps1xml`) that run when the module is +imported. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++When you import the module, PowerShell runs the `Update-TypeData` cmdlet with +the specified files. Because type files aren't scoped, they affect all session +states in the session. ++For more information on type files, see +[about_Types.ps1xml](about_Types.ps1xml.md) ++For example, when you import this manifest, PowerShell loads the types specified +in the `Example.ps1xml` file from the `Types` folder located in the same +directory as the module manifest. ++```powershell +@{ + TypesToProcess = @( + 'Types\Example.ps1xml' + ) +} +``` ++### FormatsToProcess ++This setting specifies the formatting files (`.ps1xml`) that run when the module +is imported. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++When you import a module, PowerShell runs the `Update-FormatData` cmdlet with +the specified files. Because formatting files aren't scoped, they affect all +session states in the session. ++For more information on type files, see +[about_Format.ps1xml](about_Format.ps1xml.md) ++For example, when you import this module, PowerShell loads the formats specified +in the `Example.ps1xml` file from the `Formats` folder located in the same +directory as the module manifest. ++```powershell +@{ + FormatsToProcess = @( + 'Formats\Example.ps1xml' + ) +} +``` ++### NestedModules ++This setting specifies script modules (`.psm1`) and binary modules (`.dll`) that +are imported into the module's session state. You can also specify script files +(`.ps1`). The files in this setting run in the order in which they're listed. ++| | Value | +| --------------------- | --------------------------------------------------- | +| **Input Type** | `System.String[]`, `System.Collections.Hashtable[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Entries for this setting can be a module name, a full module specification, or a +path to a module or script file. ++When the value is a path, the path can be fully qualified or relative. ++When the value is a module name or specification, PowerShell searches the +**PSModulePath** for the specified module. ++A module specification is a hash table that has the following keys. ++- `ModuleName` - **Required**. Specifies the module name. +- `GUID` - **Optional**. Specifies the GUID of the module. +- It's also **Required** to specify at least one of the three below keys. The + `RequiredVersion` key can't be used with the `ModuleVersion` or + `MaximumVersion` keys. You can define an acceptable version range for the + module by specifying the `ModuleVersion` and `MaximumVersion` keys together. + - `ModuleVersion` - Specifies a minimum acceptable version of the module. + - `RequiredVersion` - Specifies an exact, required version of the module. + - `MaximumVersion` - Specifies the maximum acceptable version of the module. ++> [!NOTE] +> `RequiredVersion` was added in Windows PowerShell 5.0. +> `MaximumVersion` was added in Windows PowerShell 5.1. ++Any items that need to be exported from a nested module must exported by the +nested module using the `Export-ModuleMember` cmdlet or be listed in one of the +export properties: ++- **FunctionsToExport** +- **CmdletsToExport** +- **VariablesToExport** +- **AliasesToExport** ++Nested modules in the module session state are available to the root module, but +they aren't returned by a `Get-Module` command in the caller's session state. ++Scripts (`.ps1`) that are listed in this setting are run in the module's session +state, not in the caller's session state. To run a script in the caller's +session state, list the script filename in the **ScriptsToProcess** setting. ++For example, when you import this manifest, the `Helpers.psm1` module is loaded +into the root module's session state. Any cmdlets declared in the nested module +are exported unless otherwise restricted. ++```powershell +@{ + NestedModules = @( + 'Helpers\Helpers.psm1' + ) +} +``` ++### FunctionsToExport ++This setting specifies the functions that the module exports. You can use this +setting to restrict the functions that are exported by the module. It can remove +functions from the list of exported functions, but it can't add functions to the +list. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++You can specify entries in this setting with wildcards. All matching functions +in the list of exported functions are exported. ++> [!TIP] +> For performance and discoverability, you should always explicitly list the +> functions you want your module to export in this setting without using any +> wildcards. ++For example, when you import a module with the setting commented out, all +functions in the root module and any nested modules are exported. ++```powershell +@{ + # FunctionsToExport = @() +} +``` ++This manifest is functionally identical to not specifying the setting at all. ++```powershell +@{ + FunctionsToExport = '*' +} +``` ++With **FunctionsToExport** set as an empty array, when you import this module no +functions the root module or any nested modules export are available. ++```powershell +@{ + FunctionsToExport = @() +} +``` ++> [!NOTE] +> If you create your module manifest with the `New-ModuleManifest` command and +> do not specify the **FunctionsToExport** parameter, the created manifest has +> this setting specified as an empty array. Unless you edit the manifest, no +> functions from the module are exported. ++With **FunctionsToExport** set to only include the `Get-Example` function, when +you import this module only the `Get-Example` function is made available, even +if other functions were exported by the root module or any nested modules. ++```powershell +@{ + FunctionsToExport = @( + 'Get-Example' + ) +} +``` ++With **FunctionsToExport** set with a wildcard string, when you import this +module any function whose name ends with `Example` is made available, even if +other functions were exported as module members by the root module or any nested +modules. ++```powershell +@{ + FunctionsToExport = @( + '*Example' + ) +} +``` ++### CmdletsToExport ++This setting specifies the cmdlets that the module exports. You can use this +setting to restrict the cmdlets that are exported by the module. It can remove +cmdlets from the list of exported module members, but it can't add cmdlets to +the list. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++You can specify entries in this setting with wildcards. All matching cmdlets +in the list of exported cmdlets is exported. ++> [!TIP] +> For performance and discoverability, you should always explicitly list the +> cmdlets you want your module to export in this setting without using any +> wildcards. ++For example, when you import a module with this setting commented out, all +cmdlets in the root module and any nested modules are exported. ++```powershell +@{ + # CmdletsToExport = @() +} +``` ++This manifest is functionally identical to not specifying the setting at all. ++```powershell +@{ + CmdletsToExport = '*' +} +``` ++With **CmdletsToExport** set as an empty array, when you import this module no +cmdlets the root module or any nested modules export are available. ++```powershell +@{ + CmdletsToExport = @() +} +``` ++> [!NOTE] +> If you create your module manifest with the `New-ModuleManifest` command and +> do not specify the **CmdletsToExport** parameter, the created manifest has +> this setting specified as an empty array. Unless you edit the manifest, no +> cmdlets from the module is exported. ++With **CmdletsToExport** set to only include the `Get-Example` cmdlet, when +you import this module only the `Get-Example` cmdlet is made available, even +if other cmdlets were exported by the root module or any nested modules. ++```powershell +@{ + CmdletsToExport = @( + 'Get-Example' + ) +} +``` ++With **CmdletsToExport** set with a wildcard string, when you import this +module any cmdlet whose name ends with `Example` is made available, even if +other cmdlets were exported as module members by the root module or any nested +modules. ++```powershell +@{ + CmdletsToExport = @( + '*Example' + ) +} +``` ++### VariablesToExport ++This setting specifies the variables that the module exports. You can use this +setting to restrict the variables that are exported by the module. It can remove +variables from the list of exported module members, but it can't add variables +to the list. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++You can specify entries in this setting with wildcards. All matching variables +in the list of exported module members is exported. ++> [!TIP] +> For performance and discoverability, you should always explicitly list the +> variables you want your module to export in this setting without using any +> wildcards. ++For example, when you import a module with this setting commented out, all +variables in the root module and any nested modules are exported. ++```powershell +@{ + # VariablesToExport = @() +} +``` ++This manifest is functionally identical to not specifying the setting at all. ++```powershell +@{ + VariablesToExport = '*' +} +``` ++> [!NOTE] +> If you create your module manifest with the `New-ModuleManifest` command and +> do not specify the **VariablesToExport** parameter, the created manifest has +> this setting specified as `'*'`. Unless you edit the manifest, all variables +> from the module is exported. ++With **VariablesToExport** set as an empty array, when you import this module no +variables the root module or any nested modules export are available. ++```powershell +@{ + VariablesToExport = @() +} +``` ++With **VariablesToExport** set to only include the `SomeExample` variable, when +you import this module only the `$SomeExample` variable is made available, even +if other variables were exported by the root module or any nested modules. ++```powershell +@{ + VariablesToExport = @( + 'SomeExample' + ) +} +``` ++With **VariablesToExport** set with a wildcard string, when you import this +module any variable whose name ends with `Example` is made available, even if +other variables were exported as module members by the root module or any nested +modules. ++```powershell +@{ + VariablesToExport = @( + '*Example' + ) +} +``` ++### DscResourcesToExport ++This setting specifies the DSC Resources that the module exports. You can use +this setting to restrict the class-based DSC Resources that are exported by the +module. It can remove DSC Resources from the list of exported module members, +but it can't add DSC Resources to the list. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++You can specify entries in this setting with wildcards. All matching class-based +DSC Resources in the module are exported. ++> [!TIP] +> For discoverability, you should always explicitly list all of the DSC +> Resources your module module exports. ++For more information on authoring and using DSC Resources, see the +[documentation for DSC](/powershell/dsc/overview). ++This manifest exports all of the class-based and MOF-based DSC Resources defined +in the root module and any nested modules. ++```powershell +@{ + # DscResourcesToExport = @() +} +``` ++This manifest exports all of the MOF-based DSC Resources defined in the root +module and any nested modules, but only one class-based DSC Resource, +`ExampleClassResource`. ++```powershell +@{ + DscResourcesToExport = @( + 'ExampleClassResource' + ) +} +``` ++This manifest exports all of the DSC Resources it includes. Even if the +MOF-Based resource was not listed, the module would still export it. ++```powershell +@{ + DscResourcesToExport = @( + 'ExampleClassResource' + 'ExampleMofResourceFirst' + ) +} +``` ++### ModuleList ++This setting is an informational inventory list of the modules included in this +one. This list does not affect the behavior of the module. ++| | Value | +| --------------------- | --------------------------------------------------- | +| **Input Type** | `System.String[]`, `System.Collections.Hashtable[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Entries for this setting can be a module name, a full module specification, or a +path to a module or script file. ++When the value is a path, the path can be fully qualified or relative. ++When the value is a module name or specification, PowerShell searches the +**PSModulePath** for the specified module. ++A module specification is a hash table that has the following keys. ++- `ModuleName` - **Required**. Specifies the module name. +- `GUID` - **Optional**. Specifies the GUID of the module. +- It's also **Required** to specify at least one of the three below keys. The + `RequiredVersion` key can't be used with the `ModuleVersion` or + `MaximumVersion` keys. You can define an acceptable version range for the + module by specifying the `ModuleVersion` and `MaximumVersion` keys together. + - `ModuleVersion` - Specifies a minimum acceptable version of the module. + - `RequiredVersion` - Specifies an exact, required version of the module. + - `MaximumVersion` - Specifies the maximum acceptable version of the module. ++> [!NOTE] +> `RequiredVersion` was added in Windows PowerShell 5.0. +> `MaximumVersion` was added in Windows PowerShell 5.1. ++This manifest does not provide an informational list of the modules it includes. +It may or may not have modules. Even though this setting is not specified, any +modules listed in the **RootModule**, **ScriptsToProcess**, or **NestedModules** +settings will still behave as normal. ++```powershell +@{ + # ModuleList = @() +} +``` ++This manifest declares that the only modules it includes are `Example.psm1` and +the submodules `First.psm1` and `Second.psm1` in the `Submodules` folder. ++```powershell +@{ + ModuleList = @( + 'Example.psm1' + 'Submodules\First.psm1' + 'Submodules\Second.psm1' + ) +} +``` ++### FileList ++This setting is an informational inventory list of the files included in this +module. This list does not affect the behavior of the module. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++Entries for this setting should be the relative path to a file from the folder +containing the module manifest. ++When a user calls `Get-Module` against a manifest with this setting defined, the +**FileList** property of the returned object will be the full path to these +files, joining the module's path with each entry's relative path. ++This manifest does not include a list of its files. ++```powershell +@{ + # FileList = @() +} +``` ++This manifest declares that the only files it includes are listed in this +setting. ++```powershell +@{ + Filelist = @( + 'Example.psd1' + 'Example.psm1' + 'Assemblies\Example.dll' + 'Scripts\Initialize.ps1' + 'Submodules\First.psm1' + 'Submodules\Second.psm1' + ) +} +``` ++### PrivateData ++This setting defines a hash table of data that is available to any commands or +functions in the root module's scope. ++| | Value | +| --------------------- | ------------------------------ | +| **Input Type** | `System.Collections.Hashtable` | +| **Required** | PowerShell Gallery | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This setting has two primary effects: ++1. Any keys added to this setting are available to functions and cmdlets in the + root module with `$MyInvocation.MyCommand.Module.PrivateData`. The hash table + is not available in the module scope itself, only in cmdlets you define in + the module. +1. You can add the **PSData** key with a hash table for metadata needed when + publishing 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](/powershell/scripting/gallery/concepts/package-manifest-affecting-ui) ++For example, this manifest defines the **PublishedDate** key in **PrivateData**. ++```powershell +@{ + PrivateData = @{ + PublishedDate = '2022-06-01' + } +} +``` ++Cmdlets in the module can access this value with the `$MyInvocation` variable. ++```powershell +Function Get-Stale { + [CmdletBinding()] + param() ++ $PublishedDate = $MyInvocation.MyCommand.Module.PrivateData.PublishedDate + $CurrentDate = Get-Date ++ try { + $PublishedDate = Get-Date -Date $PublishedDate -ErrorAction Stop + } catch { + # The date was set in the manifest, set to an invalid value, or the + # script module was directly imported without the manifest. + Throw "Unable to determine published date. Check the module manifest." + } ++ if ($CurrentDate -gt $PublishedDate.AddDays(30)) { + Write-Warning "This module version was published more than 30 days ago." + } else { + $TimeUntilStale = $PublishedDate.AddDays(30) - $CurrentDate + "This module will be stale in $($TimeUntilStale.Days) days" + } +} +``` ++Once the module is imported, the function uses the value from **PrivateData** +to determine when the module was published. ++```powershell +Get-Stale -TestDate '2022-06-15' +Get-Stale -TestDate '2022-08-01' +``` ++```Output +This module will be stale in 16 days ++WARNING: This module version was published more than 30 days ago. +``` ++### HelpInfoURI ++This setting specifies the internet address of the HelpInfo XML file for the +module. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This setting's value must be a Uniform Resource Identifier (URI) that begins +with **http** or **https**. ++The HelpInfo XML file supports the Updatable Help feature that was introduced in +PowerShell 3.0. It 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_Updatable_Help.md). For information about +the HelpInfo XML file, see +[Supporting Updatable Help](/powershell/scripting/developer/module/supporting-updatable-help). ++For example, this module supports updatable help. ++```powershell +@{ + HelpInfoUri = 'http://https://go.microsoft.com/fwlink/?LinkID=603' +} +``` ++### DefaultCommandPrefix ++This setting specifies a prefix that is prepended to the nouns of all commands +in the module when they're imported into a session. Prefixes help prevent +command name conflicts in a user's session. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Module users can override this prefix by specifying the **Prefix** parameter of +the `Import-Module` cmdlet. ++This setting was introduced in PowerShell 3.0. ++When this manifest is imported, any cmdlets imported from this module have +`Example` prepended to the noun in their name. For example, `Get-Item` is +imported as `Get-ExampleItem`. ++```powershell +@{ + DefaultCommandPrefix = 'Example' +} +``` ++## See also ++- [about_PowerShell_Editions](/powershell/module/microsoft.powershell.core/about/about_powershell_editions) +- [New-ModuleManifest](xref:Microsoft.PowerShell.Core.New-ModuleManifest) +- [Test-ModuleManifest](xref:Microsoft.PowerShell.Core.Test-ModuleManifest) +- [Modules with compatible PowerShell Editions](/powershell/scripting/gallery/concepts/module-psedition-support). +- [Package manifest values that impact the PowerShell Gallery UI](/powershell/scripting/gallery/concepts/package-manifest-affecting-ui) +- [PowerShell module authoring considerations](/powershell/scripting/dev-cross-plat/performance/module-authoring-considerations) |
PackageManagement | Packagemanagement (7.2) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/PackageManagement/PackageManagement.md | Help Version: 7.2.0.0 Locale: en-US Module Guid: 4ae9fd46-338a-459c-8186-07f910774cb8 Module Name: PackageManagement Previously updated : 06/09/2017 Last updated : 04/21/2022 schema: 2.0.0 Title: PackageManagement --- Title: PackageManagement ## Description -This topic displays help topics for the Package Management Cmdlets. +This topic displays help topics for the Package Management Cmdlets. The cmdlet reference +documentation on this site documents the latest version of the module. > [!IMPORTANT] > As of April 2020, the PowerShell Gallery no longer supports Transport Layer Security (TLS) This topic displays help topics for the Package Management Cmdlets. > trying to access the PowerShell Gallery. Use the following command to ensure you are using TLS > 1.2: >-> `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` +> `[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12` > > For more information, see the > [announcement](https://devblogs.microsoft.com/powershell/powershell-gallery-tls-support/) in the |
PowerShellGet | Powershellget (7.2) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/PowerShellGet/PowerShellGet.md | Help Version: 7.2.0.0 Locale: en-US Module Guid: 1d73a601-4a6c-43c5-ba3f-619b18bbb404 Module Name: PowerShellGet Previously updated : 06/09/2017 Last updated : 04/21/2022 schema: 2.0.0 Title: PowerShellGet --- Title: PowerShellGet PowerShellGet is a module with commands for discovering, installing, updating and publishing PowerShell artifacts like Modules, DSC Resources, Role Capabilities, and Scripts. +The cmdlet reference documentation on this site documents the latest version of the module. + > [!IMPORTANT] > As of April 2020, the PowerShell Gallery no longer supports Transport Layer Security (TLS) > versions 1.0 and 1.1. If you are not using TLS 1.2 or higher, you will receive an error when > trying to access the PowerShell Gallery. Use the following command to ensure you are using TLS > 1.2: >-> `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` +> `[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12` > > For more information, see the > [announcement](https://devblogs.microsoft.com/powershell/powershell-gallery-tls-support/) in the PowerShell artifacts like Modules, DSC Resources, Role Capabilities, and Scripts Finds PowerShell commands in modules. ### [Find-DscResource](Find-DscResource.md)-Finds Desired State Configuration (DSC) resources. +Finds a DSC resource. ### [Find-Module](Find-Module.md) Finds modules in a repository that match specified criteria. |
Microsoft.PowerShell.Core | About Module Manifests (7.3) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.3/Microsoft.PowerShell.Core/About/about_Module_Manifests.md | +--- +description: Describes the settings and practices for writing module manifest files. +Locale: en-US Last updated : 03/30/2022+online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_module_manifests?view=powershell-7.3&WT.mc_id=ps-gethelp +schema: 2.0.0 + Title: about Module Manifests +--- +# about_Module_Manifests ++## Short description +Describes the settings and practices for writing module manifest files. ++## Long description ++A module manifest is a PowerShell data file (`.psd1`) containing a hash table. +The keys/value pairs in the hash table describe the contents and attributes of +the module, define the prerequisites, and control how the components are +processed. ++Manifests aren't required to load a module but they are required to publish a +module to the PowerShell Gallery. Manifests also enable you to separate your +module's implementation from how it loads. With a manifest, you can define +requirements, compatibility, loading order, and more. ++When you use `New-ModuleManifest` without specifying any parameters for the +manifest's settings it writes a minimal manifest file. The snippet below shows +you this default output, snipped of commentary and spacing for brevity: ++```powershell +@{ +# RootModule = '' +ModuleVersion = '1.0' +# CompatiblePSEditions = @() +GUID = 'e7184b71-2527-469f-a50e-166b612dfb3b' +Author = 'username' +CompanyName = 'Unknown' +Copyright = '(c) 2022 username. All rights reserved.' +# Description = '' +# PowerShellVersion = '' +# PowerShellHostName = '' +# PowerShellHostVersion = '' +# DotNetFrameworkVersion = '' +# CLRVersion = '' +# ProcessorArchitecture = '' +# RequiredModules = @() +# RequiredAssemblies = @() +# ScriptsToProcess = @() +# TypesToProcess = @() +# FormatsToProcess = @() +# NestedModules = @() +FunctionsToExport = @() +CmdletsToExport = @() +VariablesToExport = '*' +AliasesToExport = @() +# DscResourcesToExport = @() +# ModuleList = @() +# FileList = @() +PrivateData = @{ + PSData = @{ + # Tags = @() + # LicenseUri = '' + # ProjectUri = '' + # IconUri = '' + # ReleaseNotes = '' + } # End of PSData hashtable +} # End of PrivateData hashtable +# HelpInfoURI = '' +# DefaultCommandPrefix = '' +} +``` ++You can use `Test-ModuleManifest` to validate a module manifest before you +publish your module. `Test-ModuleManifest` returns an error if the manifest is +invalid or the module can't be imported into the current session because the +session does not meet requirements set in the manifest. ++## Manifest settings ++The following sections detail every available setting in a module manifest and +how you can use them. They start with a synopsis of the setting and are followed +by a matrix which lists: ++- **Input type**: The object type that you can specify for this setting in the + manifest. +- **Required**: If this value is `Yes`, the setting is required both to import + the module and to publish it to the PowerShell Gallery. If it is `No`, it is + required for neither. If it is `PowerShell Gallery`, it is only required for + publishing to the PowerShell Gallery. +- **Value if unset**: The value this setting has when imported and not + explicitly set. +- **Accepts wildcards**: Whether this setting can take a wildcard + value or not. ++### RootModule ++This setting specifies the primary or root file of the module. When the module +is imported, the members exported by the root module file are imported into the +caller's session state. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++The value must be the file path to one of the following: ++- a script (`.ps1`) +- a script module (`.psm1`) +- a module manifest (`.psd1`) +- an assembly (`.dll`) +- a cmdlet definition XML file (`.cdxml`) +- a Windows PowerShell 5.1 Workflow (`.xaml`) ++The file path should be relative to the module manifest. ++If a module has a manifest file and no root file was designated in the +**RootModule** key, the manifest becomes the primary file for the module, and +the module becomes a manifest module (ModuleType = Manifest). When +**RootModule** is defined, the module's type is determined from the file +extension used: ++- a `.ps1` or `.psm1` file makes the module type **Script** +- a `.psd1` file makes the module type **Manifest** +- a `.dll` file makes the module type **Binary** +- a `.cdxml` file makes the module type **CIM** +- a `.xaml` file makes the module type **Workflow** ++By default, all module members in the **RootModule** are exported. ++> [!TIP] +> Module loading speed differs between **Binary**, **Script**, and **CIM** +> module types. For more information, see +> [PowerShell module authoring considerations](/powershell/scripting/dev-cross-plat/performance/module-authoring-considerations) ++For example, this module's **ModuleType** is **Manifest**. The only module +members this module can export are those defined in the modules specified with +the **NestedModules** setting. ++```powershell +@{ + RootModule = '' +} +``` ++> [!NOTE] +> This setting may also be specified in module manifests as **ModuleToProcess**. +> While that name for this setting is valid, it is best practice to use +> **RootModule** instead. ++### ModuleVersion ++This setting specifies the version of the module. When multiple versions of a +module exist on a system, the latest version is loaded by default when you run +`Import-Module`. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | Yes | +| **Value if unset** | None | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to `System.Version` when you run +`Import-Module`. ++For example, this manifest declares the module's version as `'1.2.3'`. ++```powershell +@{ + ModuleVersion = '1.2.3' +} +``` ++When you import the module and inspect the **Version** property, note that it is +a **System.Version** object and not a string: ++```powershell +$ExampleModule = Import-Module example.psd1 +$ExampleModule.Version +$ExampleModule.Version.GetType().Name +``` ++```Output +Major Minor Build Revision +----- ----- ----- -------- +1 2 3 -1 ++Version +``` ++### CompatiblePSEditions ++This setting specifies the module's compatible PSEditions. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Accepted Values** | `Desktop`, `Core` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++If the value of this setting is `$null`, the module can be imported regardless +of the PSEdition of the session. You can set it to one or more of the accepted +values. ++For information about PSEdition, see: ++- [about_PowerShell_Editions](/powershell/module/microsoft.powershell.core/about/about_powershell_editions) +- [Modules with compatible PowerShell Editions](/powershell/scripting/gallery/concepts/module-psedition-support). ++When this setting is defined, the module can only be imported into a session +where the `$PSEdition` automatic variable's value is included in the setting. ++> [!NOTE] +> Because the `$PSEdition` automatic variable was introduced in version 5.1, +> older versions of Windows PowerShell can't load a module that uses the +> **CompatiblePSEditions** setting. ++For example, you can import this module manifest in any session: ++```powershell +@{ + # CompatiblePSEditions = @() +} +``` ++With the setting specified, this module can only be imported in sessions where +the `$PSEdition` automatic variable's value is `Core`. ++```powershell +@{ + CompatiblePSEditions = @('Core') +} +``` ++### GUID ++This setting specifies a unique identifier for the module. The **GUID** is used +to distinguish between modules with the same name. ++| | Value | +| --------------------- | -------------------------------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `00000000-0000-0000-0000-000000000000` | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to `System.Guid` when you run +`Import-Module`. ++> [!CAUTION] +> While it is not a required setting, not specifying a **GUID** in a manifest +> has no benefits and may lead to name collisions for modules. ++You can create a new guid to use in your manifest: ++```powershell +New-Guid | Select-Object -ExpandProperty Guid +``` ++```Output +8456b025-2fa5-4034-ae47-e6305f3917ca +``` ++```powershell +@{ + GUID = '8456b025-2fa5-4034-ae47-e6305f3917ca' +} +``` ++If there is another module on the machine with the same name, you can still +import the one you want by specifying the module's fully qualified name: ++```powershell +Import-Module -FullyQualifiedName @{ + ModuleName = 'Example' + GUID = '8456b025-2fa5-4034-ae47-e6305f3917ca' + ModuleVersion = '1.0.0' +} +``` ++### Author ++This setting identifies the module author. ++| | Value | +| --------------------- | ------------------ | +| **Input Type** | `System.String` | +| **Required** | PowerShell Gallery | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This manifest declares that the module's author is the Contoso Developer +Experience Team. ++```powershell +@{ + Author = 'Contoso Developer Experience Team' +} +``` ++### CompanyName ++This setting identifies the company or vendor who created the module. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This manifest declares that the module was created by Contoso, Ltd. ++```powershell +@{ + CompanyName = 'Contoso, Ltd.' +} +``` ++### Copyright ++This setting specifies a copyright statement for the module. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This manifest declares a copyright statement reserving all rights to Contoso, +Ltd. as of 2022. ++```powershell +@{ + Copyright = '(c) 2022 Contoso, Ltd. All rights reserved.' +} +``` ++### Description ++This setting describes the module at a high level. ++| | Value | +| --------------------- | ------------------ | +| **Input Type** | `System.String` | +| **Required** | PowerShell Gallery | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This manifest includes a short description. You can also use a here-string to +write a longer or multi-line description. ++```powershell +@{ + Description = 'Provides example commands to show a valid module manifest' +} +``` ++### PowerShellVersion ++This setting specifies the minimum version of PowerShell this module requires. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to `System.Version` when you run +`Import-Module`. ++If this setting is not set, PowerShell does not restrict the module's import +based on the current version. ++For example, this manifest declares that the module is compatible with every +version of PowerShell and Windows PowerShell. ++```powershell +@{ + # PowerShellVersion = '' +} +``` ++With **PowerShellVersion** set to `7.2`, you can only import the module in +PowerShell 7.2 or higher. ++```powershell +@{ + PowerShellVersion = '7.2' +} +``` ++### PowerShellHostName ++This setting specifies the name of the PowerShell host program that the module +requires, such as **Windows PowerShell ISE Host** or **ConsoleHost**. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++You can find the name of the host for a session with the `$Host.Name` statement. +For example, you can see that the host for a remote session is +**ServerRemoteHost** instead of **ConsoleHost**: ++```powershell +$Host.Name +Enter-PSSession -ComputerName localhost +$Host.Name +``` ++```Output +ConsoleHost +[localhost]: PS C:\Users\username\Documents> $Host.Name +ServerRemoteHost +``` ++This module can be imported into any host. ++```powershell +@{ + # PowerShellHostName = '' +} +``` ++With **PowerShellHostName** set to `ServerRemoteHost`, you can only import the +module in a remote PowerShell session. ++```powershell +@{ + PowerShellHostName = 'ServerRemoteHost' +} +``` ++### PowerShellHostVersion ++This setting specifies the minimum version of a PowerShell host program that the +module requires. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to `System.Version` when you run +`Import-Module`. ++> [!CAUTION] +> While this setting can be used without the **PowerShellHostName** setting, it +> increases the odds of unexpected behavior. Only use this setting when you are +> also using the **PowerShellHostName** setting. ++For example, this manifest's module can be imported from any PowerShell session +running in **ConsoleHost**, regardless of the host's version. ++```powershell +@{ + PowerShellHostName = 'ConsoleHost' + # PowerShellHostVersion = '' +} +``` ++With the **PowerShellHostVersion** set to `5.1`, you can only import the module +from any PowerShell session running in **ConsoleHost** where the host's version +is 5.1 or higher. ++```powershell +@{ + PowerShellHostName = 'ConsoleHost' + PowerShellHostVersion = '5.1' +} +``` ++### DotNetFrameworkVersion ++This setting specifies the minimum version of the Microsoft .NET Framework that +the module requires. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This setting only applies to Windows PowerShell. The value of this setting must +be convertible to `System.Version` when you run `Import-Module`. ++For example, this manifest declares that its module can be imported in any +PowerShell or Windows PowerShell session, regardless of the version of the +Microsoft .NET Framework. ++```powershell +@{ + # DotNetFrameworkVersion = '' +} +``` ++With **DotNetFrameworkVersion** set to `4.0`, you can import this module in any +session of Windows PowerShell where the latest available version of the +Microsoft .NET Framework is at least 4.0. You can also import it in any +PowerShell session. ++```powershell +@{ + DotNetFrameworkVersion = '4.0' +} +``` ++### CLRVersion ++This setting specifies the minimum version of the Common Language Runtime (CLR) +of the Microsoft .NET Framework that the module requires. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This setting only applies to Windows PowerShell. The value of this setting must +be convertible to `System.Version` when you run `Import-Module`. ++For example, this manifest declares that its module can be imported in any +PowerShell or Windows PowerShell session, regardless of the version of the +Microsoft .NET Framework's CLR version. ++```powershell +@{ + # CLRVersion = '' +} +``` ++With **CLRVersion** set to `4.0`, you can import this module in any session of +Windows PowerShell where the latest available version of the CLR is at least +4.0. You can also import it in any PowerShell session. ++```powershell +@{ + CLRVersion = '4.0' +} +``` ++### ProcessorArchitecture ++This setting specifies the processor architecture that the module requires. ++| | Value | +| --------------------- | --------------------------------------------- | +| **Input Type** | `System.String` | +| **Accepted Values** | `None`, `MSIL`, `X86`, `IA64`, `Amd64`, `Arm` | +| **Required** | No | +| **Value if unset** | `None` | +| **Accepts wildcards** | No | ++The value of this setting must be convertible to +`System.Reflection.ProcessorArchitecture` when you run `Import-Module`. ++For example, this manifest declares that its module can be imported in any +session, regardless of the system's processor architecture. ++```powershell +@{ + # ProcessorArchitecture = '' +} +``` ++With **ProcessorArchitecture** set to `Amd64`, you can only import this module +in a session running on a machine with a matching architecture. ++```powershell +@{ + ProcessorArchitecture = 'Amd64' +} +``` ++### RequiredModules ++This setting specifies modules that must be in the global session state. If the +required modules aren't in the global session state, PowerShell imports them. If +the required modules aren't available, the `Import-Module` command fails. ++| | Value | +| --------------------- | --------------------------------------------------- | +| **Input Type** | `System.String[]`, `System.Collections.Hashtable[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Entries for this setting can be a module name, a full module specification, or a +path to a module file. ++When the value is a path, the path can be fully qualified or relative. ++When the value is a name or module specification, PowerShell searches the +**PSModulePath** for the specified module. ++A module specification is a hash table that has the following keys. ++- `ModuleName` - **Required**. Specifies the module name. +- `GUID` - **Optional**. Specifies the GUID of the module. +- It's also **Required** to specify at least one of the three below keys. The + `RequiredVersion` key can't be used with the `ModuleVersion` or + `MaximumVersion` keys. You can define an acceptable version range for the + module by specifying the `ModuleVersion` and `MaximumVersion` keys together. + - `ModuleVersion` - Specifies a minimum acceptable version of the module. + - `RequiredVersion` - Specifies an exact, required version of the module. + - `MaximumVersion` - Specifies the maximum acceptable version of the module. ++> [!NOTE] +> `RequiredVersion` was added in Windows PowerShell 5.0. +> `MaximumVersion` was added in Windows PowerShell 5.1. ++For example, this manifest declares that its module does not require any other +modules for its functionality. ++```powershell +@{ + # RequiredModules = @() +} +``` ++This manifest declares that it requires the PSReadLine module. When you run +`Import-Module` on this manifest, PowerShell imports the latest version of +PSReadline that is available to the session. If no version is available, the +import returns an error. ++```powershell +@{ + RequiredModules = @( + 'PSReadLine' + ) +} +``` ++> [!TIP] +> In PowerShell 2.0, `Import-Module` doesn't import required modules +> automatically. It only verifies that the required modules are in the global +> session state. ++This manifest declares that it requires a version of the PSReadLine module +vendored in it's own module folder. When you run `Import-Module` on this +manifest, PowerShell imports the vendored PSReadLine from the specified path. ++```powershell +@{ + RequiredModules = @( + 'Vendored\PSReadline\PSReadline.psd1' + ) +} +``` ++This manifest declares that it specifically requires version 2.0.0 of the +PSReadLine module. When you run `Import-Module` on this manifest, PowerShell +imports version 2.0.0 of PSReadline if it is available. If it is not available, +`Import-Module` returns an error. ++```powershell +@{ + RequiredModules = @( + @{ + ModuleName = 'PSReadLine' + RequiredVersion = '2.0.0' + } + ) +} +``` ++This manifest declares that it requires the PSReadLine module to be imported at +version 2.0.0 or higher. ++```powershell +@{ + RequiredModules = @( + @{ + ModuleName = 'PSReadLine' + ModuleVersion = '2.0.0' + } + ) +} +``` ++This manifest declares that it requires the PSReadLine module to be imported at +version 2.0.0 or lower. ++```powershell +@{ + RequiredModules = @( + @{ + ModuleName = 'PSReadLine' + MaximumVersion = '2.0.0' + } + ) +} +``` ++This manifest declares that it requires the PSDesiredStateConfiguration module +to be imported at a version equal to or higher than 2.0.0 but no higher than +2.99.99. ++```powershell +@{ + RequiredModules = @( + @{ + ModuleName = 'PSDesiredStateConfiguration' + ModuleVersion = '2.0.0' + MaximumVersion = '2.99.99' + } + ) +} +``` ++### RequiredAssemblies ++This setting specifies the assembly (`.dll`) files that the module requires. +PowerShell loads the specified assemblies before updating types or formats, +importing nested modules, or importing the module file that is specified in the +value of the **RootModule** key. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Entries for this setting can be the filename of an assembly or the path to one. +List all required assemblies, even if they are also listed as binary modules in +the **NestedModules** setting. ++This manifest requires the `example.dll` assembly. Before loading any formatting +or type files specified in this manifest, PowerShell loads `example.dll` from +the `Assemblies` folder located in the same directory as the module manifest. ++```powershell +@{ + RequiredAssemblies = @( + 'Assemblies\Example.dll' + ) +} +``` ++### ScriptsToProcess ++This setting specifies script (`.ps1`) files that run in the caller's session +state when the module is imported. You can use these scripts to prepare an +environment, just as you might use a login script. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++To specify scripts that run in the module's session state, use the +**NestedModules** key. ++When you import this manifest, PowerShell runs the `Initialize.ps1` in your +current session. ++```powershell +@{ + ScriptsToProcess = @( + 'Scripts\Initialize.ps1' + ) +} +``` ++For example, if `Initialize.ps1` writes informational messages and sets the +`$ExampleState` variable: ++```powershell +if ([string]::IsNullOrEmpty($ExampleState)) { + Write-Information "Example not initialized." + Write-Information "Initializing now..." + $ExampleState = 'Initialized' +} else { + Write-Information "Example already initialized." +} +``` ++When you import the module, the script runs, writing those messages and setting +`$ExampleState` in your session. ++```powershell +$InformationPreference = 'Continue' +"Example State is: $ExampleState" +Import-Module .\example7x.psd1 +"Example State is: $ExampleState" +Import-Module .\example7x.psd1 -Force +``` ++```Output +Example State is: ++Example not initialized. +Initializing now... ++Example State is: Initialized ++Example already initialized. +``` ++### TypesToProcess ++This setting specifies the type files (`.ps1xml`) that run when the module is +imported. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++When you import the module, PowerShell runs the `Update-TypeData` cmdlet with +the specified files. Because type files aren't scoped, they affect all session +states in the session. ++For more information on type files, see +[about_Types.ps1xml](about_Types.ps1xml.md) ++For example, when you import this manifest, PowerShell loads the types specified +in the `Example.ps1xml` file from the `Types` folder located in the same +directory as the module manifest. ++```powershell +@{ + TypesToProcess = @( + 'Types\Example.ps1xml' + ) +} +``` ++### FormatsToProcess ++This setting specifies the formatting files (`.ps1xml`) that run when the module +is imported. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++When you import a module, PowerShell runs the `Update-FormatData` cmdlet with +the specified files. Because formatting files aren't scoped, they affect all +session states in the session. ++For more information on type files, see +[about_Format.ps1xml](about_Format.ps1xml.md) ++For example, when you import this module, PowerShell loads the formats specified +in the `Example.ps1xml` file from the `Formats` folder located in the same +directory as the module manifest. ++```powershell +@{ + FormatsToProcess = @( + 'Formats\Example.ps1xml' + ) +} +``` ++### NestedModules ++This setting specifies script modules (`.psm1`) and binary modules (`.dll`) that +are imported into the module's session state. You can also specify script files +(`.ps1`). The files in this setting run in the order in which they're listed. ++| | Value | +| --------------------- | --------------------------------------------------- | +| **Input Type** | `System.String[]`, `System.Collections.Hashtable[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Entries for this setting can be a module name, a full module specification, or a +path to a module or script file. ++When the value is a path, the path can be fully qualified or relative. ++When the value is a module name or specification, PowerShell searches the +**PSModulePath** for the specified module. ++A module specification is a hash table that has the following keys. ++- `ModuleName` - **Required**. Specifies the module name. +- `GUID` - **Optional**. Specifies the GUID of the module. +- It's also **Required** to specify at least one of the three below keys. The + `RequiredVersion` key can't be used with the `ModuleVersion` or + `MaximumVersion` keys. You can define an acceptable version range for the + module by specifying the `ModuleVersion` and `MaximumVersion` keys together. + - `ModuleVersion` - Specifies a minimum acceptable version of the module. + - `RequiredVersion` - Specifies an exact, required version of the module. + - `MaximumVersion` - Specifies the maximum acceptable version of the module. ++> [!NOTE] +> `RequiredVersion` was added in Windows PowerShell 5.0. +> `MaximumVersion` was added in Windows PowerShell 5.1. ++Any items that need to be exported from a nested module must exported by the +nested module using the `Export-ModuleMember` cmdlet or be listed in one of the +export properties: ++- **FunctionsToExport** +- **CmdletsToExport** +- **VariablesToExport** +- **AliasesToExport** ++Nested modules in the module session state are available to the root module, but +they aren't returned by a `Get-Module` command in the caller's session state. ++Scripts (`.ps1`) that are listed in this setting are run in the module's session +state, not in the caller's session state. To run a script in the caller's +session state, list the script filename in the **ScriptsToProcess** setting. ++For example, when you import this manifest, the `Helpers.psm1` module is loaded +into the root module's session state. Any cmdlets declared in the nested module +are exported unless otherwise restricted. ++```powershell +@{ + NestedModules = @( + 'Helpers\Helpers.psm1' + ) +} +``` ++### FunctionsToExport ++This setting specifies the functions that the module exports. You can use this +setting to restrict the functions that are exported by the module. It can remove +functions from the list of exported functions, but it can't add functions to the +list. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++You can specify entries in this setting with wildcards. All matching functions +in the list of exported functions are exported. ++> [!TIP] +> For performance and discoverability, you should always explicitly list the +> functions you want your module to export in this setting without using any +> wildcards. ++For example, when you import a module with the setting commented out, all +functions in the root module and any nested modules are exported. ++```powershell +@{ + # FunctionsToExport = @() +} +``` ++This manifest is functionally identical to not specifying the setting at all. ++```powershell +@{ + FunctionsToExport = '*' +} +``` ++With **FunctionsToExport** set as an empty array, when you import this module no +functions the root module or any nested modules export are available. ++```powershell +@{ + FunctionsToExport = @() +} +``` ++> [!NOTE] +> If you create your module manifest with the `New-ModuleManifest` command and +> do not specify the **FunctionsToExport** parameter, the created manifest has +> this setting specified as an empty array. Unless you edit the manifest, no +> functions from the module are exported. ++With **FunctionsToExport** set to only include the `Get-Example` function, when +you import this module only the `Get-Example` function is made available, even +if other functions were exported by the root module or any nested modules. ++```powershell +@{ + FunctionsToExport = @( + 'Get-Example' + ) +} +``` ++With **FunctionsToExport** set with a wildcard string, when you import this +module any function whose name ends with `Example` is made available, even if +other functions were exported as module members by the root module or any nested +modules. ++```powershell +@{ + FunctionsToExport = @( + '*Example' + ) +} +``` ++### CmdletsToExport ++This setting specifies the cmdlets that the module exports. You can use this +setting to restrict the cmdlets that are exported by the module. It can remove +cmdlets from the list of exported module members, but it can't add cmdlets to +the list. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++You can specify entries in this setting with wildcards. All matching cmdlets +in the list of exported cmdlets is exported. ++> [!TIP] +> For performance and discoverability, you should always explicitly list the +> cmdlets you want your module to export in this setting without using any +> wildcards. ++For example, when you import a module with this setting commented out, all +cmdlets in the root module and any nested modules are exported. ++```powershell +@{ + # CmdletsToExport = @() +} +``` ++This manifest is functionally identical to not specifying the setting at all. ++```powershell +@{ + CmdletsToExport = '*' +} +``` ++With **CmdletsToExport** set as an empty array, when you import this module no +cmdlets the root module or any nested modules export are available. ++```powershell +@{ + CmdletsToExport = @() +} +``` ++> [!NOTE] +> If you create your module manifest with the `New-ModuleManifest` command and +> do not specify the **CmdletsToExport** parameter, the created manifest has +> this setting specified as an empty array. Unless you edit the manifest, no +> cmdlets from the module is exported. ++With **CmdletsToExport** set to only include the `Get-Example` cmdlet, when +you import this module only the `Get-Example` cmdlet is made available, even +if other cmdlets were exported by the root module or any nested modules. ++```powershell +@{ + CmdletsToExport = @( + 'Get-Example' + ) +} +``` ++With **CmdletsToExport** set with a wildcard string, when you import this +module any cmdlet whose name ends with `Example` is made available, even if +other cmdlets were exported as module members by the root module or any nested +modules. ++```powershell +@{ + CmdletsToExport = @( + '*Example' + ) +} +``` ++### VariablesToExport ++This setting specifies the variables that the module exports. You can use this +setting to restrict the variables that are exported by the module. It can remove +variables from the list of exported module members, but it can't add variables +to the list. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++You can specify entries in this setting with wildcards. All matching variables +in the list of exported module members is exported. ++> [!TIP] +> For performance and discoverability, you should always explicitly list the +> variables you want your module to export in this setting without using any +> wildcards. ++For example, when you import a module with this setting commented out, all +variables in the root module and any nested modules are exported. ++```powershell +@{ + # VariablesToExport = @() +} +``` ++This manifest is functionally identical to not specifying the setting at all. ++```powershell +@{ + VariablesToExport = '*' +} +``` ++> [!NOTE] +> If you create your module manifest with the `New-ModuleManifest` command and +> do not specify the **VariablesToExport** parameter, the created manifest has +> this setting specified as `'*'`. Unless you edit the manifest, all variables +> from the module is exported. ++With **VariablesToExport** set as an empty array, when you import this module no +variables the root module or any nested modules export are available. ++```powershell +@{ + VariablesToExport = @() +} +``` ++With **VariablesToExport** set to only include the `SomeExample` variable, when +you import this module only the `$SomeExample` variable is made available, even +if other variables were exported by the root module or any nested modules. ++```powershell +@{ + VariablesToExport = @( + 'SomeExample' + ) +} +``` ++With **VariablesToExport** set with a wildcard string, when you import this +module any variable whose name ends with `Example` is made available, even if +other variables were exported as module members by the root module or any nested +modules. ++```powershell +@{ + VariablesToExport = @( + '*Example' + ) +} +``` ++### DscResourcesToExport ++This setting specifies the DSC Resources that the module exports. You can use +this setting to restrict the class-based DSC Resources that are exported by the +module. It can remove DSC Resources from the list of exported module members, +but it can't add DSC Resources to the list. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++You can specify entries in this setting with wildcards. All matching class-based +DSC Resources in the module are exported. ++> [!TIP] +> For discoverability, you should always explicitly list all of the DSC +> Resources your module module exports. ++For more information on authoring and using DSC Resources, see the +[documentation for DSC](/powershell/dsc/overview). ++This manifest exports all of the class-based and MOF-based DSC Resources defined +in the root module and any nested modules. ++```powershell +@{ + # DscResourcesToExport = @() +} +``` ++This manifest exports all of the MOF-based DSC Resources defined in the root +module and any nested modules, but only one class-based DSC Resource, +`ExampleClassResource`. ++```powershell +@{ + DscResourcesToExport = @( + 'ExampleClassResource' + ) +} +``` ++This manifest exports all of the DSC Resources it includes. Even if the +MOF-Based resource was not listed, the module would still export it. ++```powershell +@{ + DscResourcesToExport = @( + 'ExampleClassResource' + 'ExampleMofResourceFirst' + ) +} +``` ++### ModuleList ++This setting is an informational inventory list of the modules included in this +one. This list does not affect the behavior of the module. ++| | Value | +| --------------------- | --------------------------------------------------- | +| **Input Type** | `System.String[]`, `System.Collections.Hashtable[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Entries for this setting can be a module name, a full module specification, or a +path to a module or script file. ++When the value is a path, the path can be fully qualified or relative. ++When the value is a module name or specification, PowerShell searches the +**PSModulePath** for the specified module. ++A module specification is a hash table that has the following keys. ++- `ModuleName` - **Required**. Specifies the module name. +- `GUID` - **Optional**. Specifies the GUID of the module. +- It's also **Required** to specify at least one of the three below keys. The + `RequiredVersion` key can't be used with the `ModuleVersion` or + `MaximumVersion` keys. You can define an acceptable version range for the + module by specifying the `ModuleVersion` and `MaximumVersion` keys together. + - `ModuleVersion` - Specifies a minimum acceptable version of the module. + - `RequiredVersion` - Specifies an exact, required version of the module. + - `MaximumVersion` - Specifies the maximum acceptable version of the module. ++> [!NOTE] +> `RequiredVersion` was added in Windows PowerShell 5.0. +> `MaximumVersion` was added in Windows PowerShell 5.1. ++This manifest does not provide an informational list of the modules it includes. +It may or may not have modules. Even though this setting is not specified, any +modules listed in the **RootModule**, **ScriptsToProcess**, or **NestedModules** +settings will still behave as normal. ++```powershell +@{ + # ModuleList = @() +} +``` ++This manifest declares that the only modules it includes are `Example.psm1` and +the submodules `First.psm1` and `Second.psm1` in the `Submodules` folder. ++```powershell +@{ + ModuleList = @( + 'Example.psm1' + 'Submodules\First.psm1' + 'Submodules\Second.psm1' + ) +} +``` ++### FileList ++This setting is an informational inventory list of the files included in this +module. This list does not affect the behavior of the module. ++| | Value | +| --------------------- | ----------------- | +| **Input Type** | `System.String[]` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | Yes | ++Entries for this setting should be the relative path to a file from the folder +containing the module manifest. ++When a user calls `Get-Module` against a manifest with this setting defined, the +**FileList** property of the returned object will be the full path to these +files, joining the module's path with each entry's relative path. ++This manifest does not include a list of its files. ++```powershell +@{ + # FileList = @() +} +``` ++This manifest declares that the only files it includes are listed in this +setting. ++```powershell +@{ + Filelist = @( + 'Example.psd1' + 'Example.psm1' + 'Assemblies\Example.dll' + 'Scripts\Initialize.ps1' + 'Submodules\First.psm1' + 'Submodules\Second.psm1' + ) +} +``` ++### PrivateData ++This setting defines a hash table of data that is available to any commands or +functions in the root module's scope. ++| | Value | +| --------------------- | ------------------------------ | +| **Input Type** | `System.Collections.Hashtable` | +| **Required** | PowerShell Gallery | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This setting has two primary effects: ++1. Any keys added to this setting are available to functions and cmdlets in the + root module with `$MyInvocation.MyCommand.Module.PrivateData`. The hash table + is not available in the module scope itself, only in cmdlets you define in + the module. +1. You can add the **PSData** key with a hash table for metadata needed when + publishing 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](/powershell/scripting/gallery/concepts/package-manifest-affecting-ui) ++For example, this manifest defines the **PublishedDate** key in **PrivateData**. ++```powershell +@{ + PrivateData = @{ + PublishedDate = '2022-06-01' + } +} +``` ++Cmdlets in the module can access this value with the `$MyInvocation` variable. ++```powershell +Function Get-Stale { + [CmdletBinding()] + param() ++ $PublishedDate = $MyInvocation.MyCommand.Module.PrivateData.PublishedDate + $CurrentDate = Get-Date ++ try { + $PublishedDate = Get-Date -Date $PublishedDate -ErrorAction Stop + } catch { + # The date was set in the manifest, set to an invalid value, or the + # script module was directly imported without the manifest. + Throw "Unable to determine published date. Check the module manifest." + } ++ if ($CurrentDate -gt $PublishedDate.AddDays(30)) { + Write-Warning "This module version was published more than 30 days ago." + } else { + $TimeUntilStale = $PublishedDate.AddDays(30) - $CurrentDate + "This module will be stale in $($TimeUntilStale.Days) days" + } +} +``` ++Once the module is imported, the function uses the value from **PrivateData** +to determine when the module was published. ++```powershell +Get-Stale -TestDate '2022-06-15' +Get-Stale -TestDate '2022-08-01' +``` ++```Output +This module will be stale in 16 days ++WARNING: This module version was published more than 30 days ago. +``` ++### HelpInfoURI ++This setting specifies the internet address of the HelpInfo XML file for the +module. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++This setting's value must be a Uniform Resource Identifier (URI) that begins +with **http** or **https**. ++The HelpInfo XML file supports the Updatable Help feature that was introduced in +PowerShell 3.0. It 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_Updatable_Help.md). For information about +the HelpInfo XML file, see +[Supporting Updatable Help](/powershell/scripting/developer/module/supporting-updatable-help). ++For example, this module supports updatable help. ++```powershell +@{ + HelpInfoUri = 'http://https://go.microsoft.com/fwlink/?LinkID=603' +} +``` ++### DefaultCommandPrefix ++This setting specifies a prefix that is prepended to the nouns of all commands +in the module when they're imported into a session. Prefixes help prevent +command name conflicts in a user's session. ++| | Value | +| --------------------- | --------------- | +| **Input Type** | `System.String` | +| **Required** | No | +| **Value if unset** | `$null` | +| **Accepts wildcards** | No | ++Module users can override this prefix by specifying the **Prefix** parameter of +the `Import-Module` cmdlet. ++This setting was introduced in PowerShell 3.0. ++When this manifest is imported, any cmdlets imported from this module have +`Example` prepended to the noun in their name. For example, `Get-Item` is +imported as `Get-ExampleItem`. ++```powershell +@{ + DefaultCommandPrefix = 'Example' +} +``` ++## See also ++- [about_PowerShell_Editions](/powershell/module/microsoft.powershell.core/about/about_powershell_editions) +- [New-ModuleManifest](xref:Microsoft.PowerShell.Core.New-ModuleManifest) +- [Test-ModuleManifest](xref:Microsoft.PowerShell.Core.Test-ModuleManifest) +- [Modules with compatible PowerShell Editions](/powershell/scripting/gallery/concepts/module-psedition-support). +- [Package manifest values that impact the PowerShell Gallery UI](/powershell/scripting/gallery/concepts/package-manifest-affecting-ui) +- [PowerShell module authoring considerations](/powershell/scripting/dev-cross-plat/performance/module-authoring-considerations) |
PackageManagement | Packagemanagement (7.3) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.3/PackageManagement/PackageManagement.md | Help Version: 7.2.0.0 Locale: en-US Module Guid: 4ae9fd46-338a-459c-8186-07f910774cb8 Module Name: PackageManagement Previously updated : 06/09/2017 Last updated : 04/21/2022 schema: 2.0.0 Title: PackageManagement --- Title: PackageManagement ## Description -This topic displays help topics for the Package Management Cmdlets. +This topic displays help topics for the Package Management Cmdlets. The cmdlet reference +documentation on this site documents the latest version of the module. > [!IMPORTANT] > As of April 2020, the PowerShell Gallery no longer supports Transport Layer Security (TLS) This topic displays help topics for the Package Management Cmdlets. > trying to access the PowerShell Gallery. Use the following command to ensure you are using TLS > 1.2: >-> `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` +> `[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12` > > For more information, see the > [announcement](https://devblogs.microsoft.com/powershell/powershell-gallery-tls-support/) in the |
PowerShellGet | Powershellget (7.3) | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.3/PowerShellGet/PowerShellGet.md | --- Download Help Link: https://aka.ms/powershell73-help -Help Version: 7.2.0.0 +Help Version: 7.3.0.0 Locale: en-US Module Guid: 1d73a601-4a6c-43c5-ba3f-619b18bbb404 Module Name: PowerShellGet Previously updated : 06/09/2017 Last updated : 04/21/2022 schema: 2.0.0 Title: PowerShellGet --- Title: PowerShellGet PowerShellGet is a module with commands for discovering, installing, updating and publishing PowerShell artifacts like Modules, DSC Resources, Role Capabilities, and Scripts. +The cmdlet reference documentation on this site documents the latest version of the module. + > [!IMPORTANT] > As of April 2020, the PowerShell Gallery no longer supports Transport Layer Security (TLS) > versions 1.0 and 1.1. If you are not using TLS 1.2 or higher, you will receive an error when > trying to access the PowerShell Gallery. Use the following command to ensure you are using TLS > 1.2: >-> `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` +> `[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12` > > For more information, see the > [announcement](https://devblogs.microsoft.com/powershell/powershell-gallery-tls-support/) in the PowerShell artifacts like Modules, DSC Resources, Role Capabilities, and Scripts Finds PowerShell commands in modules. ### [Find-DscResource](Find-DscResource.md)-Finds Desired State Configuration (DSC) resources. +Finds a DSC resource. ### [Find-Module](Find-Module.md) Finds modules in a repository that match specified criteria. |
gallery | Getting Started | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/gallery/getting-started.md | These hostnames should be added to the allow lists that control access from your Hosts required for package discovery and download: - `onegetcdn.azureedge.net` - CDN hostname+- `psg-prod-centralus.azureedge.net` - CDN hostname - `psg-prod-eastus.azureedge.net` - CDN hostname-- `az818661.vo.msecnd.net` - CDN hostname Hosts required when using the PowerShell Gallery website: |
gallery | Install On Older Systems | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/gallery/install-on-older-systems.md | +--- +description: This article explains how to install the PowerShellGet module in older versions of PowerShell. Last updated : 04/21/2022+ Title: Installing PowerShellGet on older Windows systems +--- +# Installing PowerShellGet on older Windows systems ++Older versions of Windows shipped with different versions of PowerShell. The **PowerShellGet** +module requires **PowerShell 3.0 or newer**. ++**PowerShellGet** requires .NET Framework 4.5 or above. For more information, see +[Install the .NET Framework for developers](/dotnet/framework/install/guide-for-developers). +++## For computers running PowerShell 3.0 or PowerShell 4.0 ++These instructions apply to computers that have the **PackageManagement Preview** installed or don't +have any version of **PowerShellGet** installed. ++The `Save-Module` cmdlet is used in both sets of instructions. `Save-Module` downloads and saves a +module and any dependencies from a registered repository. The module's most current version is saved +to a specified path on the local computer, but isn't installed. To install the modules in PowerShell +3.0 or 4.0, copy the saved module folders to `$env:ProgramFiles\WindowsPowerShell\Modules`. ++For more information, see [Save-Module](/powershell/module/PowershellGet/Save-Module). ++> [!NOTE] +> PowerShell 3.0 and PowerShell 4.0 only supported one version of a module. Starting in PowerShell +> 5.0, modules are installed in `<modulename>\<version>`. This allows you to install +> multiple versions side-by-side. After downloading the module using `Save-Module` you must copy the +> files from the `<modulename>\<version>` to the `<modulename>` folder on the destination machine, +> as shown in the instructions below. ++### Preparatory Step on computers running PowerShell 3.0 ++The instructions in the sections below install the modules in directory +`$env:ProgramFiles\WindowsPowerShell\Modules`. In PowerShell 3.0, this directory isn't listed in +`$env:PSModulePath` by default, so you'll need to add it in order for the modules to be auto-loaded. ++Open an elevated PowerShell session and run the following command: ++```powershell +[Environment]::SetEnvironmentVariable( + 'PSModulePath', + ((([Environment]::GetEnvironmentVariable('PSModulePath', 'Machine') -split ';') + "$env:ProgramFiles\WindowsPowerShell\Modules") -join ';'), + 'Machine' +) +``` ++The updated value of `$env:PSModulePath` is not available in the current session. You must open a +new PowerShell session. ++### For computers with the PackageManagement Preview installed ++> [!NOTE] +> PackageManagement Preview was a downloadable component that made PowerShellGet available to +> PowerShell versions 3 and 4, but it is no longer available. To test if it was installed on a given +> computer, run `Get-Module -ListAvailable PowerShellGet`. ++1. From a PowerShell session, use `Save-Module` to download the current version of + **PowerShellGet**. Two folders are downloaded: **PowerShellGet** and **PackageManagement**. Each + folder contains a subfolder with a version number. ++ ```powershell + Save-Module -Name PowerShellGet -Path C:\LocalFolder -Repository PSGallery + ``` ++1. Ensure that the **PowerShellGet** and **PackageManagement** modules aren't loaded in any other + processes. ++1. Reopen the PowerShell console with elevated permissions and run the following command. ++ ```powershell + 'PowerShellGet', 'PackageManagement' | % { + $targetDir = "$env:ProgramFiles\WindowsPowerShell\Modules\$_" + Remove-Item $targetDir\* -Recurse -Force + Copy-Item C:\LocalFolder\$_\*\* $targetDir\ -Recurse -Force + } + ``` |
gallery | Installing Psget | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/gallery/installing-psget.md | --- description: This article explains how to install the PowerShellGet module in various versions of PowerShell. Previously updated : 10/05/2021 Last updated : 04/21/2022 Title: Installing PowerShellGet --- -# Installing PowerShellGet +# Installing PowerShellGet on Windows -## PowerShellGet is an in-box module in the following releases +Windows PowerShell 5.1 comes with version 1.0.0.1 of **PowerShellGet** preinstalled. -- [Windows 10](https://www.microsoft.com/windows) or newer-- [Windows Server 2016](/windows-server/windows-server) or newer-- [Windows Management Framework (WMF) 5.0](https://www.microsoft.com/download/details.aspx?id=50395)- or newer -- [PowerShell 6](https://github.com/PowerShell/PowerShell/releases)+> [!IMPORTANT] +> This version of PowerShellGet has a limited features and doesn't support the updated capabilities +> of the PowerShell Gallery. To be supported, you must update to the latest version. -## Get the latest version from PowerShell Gallery +PowerShell 6.0 shipped with version 1.6.0 of **PowerShellGet**. PowerShell 7.0 shipped with version +2.2.3 of **PowerShellGet**. The current supported version of **PowerShellGet** is 2.2.5. -Before updating **PowerShellGet**, you should always install the latest **NuGet** provider. From an -elevated PowerShell session, run the following command. +If you are running PowerShell 6 or higher, you have a usable version of **PowerShellGet**. If you +are running Windows PowerShell 5.1, you must install a newer version. -```powershell -Install-PackageProvider -Name NuGet -Force -``` +For best results, you should always install the latest supported version. +## Updating the preinstalled version of PowerShellGet -### For systems with PowerShell 5.0 (or newer) you can install the latest PowerShellGet +The PowerShellGet module includes cmdlets to install and update modules: -To install PowerShellGet on any system with WMF 5.1 installed, run the following commands from an -elevated PowerShell session. +- `Install-Module` installs the latest (non-prerelease) version of a module. +- `Update-Module` installs the latest (non-prerelease) version of a module if it is newer than the + currently installed module. However, this cmdlet only works if the previous version was installed + using `Install-Module`. -```powershell -Install-Module -Name PowerShellGet -Force -``` +To update the preinstalled module you must use `Install-Module`. After you have installed the new +version from the PowerShell Gallery, you can use `Update-Module` to install newer releases. -Use `Update-Module` to get newer versions. +## Updating PowerShellGet for Windows PowerShell 5.1 -```powershell -Update-Module -Name PowerShellGet -Exit -``` +### System requirements -### For computers running PowerShell 3.0 or PowerShell 4.0 +- **PowerShellGet** requires .NET Framework 4.5 or above. For more information, see + [Install the .NET Framework for developers](/dotnet/framework/install/guide-for-developers). -These instructions apply to computers that have the **PackageManagement Preview** installed or don't -have any version of **PowerShellGet** installed. +- To access the PowerShell Gallery, you must use Transport Layer Security (TLS) 1.2 or higher. By + default, PowerShell is not configured to use TLS 1.2. Use the following command to enable TLS 1.2 + in your PowerShell session. -The `Save-Module` cmdlet is used in both sets of instructions. `Save-Module` downloads and saves a -module and any dependencies from a registered repository. The module's most current version is saved -to a specified path on the local computer, but isn't installed. To install the modules in PowerShell -3.0 or 4.0, copy the module saved folders to `$env:ProgramFiles\WindowsPowerShell\Modules`. + ```powershell + [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12 + ``` -For more information, see -[Save-Module](/powershell/module/PowershellGet/Save-Module). + We also recommend adding this line of code to your PowerShell profile script. For more information + about profiles, see + [about_Profiles](/powershell/module/microsoft.powershell.core/about/about_profiles). ++### Installing the latest version of PowerShellGet ++Windows PowerShell 5.1 comes with **PowerShellGet** version 1.0.0.1, which doesn't include the NuGet +provider. The provider is required by **PowerShellGet** when working with the PowerShell Gallery. > [!NOTE]-> PowerShell 3.0 and PowerShell 4.0 only supported one version of a module. Starting in PowerShell -> 5.0, modules are installed in `<modulename>\<version>`. This allows you to install -> multiple versions side-by-side. After downloading the module using `Save-Module` you must copy the -> files from the `<modulename>\<version>` to the `<modulename>` folder on the destination machine, -> as shown in the instructions below. +> The following commands must be run from an elevated PowerShell session. Right-click the PowerShell +> icon and choose **Run as administrator** to start an elevated session. -#### Preparatory Step on computers running PowerShell 3.0 +There are two ways to install the NuGet provider: -The instructions in the sections below install the modules in directory -`$env:ProgramFiles\WindowsPowerShell\Modules`. In PowerShell 3.0, this directory isn't listed in -`$env:PSModulePath` by default, so you'll need to add it in order for the modules to be auto-loaded. +- Use `Install-PackageProvider` to install NuGet before installing other modules -Open an elevated PowerShell session and run the following command (which will take effect in future -sessions): + Run the following command to install the NuGet provider. -```powershell -[Environment]::SetEnvironmentVariable( - 'PSModulePath', - ((([Environment]::GetEnvironmentVariable('PSModulePath', 'Machine') -split ';') + "$env:ProgramFiles\WindowsPowerShell\Modules") -join ';'), - 'Machine' -) -``` + ```powershell + Install-PackageProvider -Name NuGet -Force + ``` ++ After you have installed the provider you should be able to use any of the **PowerShellGet** + cmdlets with the PowerShell Gallery. -#### Computers with the PackageManagement Preview installed +- Let `Install-Module` prompt you to install the NuGet provider ++ The following command attempts to install the updated PowerShellGet module without the NuGet + provider. ++ ```powershell + Install-Module PowerShellGet -AllowClobber -Force + ``` ++ `Install-Module` prompts you to install the NuGet provider. Type <kbd>Y</kbd> to install the + provider. ++ ```Output + NuGet provider is required to continue + PowerShellGet requires NuGet provider version '2.8.5.201' or newer to interact with NuGet-based + repositories. The NuGet provider must be available in 'C:\Program Files\PackageManagement\ProviderAssemblies' + or 'C:\Users\user1\AppData\Local\PackageManagement\ProviderAssemblies'. You can also install the NuGet + provider by running 'Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force'. Do you + want PowerShellGet to install and import the NuGet provider now? + [Y] Yes [N] No [S] Suspend [?] Help (default is "Y"): Y + VERBOSE: Installing NuGet provider. + ``` > [!NOTE]-> PackageManagement Preview was a downloadable component that made PowerShellGet available to -> PowerShell versions 3 and 4, but it is no longer available. To test if it was installed on a given -> computer, run `Get-Module -ListAvailable PowerShellGet`. --1. From a PowerShell session, use `Save-Module` to download the current version of - **PowerShellGet**. Two folders are downloaded: **PowerShellGet** and **PackageManagement**. Each - folder contains a subfolder with a version number. -- ```powershell - Save-Module -Name PowerShellGet -Path C:\LocalFolder -Repository PSGallery - ``` --1. Ensure that the **PowerShellGet** and **PackageManagement** modules aren't loaded in any other - processes. --1. Reopen the PowerShell console with elevated permissions and run the following command. -- ```powershell - 'PowerShellGet', 'PackageManagement' | % { - $targetDir = "$env:ProgramFiles\WindowsPowerShell\Modules\$_" - Remove-Item $targetDir\* -Recurse -Force - Copy-Item C:\LocalFolder\$_\*\* $targetDir\ -Recurse -Force - } - ``` --#### Computers without PowerShellGet --For computers without any version of **PowerShellGet** installed (test with -`Get-Module -ListAvailable PowerShellGet`), a computer with **PowerShellGet** installed is needed to -download the modules. --1. From the computer that has **PowerShellGet** installed, use `Save-Module` to download the current - version of **PowerShellGet**. Two folders are downloaded: **PowerShellGet** and - **PackageManagement**. Each folder contains a subfolder with a version number. -- ```powershell - Save-Module -Name PowerShellGet -Path C:\LocalFolder -Repository PSGallery - ``` --1. Copy the respective `<version>` subfolder in the **PowerShellGet** and **PackageManagement** - folders to the computer that doesn't have **PowerShellGet** installed, into folders - `$env:ProgramFiles\WindowsPowerShell\Modules\PowerShellGet\` and - `$env:ProgramFiles\WindowsPowerShell\Modules\PackageManagement\` respectively, which requires an - elevated session. --1. For instance, if you can access the download folder on the other computer, say `ws1`, from the - target computer via a UNC path, say `\\ws1\C$\LocalFolder`, open a PowerShell console with - elevated permissions and run the following command: -- ```powershell - 'PowerShellGet', 'PackageManagement' | % { - $targetDir = "$env:ProgramFiles\WindowsPowerShell\Modules\$_" - $null = New-Item -Type Directory -Force $targetDir - $fromComputer = 'ws1' # Specify the name of the other computer here. - Copy-Item \\$fromComputer\C$\LocalFolder\$_\*\* $targetDir -Recurse -Force - if (-not (Get-ChildItem $targetDir)) { Throw "Copying failed." } - } - ``` +> If you have not configured TLS 1.2, any attempts to install the NuGet provider and other +> packages will fail. ++### After installing PowerShellGet ++After you have installed the new version of **PowerShellGet**, you should open a new PowerShell +session. PowerShell automatically loads the newest version of the module when you use a +**PowerShellGet** cmdlet. ++We also recommend that you register the PowerShell Gallery as a trusted repository. Use the following command: ++```powershell +Set-PSRepository -Name PSGallery -InstallationPolicy Trusted +``` ++For more information, see [Set-PSRepository](xref:PowerShellGet.Set-PSRepository). |
gallery | Overview | https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/gallery/overview.md | --- description: The PowerShell Gallery is the central repository for PowerShell modules, scripts, and DSC resources. Previously updated : 10/22/2021 Last updated : 04/21/2022 Title: The PowerShell Gallery --- # The PowerShell Gallery -The PowerShell Gallery is the central repository for PowerShell content. In it, you can find useful -PowerShell modules containing PowerShell commands and Desired State Configuration (DSC) resources. -You can also find PowerShell scripts, some of which may contain PowerShell workflows, and which -outline a set of tasks and provide sequencing for those tasks. Some of these packages are authored -by Microsoft, and others are authored by the PowerShell community. +The PowerShell Gallery is the central repository for PowerShell content. In it, you can find +PowerShell scripts, modules containing PowerShell cmdlets and Desired State Configuration (DSC) +resources. Some of these packages are authored by Microsoft, and others are authored by the +PowerShell community. -## PowerShellGet Overview +## The PowerShellGet module -The PowerShellGet module contains cmdlets for discovering, installing, updating and publishing -PowerShell packages which contain artifacts such as Modules, DSC Resources, Role Capabilities and -Scripts from the [PowerShell Gallery](https://www.PowerShellGallery.com) and other private -repositories. +The **PowerShellGet** module contains cmdlets for discovering, installing, updating, and publishing +PowerShell packages from the [PowerShell Gallery](https://www.powershellgallery.com). These packages +can contain artifacts such as Modules, DSC Resources, Role Capabilities, and Scripts. -## Getting Started with the Gallery +### Version history -Installing packages from the Gallery requires the latest version of the PowerShellGet module. See -[Installing PowerShellGet](installing-psget.md) for complete instructions. +Windows PowerShell 5.1 comes with version 1.0.0.1 of **PowerShellGet** preinstalled. -Check out the [Getting Started](getting-started.md) page for more information on how to use -PowerShellGet commands with the Gallery. You can also run `Update-Help -Module PowerShellGet` to -install local help for these commands. +> [!IMPORTANT] +> This version of PowerShellGet has a limited features and doesn't support the updated capabilities +> of the PowerShell Gallery. To be supported, you must update to the latest version. ++PowerShell 6.0 shipped with version 1.6.0 of **PowerShellGet**. PowerShell 7.0 shipped with version +2.2.3 of **PowerShellGet**. The current supported version of **PowerShellGet** is 2.2.5. -## Supported Operating Systems +For best results, use the latest version of the **PowerShellGet** module. See +[Installing PowerShellGet](installing-psget.md) for complete instructions. The cmdlet reference +documentation on this site documents the latest version. -The **PowerShellGet** module requires **PowerShell 3.0 or newer**. +## Getting Started with the PowerShell Gallery -**PowerShellGet** requires .NET Framework 4.5 or above. For more information, see -[Install the .NET Framework for developers](/dotnet/framework/install/guide-for-developers). +Check out the [Getting Started](getting-started.md) page for more information on how to use +**PowerShellGet** commands with the Gallery. You can also run +`Update-Help -Module PowerShellGet -Force` to install local help for these commands. -PowerShell is cross-platform, which means it works on Windows, Linux and MacOS. That also makes +PowerShell is cross-platform, which means it works on Windows, Linux, and macOS. That also makes **PowerShellGet** available on those systems. For a full list of systems supported by PowerShell see [Installing PowerShell](/powershell/scripting/install/installing-powershell). -Many modules hosted in the gallery support different OSes and have additional requirements. -Please refer to the documentation for the modules for more information. +Modules in the PowerShell Gallery can support different operating systems and have additional +requirements. For information, see the documentation for the module. ## Got a question? Have feedback? -More information about the PowerShell Gallery and PowerShellGet can be found in the +More information about the PowerShell Gallery and **PowerShellGet** can be found in the [Getting Started](getting-started.md) page. To see the current status of the PowerShell Gallery services, see the-[PowerShell Gallery Status](https://github.com/PowerShell/PowerShellGallery/blob/master/psgallery_status.md) -page on GitHub. +[PowerShell Gallery Status](https://aka.ms/psgallery-status) page on GitHub. -Please provide feedback and report issues the -[GitHub repository](https://github.com/PowerShell/PowerShellGallery/issues). +Please provide feedback and report issues in the [GitHub repository](https://aka.ms/psgallery-issues). |