Functions/New-Credential.ps1

function New-Credential {
    <#
.SYNOPSIS
    Returns a [PSCredential] given a passed UserName, and either a string 'Password' or a securestring 'SecureString'
.DESCRIPTION
    Returns a [PSCredential] given a passed UserName, and either a string 'Password' or a securestring 'SecureString'. Behavior is controlled by ParameterSetName
.PARAMETER UserName
    A mandatory parameter of type [string] that represents a username that you are creating. Can be of the form 'username', or 'domain\username', or 'username@company.com'. In both parameter set names 'SecureString' and 'Password'
.PARAMETER SecureString
    A mandatory parameter of type [securestring] that represents a securestring password. In parameter set name 'SecureString'
.PARAMETER Password
    A mandatory parameter of type [tring] that represents a plaintext password. In parameter set name 'Password'
.EXAMPLE
    $Credential = New-Credential -UserName 'donaldduck' -Password 'Quack'
.EXAMPLE
    $SecureString = Read-Host -Prompt 'Enter password' -AsSecureString
    $Cred2 = New-Credential -UserName 'mickeymouse' -SecureString $SecureString
.INPUTS
    'string', 'securestring'
 
    or
 
    'string', 'string'
.OUTPUTS
    'PSCredential'
.NOTES
    Medium to High impact as this function will return the password, albeit hidden from default view
#>


    [CmdletBinding(DefaultParameterSetName = 'SecureString', ConfirmImpact = 'Medium')]
    [OutputType('PSCredential')]
    Param
    (

        [Parameter(Mandatory, Position = 0, ParameterSetName = 'SecureString')]
        [Parameter(Mandatory, Position = 0, ParameterSetName = 'Password')]
        [string] $UserName,

        [Parameter(Mandatory, Position = 1, ParameterSetName = 'SecureString')]
        [securestring] $SecureString,

        [Parameter(Mandatory,HelpMessage='Please enter the Password', Position = 1, ParameterSetName = 'Password')]
        [string] $Password

    )
    #endregion parameter

    begin {
        Write-Verbose -Message "Starting [$($MyInvocation.Mycommand)]"
        Write-Verbose -Message "ParameterSetName [$($PsCmdlet.ParameterSetName)]"
    }

    process {
        switch ($PsCmdlet.ParameterSetName) {
            'SecureString' {
            }
            'Password' {
                Write-Verbose -Message 'Creating $SecureString'
                $securestring = ConvertTo-SecureString -String $Password -AsPlainText -Force
            }
        }
        New-Object -TypeName 'PSCredential' -ArgumentList $UserName, $SecureString
    }

    end {
        Write-Verbose -Message "Ending $($MyInvocation.Mycommand)"
    }

}