powershellscripts.com

Tutorials  PowerShell Cmdlet Help for Import-PSSession



NAME
Import-PSSession

SYNOPSIS
Imports commands from another session into the current session.

SYNTAX
Import-PSSession [-Session] [[-CommandName] ] [[-FormatTypeName] ] [-AllowClobber]
[-ArgumentList ] [-CommandType {Alias | Function | Filter | Cmdlet | ExternalScript | Application | Scrip
t | All}] [-Module ] [-Prefix ] []


DESCRIPTION
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 can import any command that Get-Command can find in the PSSession.

Use an Import-PSSession command to import commands from a customized shell, such as a Microsoft Exchange Server she
ll, or from a session that includes Windows PowerShell modules and snap-ins or other elements that are not in the c
urrent 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-PSSession imports all commands except for commands that have the same n
ames 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, t
he imported part of the command runs implicitly in the session from which it was imported. However, the remote oper
ations are handled entirely by Windows PowerShell. You need not even be aware of them, except that you must keep th
e 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 m
ore 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 represents the module. To create a persistent module that you can use i
n 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 original session or in a similar session on the originating compu
ter.


PARAMETERS
-AllowClobber []
Imports the specified commands, even if they have the same names as commands in the current session.

If you import a command with the same name as a command in the current session, the imported command hides or r
eplaces the original commands. For more information, see about_Command_Precedence.

By default, Import-PSSession does not import commands that have the same name as commands in the current sessio
n.

Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false

-ArgumentList
Imports the variant of the command that results from using the specified arguments (parameter values).

For example, to import the variant of the Get-Item command in the certificate (Cert:) drive in the PSSession in
$s, type "import-pssession -session $s -command get-item -argumentlist cert:".

Required? false
Position? named
Default value All command in the PSSession, except for commands with the same names as commands
in the current session.
Accept pipeline input? false
Accept wildcard characters? false

-CommandName
Imports only the commands with the specified names or name patterns. Wildcards are permitted. Use "CommandName"
or its alias, "Name".

By default, Import-PSSession imports all commands from the session, except for commands that have the same name
s as commands in the current session. This prevents imported commands from hiding or replacing commands in the
session. To import all commands, even those that hide or replace other commands, use the AllowClobber parameter
.

If you use the CommandName parameter, the formatting files for the commands are not imported unless you use the
FormatTypeName parameter. Similarly, if you use the FormatTypeName parameter, no commands are imported unless
you use the CommandName parameter.

Required? false
Position? 3
Default value All commands in the PSSession, except for commands with the same names as commands
in the current session.
Accept pipeline input? false
Accept wildcard characters? true

-CommandType
Imports only the specified types of command objects. The default value is Cmdlet. Use "CommandType" or its alia
s, "Type".

Valid values are:
-- Alias: The Windows PowerShell aliases in the remote session.
-- All: The cmdlets and functions in the remote session.
-- Application: All the files other than Windows-PowerShell files in the paths that are listed in the Path envi
ronment variable ($env:path) in the remote session, including .txt, .exe, and .dll files.
-- Cmdlet: The cmdlets in the remote session. "Cmdlet" is the default.
-- ExternalScript: The .ps1 files in the paths listed in the Path environment variable ($env:path) in the remot
e session.
-- Filter and Function: The Windows PowerShell functions in the remote session.
-- Script: The script blocks in the remote session.

Required? false
Position? named
Default value All command in the PSSession, except for commands with the same names as commands
in the current session.
Accept pipeline input? false
Accept wildcard characters? false

-FormatTypeName
Imports formatting instructions for the specified Microsoft .NET Framework types. Enter the type names. Wildcar
ds are permitted.

The value of this parameter must be the name of a type that is returned by a Get-FormatData command in the sess
ion from which the commands are being imported. To get all of the formatting data in the remote session, type *
.

If the command does not include either the CommandName or FormatTypeName parameters, Import-PSSession
imports formatting instructions for all .NET Framework types returned by a Get-FormatData command in the remote
session.

If you use the FormatTypeName parameter, no commands are imported unless you use the CommandName parameter.
Similarly, if you use the CommandName parameter, the formatting files for the commands are not imported unless
you use the FormatTypeName parameter.

Required? false
Position? 4
Default value Types in the System.Management.Automation namespace
Accept pipeline input? false
Accept wildcard characters? true

-Module
Imports only the commands in the specified Windows PowerShell snap-ins and modules. Enter the snap-in and modul
e names. Wildcards are not permitted.

For more information, see about_PSSnapins and Import-Module.

Required? false
Position? named
Default value All command in the PSSession, except for commands with the same names as commands
in the current session.
Accept pipeline input? false
Accept wildcard characters? false

-Prefix
Adds the specified prefix to the nouns in the names of imported commands.

Use this parameter to avoid name conflicts that might occur when different commands in the session have the sam
e name.
For example, if you specify the prefix "Remote" and then import a Get-Date cmdlet, the cmdlet is known in the s
ession as Get-RemoteDate and it is not confused with the original Get-Date cmdlet.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Session
Specifies the PSSession from which the cmdlets are imported. Enter a variable that contains a session object or
a command that gets a session object, such as a New-PSSession or Get-PSSession command. You can specify only o
ne session. This parameter is required.

Required? true
Position? 1
Default value None
Accept pipeline input? false
Accept wildcard characters? false


This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".

INPUTS
None
You cannot pipe objects to this cmdlet.


OUTPUTS
System.Management.Automation.PSModuleInfo
Import-PSSession returns the same module object that New-Module and Get-Module return. However, the imported mo
dule is temporary and exists only in the current session. To create a permanent module on disk, use the Export-
PSSession cmdlet.


NOTES


Import-PSSession relies on the Windows PowerShell remoting infrastructure. To use this cmdlet, the computer mus
t be configured for WS-Management remoting. For more information, see about_Remote and about_Remote_Requirement
s.

You cannot use Import-PSSession to import variables or Windows PowerShell providers.

When you import commands that have the same names as commands in the current session, the imported commands can
hide aliases, functions, and cmdlets in the session and they can replace functions and variables in the sessio
n. For more information, see about_Command_Precedence.

Import-PSSession converts all commands into functions before it imports them. As a result, imported commands be
have a bit differently than they would if they retained their original command type. For example, if you import
a cmdlet from a PSSession and then import a cmdlet with the same name from a module or snap-in, the cmdlet tha
t is imported from the PSSession always runs by default because functions take precedence over cmdlets. Convers
ely, if you import an alias into a session that has an alias with the same name, the original alias is always u
sed, because aliases take precedence over functions. For more information, see about_Command_Precedence.

Import-PSSession uses the Write-Progress cmdlet to display the progress of the command. You might see the progr
ess bar while the command is running.

To find the commands to import, Import-PSSession uses the Invoke-Command cmdlet to run a Get-Command command in
the PSSession. To get formatting data for the commands, it uses the Get-FormatData cmdlet. You might see error
messages from Invoke-Command, Get-Command, and Get-FormatData when you run an Import-PSSession command. Also,
Import-PSSession cannot import commands from a PSSession that does not include the Get-Command, Get-FormatData,
Select-Object, and Get-Help cmdlets.

Imported commands have the same limitations as other remote commands, including the inability to start a progra
m with a user interface, such as Notepad.

Because Windows PowerShell profiles are not run in PSSessions, the commands that a profile adds to a session ar
e not available to Import-PSSession. To import commands from a profile, use an Invoke-Command command to run th
e profile in the PSSession manually before importing commands.

The temporary module that Import-PSSession creates might include a formatting file, even if the command does no
t import formatting data. If the command does not import formatting data, any formatting files that are created
will not contain formatting data.

To use Import-PSSession, the execution policy in the current session cannot be Restricted or AllSigned, because
the module that Import-PSSession creates contains unsigned script files that are prohibited by these policies.
To use Import-PSSession without changing the execution policy for the local computer, use the Scope parameter
of Set-ExecutionPolicy to set a less restrictive execution policy for a single process.


-------------------------- EXAMPLE 1 --------------------------

C:\PS>$s = new-pssession -computername Server01

C:\PS> import-pssession -session $s


Description
-----------
This command imports all commands from a PSSession on the Server01 computer into the current session, except for co
mmands 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 fo
r the imported commands.





-------------------------- EXAMPLE 2 --------------------------

C:\PS>$s = new-pssession https://ps.testlabs.com/powershell

C:\PS> import-pssession -session $s -commandname *-test -formatTypeName *

C:\PS> new-test -name test1

C:\PS> get-test test1 | run-test


Description
-----------
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 se
ssion. 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 actua
lly added to the current session, you use the local syntax to run them. You do not need to use the Invoke-Command c
mdlet to run an imported command.





-------------------------- EXAMPLE 3 --------------------------

C:\PS>$s1 = new-pssession -computername s1

C:\PS> $s2 = new-pssession -computername s2

C:\PS> import-pssession -session s1 -type cmdlet -name New-Test, Get-Test -FormatTypeName *

C:\PS> import-pssession -session s2 -type cmdlet -name Set-Test -FormatTypeName *

C:\PS> new-test Test1 | set-test -runtype full


Description
-----------
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 --------------------------

C:\PS>$s = new-pssession -computername Server01

C:\PS> import-pssession -session $s -commandname *-test* -formattypename *

C:\PS> $batch = new-test -name Batch -asjob

C:\PS> receive-job $batch


Description
-----------
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 you 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 sessi
on.

The third command uses the AsJob parameter of the imported New-Test cmdlet to run a New-Test command as a backgroun
d job. The command saves the job object that New-Test 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 --------------------------

C:\PS>$s = new-pssession -comp Server01

C:\PS> invoke-command -session $s {import-module TestManagement}

C:\PS> import-pssession -session $s -module TestManagement


Description
-----------
This example shows how to import the cmdlets and functions from a Windows PowerShell module on a remote computer in
to 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, b
ut 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 i
nto the current session.





-------------------------- EXAMPLE 6 --------------------------

C:\PS>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_79
468106-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 : {}


Description
-----------
This example shows that Import-PSSession creates a module in a temporary file on disk. It also shows that all comma
nds are converted into functions before they are imported 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 Pa
th property shows that Import-PSSession created a script module (.psm1) file in a temporary location. The ExportedF
unctions property shows that the Get-Date cmdlet and the SearchHelp function were both imported as functions.





-------------------------- EXAMPLE 7 --------------------------

C:\PS>import-pssession $s -CommandName Get-Date -formatTypeName * -AllowClobber

C:\PS> get-command get-date

CommandType Name Definition
----------- ---- ----------
Function Get-Date ...
Cmdlet Get-Date Get-Date [[-Date] ] [-Year ] [-Month ]

C:\PS> Get-Date
09074

C:\PS> (get-command -type cmdlet -name get-date).pssnapin.name
Microsoft.PowerShell.Utility

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

Sunday, March 15, 2009 2:08:26 PM


Description
-----------
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 incl
udes a Get-Date cmdlet, the AllowClobber parameter is required in the command.

The second command uses the Get-Command cmdlet to get the Get-Date commands in the current session. The output show
s that the session includes the original Get-Date cmdlet and a Get-Date function. The Get-Date function runs the im
ported 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 Julian date.

The fourth and fifth commands show how to use a qualified name to run a command that is hidden by an imported comma
nd.

The fourth command gets the name of the Windows PowerShell snap-in that added the original Get-Date cmdlet to the c
urrent 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 --------------------------

C:\PS>import-pssession -session $s -commandName *Item* -AllowClobber


Description
-----------
This command imports commands whose names include "Item" from the PSSession in $s. Because the command includes the
CommandName parameter but not the FormatTypeData parameter, 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 session.





-------------------------- EXAMPLE 9 --------------------------

C:\PS>$m = import-pssession -session $s -CommandName *bits* -formattypename *bits*

C:\PS> 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


Description
-----------
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 returns a temporary module, and the command saves the module in t
he $m variable.

The second command uses the Get-Command cmdlet to get the commands that are exported by the module in the $m variab
le.

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 method on the module object, which returns the module name.

The Get-Command command is the equivalent of "get-command $m.name".






RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=135221
about_Command_Precedence
New-PSSession
Export-PSSession
about_Jobs
about_PSSessions