通过

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 环境变量指定位置的模块才会自动导入。 必须通过运行 Import-Module cmdlet 导入其他位置的模块。

此外，使用 PowerShell 提供程序的命令不会自动导入模块。 例如，如果使用需要 WSMan： 驱动器的命令（如 Get-PSSessionConfiguration cmdlet），则可能需要运行 Import-Module cmdlet 以导入包含该驱动器的 WSMan: 模块。

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

如何使用模块

要使用模块，请执行以下任务：

  1. 安装模块。 （这通常是为您完成的。
  2. 找到模块添加的命令。
  3. 使用模块添加的命令。

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

如何安装模块

如果您以文件夹的形式接收模块，其中包含文件，则需要先将其安装在您的计算机上，然后才能在 PowerShell 中使用它。

大多数模块都是为您安装的。 PowerShell 附带了几个预安装的模块，有时称为 核心 模块。 在基于 Windows 的计算机上，如果作系统附带的功能具有用于管理这些功能的 cmdlet，则会预安装这些模块。 安装 Windows 功能时，例如，通过使用服务器管理器中的“添加角色和功能向导”或“控制面板”中的“打开或关闭 Windows 功能”对话框，将安装属于该功能的任何 PowerShell 模块。 许多其他模块都来自安装模块的安装程序或 Setup 程序。

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

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

将整个 module 文件夹复制到 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

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

如何在模块中查找命令

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

若要查找模块中的所有命令，请键入：

Get-Command -Module <module-name>

例如，要在 BitsTransfer 模块中查找命令，请键入：

Get-Command -Module BitsTransfer

有关 Get-Command cmdlet 的详细信息，请参阅 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

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

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

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 位于用户配置文件中 Documents 位置的文件夹。 该位置的具体路径因 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 配置文件，或使用控制面板中的系统更改注册表中 PSModulePath 环境变量的值。

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

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

模块和名称冲突

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

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

隐藏

如果命令不是键入命令名称时运行的命令，则该命令处于隐藏状态，但您可以使用其他方法运行该命令，例如，使用命令名称所在的模块或管理单元的名称限定命令名称。

已替换

如果命令因被同名命令覆盖而无法运行，则会替换该命令。 即使删除导致冲突的模块，也无法运行替换的命令，除非重新启动会话。

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

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

若要防止名称冲突，请使用 cmdlet 的 NoClobber 或 Import-Module 参数。 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

例如，若要查找 Get-Date cmdlet 的源，请键入：

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

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

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

此消息只是警告。 仍导入完整的模块，包括不符合的命令。 尽管消息显示给模块用户，但模块作者应修复命名问题。

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

内置模块和管理单元

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

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

注释

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

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

  • CimCmdlets
  • Microsoft.PowerShell.存档
  • Microsoft.PowerShell.Core
  • Microsoft.PowerShell.Diagnostics
  • Microsoft.PowerShell.Host
  • Microsoft.PowerShell.Management
  • Microsoft.PowerShell.Security
  • Microsoft.PowerShell.Utility
  • Microsoft.WSMan.Management
  • 包管理
  • PowerShellGet
  • PSDesiredStateConfiguration
  • PS 诊断
  • PSReadline

日志记录模块事件

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

另请参阅