Public/Set-UserGroup.ps1
|
function Set-UserGroup { <# .SYNOPSIS Modifies the properties of a local security group. .DESCRIPTION The Set-UserGroup cmdlet modifies the properties of a local security group in the Windows Security Accounts Manager. .PARAMETER InputObject Specifies the local group account to modify. .PARAMETER Name Specifies the local group to be modified. .PARAMETER SID Specifies a security group from the local Security Accounts Manager by SecurityIdentifier. .PARAMETER Description A descriptive comment. .EXAMPLE Set-UserGroup -Name "MyGroup" -Description "New description" Sets the description for the local group MyGroup. #> [CmdletBinding(SupportsShouldProcess = $true)] param( [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, ParameterSetName = 'InputObject')] [UserGroup]$InputObject, [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, ParameterSetName = 'Default')] [string]$Name, [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, ParameterSetName = 'SecurityIdentifier')] [System.Security.Principal.SecurityIdentifier]$SID, [Parameter(Mandatory = $true)] [ValidateNotNull()] [string]$Description ) process { $group = $null $targetName = $null if ($null -ne $InputObject) { $group = $InputObject $targetName = $group.ToString() } elseif ($null -ne $Name) { # Check if group exists first $group = [LocalAccountHelper]::GetUserGroupByName($Name) if ($null -eq $group) { $ex = [GroupNotFoundException]::new($Name, $Name) Write-Error -Message $ex.Message -ErrorId 'GroupNotFound' -Category ObjectNotFound -TargetObject $Name return } $targetName = $Name } elseif ($null -ne $SID) { # Check if group exists first $group = [LocalAccountHelper]::GetUserGroupBySid($SID) if ($null -eq $group) { $ex = [GroupNotFoundException]::new($SID.Value, $SID) Write-Error -Message $ex.Message -ErrorId 'GroupNotFound' -Category ObjectNotFound -TargetObject $SID return } $targetName = $SID.ToString() } if ($null -eq $group) { return } if ($PSCmdlet.ShouldProcess($targetName, 'Set group')) { try { [LocalAccountHelper]::SetUserGroup($group, $Description) } catch [System.UnauthorizedAccessException] { $ex = [AccessDeniedException]::new($targetName) Write-Error -Message $ex.Message -ErrorId 'AccessDenied' -Category PermissionDenied -TargetObject $targetName } catch { Write-Error -Message $_.Exception.Message -ErrorId 'InvalidUserGroupOperation' -Category InvalidOperation -TargetObject $targetName } } } } |