Retrieve all users in a domain or container that match the specified conditions. Supported are both Active Directory Domain Services (AD DS) and Active Directory Lightweight Directory Services (AD LDS).

This cmdlet is part of the Quest ActiveRoles Server product. Use Get-QARSProductInfo to view information about ActiveRoles Server.

Contents

 [hide]

Syntax

Get-QADUser [[-Identity] <IdentityParameter>] [-AccountExpiresAfter <DateTime>] [-AccountExpiresBefore <DateTime>] [-AccountNeverExpires] [-Activity <string>] [-Anr <string>] [-AttributeScopeQuery <string>] [-City <string[]>] [-Company <string[]>] [-Connection <ArsConnection>] [-ConnectionAccount <string>] [-ConnectionPassword <SecureString>] [-Control <hashtable>] [-CreatedAfter <DateTime>] [-CreatedBefore <DateTime>] [-CreatedOn <DateTime>] [-Credential <PSCredential>] [-Department <string[]>] [-Description <string[]>] [-Disabled] [-DisplayName <string[]>] [-DontConvertValuesToFriendlyRepresentation] [-DontUseDefaultIncludedProperties] [-Email <string[]>] [-Enabled] [-ExcludedProperties <string[]>] [-ExpiredFor <int>] [-Fax <string[]>] [-FirstName <string[]>] [-HomeDirectory <string[]>] [-HomeDrive <string[]>] [-HomePhone <string[]>] [-Inactive] [-InactiveFor <int>] [-IncludeAllProperties] [-IncludedProperties <string[]>] [-IndirectMemberOf <IdentityParameter[]>] [-Initials <string[]>] [-LastChangedAfter <DateTime>] [-LastChangedBefore <DateTime>] [-LastChangedOn <DateTime>] [-LastKnownParent <IdentityParameter>] [-LastName <string[]>] [-LdapFilter <string>] [-Locked] [-LogonScript <string[]>] [-Manager <IdentityParameter>] [-MemberOf <IdentityParameter[]>] [-MobilePhone <string[]>] [-Name <string[]>] [-Notes <string[]>] [-NotIndirectMemberOf <IdentityParameter[]>] [-NotLoggedOnFor <int>] [-NotMemberOf <IdentityParameter[]>] [-Office <string[]>] [-Pager <string[]>] [-PageSize <int>] [-PasswordNeverExpires] [-PasswordNotChangedFor <int>] [-PhoneNumber <string[]>] [-PostalCode <string[]>] [-PostOfficeBox <string[]>] [-PrimaryProxyAddress <string[]>] [-ProfilePath <string[]>] [-ProgressThreshold <int>] [-Proxy] [-ProxyAddress <string[]>] [-Recycled] [-ReturnPropertyNamesOnly] [-SamAccountName <string[]>] [-SearchAttributes <Object>] [-SearchRoot <IdentityParameter[]>] [-SearchScope {Base | OneLevel | Subtree}] [-SecondaryProxyAddress <string[]>] [-SecurityMask {None | Owner | Group | Dacl | Sacl}] [-SerializeValues] [-Service <string>] [-ShowProgress] [-SizeLimit <int>] [-StateOrProvince <string[]>] [-StreetAddress <string[]>] [-Title <string[]>] [-Tombstone] [-UseDefaultExcludedProperties <Boolean>] [-UseDefaultExcludedPropertiesExcept <string[]>] [-UseGlobalCatalog] [-UserPrincipalName <string[]>] [-WebPage <string[]>] [-WildcardMode <WildcardMode>] [<CommonParameters>]

Detailed Description

Use this cmdlet to search an Active Directory domain or container for user accounts that meet certain search criteria, or to bind to a certain user account by DN, SID, GUID, UPN or Domain\UserName. You can search by user attributes or specify your search criteria by using an LDAP search filter.

The output of the cmdlet is a collection of objects, with each object representing one of the user accounts found by the cmdlet. You can pipe the output into another cmdlet, such as Set-QADUser, to make changes to the user accounts returned by this cmdlet.

The cmdlet takes a series of optional, attribute-specific parameters allowing you to search by user attributes. The attribute-specific parameters have effect if SearchRoot is specified whereas Identity is not. If you specify SearchRoot only, then the cmdlet returns all users found in the SearchRoot container.

You can use attribute-specific parameters to search for user accounts that have specific values of certain attributes. Thus, to find all user accounts that have the givenName attribute set to Martin, you may add the following on the command line: "-FirstName Martin". To search for user accounts that have a certain attribute not set specify (empty string) as the parameter value.

If a given attribute is referred to by both the ObjectAttributes array and an attribute-specific parameter, the ObjectAttributes setting has no effect on that attribute. The cmdlet searches for the attribute value specified by the attribute-specific parameter.

With more than one attribute-specific parameter supplied, the search conditions are combined by using the AND operator, so as to find the user accounts that meet all the specified conditions. Thus, if you supply both the -FirstName and -LastName parameters, the cmdlet searches for the user accounts that have the givenName attribute set to the FirstName parameter value and the sn attribute set to the LastName parameter value.

Each of the attribute-specific parameters accepts the * wildcard character in the parameter value to match zero or more characters (case-insensitive). For instance, a* matches A, ag, Amsterdam, and does not match New York.

The cmdlet has optional parameters that determine the server and the security context for the operation. Normally, the connection parameters could be omitted so far as a connection to a server is established prior to using the cmdlet. In this case, the server and the security context are determined by the Connect-QADService cmdlet.

If you do not use Connect-QADService and have no connection established prior to using a cmdlet, then the connection settings, including the server and the security context, are determined by the connection parameters of the first cmdlet you use. Subsequent cmdlets will use those settings by default.



Parameters

Name Description Required? Pipeline Input Default Value
AccountExpiresAfter Retrieve user accounts that are configured to expire after a certain date. Parameter value is a DateTime object that specifies the date you want. false false
AccountExpiresBefore Retrieve user accounts that are configured to expire before a certain date. Parameter value is a DateTime object that specifies the date you want. false false
AccountNeverExpires Set the value of this parameter to 'true' if you want the cmdlet to retrieve only those user accounts that are configured to never expire. false false
Activity Use this parameter to specify the line of text above the progress bar which the cmdlet displays to depict the status of the running command in case of a lengthy operation. This text describes the activity whose progress is being reported (see also ShowProgress and ProgressThreshold). If this parameter is omitted, the name of the cmdlet is displayed above the progress bar. false false
Anr Specify a value to be resolved using ambiguous name resolution (ANR). Which attributes are included in an ANR search depends upon the Active Directory schema. Thus, in Windows Server 2003 based Active Directory, the following attributes are set for ANR by default:
Display-Name (displayName) 
Given-Name (givenName) 
Legacy-Exchange-DN (legacyExchangeDN) 
ms-DS-Additional-Sam-Account-Name (msDS-AdditionalSamAccountName) 
Physical-Delivery-Office-Name (physicalDeliveryOfficeName) 
Proxy-Addresses (proxyAddresses) 
RDN (name) 
SAM-Account-Name (sAMAccountName) 
Surname (sn) 

For instance, when you supply 'ann*' as the value of this parameter, the cmdlet searches for objects that have ann at the beginning of the value of at least one of the attributes listed above.

false false
AttributeScopeQuery Specify the LDAP display name of an attribute that has DN syntax (for example, 'memberOf'). The cmdlet enumerates the distinguished name values of the attribute on the object specified by the SearchRoot parameter, and performs the search on the objects represented by the distinguished names. The SearchScope parameter has no effect in this case. The object to search must be specified by using the SearchRoot parameter rather than the Identity parameter.

For instance, with the value of this parameter set to 'memberOf', the cmdlet searches the collection of the groups to which the SearchRoot object belongs.

false false
City Search by the 'l' attribute. false false
Company Search by the 'company' attribute. false false
Connection For parameter description, see help on the Connect-QADService cmdlet. false false
ConnectionAccount For parameter description, see help on the Connect-QADService cmdlet. false false
ConnectionPassword For parameter description, see help on the Connect-QADService cmdlet. false false
Control Use this parameter to pass request controls (in-controls) to ActiveRoles Server as part of an operation request. In ActiveRoles Server, request controls are used to send extra information along with an operation request, to control how ActiveRoles Server performs the request.

The parameter value is a hash table that defines the names and values of the request controls to be passed to ActiveRoles Server. The parameter syntax is as follows:

   -Control @{<name> = <value>; [<name> = <value>] ...}

In this syntax, each of the name-value pairs is the name and the value of a single control. For instructions on how to create and use hash tables, see topic "about_associative_array" or "about_hash_tables" in Windows PowerShell Help. For information about ActiveRoles Server request controls, refer to ActiveRoles Server SDK documentation.

Note that this parameter only has an effect on the operations that are performed through ActiveRoles Server (connection established using the Proxy parameter); otherwise, this parameter causes an error condition in ActiveRoles Management Shell.

false false
CreatedAfter Specify the lower boundary of the object creation date and time by which to filter objects found. The cmdlet returns only the objects that were created after the date and time specified. Supplying both CreatedAfter and CreatedBefore bounds a time interval for the objects' creation. If you supply only CreatedAfter, there is no upper boundary on the date. Parameter value is a DateTime object that specifies the date and time you want. false false
CreatedBefore Specify the upper boundary of the object creation date and time by which to filter objects found. The cmdlet returns only the objects that were created before the date and time specified. Supplying both CreatedAfter and CreatedBefore bounds a time interval for the objects' creation. If you supply only CreatedBefore, there is no lower boundary on the date. Parameter value is a DateTime object that specifies the date and time you want. false false
CreatedOn Specify the object creation date by which to filter objects found, searching for objects created within the date specified. This parameter is mutually exclusive with the CreatedAfter and CreatedBefore parameters. Parameter value is a DateTime object that specifies the date you want. false false
Credential For parameter description, see help on the Connect-QADService cmdlet. false false
Department Search by the 'department' attribute. false false
Description Search by the 'description' attribute. false false
Disabled Supply this parameter on the command line if you want the search results produced by this cmdlet to include only those user accounts that are disabled. false false
DisplayName Search by the 'displayName' attribute. false false
DontConvertValuesToFriendlyRepresentation This parameter causes the cmdlet to represent the Integer8 and OctetString attribute values "as is," without converting them to a user-friendly, human-readable form. If this parameter is omitted, the cmdlet performs the following data conversions:
- The values of the Integer8 attributes listed in the 
  Integer8AttributesThatContainDateTimes array 
  (see the parameter descriptions for the 
  Get-QADPSSnapinSettings and Set-QADPSSnapinSettings
  cmdlets) are converted from IADsLargeInteger to DateTime
- The values of the Integer8 attributes listed in the 
  Integer8AttributesThatContainNegativeTimeSpans array 
  (see the parameter descriptions for the 
  Get-QADPSSnapinSettings and Set-QADPSSnapinSettings
  cmdlets) are converted from IADsLargeInteger to TimeSpan
- The values of the other Integer8 attributes are 
  converted from IADsLargeInteger to Int64
- The values of the OctetString attributes are converted
  from byte[] to BinHex strings

Note: This parameter has an effect only on the properties of the output object that have the member type of NoteProperty. Such properties are normally added to the output object in order to provide access to the attribute values of the respective directory object that are loaded to the local memory cache but cannot be accessed by using properties of the base object (the object for which the output object serves as a wrapper).

false false
DontUseDefaultIncludedProperties This parameter causes the cmdlet to load only a small set of attributes from the directory to the local memory cache (normally, this set is limited to objectClass and ADsPath). Other attributes are retrieved from the directory as needed when you use the cmdlet's output objects to read attribute values. Thus, if you want only to count the objects that meet certain conditions (rather than examine values of particular attributes), then you can use this parameter to increase performance of your search. For examples of how to use this parameter, see help on the Get-QADUser cmdlet.

Note: If a cmdlet does not cache a particular attribute, then the output object returned by the cmdlet may not have a property that would provide access to the value of the attribute.

false false
Email Search by the 'mail' attribute. false false
Enabled Supply this parameter on the command line if you want the search results produced by this cmdlet to include only those user accounts that are enabled (not disabled). false false
ExcludedProperties Use this parameter to specify the attributes that you do not want the cmdlet to retrieve from the directory and store in the memory cache on the local computer. Supply a list of the attribute LDAP display names as the parameter value. By default, the cmdlet caches a certain pre-defined set of attributes, which you can view or modify by using the Get-QADPSSnapinSettings or Set-QADPSSnapinSettings cmdlet, respectively. Using the ExcludedProperties parameter you can change this default behavior on an ad-hoc basis, in order to prevent certain attributes from being loaded. Another scenario involves the use of this parameter in conjunction with IncludeAllProperties in order to restrict the set of the cached attributes.

Note: If a cmdlet does not cache a particular attribute, then the output object returned by the cmdlet may not have a property that would provide access to the value of the attribute.

false false
ExpiredFor Use this parameter to retrieve accounts that remain in the expired state for at least the number of days specified by the parameter value. This parameter overrides the expiry-related inactivity condition of the Inactive or InactiveFor parameter. Thus, if the ExpiredFor value of 0 is supplied in conjunction with the InactiveFor value of 30, the cmdlet searches for accounts that are currently expired, or have the password age of 30 or more days, or have not been used to log on for 30 or more days. false false
Fax Search by the 'facsimileTelephoneNumber' attribute. false false
FirstName Search by the 'givenName' attribute. false false
HomeDirectory Search by the 'homeDirectory' attribute. false false
HomeDrive Search by the 'homeDrive' attribute. false false
HomePhone Search by the 'homePhone' attribute. false false
Identity Specify the DN, SID, GUID, UPN or Domain\UserName of the user account you want to find.

The cmdlet attempts to find the user that is identified by the value of this parameter, disregarding the other parameters. If you want other parameters to have effect, do not supply any value of this parameter on the command line.

false true (ByValue, ByPropertyName)
Inactive Supply this parameter to retrieve user accounts that meet the default inactivity conditions. You can view or change the default inactivity conditions by using the Get-QADInactiveAccountsPolicy or Set-QADInactiveAccountsPolicy cmdlet, respectively. When considering whether an account is inactive, the cmdlet verifies each of these values:
- The number of days that the account remains in the expired state
- The number of days that the password of the account remains unchanged
- The number of days that the account remains unused for logon

If any of these values exceeds a certain, default limit, then the account is considered inactive, and thus is retrieved by the Inactive parameter. The default limits can be overridden by supplying other account-inactivity related parameters, such as InactiveFor, ExpiredFor, NotLoggedOnFor, and PasswordNotChangedFor. Thus, if the NotLoggedOnFor value of 60 is supplied in conjunction with the Inactive parameter, the cmdlet searches for accounts that meet the default expiry-related or password-related inactivity condition, or have not been used to log on for 60 or more days.

To retrieve only those accounts that are not inactive, use the following syntax: -Inactive:$false

false false
InactiveFor Use this parameter to retrieve user accounts that meet any of the following conditions:
- The account remains in the expired state for at least the number of days specified by the parameter value
- The account does not have its password changed for at least the number of days specified by the parameter value
- The account has not been used to log on for at least the number of days specified by the parameter value

For example, the parameter value of 30 causes the cmdlet to search for accounts that are expired for 30 or more days, or have the password age of 30 or more days, or have not been used to log on for 30 or more days.

The value of this parameter overrides the default inactivity conditions, so the Inactive parameter has no effect when used together with this parameter. Similarly, the other account-inactivity related parameters such as ExpiredFor, NotLoggedOnFor and PasswordNotChangedFor override the corresponding conditions of this parameter. Thus, if the NotLoggedOnFor value of 60 is supplied in conjunction with the InactiveFor value of 30, the cmdlet searches for accounts that are expired for 30 or more days, or have the password age of 30 or more days, or have not been used to log on for 60 or more days.

false false
IncludeAllProperties With this parameter, the cmdlet retrieves all attributes of the respective directory object (such as a User object), and stores the attribute values in the memory cache on the local computer. Attribute values can be read from the memory cache by using properties of the object returned by the cmdlet. Thus, when used in conjunction with the SerializeValues parameter, it allows an entire object to be exported from the directory to a text file. For examples of how to use this parameter, see help on the Get-QADUser or Get-QADObject cmdlet. false false
IncludedProperties Use this parameter to specify the attributes that you want the cmdlet to retrieve from the directory and store in the memory cache on the local computer. Supply a list of the attribute LDAP display names as the parameter value. By default, the cmdlet caches a certain pre-defined set of attributes, which you can view or modify by using the Get-QADPSSnapinSettings or Set-QADPSSnapinSettings cmdlet, respectively. Using the IncludedProperty parameter you can direct the cmdlet to cache some attributes in addition to the default set.

Note: Caching an attribute guarantees that the value of the attribute can be read by using properties of the output object returned by the cmdlet.

false false
IndirectMemberOf Retrieve objects that belong to the group or groups specified by this parameter, whether directly or because of group nesting. The cmdlet returns an object if the object has direct or indirect membership in the group specified by this parameter value. false false
Initials Search by the 'initials' attribute. false false
LastChangedAfter Specify the lower boundary of the object modification date and time by which to filter objects found. The cmdlet returns only the objects that have last changed after the date and time specified. Supplying both LastChangedAfter and LastChangedBefore bounds a time interval for the objects' last change. If you supply only LastChangedAfter, there is no upper boundary on the date. Parameter value is a DateTime object that specifies the date and time you want. false false
LastChangedBefore Specify the upper boundary of the object modification date and time by which to filter objects found. The cmdlet returns only the objects that have last changed before the date and time specified. Supplying both LastChangedAfter and LastChangedBefore bounds a time interval for the objects' last change. If you supply only LastChangedBefore, there is no lower boundary on the date. Parameter value is a DateTime object that specifies the date and time you want. false false
LastChangedOn Specify the object modification date by which to filter objects found, searching for objects that have last changed within the date specified. This parameter is mutually exclusive with the LastChangedAfter and LastChangedBefore parameters. Parameter value is a DateTime object that specifies the date you want. false false
LastKnownParent When searching for a deleted object by using the Tombstone parameter, specify the DN of the container the object was in before it became a tombstone. This allows you to find objects that were deleted from a particular container.

Note that the lastKnownParent attribute is only set if the object was deleted on a domain controller running Windows Server 2003 or later version of Microsoft Windows Server. Therefore, it is possible that the lastKnownParent attribute value is inaccurate.

false false
LastName Search by the 'sn' attribute. false false
LdapFilter Specify the LDAP search filter that defines your search criteria. Note that the search filter string is case-sensitive.

The cmdlet disregards this parameter if an Identity value is supplied. If you want this parameter to have effect, do not supply any Identity value on the command line. Instead, supply a SearchRoot value.

If you supply the LdapFilter parameter along with attribute-specific parameters, then your search returns objects that meet the conditions defined by the LDAP filter and have the specified attributes set to the specified values.

false false
Locked Supply this parameter on the command line if you want the search results produced by this cmdlet to include only those user accounts that are locked out. false false
LogonScript Search by the 'scriptPath' attribute. false false
Manager Search by the 'manager' attribute. false false
MemberOf Retrieve objects that are direct members of the group or groups specified by this parameter. The cmdlet returns an object if the object has direct membership in the group specified by this parameter value. false false
MobilePhone Search by the 'mobile' attribute. false false
Name Search by the 'name' attribute. false false
Notes Search by the 'info' attribute. false false
NotIndirectMemberOf Retrieve objects that do not belong to the group or groups specified by this parameter, whether directly or because of group nesting. The cmdlet returns an object if the object has neither direct nor indirect membership in the group specified by this parameter value. false false
NotLoggedOnFor Use this parameter to retrieve user accounts that have not been used to log on for at least the number of days specified by the parameter value. This parameter overrides the logon-related inactivity condition of the Inactive or InactiveFor parameter. Thus, if the NotLoggedOnFor value of 60 is supplied in conjunction with the InactiveFor value of 30, the cmdlet searches for accounts that are expired for 30 or more days, or have the password age of 30 or more days, or have not been used to log on for 60 or more days. false false
NotMemberOf Retrieve objects that are not direct members of the group or groups specified by this parameter. The cmdlet returns an object if the object does not have direct membership in the group specified by this parameter value. false false
Office Search by the 'physicalDeliveryOfficeName' attribute. false false
Pager Search by the 'pager' attribute. false false
PageSize Set the maximum number of items in each page of the search results that will be returned by the cmdlet. After the directory server has found the number of objects that are specified by this parameter, it will stop searching and return the results to the cmdlet. When the cmdlet requests more data, the server will restart the search where it left off. You can use this setting to adjust the number of requests (network calls) to the directory server issued by the cmdlet during a search.

Normally, the default page size is 50. You can view or modify this default setting by using the Get-QADPSSnapinSettings or Set-QADPSSnapinSettings cmdlet, respectively.

false false
PasswordNeverExpires Set the value of this parameter to 'true' if you want the cmdlet to retrieve only those user accounts that have the password configured to never expire. false false
PasswordNotChangedFor Use this parameter to retrieve user accounts whose password has not been changed for at least the number of days specified by the parameter value. This parameter overrides the password-related inactivity condition of the Inactive or InactiveFor parameter. Thus, if the PasswordNotChangedFor value of 60 is supplied in conjunction with the InactiveFor value of 30, the cmdlet searches for accounts that are expired for 30 or more days, or have the password age of 60 or more days, or have not been used to log on for 30 or more days. false false
PhoneNumber Search by the 'telephoneNumber' attribute. false false
PostalCode Search by the 'postalCode' attribute. false false
PostOfficeBox Search by the 'postOfficeBox' attribute. false false
PrimaryProxyAddress Specify one or more e-mail addresses to retrieve Exchange mailbox users for which any of the specified e-mail addresses is set as a primary (reply-to) e-mail address. false false
ProfilePath Search by the 'profilePath' attribute. false false
ProgressThreshold Use this parameter to specify a delay, in seconds, before the cmdlet displays a progress bar that depicts the status of the running command in case of a lengthy operation. If the running command finishes before the threshold time has elapsed, a progress bar does not appear. The default threshold time setting can be configured by using the Set-QADProgressPolicy cmdlet. false false
Proxy For parameter description, see help on the Connect-QADService cmdlet. false false
ProxyAddress Specify one or more e-mail addresses to retrieve Exchange mailbox users that have any of the specified e-mail addresses. false false
Recycled This parameter has an effect only if all of the following conditions are true:
- A domain is supplied as the SearchRoot parameter value.
- Active Directory Recycle Bin is enabled in that domain.

You can use this parameter in conjunction with the Tombstone parameter for the search results to include both the deleted and recycled objects that meet the search conditions. Without this parameter, the cmdlet returns only deleted objects.

false false
ReturnPropertyNamesOnly This parameter causes the cmdlet to list the names of the object attributes whose values the cmdlet retrieves from the directory and stores in the memory cache on the local computer. Thus, when used in conjunction with the IncludeAllProperties parameter, it lists the names of all attributes of the respective directory object (such as a User object). For examples of how to use this parameter, see help on the Get-QADUser or Get-QADObject cmdlet.

Note: Caching an attribute guarantees that the value of the attribute can be read by using properties of the output object returned by the cmdlet. If a particular attribute is not in the cache, the output object may not have a property that would provide access to the value of the attribute.

false false
SamAccountName Search by the 'sAMAccountName' attribute. false false
SearchAttributes Specify an associative array that defines the object attributes and values you want. The cmdlet searches for objects that have the specified attributes set to the specified values. Array syntax:

@{attr1='val1';attr2='val2';...}

In this syntax, each of the key-value pairs is the LDAP display name and the value of an attribute to search. A value may include an asterisk character - a wildcard representing any group of characters. For information about associative arrays, type the following command at the PowerShell command-prompt:

help about_associative_array

false false
SearchRoot Specify the DN, GUID or canonical name of the domain or container to search. By default, the cmdlet searches the entire sub-tree of which SearchRoot is the topmost object (sub-tree search). This default behavior can be altered by using the SearchScope parameter.

The search criteria are defined by the LdapFilter parameter value and the values of attribute-specific parameters.

The cmdlet disregards this parameter if an Identity value is supplied. If you want this parameter to have effect, do not supply any Identity value on the command line.

false false
SearchScope Specify one of these parameter values:
  'Base'     Limits the search to the base (SearchRoot) object.
             The result contains a maximum of one object.
  'OneLevel' Searches the immediate child objects of the base (SearchRoot)
             object, excluding the base object.
  'Subtree'  Searches the whole sub-tree, including the base (SearchRoot)
             object and all its child objects.

Normally, if this parameter is not supplied, the cmdlet performs a Subtree search. You can view or modify this default setting by using the Get-QADPSSnapinSettings or Set-QADPSSnapinSettings cmdlet, respectively.

The following values are permitted for this object type.

false false
SecondaryProxyAddress Specify one or more e-mail addresses to retrieve Exchange mailbox users for which any of the specified e-mail addresses is set as a non-primary e-mail address. false false
SecurityMask Specify which elements of the object's security descriptor to retrieve. Valid parameter values are:
   'None' - do not retrieve any security data
   'Owner' - retrieve the owner data
   'Group' - retrieve the primary group data
   'Dacl' - retrieve the discretionary access-control list data
   'Sacl' - retrieve the system access-control list data

You can supply a combination of these values, separating them by commas. For example, you can supply the parameter value of 'Dacl,Sacl' in order to retrieve both the discretionary and system access-control list data.

The following values are permitted for this object type.

false false
SerializeValues This parameter causes the cmdlet to output an object whose properties store the attribute values of the respective directory object that are loaded to the local memory cache. The value returned by each property of the output object is represented as a string (serialized) so as to facilitate the export of the attribute values to a text file. Thus, when used in conjunction with the IncludeAllProperties parameter, it allows an entire object to be exported from the directory to a text file. For examples of how to use this parameter, see help on the Get-QADUser cmdlet. false false
Service For parameter description, see help on the Connect-QADService cmdlet. false false
ShowProgress Supply this parameter if you want the cmdlet to display a progress bar that depicts the status of the running command in case of a lengthy operation. If this parameter is omitted, whether the cmdlet displays a progress bar depends upon the ShowProgress setting configured by using the Set-QADProgressPolicy cmdlet. false false
SizeLimit Set the maximum number of items to be returned by the cmdlet. Normally, the default size limit is 1000. You can view or modify this default setting by using the Get-QADPSSnapinSettings or Set-QADPSSnapinSettings cmdlet, respectively. false false
StateOrProvince Search by the 'st' attribute. false false
StreetAddress Search by the 'streetAddress' attribute. false false
Title Search by the 'title' attribute. false false
Tombstone Search for deleted objects of the respective object class. The search output is normally intended to be passed (piped in) to the Restore-QADDeletedObject cmdlet for restoring deleted objects.

In a domain with Active Directory Recycle Bin (a feature of Windows Server 2008 R2) this parameter retrieves deleted objects (rather than tombstones, which in that case are referred to as recycled objects). Recycle Bin preserves all attributes on the deleted objects, so you can use a search filter based on any attributes.

In a domain without Active Directory Recycle Bin, deleting an object converts that object to a tombstone. A search using this parameter returns tombstone objects that meet the filtering criteria supplied. Upon deletion of an object only a small number of the object's attributes are saved in the tombstone, with most of the attributes being lost. To search for deleted objects, your search filter should be based on the attributes that are preserved in tombstones.

When the Tombstone parameter is supplied, the search results include the deleted objects or tombstones that match the specified search filter. However, a search filter that matches a live object may not work as expected after the object is deleted. This is because not all attributes are retained in the tombstone. For example, a filter such as (&(objectClass=user)(objectCategory=person)) would not match any tombstone objects since the objectCategory attribute is removed upon object deletion. Conversely, the objectClass attribute is retained on tombstone objects, so a filter of (objectClass=user) would match deleted user objects.

The name of a tombstone object begins with the name of the deleted object, so a search using the Tombstone parameter can be refined by adding a filter based on object name. For example, to search for deleted objects with a name that begins with "John", you can use a filter such as (cn=John*).

It is also possible to find a specific deleted object. If you know the name of the object and the Distinguished Name (DN) of the container the object was in before it was deleted, then you can pass the container's DN to the LastKnownParent parameter and apply a filter of (cn=<name of the object>*) in order to have the cmdlet retrieve that specific object. However, if an object is deleted, a new object with the same DN is created, and then deleted as well, the above search would return more than one object. The returned objects are distinguished by the GUIDs of the deleted objects, with the name of each ending in the GUID of the respective deleted object.

false false
UseDefaultExcludedProperties When set to 'true', this parameter causes the cmdlet not to load a certain pre-defined set of attributes from the directory to the local memory cache. This pre-defined set of attributes (referred to as "default excluded properties") can be viewed or modified by using the Get-QADPSSnapinSettings or Set-QADPSSnapinSettings cmdlet, respectively. Normally, this parameter is used in conjunction with IncudeAllProperties to avoid retrieval of unnecessary data from the directory server, thereby increasing performance of the search operation performed by the cmdlet.

Note: If a cmdlet does not cache a particular attribute, then the output object returned by the cmdlet may not have a property that would provide access to the value of the attribute.

false false
UseDefaultExcludedPropertiesExcept This parameter is deprecated, and has no effect. false false
UseGlobalCatalog For parameter description, see help on the Connect-QADService cmdlet. false false
UserPrincipalName Search by the 'userPrincipalName' attribute. false false
WebPage Search by the 'wWWHomePage' attribute. false false
WildcardMode Specify either 'PowerShell' or 'LDAP' as the parameter value. Normally, if this parameter is not supplied, the cmdlet assumes that WildcardMode is set to 'LDAP'. You can view or modify this default setting by using the Get-QADPSSnapinSettings or Set-QADPSSnapinSettings cmdlet, respectively.

The 'PowerShell' value causes the cmdlet to use PowerShell wildcards and quoting rules. Wildcards are processed on the client side, which may result in slow search performance.

For information about PowerShell wildcards and quoting rules, type the following commands at the PowerShell command-prompt:

   help about_wildcard
   help about_quoting_rule

The 'LDAP' value causes the cmdlet to use LDAP wildcards (asterisks only) and LDAP quoting rules (backslash as the escape character). Wildcards are processed on the server side, which enables faster search results.

false false

Examples

EXAMPLE 1

(get-QADUser 'CN=John Smith,OU=CompanyOU,DC=company,DC=com').DirectoryEntry.description

Description


Connect to any available domain controller with the credentials of the locally logged on user, bind to a specific user account by DN, and display the user description.

EXAMPLE 2

$pw = read-host "Enter password" -AsSecureString

C:\PS>connect-QADService -service 'server.company.com' -ConnectionAccount 'company\administrator' -ConnectionPassword $pw

C:\PS>(get-QADUser -identity 'S-1-5-21-1279736177-1630491018-182859109-1305').DirectoryEntry.description 

C:\PS>disconnect-QADService

Description


Connect to a specific domain controller with the credentials of a specific user, bind to a certain user account by SID, display the user description, and then disconnect.

EXAMPLE 3

get-QADUser -SearchRoot 'company.com/UsersOU' -LdapFilter '(description=a*)'

Description


Connect to any available domain controller with the credentials of the locally logged on user, search for users in a specific container by using an LDAP search filter, and display a list of the users found.

EXAMPLE 4

get-QADUser -SearchRoot 'company.com/UsersOU' |	
 %{$_.DirectoryEntry.distinguishedName, $_.DirectoryEntry.description}

Description


Connect to any available domain controller with the credentials of the locally logged on user, find all users in a specific container, and display a list of the users found.

EXAMPLE 5

$pw = read-host "Enter password" -AsSecureString

C:\PS>connect-QADService -ConnectionAccount 'company\administrator' -ConnectionPassword $pw

C:\PS>get-QADUser -SearchRoot 'company.com/UsersOU' -title '' |	
 set-QADUser -title 'A title' 

C:\PS>disconnect-QADService

Description


Connect to any available domain controller with the credentials of a specific user, search a certain container to find all users with empty title, set a title for each of those users, and then disconnect.

EXAMPLE 6

connect-QADService -service 'localhost' -proxy

C:\PS>get-QADUser -SearchRoot 'company.com/UsersOU' -name 'a*' -ObjectAttributes @{name='B*';title='*manager'} |	
 set-QADUser -description 'A manager whose name begins with A' 

C:\PS>disconnect-QADService

Description


Connect to the local Administration Service with the credentials of the locally logged on user, find all users whose names begin with 'A' and titles end in 'Manager' and modify the description for each of those users; then, disconnect.

Note that the condition based on the Name parameter overrides the condition imposed on the 'Name' attribute by the ObjectAttributes parameter, so you could omit the Name parameter and type name='A*' instead of name='B*' in the value of the ObjectAttributes parameter, or you could only remove the name='B*' entry from the value of the ObjectAttributes parameter.

EXAMPLE 7

Get-QADUser -IncludeAllProperties -ReturnPropertyNamesOnly

Description


List the names of the properties specific to a user object.

EXAMPLE 8

Get-QADUser JSmith -IncludeAllProperties -SerializeValues |	
 Format-List

Description


List the values of all properties of the user account.

EXAMPLE 9

Get-QADUser jsmith -IncludeAllProperties -SerializeValues |	
 Export-Clixml user.xml

Description


Export the user account to an XML file. Exported are the values of all properties.

EXAMPLE 10

Get-QADUser -DontUseDefaultIncludedProperties -ObjectAttributes @{homeDirectory='*'} -IncludedProperties 'msDS-ReplAttributeMetaData',homeDirectory |	
 Format-Table name, homeDirectory, 'msDS-ReplAttributeMetaData'

Description


Find user objects with a non-empty value of the 'homeDirectory' property, and display the values of the 'Name', 'HomeDirectory' and 'msDS-ReplAttributeMetaData' properties for each object found.

EXAMPLE 11

Get-QADuser jsmith -SerializeValues |	
 export-csv user.csv

C:\PS>import-csv user.csv |	
 New-QADUser -ParentContainer MyDomain.lab.local/MyOU -DeserializeValues -Name importedUser -LogonName importedUser -UserPassword 'P@ssw0rd'

Description


Export the user object to a CSV file. Then, import that user object from that file.

EXAMPLE 12

Get-QADUser -DontUseDefaultIncludedProperties -SizeLimit 0 |	
 Measure-Object

Description


Count all user objects that exist in your Active Directory domain.

EXAMPLE 13

get-QADUser -Service 'server.domain.local:389' -SearchRoot '<DN of container>' -LdapFilter '(description=a*)' |	
 Format-List name,description

Description


Connect to the AD LDS instance on 'server.domain.local:389' with the credentials of the locally logged on user, search a specific container to find all AD LDS user objects matching a certain LDAP search filter, and display the name and description of each user object found.

EXAMPLE 14

get-QADUser '<DN of user object>' -Service 'server.domain.local:389' |	
 Format-List name,description

Description


Connect to the AD LDS instance on 'server.domain.local:389' with the credentials of the locally logged on user, and display the name and description of the AD LDS user object that is identified by DN.

EXAMPLE 15

get-QADUser -SearchRoot '<DN of container>' -IndirectMemberOf 'domainName\groupName'

Description


Retrieve user accounts from a particular container that are direct or indirect members of a particular group.

EXAMPLE 16

Get-QADUser -Tombstone -LastKnownParent '<DN of container>'

Description


Retrieve all user accounts that were deleted from a particular container.

EXAMPLE 17

Get-QADUser -Tombstone -Name 'John Smith*'

Description


Retrieve deleted user accounts with the name (RDN) of John Smith.

EXAMPLE 18

Get-QADUser -Tombstone -LastKnownParent '<DN of container>' -LastChangedOn (get-date)

Description


Retrieve all user accounts that were deleted from a particular container on the current date.

EXAMPLE 19

Get-QADUser -Tombstone -LastChangedOn (get-date -year 2008 -month 9 -day 1)

Description


Retrieve all user accounts that were deleted on September 1, 2008.

EXAMPLE 20

Get-QADUser -ShowProgress -Activity 'Retrieving all domain users' -ProgressThreshold 0 |	
 Out-Null

Description


View progress of a command that retrieves all domain users.

EXAMPLE 21

Get-QADUser -Inactive

Description


Retrieve the user accounts that meet any of the default inactivity conditions (inactive accounts).

EXAMPLE 22

Get-QADUser -Inactive:$false

Description


Retrieve the user accounts that do not meet any of the default inactivity conditions (active accounts).

EXAMPLE 23

Get-QADUser -InactiveFor 30

Description


Retrieve the user accounts that remain in the expired state for 30 or more days, or have the password age of 30 or more days, or have not been used to log on for 30 or more days.

EXAMPLE 24

Get-QADUser -Inactive -PasswordNotChangedFor 10

Description


Retrieve the user accounts that meet the default expiry-related or logon-related inactivity condition, or have the password unchanged for 10 or more days.

EXAMPLE 25

Get-QADUser -Inactive:$false -ExpiredFor 20

Description


Retrieve the user accounts that do not meet any of the default inactivity conditions, but remain in the expired state for 20 or more days.

EXAMPLE 26

Get-QADUser -InactiveFor 30 -NotLoggedOnFor 60

Description


Retrieve the user accounts that are expired for 30 or more days, or have the password age of 30 or more days, or have not been used to log on for 60 or more days.

EXAMPLE 27

Get-QADUser DomainName\UserName |	
 Select-Object -ExpandProperty ProxyAddresses

Description


For a given mailbox user, list the e-mail addresses that are currently assigned to the mailbox.