Public/Rename-User.ps1
|
function Rename-User { <# .SYNOPSIS Renames a local user account. .DESCRIPTION The Rename-User cmdlet renames a local user account in the Security Accounts Manager. .PARAMETER InputObject Specifies the local user account to rename. .PARAMETER Name Specifies the local user account to be renamed. .PARAMETER SID Specifies the local user to rename by SecurityIdentifier. .PARAMETER NewName Specifies the new name for the local user account. .EXAMPLE Rename-User -Name "John" -NewName "Jane" Renames the local user John to Jane. #> [CmdletBinding(SupportsShouldProcess = $true)] param( [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, ParameterSetName = 'InputObject')] [LocalUser]$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 { $user = $null if ($null -ne $InputObject) { $user = $InputObject $targetName = $user.ToString() } elseif ($null -ne $Name) { # Check if user exists first $user = [LocalAccountHelper]::GetLocalUserByName($Name) if ($null -eq $user) { $ex = [UserNotFoundException]::new($Name, $Name) Write-Error -Message $ex.Message -ErrorId 'UserNotFound' -Category ObjectNotFound -TargetObject $Name return } $targetName = $Name } elseif ($null -ne $SID) { # Check if user exists first $user = [LocalAccountHelper]::GetLocalUserBySid($SID) if ($null -eq $user) { $ex = [UserNotFoundException]::new($SID.Value, $SID) Write-Error -Message $ex.Message -ErrorId 'UserNotFound' -Category ObjectNotFound -TargetObject $SID return } $targetName = $SID.ToString() } if ($null -eq $user) { return } if ($PSCmdlet.ShouldProcess($targetName, "Rename user account to $NewName")) { try { [LocalAccountHelper]::RenameLocalUser($user, $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 'InvalidLocalUserOperation' -Category InvalidOperation -TargetObject $targetName } } } } |