通过

about_Modules

  • 项目

简短说明

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

长说明

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

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

本主题说明如何使用 PowerShell 模块。 有关如何编写 PowerShell 模块的信息，请参阅 编写 PowerShell 模块。

什么是模块？

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

模块自动加载

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

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

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

  • 运行命令

    Get-CimInstance Win32_OperatingSystem

  • 获取命令

    Get-Command Get-CimInstance

  • 获取命令的帮助

    Get-Help Get-CimInstance

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

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

此外，使用 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 复制到 Modules 目录，请键入：

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-Help 和 Update-Help。

如何导入模块

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

还可以选择导入模块，以便可以使用命令的参数 Import-Module ，例如 Prefix 参数（向所有导入的命令的名词名称添加一个独特的前缀）或 NoClobber 参数，这会阻止模块添加隐藏或替换会话中的现有命令的命令。

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

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

Import-Module <module-name>

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

Import-Module BitsTransfer

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

例如，若要将目录中的 TestCmdlets 模块 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 时Import-Module，Get-Module命令将模块包含在该路径中。

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

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

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

模块和名称冲突

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

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

Hidden

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

已替换

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

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

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

若要防止名称冲突，请使用 cmdlet 的 Import-ModuleNoClobber 或 Prefix 参数。 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 会话中启用模块日志记录。 有关详细信息，请参阅日志记录和组策略文章。

另请参阅