In a multi-forest topology, returns information about user accounts from forests other than your home forest.
Syntax
Get-CsAdContact [-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 returned. 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 (e.g., litwareinc\kenmyer); and, 4_ the user's Active Directory display name (for example, Ken Myer). Note that the SAMAccountName cannot be used as an identity; that's because these names are not necessarily unique in a forest. Note that 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-CsAdContact 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 using the Get-Credential cmdlet. See the help topic for that cmdlet for more information. |
|
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 (e.g., 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 Microsoft 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 used by the Where-Object cmdlet. For example, a filter that returns only users who have been enabled for Unified Communications would look like this: {UCEnabled -eq $True}, with UCEnabled representing the Active Directory attribute; -eq representing the comparison operator (equal to); and $True (a built-in PowerShell variable) representing the filter value. For more information, see the help topic about_communications_server_filters. |
|
LDAPFilter |
Optional |
String |
Enables you to limit the returned data by filtering "generic" Active Directory attributes (that is, attributes that are not specific to Microsoft Communications Server). For example, you can limit returned data to users who work in a specific department, or users who have a the 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 attribute (locality); "=" representing the comparison operator (equal to); and "Redmond" representing the filter value. For more information, 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 just 7 contacts (regardless of how many contacts are in your forest) simply include the -ResultSize parameter and set the parameter value to 7. Note that there is no way to guarantee which 7 contacts will be returned. If you set the ResultSize to 7 but you have only 3 contacts in your forest the command will return those 3 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
In a multi-forest topology, users from other forests are represented as contacts. Note that these are not the same thing as Active Directory contacts; if you use Active Directory Users and Computers to create a new contacts those contacts will not be returned if you run the Get-CsAdContact cmdlet. Instead, Get-CsAdContact only returns information about users from forests other than your home forest. If you do not have a multi-forest topology then you will have no need to call Get-CsAdContact. (You can still run the cmdlet, but you will simply get back the message that no contacts could be found.)
In slightly-more technical terms, Get-CsAdContact returns any user who has a value configured for the msRTCSIP-OriginatorSid attribute.
Return Types
Get-CsAdContact returns instances of the Microsoft.Rtc.Management.ADConnect.Schema.ADContact object.
Examples
-------------------------- Example 1 ------------------------
 Copy Code |
|
|---|---|
Get-CsAdContact |
|
The command shown in Example 1 returns a collection of all the multi-forest contacts found in Active Directory. Calling Get-CsAdContact without any additional parameters returns all the property values for all the Active Directory contacts.
-------------------------- Example 2 ------------------------
| Copy Code |
|
|---|---|
Get-CsAdContact | Select-Object DisplayName, SIPAddress |
|
Example 2 also returns a collection of all the Active Directory contacts. In this case, however, that collection is piped to the Select-Object cmdlet, which indicates the only two attributes that will actually be displayed onscreen: DisplayName and SIPAddress.
-------------------------- Example 3 ------------------------
| Copy Code |
|
|---|---|
Get-CsAdContact -Identity "fabrikam\kenmyer" |
|
The preceding command returns information for a single Active Directory contact: the contact with the Identity "fabrikam\kenmyer".
-------------------------- Example 4 ------------------------
| Copy Code |
|
|---|---|
Get-CsAdContact -LDAPFilter "Organization=Fabrikam" |
|
In Example 4, the command returns all the Active Directory contacts who work for Fabrikam. To do this, Get-CsAdContact is called, along with the -LDAPFilter parameter, which allows you to set a filter based on an Active Directory attribute. In this case, the filter is selecting all the users who have the Organization attribute set to "Fabrikam".
-------------------------- Example 5 ------------------------
| Copy Code |
|
|---|---|
$x = Get-Credential -Credential "litwareinc\administrator" Get-CsAdContact -Credential $x |
|
The two commands shown in Example 5 illustrate the use of the -Credential parameter, which enables you to run Get-CsAdContact under alternate credentials. In the first command, the Get-Credential cmdlet is called in order to create a PSCredential object for the account litwareinc\administrator. This command will display a Credential Request dialog box for the user litwareinc\administrator. After you supply the password for this account, that credential information will be stored in the variable $x. In the second command, Get-CsAdContact is called along with the -Credential parameter; the variable $x is used as the parameter value, indicating that Get-CsAdContact should be run under the account litwareinc\administrator.