Applies to: Exchange Server 2010 SP3, Exchange Server 2010 SP2

Topic Last Modified: 2012-11-19

Use the Test-PowerShellConnectivity cmdlet to test whether Windows PowerShell remoting on the target Client Access server is functioning correctly.

Syntax

Test-PowerShellConnectivity [-ClientAccessServer <ServerIdParameter>] [-Authentication <Default | Basic | Negotiate | NegotiateWithImplicitCredential | Credssp | Digest | Kerberos>] [-Confirm [<SwitchParameter>]] [-DomainController <Fqdn>] [-MailboxServer <ServerIdParameter>] [-MonitoringContext <SwitchParameter>] [-ResetTestAccountCredentials <SwitchParameter>] [-TestType <Internal | External>] [-TrustAnySSLCertificate <SwitchParameter>] [-VirtualDirectoryName <String>] [-WhatIf [<SwitchParameter>]]
Test-PowerShellConnectivity -ConnectionUri <Uri> -TestCredential <PSCredential> [-Authentication <Default | Basic | Negotiate | NegotiateWithImplicitCredential | Credssp | Digest | Kerberos>] [-Confirm [<SwitchParameter>]] [-DomainController <Fqdn>] [-MailboxServer <ServerIdParameter>] [-MonitoringContext <SwitchParameter>] [-ResetTestAccountCredentials <SwitchParameter>] [-TrustAnySSLCertificate <SwitchParameter>] [-WhatIf [<SwitchParameter>]]

Detailed Description

The Test-PowerShellConnectivity cmdlet enables you to connect to a Client Access server to test whether Windows PowerShell remoting on that server is working correctly and whether the Client Access server can perform commands against a remote Mailbox server.

When you run the Test-PowerShellConnectivity cmdlet, you must specify either the fully qualified domain name (FQDN) of the Client Access server to connect to by using the ClientAccessServer parameter, or the Uniform Resource Identifier (URI) of a Client Access server by using the ConnectionUri parameter. You can't use both the ClientAccessServer and ConnectionUri parameters in the same command.

The first time you use the Test-PowerShellConnectivity cmdlet with the ClientAccessServer parameter, you might be required to create a new test user. To create a new test user, use the New-TestCasConnectivityUser.ps1 script.

You need to be assigned permissions before you can run this cmdlet. Although all parameters for this cmdlet are listed in this topic, you may not have access to some parameters if they're not included in the permissions assigned to you. To see what permissions you need, see the "PowerShell virtual directories" entry in the Exchange and Shell Infrastructure Permissions topic.

Parameters

Parameter Required Type Description

ConnectionUri

Required

System.Uri

The ConnectionUri parameter specifies the URI of the Client Access server to test, for example, https://contoso.com/powershell. If the ClientAccessServer parameter is specified, you can't use the ConnectionUri parameter.

TestCredential

Required

System.Management.Automation.PSCredential

The TestCredential parameter specifies the credentials to use when connecting to the Client Access server. This parameter can only be used when the ConnectionUri parameter is specified.

This parameter requires the creation and passing of a credential object. This credential object is created by using the Get-Credential cmdlet. For more information, see Get-Credential.

Authentication

Optional

System.Management.Automation.Runspaces.AuthenticationMechanism

The Authentication parameter specifies the type of authentication to use when establishing a connection. You can use one of the following values:

  • Default

  • Basic

  • Negotiate

  • NegotiateWithImplicitCredential

  • Credssp

  • Digest

  • Kerberos

ClientAccessServer

Optional

Microsoft.Exchange.Configuration.Tasks.ServerIdParameter

The ClientAccessServer parameter specifies the name of the Client Access server to test. If the ConnectionUri parameter is specified, you can't use the ClientAccessServer parameter.

Confirm

Optional

System.Management.Automation.SwitchParameter

The Confirm switch causes the command to pause processing and requires you to acknowledge what the command will do before processing continues. You don't have to specify a value with the Confirm switch.

DomainController

Optional

Microsoft.Exchange.Data.Fqdn

The DomainController parameter specifies the fully qualified domain name (FQDN) of the domain controller that retrieves data from Active Directory.

MailboxServer

Optional

Microsoft.Exchange.Configuration.Tasks.ServerIdParameter

The MailboxServer parameter specifies the name of the Mailbox server to test. If not specified, all Mailbox servers in the local Active Directory site are tested.

MonitoringContext

Optional

System.Management.Automation.SwitchParameter

The MonitoringContext switch specifies whether the command is run by Microsoft System Center Operations Manager 2007. Running the command with this parameter without System Center Operations Manager 2007 causes the command to fail. If this parameter is excluded, you must run the task interactively.

ResetTestAccountCredentials

Optional

System.Management.Automation.SwitchParameter

The ResetTestAccountCredentials parameter resets the test account credentials to use with this command.

TestType

Optional

Microsoft.Exchange.Monitoring.OwaConnectivityTestType

The TestType parameter specifies whether the command should test the internal or external URL of a virtual directory. This parameter can only be used with the ClientAccessServer parameter. The valid values are Internal and External. The default in Internal.

TrustAnySSLCertificate

Optional

System.Management.Automation.SwitchParameter

The TrustAnySSLCertificate parameter specifies whether Secure Sockets Layer (SSL) certificate validation failures are reported. This parameter instructs the command to check Windows PowerShell connectivity without generating an error when the certificate doesn't match the URL of the Client Access server.

VirtualDirectoryName

Optional

System.String

The VirtualDirectoryName parameter specifies the virtual directory on the Client Access server to test. The VirutalDirectoryName parameter can only be used with the ClientAccessServer parameter. If the VirutalDirectoryName parameter isn't specified, all virtual directories on the Client Access server are tested.

WhatIf

Optional

System.Management.Automation.SwitchParameter

The WhatIf switch instructs the command to simulate the actions that it would take on the object. By using the WhatIf switch, you can view what changes would occur without having to apply any of those changes. You don't have to specify a value with the WhatIf switch.

Input Types

To see the input types that this cmdlet accepts, see Cmdlet Input and Output Types. If the Input Type field for a cmdlet is blank, the cmdlet doesn’t accept input data.

Return Types

To see the return types, which are also known as output types, that this cmdlet accepts, see Cmdlet Input and Output Types. If the Output Type field is blank, the cmdlet doesn’t return data.

Examples

EXAMPLE 1

This example tests the PowerShell (Default Web Site) virtual directory on the CAS2 server. The TrustAnySSLCertificate switch is used to skip the certificate check during connection. You might need to use the New-TestCasConnectivityUser.ps1 script to create a test user that the command can use to test the Windows PowerShell virtual directory.

Copy Code
Test-PowerShellConnectivity -ClientAccessServer CAS2 -VirtualDirectoryName "PowerShell (Default Web Site)" -TrustAnySSLCertificate

EXAMPLE 2

This example tests the remote Windows PowerShell virtual directory at the URI https://contoso.com/powershell. Because the SSL certificate should be valid, the TrustAnySSLCertificate switch isn't used. The remote server uses Basic authentication so the Authentication parameter is used with a value of Basic.

Before running the test, the credentials to be used to connect to the remote Windows PowerShell virtual directory need to be retrieved. The following command retrieves the credentials from the person running the test using the Get-Credential cmdlet and stores them in the $UserCredentials variable.

Copy Code
$UserCredentials = Get-Credential

The test is then run using the Test-PowerShellConnectivity cmdlet with the options previously described.

Copy Code
Test-PowerShellConnectivity -ConnectionUri https://contoso.com/powershell -TestCredential $UserCredentials -Authentication Basic