about_Modules

简短说明

介绍如何安装、导入和使用 PowerShell 模块。

长说明

模块是包含 PowerShell 成员的包,例如 cmdlet、提供程序、函数、工作流、变量和别名。

编写命令的人可以使用模块来组织其命令并与他人共享。 接收模块的人员可以将模块中的命令添加到其 PowerShell 会话中,并像内置命令一样使用这些命令。

本主题介绍如何使用 PowerShell 模块。 有关如何编写 PowerShell 模块的信息,请参阅 编写 PowerShell 模块

什么是模块?

模块是包含 PowerShell 成员的包,例如 cmdlet、提供程序、函数、工作流、变量和别名。 此包的成员可以在 PowerShell 脚本、已编译的 DLL 或两者的组合中实现。 这些文件通常组合在一个目录中。 有关详细信息,请参阅 SDK 文档中的“了解Windows PowerShell模块”。

模块自动加载

从 PowerShell 3.0 开始,PowerShell 会在首次在已安装模块中运行任何命令时自动导入模块。 现在,你可以在没有任何设置或配置文件配置的情况下使用模块中的命令,因此在计算机上安装模块后,无需再对其进行管理。

模块中的命令也更易于查找。 cmdlet Get-Command 现在会获取所有已安装模块中的所有命令,即使它们尚未在会话中也是如此。 你可以找到一个命令并使用它,而无需先导入模块。

以下示例中的每个示例都会导致 CimCmdlet 模块(包含 Get-CimInstance)导入到会话中。

  • 运行命令

    Get-CimInstance Win32_OperatingSystem
    
  • 获取命令

    Get-Command Get-CimInstance
    
  • 获取命令的帮助

    Get-Help Get-CimInstance
    

Get-Command 包含通配符 (*) 的命令被视为用于发现、不使用和不导入任何模块。

仅自动导入存储在 PSModulePath 环境变量指定位置的模块。 其他位置中的模块必须通过运行 Import-Module cmdlet 导入。

此外,使用 PowerShell 提供程序的命令不会自动导入模块。 例如,如果使用需要 WSMan: 驱动器(如 Get-PSSessionConfiguration cmdlet)的命令,则可能需要运行 Import-Module cmdlet 来导入包含WSMan:该驱动器的 Microsoft.WSMan.Management 模块。

仍可以运行 Import-Module 命令来导入模块,并使用 $PSModuleAutoloadingPreference 变量启用、禁用和配置模块的自动导入。 有关详细信息,请参阅 about_Preference_Variables

如何使用模块

若要使用模块,请执行以下任务:

  1. 安装模块。 (通常已为你完成这一步。)
  2. 找到模块所添加的命令。
  3. 使用模块所添加的命令。

本主题介绍了如何执行这些任务。 它还包括有关管理模块的其他有用信息。

如何安装模块

如果将模块作为包含文件的文件夹接收,则需要在计算机上安装它,然后才能在 PowerShell 中使用它。

已为你安装好大多数模块。 PowerShell 附带多个预安装模块,有时称为 核心 模块。 在基于 Windows 的计算机上,如果操作系统中包含的功能具有用于管理它们的 cmdlet,则预安装这些模块。 安装 Windows 功能时,例如,使用服务器管理器中的“添加角色和功能向导”,或者控制面板中打开或关闭 Windows 功能对话框时,将安装属于该功能的任何 PowerShell 模块。 许多其他模块随附在用于安装模块的安装程序中。

使用以下命令为当前用户创建 Modules 目录:

New-Item -Type Directory -Path $HOME\Documents\PowerShell\Modules

将整个模块文件夹复制到 Modules 目录中。 可以使用任何方法复制文件夹,包括 Windows 资源管理器和Cmd.exe以及 PowerShell。 在 PowerShell 中使用 Copy-Item cmdlet。 例如,若要将 MyModule 文件夹从 C:\ps-test\MyModule “模块”目录复制到“模块”目录,请键入:

Copy-Item -Path C:\ps-test\MyModule -Destination `
    $HOME\Documents\PowerShell\Modules

你可以在任何位置上安装模块,但在默认模块位置中安装模块可使其更易于管理。 有关默认模块位置的详细信息,请参阅 模块和 DSC 资源位置以及 PSModulePath 部分。

如何查找已安装的模块

若要查找已安装在默认模块位置中但尚未导入到会话中的模块,请键入:

Get-Module -ListAvailable

若要查找已导入到会话中的模块,请在 PowerShell 提示符下键入:

Get-Module

有关 cmdlet 的详细信息 Get-Module ,请参阅 Get-Module

如何在模块中查找命令

使用 Get-Command cmdlet 查找所有可用的命令。 可以使用 cmdlet 的参数 Get-Command 按模块、名称和名词等筛选命令。

若要查找模块中的所有命令,请键入:

Get-Command -Module <module-name>

例如,若要在 BitsTransfer 模块中找到命令,请键入:

Get-Command -Module BitsTransfer

有关 cmdlet 的详细信息 Get-Command ,请参阅 Get-Command

如何获取模块中命令的帮助

如果模块包含它导出的命令的帮助文件,则 Get-Help cmdlet 将显示帮助主题。 使用与在 PowerShell 中获取任何命令的帮助相同的 Get-Help 命令格式。

从 PowerShell 3.0 开始,可以下载模块的帮助文件,并下载帮助文件的更新,使其永远不会过时。

若要获取有关模块中的命令的帮助,请键入:

Get-Help <command-name>

若要联机获取模块中命令的帮助,请键入:

Get-Help <command-name> -Online

若要下载并安装模块中命令的帮助文件,请键入:

Update-Help -Module <module-name>

有关详细信息,请参阅 Get-HelpUpdate-Help

如何导入模块

你可能需要导入模块或导入模块文件。 如果模块未安装在 PSModulePath 环境变量 $env:PSModulePath指定的位置,或者模块由文件(例如.dll或 .psm1 文件)组成,而不是作为文件夹传递的典型模块,则需要导入。

还可以选择导入模块,以便可以使用命令的参数(如 Prefix 参数),该参数 Import-Module 会将一个独特的前缀添加到所有导入的命令的名词名称或 NoClobber 参数,从而阻止模块添加命令,这些命令将隐藏或替换会话中的现有命令。

若要导入模块,请使用 Import-Module cmdlet。

若要将 PSModulePath 位置中的模块导入到当前会话中,请使用以下命令格式。

Import-Module <module-name>

例如,以下命令将 BitsTransfer 模块导入当前会话。

Import-Module BitsTransfer

若要导入不在默认模块位置中的模块,请使用指向命令中的模块文件夹的完全限定的路径。

例如,若要将目录中的 TestCmdlet 模块 C:\ps-test 添加到会话,请键入:

Import-Module C:\ps-test\TestCmdlets

若要导入未包含在模块文件夹中的模块文件,请使用指向命令中的模块文件的完全限定的路径。

例如,若要将目录中的 TestCmdlets.dll 模块 C:\ps-test 添加到会话,请键入:

Import-Module C:\ps-test\TestCmdlets.dll

有关将模块添加到会话的详细信息,请参阅 Import-Module

如何将模块导入到每个会话

Import-Module 命令将模块导入当前 PowerShell 会话。 要将模块导入到启动的每个 PowerShell 会话中,请将 Import-Module 该命令添加到 PowerShell 配置文件。

有关配置文件的详细信息,请参阅 about_Profiles

如何删除模块

当你删除模块时,该模块所添加的命令将从会话中删除。

若要从会话中删除模块,请使用以下命令格式。

Remove-Module <module-name>

例如,以下命令从当前会话中删除 BitsTransfer 模块。

Remove-Module BitsTransfer

删除模块与导入模块的操作相反。 删除模块不会卸载该模块。 有关详细信息,请参阅 Remove-Module

模块和 DSC 资源位置以及 PSModulePath

环境变量 $env:PSModulePath 包含搜索以查找模块和资源的文件夹位置的列表。

默认情况下,分配给 $env:PSModulePath 的有效位置为:

  • 系统范围的位置: $PSHOME\Modules

    这些文件夹包含随 Windows 和 PowerShell 一起随附的模块。

    PowerShell 附带的 DSC 资源存储在 $PSHOME\Modules\PSDesiredStateConfiguration\DSCResources 文件夹中。

  • 特定于用户的模块:这些模块由用户安装在用户范围内。 Install-Module 具有一个 Scope 参数,用于指定是为当前用户还是所有用户安装模块。 有关详细信息,请参阅 Install-Module

    Windows 上特定于用户的 CurrentUser 位置是 PowerShell\Modules 位于用户配置文件中的 “文档 ”位置的文件夹。 该位置的特定路径因 Windows 版本而异,以及是否使用文件夹重定向。 Microsoft OneDrive 还可以更改 Documents 文件夹的位置。

    默认情况下,在Windows 10及更高版本上,该位置为 $HOME\Documents\PowerShell\Modules。 在 Linux 或 Mac 上, CurrentUser 位置为 $HOME/.local/share/powershell/Modules.

    备注

    可以使用以下命令验证 Documents 文件夹的位置: [Environment]::GetFolderPath('MyDocuments')

  • AllUsers 位置位于 $env:PROGRAMFILES\PowerShell\Modules Windows 上。 在 Linux 或 Mac 上,模块存储在 /usr/local/share/powershell/Modules.

备注

若要在目录中添加或更改文件 $env:Windir\System32 ,请使用 “以管理员身份运行 ”选项启动 PowerShell。

可以通过更改 PSModulePath 环境变量 $Env:PSModulePath的值来更改系统上的默认模块位置。 PSModulePath 环境变量在 Path 环境变量上建模,格式相同。

若要查看默认模块位置,请键入:

$Env:PSModulePath

若要添加默认模块位置,请使用以下命令格式。

$Env:PSModulePath = $Env:PSModulePath + ";<path>"

命令中的分号 (;) 将新路径与列表中前面的路径分开。

例如,若要添加 C:\ps-test\Modules 目录,请键入:

$Env:PSModulePath + ";C:\ps-test\Modules"

若要在 Linux 或 MacOS 上添加默认模块位置,请使用以下命令格式:

$Env:PSModulePath += ":<path>"

例如,若要将 /usr/local/Fabrikam/Modules 目录添加到 PSModulePath 环境变量的值,请键入:

$Env:PSModulePath += ":/usr/local/Fabrikam/Modules"

在 Linux 或 MacOS 上,命令中的冒号 (:) 将新路径与列表中前面的路径分开。

将路径添加到 PSModulePath 时, Get-Module 命令 Import-Module 将模块包含在该路径中。

你所设置的值仅影响当前会话。 若要持久更改,请将命令添加到 PowerShell 配置文件或使用 控制面板中的 System 更改注册表中 PSModulePath 环境变量的值。

此外,若要使更改持久化,还可以使用 System.Environment 类的 SetEnvironmentVariable 方法将路径添加到 PSModulePath 环境变量。

有关 PSModulePath 变量的详细信息,请参阅 about_Environment_Variables

模块和名称冲突

当会话中的多个命令具有相同的名称时,会发生名称冲突。 当模块中的命令与会话中的命令或项具有相同名称时,导入模块将引起名称冲突。

名称冲突可能会导致命令被隐藏或替换。

Hidden

当某个命令不是键入命令名称后所运行的命令时,该命令将隐藏,但你可以使用另一种方法来运行它,例如通过使用模块名称或创建它的管理单元的名称来限定命令名称。

已替换

当由于具有相同名称的命令已覆盖某个命令而无法运行该命令时,该命令即被替换。 即使删除导致冲突的模块,也无法运行替换的命令,除非重新启动该会话。

Import-Module 可以添加在当前会话中隐藏和替换命令的命令。 此外,你的会话中的命令可以隐藏模块所添加的命令。

若要检测名称冲突,请使用 cmdlet 的 All 参数 Get-Command 。 从 PowerShell 3.0 开始, Get-Command 仅获取键入命令名称时运行的命令。 All 参数获取会话中具有特定名称的所有命令。

若要防止名称冲突,请使用 cmdlet 的 Import-ModuleNoClobberPrefix 参数。 Prefix 参数向导入的命令的名称添加前缀,使其在会话中是唯一的。 NoClobber 参数不会导入任何命令,这些命令将隐藏或替换会话中的现有命令。

还可以使用 别名Cmdlet函数变量 参数 Import-Module 仅选择要导入的命令,并且可以排除导致会话中名称冲突的命令。

模块作者可以使用模块清单的 DefaultCommandPrefix 属性来阻止名称冲突,以便向所有命令名称添加默认前缀。 Prefix 参数的值优先于 DefaultCommandPrefix 的值。

即使命令处于隐藏状态,你也可以通过使用模块名称或创建该模块的管理单元名称来限定命令名称,从而运行该命令。

PowerShell 命令优先规则确定会话包含具有相同名称的命令时运行哪个命令。

例如,当会话包含具有相同名称的函数和 cmdlet 时,PowerShell 默认运行该函数。 当会话中包含同一类型的同名命令时(例如具有相同名称的两个 cmdlet),它将在默认情况下运行最新添加的命令。

有关详细信息,包括有关运行隐藏命令的优先规则和说明的说明,请参阅 about_Command_Precedence

模块和管理单元

可以从模块和管理单元将命令添加到会话。模块可以添加所有类型的命令,包括 cmdlet、提供程序和函数,以及变量、别名和 PowerShell 驱动器等项。 管理单元只可以添加 cmdlet 和提供程序。

在从会话中删除模块或管理单元之前,请使用以下命令来确定将删除哪些命令。

若要在会话中找到 cmdlet 的源,请使用以下命令格式:

Get-Command <cmdlet-name> | Format-List -Property verb,noun,pssnapin,module

例如,若要查找 cmdlet 的 Get-Date 源,请键入:

Get-Command Get-Date | Format-List -Property verb,noun,module

模块导出的命令应遵循 PowerShell 命令命名规则。 如果导入的模块在其名称中包含未批准的谓词的 cmdlet 或函数,该 Import-Module cmdlet 将显示以下警告消息。

警告:一些导入的命令名称包括未经批准的谓词,这可能使它们更易于发现。 请使用 Verbose 参数获取详细信息或者键入 Get-Verb 以查看批准的谓词列表。

此消息只是一个警告。 仍将导入完整的模块,其中包括非一致性的命令。 尽管会向模块用户显示消息,但是模块作者应修复命名问题。

若要禁止显示警告消息,请使用 cmdlet 的 Import-ModuleDisableNameChecking 参数。

内置模块和管理单元

在 PowerShell 2.0 和 PowerShell 3.0 及更高版本中的旧式主机程序中,随 PowerShell 一起安装的核心命令打包在自动添加到每个 PowerShell 会话的管理单元中。

从 PowerShell 3.0 开始,对于实现 InitialSessionState.CreateDefault2 初始会话状态 API 的主机程序,默认情况下会将 Microsoft.PowerShell.Core 管理单元添加到每个会话。 首次使用时,模块会自动加载。

备注

远程会话(包括使用 New-PSSession cmdlet 启动的会话)是旧式会话,其中内置命令打包在管理单元中。

以下模块 (或管理单元) 随 PowerShell 一起安装。

  • CimCmdlet
  • Microsoft.PowerShell.Archive
  • Microsoft.PowerShell.Core
  • Microsoft.PowerShell.Diagnostics
  • Microsoft.PowerShell.Host
  • Microsoft.PowerShell.Management
  • Microsoft.PowerShell.Security
  • Microsoft.PowerShell.Utility
  • Microsoft.WSMan.Management
  • PackageManagement
  • PowerShellGet
  • PSDesiredStateConfiguration
  • PSDiagnostics
  • PSReadline

日志记录模块事件

从 PowerShell 3.0 开始,可以通过将模块和管理单元的 LogPipelineExecutionDetails 属性设置为 $True,在 PowerShell 模块和管理单元中记录 cmdlet 和函数的执行事件。 还可以使用组策略设置“打开模块日志记录”在所有 PowerShell 会话中启用模块日志记录。 有关详细信息,请参阅日志记录和组策略文章。

另请参阅