Returns information about all the user accounts in Active Directory Domain Services. This includes user accounts that have been enabled for Microsoft Communications Server 2010 as well as accounts that have not been enabled for Communications Server.
Syntax
Get-CsAdUser [-Identity <UserIdParameter>] [-Credential <PSCredential>] [-DomainController <Fqdn>] [-Filter <String>] [-LDAPFilter <String>] [-OU <OUIdParameter>] [-ResultSize <Unlimited>] |
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
|
Identity |
Optional |
UserIDParameter |
Indicates the Identity of the user account to be retrieved. User Identities can be specified by 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. |
|
Credential |
Optional |
PSCredential object |
Enables you to run the Get-CsAdUser cmdlet under alternate credentials. This might be required if the account you used to log on to 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 by using the Get-Credential cmdlet. For details, see the Get-Credential 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 attributes specific to Communications Server. 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 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: {EnterpriseVoiceEnabled -eq $True}, 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. 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 specific 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 help topic about_ldap_filters. |
|
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 seven 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. |
Detailed Description
Get-CsAdUser returns information about all the user accounts in Active Directory Domain Services, including user accounts that have been enabled for Communications Server 2010 and user accounts that have not been enabled for it. This differs from Get-CsUser, which returns information only for users whose accounts have been enabled for Communications Server or a previous version of the software (such as Microsoft Office Communications Server 2007 R2).
Although there is some overlap between the cmdlets, they 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 can tell you 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 about the user such as which department and organization the user works for, job title, telephone number, and office address. To see a complete list of the attribute values returned by Get-CsAdUser, type this command at the Microsoft Windows PowerShell prompt: Get-CsAdUser | Get-Member.
Get-CsAdUser provides several ways for you filter the collection of users returned when you run the cmdlet. For example, if you don't want to get back all of your Active Directory Domain Services users 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 criteria for Communications Server criteria; For example, you could 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 for 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, or 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-CsAdUser returns instances of the Microsoft.Rtc.Management.ADConnect.Schema.CSADUser object.
Examples
-------------------------- Example 1 --------------------------
 Copy Code |
|
|---|---|
Get-CsAdUser |
|
The command shown in Example 1 returns a collection of all the user accounts in your Active Directory Domain Services domain. To retrieve a complete collection of user accounts, call Get-CsAdUser without any additional parameters.
-------------------------- Example 2 --------------------------
| Copy Code |
|
|---|---|
Get-CsAdUser -Identity "Pilar Ackerman" |
|
In Example 2, Get-CsAdUser returns user account information for Pilar Ackerman. In this example, the user's display name is used to indicate her user Identity.
-------------------------- Example 3 --------------------------
| Copy Code |
|
|---|---|
Get-CsAdUser -OU "ou=Finance, dc=litwareinc,dc=com" |
|
Example 3 returns user account information for the Finance organizational unit in Active Directory Domain Services. The distinguished name of the OU must be passed to the OU parameter.
-------------------------- Example 4 --------------------------
| Copy Code |
|
|---|---|
Get-CsAdUser -Filter {CSEnabled -eq $False} | Select-Object Name
|
|
In the preceding command, the Filter parameter is used with Get-CsAdUser to restrict the return data to user accounts where the CSEnabled property is equal to (-eq) False ($False). This filter tells Get-CsAdUser to return only those user accounts that have not been enabled for use with Communications Server. After the data has been retrieved, the information is piped to the Select-Object cmdlet, which then identifies the only property (in this case, Name) that will actually be displayed on the screen. Thus the command displays a list containing the names of all the users not enabled for Communications Server.
-------------------------- Example 5 --------------------------
| Copy Code |
|
|---|---|
Get-CsAdUser -LDAPFilter "Department=Finance" |
|
In Example 5 the LDAPFilter parameter is used to limit the returned data to users who belong to the Finance department.