Public/Rename-UserGroup.ps1
|
function Rename-UserGroup { <# .SYNOPSIS Renames a local security group. .DESCRIPTION The Rename-UserGroup cmdlet renames a local security group in the Security Accounts Manager. .PARAMETER InputObject Specifies the local group account to rename. .PARAMETER Name Specifies the local group to be renamed. .PARAMETER SID Specifies a security group from the local Security Accounts Manager by SecurityIdentifier. .PARAMETER NewName Specifies the new name for the local security group. .EXAMPLE Rename-UserGroup -Name "MyGroup" -NewName "NewGroupName" Renames the local group MyGroup to NewGroupName. #> [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, Position = 1)] [ValidateNotNullOrEmpty()] [string]$NewName ) 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, "Rename group to $NewName")) { try { [LocalAccountHelper]::RenameUserGroup($group, $NewName) } 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 } } } } |