Get-CsUser

Syntax

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

Detailed Description

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

Although there is some overlap between the two, Get-CsUser and Get-CsAdUser differ in the type of information they return. In general, Get-CsUser returns values for Active Directory attributes specifically related to Lync Server. For example, Get-CsUser returns information such as the Lync Server policies that have been assigned to a user; the line Uniform Resource Identifier (URI) assigned to that user; and details about whether the user has been enabled for Enterprise Voice. These attributes will not be part of a user account unless that user has been enabled for Lync Server.

By contrast, Get-CsAdUser returns generic Active Directory attribute values: attributes that are part of the basic Active Directory user account and are present whether or not a user has been enabled for Lync Server. For example, Get-CsAdUser returns information such as the department and organization the user works for in addition to 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-CsUser, type this command at the Windows PowerShell command prompt:

Get-CsUser | Get-Member

Get-CsUser provides numerous ways for you to filter the collection of users actually returned when you run the cmdlet. For example, if you don't want to return all your Lync Server 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 Lync 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 Active Directory-based criteria; for example, users who work in a specified state or province, users who do or do not have a pager, or users with a designated job title.

Who can run this cmdlet: By default, members of the following groups are authorized to run the Get-CsUser cmdlet locally: RTCUniversalUserAdmins, RTCUniversalServerAdmins, RTCUniversalReadOnlyAdmins. To return a list of all the role-based access control (RBAC) roles this cmdlet has been assigned to (including any custom RBAC roles you have created yourself), run the following command from the Windows PowerShell prompt:

Get-CsAdminRole | Where-Object {$_.Cmdlets –match "Get-CsUser\b"}

Parameters

Input Types

String. Get-CsUser accepts a pipelined string value representing the Identity of a user account that has been enabled for Lync Server 2010.

Return Types

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

Example

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

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 Lync Server or Office Communications Server.

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

Get-CsUser | Format-Table -Property DisplayName, SipAddress, EnterpriseVoiceEnabled -AutoSize

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

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

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 (in this case, the display name) Pilar Ackerman.

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

Get-CsUser -Identity "Pilar*"

In Example 4, the wildcard character (*) is used when specifying the user's Identity. That causes Get-CsUser to return all the users who have an Identity that begins with the string value "Pilar".

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

Get-CsUser -Filter {VoicePolicy -eq $Null}

The command shown in Example 5 returns a collection of users who do not have a per-user voice policy assigned to them. To do this, the command uses the Filter parameter followed by the filter VoicePolicy -eq "$Null. When constructing filters for use with Get-CsUser, you need to specify the property name (VoicePolicy) followed by the comparison operator (in this case, "eq", the comparison operator that means " equal to"). Immediately following the comparison operator is the value you are testing for. In this example that value is $Null, a Windows PowerShell variable that represents a null value.

To return a collection of users who do have a voice policy assigned to them, use this command:

Get-CsUser -Filter {VoicePolicy -ne $Null}

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

Get-CsUser -LDAPFilter "Department=Finance"

The preceding command uses the LDAPFilter parameter to limit the returned data to users who work in the Finance department. This is done by using the LDAP filter value "Department=Finance".

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

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 work in the Finance department, and he or she must be a Manager.

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

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

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

Example 9 returns user account information for all the users with accounts in the Finance OU.

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

Get-CsUser -UnassignedUser

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

See Also

Other Resources

Disable-CsUser
Enable-CsUser
Get-CsAdUser
Move-CsUser
Set-CsUser