New-SCUserRole

Creates a user role for a group of VMM users.

Syntax

New-SCUserRole [-Name] <String> [-Description <String>] [-ID <Guid>] [-JobGroup <Guid>] [-JobVariable <String>]
 [-OnBehalfOfUser <String>] [-OnBehalfOfUserRole <UserRole>] [-PROTipID <Guid>] [-ParentUserRole <UserRole>]
 [-RunAsynchronously] -UserRoleProfile <Profile> [-VMMServer <ServerConnection>] [<CommonParameters>]

Description

The New-SCUserRole cmdlet creates a user role for a group of Virtual Machine Manager (VMM) users. You can create the following user roles: Delegated Administrator, Read-Only Administrator, and Self-Service User. Only one Administrator role exists. You cannot create another Administrator role or delete the existing one.

If you are a member of a Delegated Administrator user role, you can create a user role. However, the scope of the new user role must be a subset of the scope of its parent user role.

After you create a user role, you can use the Set-SCUserRole cmdlet to rename the user role, to add or remove members, and to add or modify the scope of objects that members of the role can manage. For a Self-Service user role, you can specify which actions members of a Self-Service user role can take on their virtual machines, and you can define a quota that limits the number of virtual machines self-service users can create. Although you cannot create or remove the Administrator role or limit its scope, you can use Set-SCUserRole to add or remove members to that role.

For information about how to modify the properties of a user role, type Get-Help Set-SCUserRole.

Examples

Example 1: Create a Delegated Administrator user role

PS C:\> New-SCUserRole -Name "ContosoDelegatedAdmin" -Description "Delegated Administrators for the Contoso.com domain" -UserRoleProfile "DelegatedAdmin"

This command creates a delegated administrator user role named ContosoDelegatedAdmin, provides the description Delegated Administrators for the Contoso.com domain, and uses the UserRoleProfile parameter to designate the user role type as Delegated Administrator.

Example 2: Create a Self Service user role

PS C:\> $SelfServiceRole = New-SCUserRole -Name "ContosoSelfServiceUsers" -UserRoleProfile "SelfServiceUser"

This command creates a new user role named ContosoSelfServiceUsers, uses the UserRoleProfile parameter to designate the new user role type as Self-Service user, and stores the new user role object in the $SelfServiceRole variable.

Parameters

-Description

Specifies a description for the user role.

Type:String
Required:False
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-ID

Specifies the unique ID for the new user role.

Type:Guid
Required:False
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-JobGroup

Specifies an identifier for a series of commands that runs as a set just before the final command that includes the same job group identifier runs.

Type:Guid
Required:False
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-JobVariable

Specifies a variable in which job progress is tracked and stored.

Type:String
Required:False
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-Name

Specifies a name for the new user role.

Type:String
Required:True
Position:0
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-OnBehalfOfUser

Specifies a user name. This cmdlet operates on behalf of the user that this parameter specifies.

Type:String
Required:False
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-OnBehalfOfUserRole

Specifies a user role. To obtain a user role, use the Get-SCUserRole cmdlet. This cmdlet operates on behalf of the user role that this parameter specifies.

Type:UserRole
Required:False
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-PROTipID

Specifies the ID of the Performance and Resource Optimization tip (PRO tip) that triggered this action. This parameter lets you audit of PRO tips.

Type:Guid
Required:False
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-ParentUserRole

Specifies an existing VMM user role as the parent of the new user role.

Type:UserRole
Required:False
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-RunAsynchronously

Indicates that the job runs asynchronously so that control returns to the command shell immediately.

Type:SwitchParameter
Required:False
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-UserRoleProfile

Specifies the type of profile that is the basis for the new user role. The acceptable values for this parameter are:

- DelegatedAdmin

  • ReadOnlyAdmin
  • SelfServiceUser

Type:Profile
Parameter Sets:Administrator, DelegatedAdmin, TenantAdmin, SelfServiceUser, ReadOnlyAdmin
Required:True
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-VMMServer

Specifies the VMM server on which this cmdlet creates a user role.

Type:ServerConnection
Required:False
Position:Named
Default value:None
Accept pipeline input:True (ByValue)
Accept wildcard characters:False

Outputs

UserRole

This cmdlet returns a **UserRole** object.