Import-Module

项目
10/30/2009

向当前会话中添加模块。

语法

Import-Module [-Name] <string[]> [-Alias <string[]>] [-ArgumentList <Object[]>] [-AsCustomObject] [-Cmdlet <string[]>] [-Force] [-Function <string[]>] [-Global] [-PassThru] [-Prefix <string>] [-Variable <string[]>] [-Version <Version>] [<CommonParameters>]

Import-Module [-程序集] <Assembly[]> [-Alias <string[]>] [-ArgumentList <Object[]>] [-AsCustomObject] [-Cmdlet <string[]>] [-Force] [-Function <string[]>] [-Global] [-PassThru] [-Prefix <string>] [-Variable <string[]>] [-Version <Version>] [<CommonParameters>]

Import-Module [-ModuleInfo] <PSModuleInfo[]> [-Alias <string[]>] [-ArgumentList <Object[]>] [-AsCustomObject] [-Cmdlet <string[]>] [-Force] [-Function <string[]>] [-Global] [-PassThru] [-Prefix <string>] [-Variable <string[]>] [-Version <Version>] [<CommonParameters>]

说明

Import-Module cmdlet 将一个或多个模块添加到当前会话中。

模块就是一个程序包，可以包含可在 Windows PowerShell 中使用的成员（如 cmdlet、提供程序、脚本、函数、变量以及其他工具和文件）。导入模块后，即可在会话中使用模块成员。

要导入模块，请使用 Name、Assembly 或 ModuleInfo 参数来标识要导入的模块。默认情况下，Import-Module 导入模块所导出的所有成员，但您可以使用 Alias、Function、Cmdlet 和 Variable 参数限制导入的成员。

Import-Module 只将模块导入到当前会话中。要将模块导入到所有的会话，请将 Import-Module 命令添加到 Windows PowerShell 配置文件。有关配置文件的详细信息，请参阅 about_Profiles。

有关模块的详细信息，请参阅 about_Modules。

参数

-Alias <string[]>

仅将模块中的指定别名导入当前会话。输入以逗号分隔的别名列表。允许使用通配符。

在您导入某些模块时，这些模块会自动将选定的别名导出到您的会话中。该参数使您可以从导出的别名中进行选择。

是否为必需？	false
位置？	named
默认值
是否接受管道输入？	false
是否接受通配符？	true

-ArgumentList <Object[]>

指定在 Import-Module 命令期间传递给脚本模块的实际参数（形式参数的值）。只有在导入脚本模块时此参数才有效。

还可以使用 ArgumentList 的别名“args”来对其进行引用。有关详细信息，请参阅 about_Aliases。

是否为必需？	false
位置？	named
默认值
是否接受管道输入？	false
是否接受通配符？	false

-AsCustomObject

返回具有表示所导入模块成员的成员的自定义对象。该参数仅对脚本模块有效。

使用 AsCustomObject 参数时，Import-Module 将模块成员导入会话，然后返回一个 PSCustomObject 对象而不是 PSModuleInfo 对象。可以将自定义对象保存在变量中并使用点表示法来调用成员。

是否为必需？	false
位置？	named
默认值
是否接受管道输入？	false
是否接受通配符？	false

-程序集 <Assembly[]>

导入指定程序集对象中实现的 cmdlet 和提供程序。输入一个包含程序集对象的变量或创建程序集对象的命令。还可以通过管道将程序集对象传递给 Import-Module。

使用此参数时，仅导入由指定的程序集实现的 cmdlet 和提供程序。如果模块包含其他文件，将不会导入这些文件，您将因此而缺少模块的重要成员。在调试和测试模块时使用此参数，或者在模块作者的指导下使用此参数。

是否为必需？	true
位置？	1
默认值
是否接受管道输入？	true (ByValue)
是否接受通配符？	false

-Cmdlet <string[]>

仅将模块中的指定 cmdlet 导入当前会话。输入 cmdlet 列表。允许使用通配符。

在您导入某些模块时，这些模块会自动将选定的 cmdlet 导出到您的会话中。该参数使您可以从导出的 cmdlet 中进行选择。

是否为必需？	false
位置？	named
默认值
是否接受管道输入？	false
是否接受通配符？	true

-Force

重新导入模块及其成员，即使该模块或其成员的访问模式为只读也是如此。

是否为必需？	false
位置？	named
默认值	False
是否接受管道输入？	false
是否接受通配符？	false

-Function <string[]>

仅将模块中的指定函数导入当前会话。输入函数列表。允许使用通配符。

在您导入某些模块时，这些模块会自动将选定的函数导出到您的会话中。该参数使您可以从导出的函数中进行选择。

是否为必需？	false
位置？	named
默认值
是否接受管道输入？	false
是否接受通配符？	true

-Global

当在脚本模块 (.psm1) 中使用此参数时，该参数将模块导入全局会话状态。

此参数只有包含在脚本模块中时才有效。否则，将忽略该参数。

默认情况下，脚本模块中的命令（包括嵌套模块中的命令）将导入到调用方的会话状态。若要限制脚本模块导出的命令，请在该模块中使用 Export-ModuleMember 命令。

是否为必需？	false
位置？	named
默认值
是否接受管道输入？	false
是否接受通配符？	false

-ModuleInfo <PSModuleInfo[]>

指定要导入的模块对象。输入一个包含模块对象的变量或一个获取模块对象的命令（如“get-module -listavailable”命令）。还可以将模块对象通过管道传递给 Import-Module。

是否为必需？	true
位置？	1
默认值
是否接受管道输入？	true (ByValue)
是否接受通配符？	false

-Name <string[]>

指定要导入的模块的名称。输入模块的名称或模块中某个文件（例如 .psd1、.psm1、.dll 或 ps1 文件）的名称。文件路径是可选的。不允许使用通配符。还可以将模块名称和文件名通过管道传送到 Import-Module。

如果省略路径，Import-Module 将查找 PSModulePath 环境变量 ($env:PSModulePath) 中保存的路径中的模块。

请尽可能只指定模块名称。如果指定文件名，将仅导入在该文件中实现的成员。如果模块包含其他文件，将不会导入这些文件，您将因此而缺少模块的重要成员。

是否为必需？	true
位置？	1
默认值
是否接受管道输入？	true (ByValue)
是否接受通配符？	false

-PassThru

返回表示已导入的模块的对象。默认情况下，此 cmdlet 将不产生任何输出。

说明

-- 将“get-module -listavailable”命令的输出通过管道传递给带有 PassThru 参数的 Import-Module 命令时，Import-Module 返回 Get-Module 传递给它的对象，而不更新该对象。结果是，仍未填充 Exported 和 NestedModules 属性。

-- 使用 Prefix 参数来指定成员的前缀时，前缀并不显示在模块对象属性的成员名称中。该对象记录在应用前缀之前导出的内容。

是否为必需？	false
位置？	named
默认值
是否接受管道输入？	false
是否接受通配符？	false

-Prefix <string>

将指定前缀添加到所导入模块成员的名称中的名词中。

使用此参数可以避免当会话中的不同成员具有相同名称时可能发生的名称冲突。此参数不会更改模块，并且不会影响模块导入供自己使用的文件（称为“嵌套模块”），它仅影响当前会话中的成员的名称。

例如，如果指定前缀“UTC”，然后导入一个 Get-Date cmdlet，则该 cmdlet 在会话中称为 Get-UTCDate，因而不会与原始 Get-Date cmdlet 混淆。

是否为必需？	false
位置？	named
默认值
是否接受管道输入？	false
是否接受通配符？	false

-Variable <string[]>

仅将模块中的指定变量导入当前会话。输入变量列表。允许使用通配符。

在您导入某些模块时，这些模块会自动将选定的变量导出到您的会话中。该参数使您可以从导出的变量中进行选择。

是否为必需？	false
位置？	named
默认值
是否接受管道输入？	false
是否接受通配符？	true

-Version <Version>

指定要导入的模块的版本。当系统上有同一模块的不同版本时使用此参数。

是否为必需？	false
位置？	named
默认值
是否接受管道输入？	false
是否接受通配符？	false

<CommonParameters>

此 cmdlet 支持通用参数：-Verbose、-Debug、-ErrorAction、-ErrorVariable、-OutBuffer 和 -OutVariable。有关详细信息，请参阅 about_Commonparameters.

输入和输出

输入类型是指可通过管道传递给 cmdlet 的对象的类型。返回类型是指 Cmdlet 所返回对象的类型。

输入

System.String, System.Management.Automation.PSModuleInfo, System.Reflection.Assembly

可以通过管道将模块名称、模块对象或程序集对象传递给 Import-Module。

输出

“无”、System.Management.Automation.PSModuleInfo、或 System.Management.Automation.PSCustomObject

默认情况下，Import-Module 不产生任何输出。如果使用 PassThru 参数，则生成表示模块的 System.Management.Automation.PSModuleInfo 对象。如果使用 AsCustomObject 参数，则生成 PSCustomObject 对象。

说明

还可以使用别名“ipmo”来引用 Import-Module。有关详细信息，请参阅 about_Aliases。

导入模块前，必须将模块目录复制到可由本地计算机访问的某个目录中。有关详细信息，请参阅 about_Modules。

模块成员在自己的私有模块会话状态中运行，因此它们用于内部处理的命令不会影响您的会话状态。

如果将具有相同名称和相同类型的成员导入您的会话中，Windows PowerShell 默认情况下将使用最后导入的成员。将替换变量和别名，且原始元素将不可访问。函数、cmdlet 和提供程序只是被新成员“遮盖”，但可以通过用其管理单元、模块或函数路径的名称限定命令名称来进行访问。

若要更新已从模块中导入的命令的格式数据，请使用 Update-FormatData cmdlet。Update-FormatData 还将在会话中更新已从模块中导入的命令的格式数据。如果模块的格式设置文件发生更改，可以运行 Update-FormatData 命令以更新已导入命令的格式数据。无需重新导入模块。

若要导入 Import-PSSession 或 Export-PSSession 创建的模块，当前会话中的执行策略不能为 Restricted 或 AllSigned，因为 Import-PSSession 和 Export-PSSession 创建的模块包含这些策略禁止的未签名脚本文件。若要在不更改本地计算机的执行策略的情况下使用 Import-Module，请使用 Set-ExecutionPolicy 的 Scope 参数为单个进程设置限制性较弱的执行策略。

示例 1

C:\PS>import-module -name BitsTransfer

说明
-----------
此命令将 BitsTransfer 模块的成员导入当前会话中。

Name 参数名 (-Name) 是可选的，可以省略。

默认情况下，Import-Module 在导入模块时不生成任何输出。若要请求输出，可使用 PassThru 或 AsCustomObject 参数，或者 Verbose 通用参数。

示例 2

C:\PS>get-module -listAvailable | import-module

说明
-----------
此命令将 PSModulePath 环境变量 ($env:psmodulepath) 指定的路径中的所有可用模块导入当前会话中。

示例 3

C:\PS>$m = get-module -ListAvailable BitsTransfer, ServerBackup

C:\PS> import-module -moduleInfo $m

说明
-----------
这些命令将 BitsTransfer 和 ServerBackup 模块的成员导入当前会话中。

第一个命令使用 Get-Module cmdlet 获取表示 BitsTransfer 和 ServerBackup 模块的 PSModuleInfo 对象。它将对象保存在 $m 变量中。要获取尚未导入到会话的模块，需要使用 ListAvailable 参数。

第二个命令使用 Import-Module 的 ModuleInfo 参数将模块导入当前会话中。

这些命令等效于使用管道运算符 (|) 将 Get-Module 命令的输出发送到 Import-Module。

示例 4

C:\PS>import-module -name c:\ps-test\modules\test -verbose

VERBOSE: Loading module from path 'C:\ps-test\modules\Test\Test.psm1'.
VERBOSE: Exporting function 'my-parm'.
VERBOSE: Exporting function 'get-parm'.
VERBOSE: Exporting function 'get-spec'.
VERBOSE: Exporting function 'get-specDetails'.

说明
-----------
此命令使用显式路径来标识要导入的模块。

它还使用 Verbose 通用参数来获取从模块导入的项列表。如果不使用 Verbose、PassThru 或 AsCustomObject 参数，Import-Module 在导入模块时将不会产生任何输出。

示例 5

C:\PS>import-module BitsTransfer -cmdlet Add-BitsTransferFile, Get-BitsTransfer

C:\PS> get-module BitsTransfer

Name              : BitsTransfer
Path              : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\BitsTransfer\BitsTransfer.psd1
Description       :
Guid              : 8fa5064b-8479-4c5c-86ea-0d311fe48875
Version           : 1.0.0.0
ModuleBase        : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\BitsTransfer
ModuleType        : Manifest
PrivateData       :
AccessMode        : ReadWrite
ExportedAliases   : {}
ExportedCmdlets   : {[Add-BitsTransfer, Add-BitsTransfer], [Complete-BitsTransfer, Complete-BitsTransfer], [Get-BitsTransfer, Get-BitsTransfer], [Rem
                    ove-BitsTransfer, Remove-BitsTransfer]...}
ExportedFunctions : {}
ExportedVariables : {}
NestedModules     : {Microsoft.BackgroundIntelligentTransfer.Management}


C:\PS> get-command -module BitsTransfer

CommandType Name                Definition
----------- ----                ----------
Cmdlet      Add-BitsTransfer    Add-BitsTransfer [-BitsJob] <BitsJob[]> [-Source] <String[]> [[-Destination] <String[]>] [-Verbose] [-Debug] [-ErrorA...
Cmdlet      Get-BitsTransfer    Get-BitsTransfer [[-Name] <String[]>] [-AllUsers] [-Verbose] [-Debug] [-ErrorAction <ActionPreference>] [-WarningActi...

说明
-----------
此命令说明如何限制导入到会话的模块成员以及对会话使用此命令的效果。

第一条命令仅导入 BitsTransfer 模块中的 Add-BitsTransfer 和 Get-BitsTransfer cmdlet。该命令使用 Cmdlet 参数限制模块导入的 cmdlet。还可以使用 Alias、Variable 和 Function 参数限制模块导入的其他成员。

第二条命令使用 Get-Module cmdlet 获取表示 BitsTransfer 模块的对象。ExportedCmdlets 属性列出该模块导出的所有 cmdlet，即使它们并未全部导入也是如此。

第三条命令使用 Get-Command cmdlet 的 Module 参数获取已从 BitsTransfer 模块导入的命令。结果证实只导入了 Add-BitsTransfer 和 Get-BitsTransfer cmdlet。

示例 6

C:\PS>import-module BitsTransfer -prefix PS -passthru

Name              : bitstransfer
Path              : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\bitstransfer\bitstransfer.psd1
Description       :
Guid              : 8fa5064b-8479-4c5c-86ea-0d311fe48875
Version           : 1.0.0.0
ModuleBase        : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\bitstransfer
ModuleType        : Manifest
PrivateData       :
AccessMode        : ReadWrite
ExportedAliases   : {}
ExportedCmdlets   : {[Add-BitsTransfer, Add-BitsTransfer], [Remove-BitsTransfer, Remove-BitsTransfer], [Complete-BitsTransfer, Complete-BitsTransfer]
                    , [Get-BitsTransfer, Get-BitsTransfer]...}
ExportedFunctions : {}
ExportedVariables : {}
NestedModules     : {Microsoft.BackgroundIntelligentTransfer.Management}


C:\PS> get-command -module bitstransfer

CommandType     Name                        Definition
-----------     ----                        ----------
Cmdlet          Add-PSBitsTransfer          Add-PSBitsTransfer [-BitsJob] <BitsJob[]> [-Source] <String[]> ...
Cmdlet          Complete-PSBitsTransfer     Complete-PSBitsTransfer [-BitsJob] <BitsJob[]> [-Verbose] [-Deb...
Cmdlet          Get-PSBitsTransfer          Get-PSBitsTransfer [[-Name] <String[]>] [-AllUsers] [-Verbose] ...
Cmdlet          Remove-PSBitsTransfer       Remove-PSBitsTransfer [-BitsJob] <BitsJob[]> [-Verbose] [-Debug...
Cmdlet          Resume-PSBitsTransfer       Resume-PSBitsTransfer [-BitsJob] <BitsJob[]> [-Asynchronous] [-...
Cmdlet          Set-PSBitsTransfer          Set-PSBitsTransfer [-BitsJob] <BitsJob[]> [-DisplayName <String...
Cmdlet          Start-PSBitsTransfer        Start-PSBitsTransfer [[-Source] <String[]>] [[-Destination] <St...
Cmdlet          Suspend-PSBitsTransfer      Suspend-PSBitsTransfer [-BitsJob] <BitsJob[]> [-Verbose] [-Debu...

说明
-----------
这些命令将 BitsTransfer 模块导入当前会话中，向其中的成员名称添加前缀，然后显示带有前缀的成员名称。

第一条命令使用 Import-Module cmdlet 导入 BitsTransfer 模块。它使用 Prefix 参数向从模块导入的所有成员添加 PS 前缀，并使用 PassThru 参数返回表示所导入模块的模块对象。

该命令返回的模块对象具有一个 ExportedCmdlets 属性，该属性列出所导出的成员。该前缀不显示在 cmdlet 名称中，因为它是在成员导出之后（但在它们导入之前）应用的。

第二条命令使用 Get-Command cmdlet 获取已从模块导入的成员。它使用 Module 参数来指定模块。输出显示出这些模块成员已加上了正确的前缀。

所使用的前缀仅应用于当前会话中的成员。它不会更改模块。

示例 7

C:\PS>get-module -list | format-table -property name, moduletype -auto

Name          ModuleType
----          ----------
Show-Calendar     Script
BitsTransfer    Manifest
PSDiagnostics   Manifest
TestCmdlets       Script

C:\PS> $a = import-module -name Show-Calendar -asCustomObject

C:\PS> $a | get-member 


   TypeName: System.Management.Automation.PSCustomObject

Name          MemberType   Definition
----          ----------   ----------
Equals        Method       bool Equals(System.Object obj)
GetHashCode   Method       int GetHashCode()
GetType       Method       type GetType()
ToString      Method       string ToString()
Show-Calendar ScriptMethod System.Object Show-Calendar();

C:\PS> $a."show-calendar"()

说明
-----------
这些命令演示如何获取和使用 Import-Module 返回的自定义对象。

自定义对象包括表示每个导入的模块成员的合成成员。例如，模块中的 cmdlet 和函数转换为自定义对象的脚本方法。

自定义对象在脚本编写中非常有用。当若干导入的对象具有相同名称时，也可以使用自定义对象。使用对象的脚本方法等效于指定导入成员的完全限定名称（包括其模块名称）。

AsCustomObject 参数只能用于脚本模块，因此第一个任务是确定哪个可用模块是脚本模块。

第一个命令使用 Get-Module cmdlet 获取可用模块。此命令使用管道运算符 (|) 将模块对象传递到 Format-Table cmdlet，后者在一个表中列出每个模块的 Name 和 ModuleType。

第二个命令使用 Import-Module cmdlet 导入 Show-Calendar 脚本模块。此命令使用 AsCustomObject 参数请求自定义对象。此命令将生成的自定义对象保存在 $a 变量中。

第三个命令使用管道运算符将 $a 变量发送到 Get-Member cmdlet，后者获取 $a 中的 PSCustomObject 的属性和方法。输出显示一个 Show-Calendar 脚本方法。

最后一个命令使用 Show-Calendar 脚本方法。方法名称必须用引号括起，因为它包含一个连字符。

示例 8

C:\PS>import-module BitsTransfer

C:\PS> import-module BitsTransfer -force -prefix PS

说明
-----------
此示例说明如何使用 Import-Module 的 Force 参数将模块重新导入同一会话。

第一条命令导入 BitsTransfer 模块。第二条命令再次导入该模块，这一次使用的是 Prefix 参数。

第二条命令还包含 Force 参数，该参数将删除该模块然后重新导入它。如果不使用此参数，则会话包含的每个 BitsTransfer cmdlet 将有两个副本，其中一个使用标准名称，另一个使用带前缀的名称。

示例 9

C:\PS>get-date

Saturday, September 12, 2009 6:47:04 PM

C:\PS> import-module TestModule

C:\PS> get-date
09255

C:\PS> get-command get-date | format-table -property commandtype, name, pssnapin, module -auto

CommandType  Name       pssnapin                       Module
-----------  ----       --------                       ------
   Function  Get-Date                                  TestModule
     Cmdlet  Get-Date   Microsoft.PowerShell.Utility


C:\PS> Microsoft.PowerShell.Utility\get-date

Saturday, September 12, 2009 6:33:23 PM

说明
-----------
此示例说明如何运行已由导入的命令隐藏的命令。

第一条命令运行 Windows PowerShell 附带的 Get-Date cmdlet。它返回一个具有当前日期的 DateTime 对象。

第二条命令导入 TestModule 模块。此模块包含一个名为 Get-Date 的函数，该函数返回儒略历日期。

第三条命令重新运行 Get-Date 命令。因为函数优先于 cmdlet，所以运行的是 TestModule 模块中的 Get-Date 函数，而不是 Get-Date cmdlet。

第四条命令显示会话中有两个 Get-Date 命令：即 TestModule 模块中的函数和 Microsoft.PowerShell.Utility 管理单元中的 cmdlet。

第五条命令通过使用管理单元名称来限定命令名称，以便运行隐藏的 cmdlet。

有关 Windows PowerShell 中命令优先级的详细信息，请参阅 about_command_precedence。

另请参阅

概念

Get-Module
New-Module
Remove-Module
Export-ModuleMember
about_Modules

通过