[This is preliminary documentation and is subject to change. Blank topics are included as placeholders.]

Returns information about all the users in your organization who have been enabled for Microsoft Communications Server 2010 or a previous version of the software (such as Microsoft Office Communications Server 2007 R2). (To return information about all your users, including those who have not been enabled for Communications Server 2010, use the cmdlet Get-CsADUser.) Get-CsUser provides several mechanisms to filter for the users who are returned. For example, you can specify users by name or by email address. You can also specify users by organization unit (OU), or write a filter that returns users based on the value of any Active Directory Domain Services user attribute.

Syntax

Get-CsUser [-Identity <UserIdParameter>] [-Credential <PSCredential>] [-DomainController <Fqdn>] [-Filter <String>] [-LdapFilter <String>] [-OU <OUIdParameter>] [-ResultSize <Unlimited>] [-UnAssignedUser <SwitchParameter>] [-WithCurrentClient <SwitchParameter>] [-WithLegacyClient <SwitchParameter>]

Parameters

Parameter Required Type Description

Identity

Optional

UserIDParameter

Indicates the Identity of the user account to be retrieved. User Identities can be specified using one of four formats: 1) The user's SIP address; 2) the user's Universal Principal Name; 3) the user's domain name and logon name, in the form domain\logon (for example, litwareinc\kenmyer); and, 4) the user's Active Directory Domain Services display name (for example, Ken Myer). Note that the SAMAccountName cannot be used as an identity because it is not necessarily unique in a forest.

You can use the asterisk (*) wildcard character when using the Display Name as the user Identity. For example, the Identity "* Smith" would return all the users with the last name Smith.

UnassignedUser

Optional

Switch Parameter

Enables you to return a collection consisting of all the users who have been enabled for Communications Server but are not currently assigned to a registrar pool. Typically these are users whose accounts have been disconnected by using the Disconnect-CsUser cmdlet. Users are not allowed to log on to Communications Server unless they are assigned to a registrar pool.

Credential

Optional

PSCredential object

Enables you to run the Get-CsUser cmdlet under alternate credentials. This might be required if the account you used to log on to the Windows does not have the necessary privileges required to work with contact objects.

To use the -Credential parameter you must first create a PSCredential object using the Get-Credential cmdlet. For details, see the Get-Credential cmdlet Help topic.

DomainController

Optional

String

Enables you to connect to the specified domain controller in order to retrieve contact information. To connect to a particular domain controller, include the DomainController parameter followed by the computer name (for example, atl-mcs-001) or its fully qualified domain name (for example, atl-mcs-001.litwareinc.com).

Filter

Optional

String

Enables you to limit the returned data by filtering on Communications Server-specific attributes. For example, you can limit returned data to users who have been assigned a specific voice policy, or users who have not been assigned a specific voice policy.

The Filter parameter uses the same Windows PowerShell filtering syntax that is used by the Where-Object cmdlet. For example, a filter that returns only users who have been enabled for Enterprise Voice would look like this, with EnterpriseVoiceEnabled representing the Active Directory Domain Services attribute, -eq representing the comparison operator (equal to), and $True (a built-in Windows PowerShell variable) representing the filter value:

{EnterpriseVoiceEnabled -eq $True}

For details, see the about_communications_server_filters Help topic.

LDAPFilter

Optional

String

Enables you to limit the returned data by filtering generic Active Directory Domain Services attributes (that is, attributes that are not specific to Communications Server). For example, you can limit returned data to users who work in a specific department, or users who have a specified manager or job title.

The LDAPFilter parameter uses LDAP query language when creating filters. For example, a filter that returns only users who work in the city of Redmond would look like this: "l=Redmond", with "l" representing the Active Directory Domain Services attribute (locality); "=" representing the comparison operator (equal to); and "Redmond" representing the filter value.

For details, see the about_ldap_filters Help topic.

OU

Optional

Distinguished name

Enables you to limit the retrieved information from a specific Active Directory Domain Services organizational unit (OU). This returns data from both the specified OU and any of its child OUs. For example, if the Finance OU has two child OUS--AccountsPayable and AccountsReceivable--users will be returned from each of these three OUs.

When specifying an OU, use the distinguished name of that container; for example: OU=Finance,dc=litwareinc,dc=com.

ResultSize

Optional

Integer

Enables you to limit the number of records returned by a command. For example, to return seven users (regardless of how many users are in your forest) include the ResultSize parameter and set the parameter value to 7. Note that there is no way to guarantee which 7 users will be returned. If you set the ResultSize to 7 but you have only three users in your forest, the command will return those three users, and then complete without error.

The result size can be set to any whole number between 0 and 2147483647, inclusive. If set to 0 the command will run, but no data will be returned.

WithLegacyClient

Optional

Switch Parameter

Returns a collection of users who are homed on a previous version of Communications Server (for example, Office Communications Server 2007 R2).

WithCurrentClient

Optional

Switch Parameter

Returns a collection of users who are homed on Communications Server 2010.

Detailed Description

Used together, the cmdlets Get-CsAdUser and Get-CsUser enable you to return detailed information about all your Active Directory Domain Services user accounts. Get-CsAdUser returns information about all your user accounts, including both users who have been enabled for Communications Server and users who have not been enabled for Communications Server. This differs from Get-CsUser, which returns information only for users whose accounts have been enabled for Communications Server.

Although there is some overlap, the two cmdlets also differ in the type of information they return. In general, Get-CsUser returns values for Active Directory Domain Services attributes specifically related to Communications Server. For example, Get-CsUser returns information such as which Communications Server policies have been assigned to a user, the line Uniform Resource Identifier (URI) and line server URI that belong to a user, and whether or not the user has been enabled for Enterprise Voice and/or remote call control. These attributes will not be part of a user account unless that user has been enabled for Communications Server.

By contrast, Get-CsAdUser returns generic Active Directory Domain Services attribute values; that is, it returns information about attributes that are part of the basic Active Directory Domain Services user account and are present whether or not a user has been enabled for Communications Server. For example, Get-CsAdUser returns information such as the department and organization the user works for, the user's job title, and the user’s telephone number and office address. To see a complete list of the attribute values returned by Get-CsAdUser, type this command at the Windows PowerShell command prompt: Get-CsAdUser | Get-Member.

Get-CsAdUser provides numerous ways for you filter the collection of users actually returned when you run the cmdlet. For example, if you don't want to return all Active Directory Domain Services user accounts, you can apply the optional parameters Filter or LDAPFilter. (These parameters are mutually exclusive: if you use Filter in a command you cannot use LDAPFilter in that same command, and vice-versa.) The Filter parameter enables you to limit the returned data to users who meet the specified Microsoft Communications Server criteria; for example, you might decide to return only users with accounts on the specified registrar pool, or only users who have been enabled for Enterprise Voice. The LDAPFilter parameter enables you to limit the returned data to users who fit other criteria stored in Active Directory Domain Services; for example, users who work in a specified state or province, users who do or do not have a pager, and users with a designated job title. Both of these parameters allow for more sophisticated filtering: for example, all the users with an account on a specific registrar pool and who have been enabled for Enterprise Voice;, or all the users in the state of Washington who have the job title Systems Analyst.

Return Types

Get-CsUser returns instances of the Microsoft.Rtc.Management.ADConnect.Schema.ADUser object.

Examples

-------------------------- Example 1 --------------------------

Copy Code
Get-CsUser

In the preceding example, Get-CsUser is called without any parameters in order to return a collection of all the domain users who have been enabled for Communications Server. To return a collection of all the domain users, including those who have not been enabled for Communications Server, use the Get-CsAdUser cmdlet.

-------------------------- Example 2 --------------------------

Copy Code
Get-CsUser | Format-Table -Property DisplayName, SipAddress, CSEnabled, EnterpriseVoiceEnabled

In Example 2, Get-CsUser is again used to return a collection of all the domain users who have been enabled for Communications Server. By default, Get-CsUser returns a very large number of properties and property values, many of which will be of no interest in a given situation. Therefore, in this example the data returned by calling Get-CsUser is piped to the Format-Table cmdlet. Format-Table then uses the Property parameter to select the properties DisplayName, SipAddress, CSEnabled, and EnterpriseVoiceEnabled, and then display just those four properties and their values in a table.

-------------------------- Example 3 --------------------------

Copy Code
Get-CsUser -Identity "Pilar Ackerman"

In Example 3, the Identity parameter is used to limit the returned data to the user account with the Identity Pilar Ackerman. In this case, the user's first name and last name are used to indicate her identity. Alternatively, you can use the user's distinguished name, universal principal name, or SIP address when providing a value to the Identity parameter. Identities can also be expressed using the domain\username format; for example, litwareinc\pilarackerman.

-------------------------- Example 4 --------------------------

Copy Code
Get-CsUser -Identity "Pilar*"

In Example 4, the wildcard character (*) is used when specifying the user's Identity. In this case, Get-CsUser will return all the users who have a first name equal to Pilar (or, more correctly, all the users who have an identity that begins with the string value Pilar).

-------------------------- Example 5 --------------------------

Copy Code
Get-CsUser -Filter {VoicePolicy -ne "*"}

The command shown in Example 5 returns a collection of users who do not have a voice policy assigned to them. To do this, the command uses the Filter parameter followed by the filter VoicePolicy -ne "*". When constructing filters for use with Get-CsUser, specify the property name (VoicePolicy) followed by the comparison operator (in this case, -ne, the comparison operator that means "not equal to"). Immediately following the comparison operator is the value you are testing for. In this case that value is the wildcard character (asterisk); that's equivalent to setting the value to "anything at all." Thus this filter returns a collection of users who have a voice policy that is not equal to anything at all; in other words, users who do not have a voice policy of any kind assigned to them.

-------------------------- Example 6 --------------------------

Copy Code
Get-CsUser -LDAPFilter "Department=Finance"

The preceding command uses the LDAPFilter parameter to limit the returned data to users who are members of the Finance department.

-------------------------- Example 7 --------------------------

Copy Code
Get-CsUser -LDAPFilter "&(Department=Finance)(Title=Manager)"

Example 7 demonstrates the use of an AND query in conjunction with the LDAPFilter parameter. This query (which uses the ampersand character & to indicate an AND query) specifies two conditions: Department=Finance and Title=Manager. For a user account to be returned by this query, both conditions must be true: a user must be a member of the Finance department, and he must be a Manager.

-------------------------- Example 8 --------------------------

Copy Code
Get-CsUser -LdapFilter "|(Title=Supervisor)(Title=Manager)"

In the command shown in Example 8, an OR query (indicated by the pipe symbol |) is used with the LDAPFilter parameter. In the AND query shown in Example 7, both conditions had to be true in order for a user account to be returned. With an OR query, only one condition must be true for the account to be returned. In this case, a user account will be returned if the user is a Supervisor or if the user is a Manager.

-------------------------- Example 9 --------------------------

Copy Code
Get-CsUser -OU "ou=Finance,ou=North America,dc=litwareinc,dc=com"

Example 9 returns user account information for the Finance OU in Active Directory Domain Services. The distinguished name of the OU must be passed to the OU parameter.

-------------------------- Example 10 --------------------------

Copy Code
Get-CsUser -UnassignedUser

The preceding command returns a collection of all the users who have been enabled for Communications Server but are not currently assigned to a registrar pool.