This is the built-in help made by Microsoft for the command 'Import-PSSession', in PowerShell version 4 - as retrieved from
Windows version 'Microsoft Windows 8.1 Enterprise' PowerShell help files on 2016-06-23.
For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.
Imports commands from another session into the current session.
Import-PSSession [-Session] <PSSession> [[-CommandName] <String[]>] [[-FormatTypeName] <String[]>] [-AllowClobber] [-ArgumentList <Object[]>] [-Certificate <X509Certi
ficate2>] [-CommandType <CommandTypes>] [-DisableNameChecking] [-Module <String[]>] [-Prefix <String>] [<CommonParameters>]
The Import-PSSession cmdlet imports commands (such as cmdlets, functions, and aliases) from a PSSession on a local or remote computer into the current session. You ca
n import any command that the Get-Command cmdlet can find in the PSSession.
Use an Import-PSSession command to import commands from a customized shell, such as a Microsoft Exchange Server shell, or from a session that includes Windows PowerSh
ell modules and snap-ins or other elements that are not in the current session.
To import commands, first use the New-PSSession cmdlet to create a PSSession. Then, use the Import-PSSession cmdlet to import the commands. By default, Import-PSSessi
on imports all commands except for commands that have the same names as commands in the current session. To import all the commands, use the AllowClobber parameter.
You can use imported commands just as you would use any command in the session. When you use an imported command, the imported part of the command runs implicitly in
the session from which it was imported. However, the remote operations are handled entirely by Windows PowerShell. You need not even be aware of them, except that you
must keep the connection to the other session (PSSession) open. If you close it, the imported commands are no longer available.
Because imported commands might take longer to run than local commands, Import-PSSession adds an AsJob parameter to every imported command. This parameter allows you
to run the command as a Windows PowerShell background job. For more information, see about_Jobs.
When you use Import-PSSession, Windows PowerShell adds the imported commands to a temporary module that exists only in your session and returns an object that represe
nts the module. To create a persistent module that you can use in future sessions, use the Export-PSSession cmdlet.
The Import-PSSession cmdlet uses the implicit remoting feature of Windows PowerShell. When you import commands into the current session, they run implicitly in the or
iginal session or in a similar session on the originating computer.
Beginning in Windows PowerShell 3.0, you can use the Import-Module cmdlet to import modules from a remote session into the current session. This feature uses implicit
remoting. It is equivalent to using Import-PSSession to import selected modules from a remote session into the current session.
<
Online Version: http://go.microsoft.com/fwlink/p/?linkid=293985
Export-PSSession
New-PSSession
about_Command_Precedence
about_PSSessions
about_Jobs
<
-------------------------- EXAMPLE 1 --------------------------
PS C:\>$s = New-PSSession -ComputerName Server01
PS C:\>Import-PSSession -Session $s
This command imports all commands from a PSSession on the Server01 computer into the current session, except for commands that have the same names as commands in the
current session.
Because this command does not use the CommandName parameter, it also imports all of the formatting data required for the imported commands.
-------------------------- EXAMPLE 2 --------------------------
PS C:\>$s = New-PSSession https://ps.testlabs.com/powershell
PS C:\>Import-PSSession -Session $s -CommandName *-test -FormatTypeName *
PS C:\>New-Test -Name Test1
PS C:\>Get-Test test1 | Run-Test
These commands import the commands with names that end in "-test" from a PSSession into the local session, and then they show how to use an imported cmdlet.
The first command uses the New-PSSession cmdlet to create a PSSession. It saves the PSSession in the $s variable.
The second command uses the Import-PSSession cmdlet to import commands from the PSSession in $s into the current session. It uses the CommandName parameter to specify
commands with the Test noun and the FormatTypeName parameter to import the formatting data for the Test commands.
The third and fourth commands use the imported commands in the current session. Because imported commands are actually added to the current session, you use the local
syntax to run them. You do not need to use the Invoke-Command cmdlet to run an imported command.
-------------------------- EXAMPLE 3 --------------------------
PS C:\>$s1 = New-PSSession -ComputerName s1
PS C:\>$s2 = New-PSSession -ComputerName s2
PS C:\>Import-PSSession -Session s1 -Type cmdlet -Name New-Test, Get-Test -FormatTypeName *
PS C:\>Import-PSSession -Session s2 -Type Cmdlet -Name Set-Test -FormatTypeName *
PS C:\>New-Test Test1 | Set-Test -RunType Full
This example shows that you can use imported cmdlets just as you would use local cmdlets.
These commands import the New-Test and Get-Test cmdlets from a PSSession on the Server01 computer and the Set-Test cmdlet from a PSSession on the Server02 computer.
Even though the cmdlets were imported from different PSSessions, you can pipe an object from one cmdlet to another without error.
-------------------------- EXAMPLE 4 --------------------------
PS C:\>$s = New-PSSession -ComputerName Server01
PS C:\>Import-PSSession -Session $s -CommandName *-test* -FormatTypeName *
PS C:\>$batch = New-Test -Name Batch -AsJob
PS C:\>Receive-Job $batch
This example shows how to run an imported command as a background job.
Because imported commands might take longer to run than local commands, Import-PSSession adds an AsJob parameter to every imported command. The AsJob parameter lets y
ou run the command as a background job.
The first command creates a PSSession on the Server01 computer and saves the PSSession object in the $s variable.
The second command uses Import-PSSession to import the Test cmdlets from the PSSession in $s into the current session.
The third command uses the AsJob parameter of the imported New-Test cmdlet to run a New-Test command as a background job. The command saves the job object that New-Te
st returns in the $batch variable.
The fourth command uses the Receive-Job cmdlet to get the results of the job in the $batch variable.
-------------------------- EXAMPLE 5 --------------------------
PS C:\>$s = New-PSSession -ComputerName Server01
PS C:\>Invoke-Command -Session $s {Import-Module TestManagement}
PS C:\>Import-PSSession -Session $s -Module TestManagement
This example shows how to import the cmdlets and functions from a Windows PowerShell module on a remote computer into the current session.
The first command creates a PSSession on the Server01 computer and saves it in the $s variable.
The second command uses the Invoke-Command cmdlet to run an Import-Module command in the PSSession in $s.
Typically, the module would be added to all sessions by an Import-Module command in a Windows PowerShell profile, but profiles are not run in PSSessions.
The third command uses the Module parameter of Import-PSSession to import the cmdlets and functions in the module into the current session.
-------------------------- EXAMPLE 6 --------------------------
PS C:\>Import-PSSession $s -CommandName Get-Date, SearchHelp -FormatTypeName * -AllowClobber
Name : tmp_79468106-4e1d-4d90-af97-1154f9317239_tcw1zunz.ttf
Path : C:\Users\User01\AppData\Local\Temp\tmp_79468106-4e1d-4d90-af97-1154f9317239_tcw1zunz.ttf\tmp_79468106-4e1d-4d90-af97-1154f9317239_
tcw1zunz.ttf.psm1
Description : Implicit remoting for http://server01.corp.fabrikam.com/wsman
Guid : 79468106-4e1d-4d90-af97-1154f9317239
Version : 1.0
ModuleBase : C:\Users\User01\AppData\Local\Temp\tmp_79468106-4e1d-4d90-af97-1154f9317239_tcw1zunz.ttf
ModuleType : Script
PrivateData : {ImplicitRemoting}
AccessMode : ReadWrite
ExportedAliases : {}
ExportedCmdlets : {}
ExportedFunctions : {[Get-Date, Get-Date], [SearchHelp, SearchHelp]}
ExportedVariables : {}
NestedModules : {}
This example shows that Import-PSSession creates a module in a temporary file on disk. It also shows that all commands are converted into functions before they are im
ported into the current session.
The command uses the Import-PSSession cmdlet to import a Get-Date cmdlet and a SearchHelp function into the current session.
The Import-PSSession cmdlet returns a PSModuleInfo object that represents the temporary module. The value of the Path property shows that Import-PSSession created a s
cript module (.psm1) file in a temporary location. The ExportedFunctions property shows that the Get-Date cmdlet and the SearchHelp function were both imported as fun
ctions.
-------------------------- EXAMPLE 7 --------------------------
PS C:\>Import-PSSession $s -CommandName Get-Date -FormatTypeName * -AllowClobber
PS C:\>Get-Command Get-Date -All
CommandType Name Definition
----------- ---- ----------
Function Get-Date ...
Cmdlet Get-Date Get-Date [[-Date] <DateTime>] [-Year <Int32>] [-Month <Int32>]
PS C:\>Get-Date
09074
PS C:\>(Get-Command -Type Cmdlet -Name Get-Date).PSSnapin.Name
Microsoft.PowerShell.Utility
PS C:\>Microsoft.PowerShell.Utility\Get-Date
Sunday, March 15, 2009 2:08:26 PM
This example shows how to run a command that is hidden by an imported command.
The first command imports a Get-Date cmdlet from the PSSession in the $s variable. Because the current session includes a Get-Date cmdlet, the AllowClobber parameter
is required in the command.
The second command uses the All parameter of the Get-Command cmdlet to get all Get-Date commands in the current session. The output shows that the session includes th
e original Get-Date cmdlet and a Get-Date function. The Get-Date function runs the imported Get-Date cmdlet in the PSSession in $s.
The third command runs a Get-Date command. Because functions take precedence over cmdlets, Windows PowerShell runs the imported Get-Date function, which returns a Jul
ian date.
The fourth and fifth commands show how to use a qualified name to run a command that is hidden by an imported command.
The fourth command gets the name of the Windows PowerShell snap-in that added the original Get-Date cmdlet to the current session.
The fifth command uses the snap-in-qualified name of the Get-Date cmdlet to run a Get-Date command.
For more information about command precedence and hidden commands, see about_Command_Precedence.
-------------------------- EXAMPLE 8 --------------------------
PS C:\>Import-PSSession -Session $s -CommandName *Item* -AllowClobber
This command imports commands whose names include "Item" from the PSSession in $s. Because the command includes the CommandName parameter but not the FormatTypeData p
arameter, only the command is imported.
Use this command when you are using Import-PSSession to run a command on a remote computer and you already have the formatting data for the command in the current ses
sion.
-------------------------- EXAMPLE 9 --------------------------
PS C:\>$m = Import-PSSession -Session $s -CommandName *bits* -FormatTypeName *bits*
PS C:\>Get-Command -Module $m
CommandType Name
----------- ----
Function Add-BitsFile
Function Complete-BitsTransfer
Function Get-BitsTransfer
Function Remove-BitsTransfer
Function Resume-BitsTransfer
Function Set-BitsTransfer
Function Start-BitsTransfer
Function Suspend-BitsTransfer
This command shows how to use the Module parameter of Get-Command to find out which commands were imported into the session by an Import-PSSession command.
The first command uses the Import-PSSession cmdlet to import commands whose names include "bits" from the PSSession in the $s variable. The Import-PSSession command r
eturns a temporary module, and the command saves the module in the $m variable.
The second command uses the Get-Command cmdlet to get the commands that are exported by the module in the $m variable.
The Module parameter takes a string value, which is designed for the module name. However, when you submit a module object, Windows PowerShell uses the ToString metho
d on the module object, which returns the module name.
The Get-Command command is the equivalent of Get-Command $m.Name".