Test-CsLocationPolicy

Test-CsLocationPolicy
    [-TargetFqdn] <String>
    [-RegistrarPort <Int32>]
    [-Subnet <String>]
    [-UserSipAddress <String>]
    [-Force]
    [-OutVerboseVariable <String>]
    [-Authentication <AuthenticationMechanism>]
    [-OutLoggerVariable <String>]
    [<CommonParameters>]

Test-CsLocationPolicy
    [[-TargetFqdn] <String>]
    -UserCredential <PSCredential>
    -UserSipAddress <String>
    [-RegistrarPort <Int32>]
    [-Subnet <String>]
    [-Force]
    [-OutVerboseVariable <String>]
    [-Authentication <AuthenticationMechanism>]
    [-OutLoggerVariable <String>]
    [<CommonParameters>]

The location policy is used to apply settings that relate to E9-1-1 functionality and client location. The location policy determines whether a user is enabled for E9-1-1, and if so what the behavior is of an emergency call. For example, you can use the location policy to define what number constitutes an emergency call (911 in the United States), whether corporate security should be automatically notified, and how the call should be routed. This cmdlet returns information about the location policy that will be used when calls are made from a particular client on a specific pool, subnet, switch, or wireless access point.

If a user is not specified in the call to this cmdlet, the currently configured user will be tested. To find the currently configured user, call the Get-CsHealthMonitoringConfiguration cmdlet. To set the configured user, call the Set-CsHealthMonitoringConfiguration cmdlet.

If a location policy was found for the user or subnet, the test will succeed. Information returned by default includes the name of the location policy (if a per-user policy is assigned) and whether the user or subnet is enabled for E9-1-1. Include the Windows PowerShell common parameter Verbose to retrieve additional information about the test.

You can test location policies on users or on network subnets. If you run the test against a subnet (by specifying a value for the Subnet parameter), the cmdlet will attempt to resolve the location policy for that subnet. If no location policy is assigned to the subnet, the location policy for the configured user will be retrieved. If the subnet policy is retrieved successfully, the output will include a LocationPolicyTagID value beginning with subnet-tagid. If a location policy for the subnet was not found, the LocationPolicyTagID will begin with user-tagid.

Test-CsLocationPolicy -TargetFqdn atl-cs-001.litwareinc.com

This example determines the location policy of the current user (or currently configured user). The TargetFqdn is required.

$cred = Get-Credential "litwareinc\kenmyer"

Test-CsLocationPolicy -TargetFqdn atl-cs-001.litwareinc.com -UserCredential $cred -UserSipAddress "sip:kenmyer@litwareinc.com"

The first line in Example 2 is a call to the Windows PowerShell Get-Credential cmdlet. This cmdlet will retrieve user credentials and return them as a secure object. The only parameter supplied to this cmdlet is the user ID. Running this cmdlet will open a dialog box that is prepopulated with the user ID supplied and has a text box that allows you to type in the user password. These user credentials are saved to the variable $cred.

Line 2 calls the Test-CsLocationPolicy cmdlet. Just like in Example 1, we supply the target FQDN. However, in this example rather than using the preconfigured user, we're going to run the test against the user with the SIP address kenmyer@litwareinc.com. We pass that value (with the sip: prefix) to the UserSipAddress parameter, and the credentials for that user (stored in the $cred variable) to the UserCredential parameter.

Test-CsLocationPolicy -TargetFqdn atl-cs-001.litwareinc.com -UserSipAddress "sip:kenmyer@litwareinc.com"

This example is similar to Example 2, but without the user credentials specified. When the Test-CsLocationPolicy cmdlet is called without specifying user credentials, the server certificate on the computer where this cmdlet is being run is used to authenticate and discover the user's location policy. If the computer does not have a server certificate, you must specify credentials as shown in Example 2. To find out whether there is a server certificate on the computer, call the Get-CsCertificate cmdlet.

Test-CsLocationPolicy -TargetFqdn atl-cs-001.litwareinc.com -Subnet 172.15.11.0

This example determines the location policy of the subnet with the subnet ID 172.15.11.0. If the subnet is not associated with a location policy, the location policy for the currently configured user will be retrieved.

Note: A location policy is set on a subnet by setting the LocationPolicy parameter of the Set-CsNetworkSite cmdlet to the location policy ID, and then setting the NetworkSiteId parameter of the Set-CsNetworkSubnet cmdlet to the ID of that site. For example:

Set-CsNetworkSite Portland -LocationPolicy Reno

Set-CsNetworkSubnet 175.15.11.0 -NetworkSiteID Portland

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

The Test-CsLocationPolicy cmdlet returns an instance of the Microsoft.Rtc.SyntheticTransactions.TaskOutput object.