关于模块

2019-09-09

简短说明

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

详细描述

模块是包含 PowerShell 命令（如 cmdlet、提供程序、函数、工作流、变量和别名）的包。

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

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

什么是模块？

模块是一组命令。会话中的所有 cmdlet 和提供程序都是由模块或管理单元添加的。

模块自动加载

从 PowerShell 3.0 开始，当您首次在已安装的模块中运行任何命令时，PowerShell 会自动导入模块。现在，您可以在模块中使用这些命令，而无需进行任何设置或配置文件配置，因此在将模块安装到计算机上后，无需管理模块。

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

以下每个示例都会导致 module contains Get-Mailbox 导入到您的会话中。

运行命令
```
Get-Mailbox -Identity Chris
```
获取命令
```
Get-Command Get-Mailbox
```
获取命令的帮助
```
Get-Help Get-Mailbox
```

Get-Command 包含通配符（*）的命令被视为用于发现，而不是使用，并且不会导入任何模块。

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

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

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

如何使用模块

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

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

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

如何安装模块

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

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

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

New-Item -Type Directory -Path $HOME\Documents\WindowsPowerShell\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\WindowsPowerShell\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

以下是 PowerShell 模块的默认位置。从 PowerShell 4.0 开始，随着 DSC 的引入，引入了新的默认模块和 DSC 资源文件夹。有关 DSC 的更多信息，请参阅 about_DesiredStateConfiguration。

系统： $PSHOME\Modules 或（）$env:windir\System32\WindowsPowerShell\v1.0\Modules系统模块是 Windows 和 PowerShell 附带的模块。

从 PowerShell 4.0 开始，引入 PowerShell Desired State Configuration （DSC）时，PowerShell 附带的 DSC 资源也存储在 $PSHOME\Modules文件夹中的 $PSHOME\Modules\PSDesiredStateConfiguration\DSCResources 中。
当前用户： $HOME\Documents\WindowsPowerShell\Modules （$env:UserProfile\Documents\WindowsPowerShell\Modules）

或

$HOME\My Documents\WindowsPowerShell\Modules（$env:UserProfile\My Documents\WindowsPowerShell\Modules）

这是 PowerShell 4.0 之前用户添加的模块的位置。

在 PowerShell 4.0 及更高版本的 PowerShell 中，用户添加的模块和 DSC 资源存储在 C:\Program Files\WindowsPowerShell\Modules中。计算机的所有用户都可以访问此位置的模块和 DSC 资源。之所以需要进行此更改，是因为 DSC 引擎作为本地系统运行，并且无法访问特定于用户的路径，例如 $home\Documents\WindowsPowerShell\Modules.

从 PowerShell 5.0 开始，随着 PowerShellGet 模块的添加，以及社区和 Microsoft 创建的资源的 PowerShell 库，该 Install-Module 命令默认将模块和 DSC 资源 C:\Program Files\WindowsPowerShell\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"

当您向 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 管理单元的更多信息，请参阅 about_PSSnapins。

模块导出的命令应遵循 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 一起安装。

Microsoft.PowerShell.存档
Microsoft.PowerShell.Core
Microsoft.PowerShell.Diagnostics
Microsoft.PowerShell.Host
Microsoft.PowerShell.Management
Microsoft.PowerShell.ODataUtils
Microsoft.PowerShell.Security
Microsoft.PowerShell.Utility
Microsoft.WSMan.Management
包管理
PowerShellGet
PSDesiredStateConfiguration
PSReadline
PSScheduledJob
PSWorkflow
PSWorkflowUtility
易视

日志记录模块事件

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