New-CMUserCollection
Create a user collection.
Syntax
ByName (Default)
New-CMUserCollection
-LimitingCollectionName <String>
-Name <String>
[-Comment <String>]
[-RefreshSchedule <IResultObject>]
[-RefreshType <CollectionRefreshType>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
ByValue
New-CMUserCollection
-InputObject <IResultObject>
-Name <String>
[-Comment <String>]
[-RefreshSchedule <IResultObject>]
[-RefreshType <CollectionRefreshType>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
ById
New-CMUserCollection
-LimitingCollectionId <String>
-Name <String>
[-Comment <String>]
[-RefreshSchedule <IResultObject>]
[-RefreshType <CollectionRefreshType>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Description
Use this cmdlet to create a user collection based on a specific limiting collection. The limiting collection determines which users can be a member of the user collection that you create. For instance, when you use the All Users collection as the limiting collection, the new collection can include any user in the Configuration Manager hierarchy.
You can then add users to the collection with membership rules. To add members to the user collection, use one of the following membership rule cmdlets:
- Add-CMUserCollectionDirectMembershipRule
- Add-CMUserCollectionExcludeMembershipRule
- Add-CMUserCollectionIncludeMembershipRule
- Add-CMUserCollectionQueryMembershipRule
For more information, see How to create collections in Configuration Manager.
Note
Run Configuration Manager cmdlets from the Configuration Manager site drive, for example PS XYZ:\>. For more information, see getting started.
Examples
Example 1: Create a user collection
This command creates a collection for all users in the Sales department. Specifying All Users for the LimitingCollectionName parameter indicates that the new collection can include any user in the Configuration Manager hierarchy.
New-CMUserCollection -Name "Sales" -LimitingCollectionName "All Users"
Parameters
-Comment
Specify an optional comment to describe and identify this collection.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Confirm
Prompts you for confirmation before running the cmdlet.
Parameter properties
| Type: | SwitchParameter |
| Default value: | False |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | cf |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-InputObject
Specify an object for the limiting collection. To get this object, use the Get-CMCollection or Get-CMUserCollection cmdlets.
Parameter properties
| Type: | IResultObject |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | LimitingCollection |
Parameter sets
ByValue
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | True |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-LimitingCollectionId
Specify the ID of the limiting collection. This value is the CollectionID property, for example, XYZ00012 or SMS00001.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
ById
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-LimitingCollectionName
Specify the name of the limiting collection.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
ByName
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Name
Specify the name for the new user collection.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-RefreshSchedule
If you set the RefreshType parameter to either Periodic or Both, use this parameter to set the schedule. Specify a schedule object for when the site runs a full update of the collection membership. To get this object, use the New-CMSchedule cmdlet.
Parameter properties
| Type: | IResultObject |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-RefreshType
Specify how the collection membership is updated:
Manual(1): An administrator manually triggers a membership update in the Configuration Manager console or with the Invoke-CMCollectionUpdate cmdlet.Periodic(2): The site does a full update on a schedule. It doesn't use incremental updates. If you don't specify a type, this value is the default.Continuous(4): The site periodically evaluates new resources and then adds new members. This type is also known as an incremental update. It doesn't do a full update on a schedule.Both(6): A combination of bothPeriodicandContinuous, with both incremental updates and a full update on a schedule.
If you specify either Periodic or Both, use the RefreshSchedule parameter to set the schedule.
Note
The None value (0) is functionally the same as Manual.
Parameter properties
| Type: | CollectionRefreshType |
| Default value: | None |
| Accepted values: | None, Manual, Periodic, Continuous, Both |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-WhatIf
Shows what would happen if the cmdlet runs. The cmdlet doesn't run.
Parameter properties
| Type: | SwitchParameter |
| Default value: | False |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | wi |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.