Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

New-PSWorkflowSession

[This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]

Creates a workflow session.

Syntax

New-PSWorkflowSession [[-ComputerName] <string[]>] [-ApplicationName <string>] [-Authentication {<Default> | <Basic> | <Negotiate> | <NegotiateWithImplicitCredential> | <Credssp> | <Digest> | <Kerberos>}] [-CertificateThumbprint <string>] [-Credential <PSCredential>] [-Name <string[]>] [-Port <int>] [-SessionOption <PSSessionOption>] [-ThrottleLimit <int>] [-UseSSL] [<CommonParameters>]

New-PSWorkflowSession [[-Session] <PSSession[]>] [-Name <string[]>] [-ThrottleLimit <int>] [<CommonParameters>]

New-PSWorkflowSession [-ConnectionURI] <Uri[]> [-AllowRedirection] [-Authentication {<Default> | <Basic> | <Negotiate> | <NegotiateWithImplicitCredential> | <Credssp> | <Digest> | <Kerberos>}] [-CertificateThumbprint <string>] [-Credential <PSCredential>] [-Name <string[]>] [-SessionOption <PSSessionOption>] [-ThrottleLimit <int>] [<CommonParameters>]

Description

The New-PSWorkflowSession cmdlet creates a user-managed session ("PSSession") that is especially designed for running Windows PowerShell workflows. It uses the Microsoft.PowerShell.Workflow custom session configuration, which includes scripts, type and formatting files, and options that are required for workflows.

This cmdlet was introduced in Windows PowerShell 3.0.

Parameters

-AllowRedirection

Allows redirection of this connection to an alternate Uniform Resource Identifier (URI).

When you use the ConnectionURI parameter, the remote destination can return an instruction to redirect to a different URI. By default, Windows PowerShell does not redirect connections, but you can use the AllowRedirection parameter to allow it to redirect the connection.

You can also limit the number of times that the connection is redirected by setting the MaximumConnectionRedirectionCount property of the $PSSessionOption preference variable, or the MaximumConnectionRedirectionCount property of the value of the SessionOption parameter.

The default value is 5. For more information, see the description of the SessionOption parameter, and see New-PSSessionOption.

 

Required?

false

Position?

named

Default Value

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-ApplicationName <string>

Specifies the application name segment of the connection URI. Use this parameter to specify the application name when you are not using the ConnectionURI parameter in the command.

The default value is the value of the $PSSessionApplicationName preference variable on the local computer. If this preference variable is not defined, the default value is "WSMAN". This value is appropriate for most uses. For more information, see about_Preference_Variables.

The WinRM service uses the application name to select a listener to service the connection request. The value of this parameter should match the value of the URLPrefix property of a listener on the remote computer.

 

Required?

false

Position?

named

Default Value

WSMAN

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-Authentication <AuthenticationMechanism>

Specifies the mechanism that is used to authenticate the user's credentials. Valid values are "Default", "Basic", "Credssp", "Digest", "Kerberos", "Negotiate", and "NegotiateWithImplicitCredential". The default value is "Default".

CredSSP authentication is available only in Windows Vista, Windows Server 2008, and later versions of Windows.

For more information about the values of this parameter, see the description of the System.Management.Automation.Runspaces.AuthenticationMechanism enumeration in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkID=144382.

Caution: Credential Security Service Provider (CredSSP) authentication, in which the user's credentials are passed to a remote computer to be authenticated, is designed for commands that require authentication on more than one resource, such as accessing a remote network share. This mechanism increases the security risk of the remote operation. If the remote computer is compromised, the credentials that are passed to it can be used to control the network session.

 

Required?

false

Position?

named

Default Value

Default

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-CertificateThumbprint <string>

Specifies the digital public key certificate (X509) of a user account that has permission to perform this action. Enter the certificate thumbprint of the certificate.

Certificates are used in client certificate-based authentication. They can be mapped only to local user accounts; they do not work with domain accounts.

To get a certificate thumbprint, use the Get-Item or Get-ChildItem command in the Windows PowerShell Cert: drive.

 

Required?

false

Position?

named

Default Value

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-ComputerName <string[]>

Creates a persistent connection (PSSession) to the specified computer. If you enter multiple computer names, New-PSSession creates multiple PSSessions, one for each computer. The default is the local computer.

Type the NetBIOS name, an IP address, or a fully qualified domain name of one or more remote computers. To specify the local computer, type the computer name, "localhost", or a dot (.). When the computer is in a different domain than the user, the fully qualified domain name is required. You can also pipe a computer name (in quotes) to New-PSSession.

To use an IP address in the value of the ComputerName parameter, the command must include the Credential parameter. Also, the computer must be configured for HTTPS transport or the IP address of the remote computer must be included in the WinRM TrustedHosts list on the local computer. For instructions for adding a computer name to the TrustedHosts list, see "How to Add a Computer to the Trusted Host List" in about_Remote_Troubleshooting.

Note: In Windows Vista and later versions of Windows, to include the local computer in the value of the ComputerName parameter, you must start Windows PowerShell with the "Run as administrator" option.

 

Required?

false

Position?

1

Default Value

Accept Pipeline Input?

true (ByValue, ByPropertyName)

Accept Wildcard Characters?

false

-ConnectionURI <Uri[]>

Specifies a Uniform Resource Identifier (URI) that defines the connection endpoint for the interactive session. The URI must be fully qualified. The format of this string is as follows:

<Transport>://<ComputerName>:<Port>/<ApplicationName>

The default value is as follows:

http://localhost:5985/WSMAN

If you do not specify a ConnectionURI, you can use the UseSSL, ComputerName, Port, and ApplicationName parameters to specify the ConnectionURI values.

Valid values for the Transport segment of the URI are HTTP and HTTPS. If you specify a connection URI with a Transport segment, but do not specify a port, the session is created with standards ports: 80 for HTTP and 443 for HTTPS. To use the default ports for Windows PowerShell remoting, specify port 5985 for HTTP or 5986 for HTTPS.

If the destination computer redirects the connection to a different URI, Windows PowerShell prevents the redirection unless you use the AllowRedirection parameter in the command.

 

Required?

true

Position?

1

Default Value

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-Credential <PSCredential>

Specifies a user account that has permission to perform this action. The default is the current user.

Type a user name, such as "User01", "Domain01\User01", or "User@Domain.com", or enter a PSCredential object, such as one returned by the Get-Credential cmdlet.

When you type a user name, you will be prompted for a password.

 

Required?

false

Position?

named

Default Value

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-Name <string[]>

Specifies a friendly name for the workflow session.

You can use the name to refer to the session when using other cmdlets, such as Get-PSSession and Enter-PSSession. The name is not required to be unique to the computer or the current session.

 

Required?

false

Position?

named

Default Value

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Port <int>

Specifies the network port on the remote computer that is used for this connection. To connect to a remote computer, the remote computer must be listening on the port that the connection uses. The default ports are 5985 (the WinRM port for HTTP) and 5986 (the WinRM port for HTTPS).

Before using an alternate port, you must configure the WinRM listener on the remote computer to listen at that port. Use the following commands to configure the listener:

1. winrm delete winrm/config/listener?Address=*+Transport=HTTP

2. winrm create winrm/config/listener?Address=*+Transport=HTTP @{Port="<port-number>"}

Do not use the Port parameter unless you must. The port setting in the command applies to all computers or sessions on which the command runs. An alternate port setting might prevent the command from running on all computers.

 

Required?

false

Position?

named

Default Value

80

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Session <PSSession[]>

Uses the specified PSSession as a model for the new PSSession. This parameter creates new PSSessions with the same properties as the specified PSSessions.

Enter a variable that contains the PSSessions or a command that creates or gets the PSSessions, such as a New-PSSession or Get-PSSession command.

The resulting PSSessions have the same computer name, application name, connection URI, port, configuration name, throttle limit, and Secure Sockets Layer (SSL) value as the originals, but they have a different display name, ID, and instance ID (GUID).

 

Required?

false

Position?

1

Default Value

Accept Pipeline Input?

true (ByValue, ByPropertyName)

Accept Wildcard Characters?

false

-SessionOption <PSSessionOption>

Sets advanced options for the session. Enter a SessionOption object that you create by using the New-PSSessionOption cmdlet.

The default values for the options are determined by the value of the $PSSessionOption preference variable, if it is set. Otherwise, the default values are established by options set in the session configuration.

The session option values take precedence over default values for sessions set in the $PSSessionOption preference variable and in the session configuration. However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152).

For a description of the session options, including the default values, see New-PSSessionOption. For information about the $PSSessionOption preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248).

 

Required?

false

Position?

named

Default Value

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-ThrottleLimit <int>

Specifies the maximum number of concurrent connections that can be established to run this command. If you omit this parameter or enter a value of 0 (zero), the default value for the Microsoft.PowerShellWorkflow session configuration, 100, is used.

The throttle limit applies only to the current command, not to the session or to the computer.

 

Required?

false

Position?

named

Default Value

32

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-UseSSL

Uses the Secure Sockets Layer (SSL) protocol to establish a connection to the remote computer. By default, SSL is not used.

WS-Management encrypts all Windows PowerShell content transmitted over the network. UseSSL is an additional protection that sends the data across an HTTPS connection instead of an HTTP connection.

If you use this parameter, but SSL is not available on the port used for the command, the command fails.

 

Required?

false

Position?

named

Default Value

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

<CommonParameters>

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, -OutVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

Inputs and Outputs

The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet returns.

 

Inputs

System.Management.Automation.Runspaces.PSSession[], System.String

You can pipe a session or a computer name to New-PSWorkflowSession.

Outputs

System.Management.Automation.Runspaces.PSSession

Example 1

C:\PS>New-PSWorkflowSession -ComputerName ServerNode01 -Name WorkflowTests -SessionOption (New-PSSessionOption -OutputBufferingMode Drop)

Description
-----------
This command creates the WorkflowTests session on the ServerNode01 remote computer. The value of the SessionOption parameter is a New-PSSessionOption command that sets the output buffering mode in the session to Drop.







Example 2

C:\PS>"ServerNode01", "Server12" | New-PSWorkflowSession -Name WorkflowSession -Credential Domain01\Admin01 -ThrottleLimit 150

Description
-----------
This command creates workflow sessions on the ServerNode01 and Server12 computers. The command uses the Credential parameter to run with the permissions of the domain administrator.

The command uses the ThrottleLimit parameter to increase the per-command throttle limit to 150. This value takes precedence over the default throttle limit of 100 that is set in the Microsoft.PowerShell.Workflow session configuration.







See Also



Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

Show:
© 2014 Microsoft. All rights reserved.