PowerShell - Using Aliases for Functions in Modules

.PowerShell - Aliases.md

Use Aliases in PowerShell Modules

This is useful when you want to maintain backward compatibility when renaming functions in a module so that old code can still use the old name.

In the module file

New-Alias -Name "Get-Policy" -Value "Get-PolicyById"

In the module definition file

    AliasesToExport   = @(
        "Get-TimeRangeIsValid"
    )

In the test file

Describe '<_>' -ForEach @('Test-TimeRangeIsValid', 'Get-TimeRangeIsValid') {

An_Example_Of_Aliases_In_PowerShell.psd1

    # Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export.
    AliasesToExport   = @(
        "Get-TimeRangeIsValid"
    )

An_Example_Of_Aliases_In_PowerShell.psm1

<#
This is an example of creating an alias for functions in a module. This is useful for backward compatibility as you change the names of functions in a module.
#>

# Create a new alias
New-Alias -Name "Get-Policy" -Value "Get-PolicyById"

function Get-PolicyById {
    <#
    .SYNOPSIS
    Gets a Policy by its ID.
    #>
    [CmdletBinding()]
    [OutputType([PSCustomObject])]
    param (
        [Parameter(Mandatory = $true)][AppDSession] $AppDSession,
        [Parameter(Mandatory = $true)][ValidateRange('NonNegative')][Int] $AppId,
        [Parameter(Mandatory = $true)][ValidateRange('NonNegative')][Int] $PolicyId
    )
    $uri = "$($AppDSession.BaseUrl)/controller/alerting/rest/v1/applications/$($AppId)/policies/$($PolicyId)"
    $Result = Invoke-RestMethod -Uri $uri -WebSession $AppDSession.WebSession
    return $Result
}

An_Example_Of_Aliases_In_PowerShell.Tests.ps1

<#
This is an example using ForEach to run the same test code against multiple functions.
#>

Describe '<_>' -ForEach @('Test-TimeRangeIsValid', 'Get-TimeRangeIsValid') {
    BeforeAll {
        $Global:MethodName = $_
    }

    It 'Succeeds' {
        (& $Global:MethodName -TimeRangeType 'Before_Now' -DurationInMinutes 5 -ThrowException $false) | Should -BeTrue -ErrorAction Continue
        (& $Global:MethodName -TimeRangeType 'Before_Time' -DurationInMinutes 5 -EndTime 5000 -ThrowException $false) | Should -BeTrue -ErrorAction Continue
        (& $Global:MethodName -TimeRangeType 'After_Time' -DurationInMinutes 5 -StartTime 5000 -ThrowException $false) | Should -BeTrue -ErrorAction Continue
        (& $Global:MethodName -TimeRangeType 'Between_Times' -startTime 4000 -EndTime 5000 -ThrowException $false) | Should -BeTrue -ErrorAction Continue
    }

    It "Throws with invalid combination of inputs TimeRangeType '<timeRangeType>' DurationInMinutes '<durationInMinutes>' StartTime '<startTime>' EndTime '<endTime>'" -ForEach @(
        @{ TimeRangeType = 'BEFORE_NOW'; DurationInMinutes = [nullable[int]]$Null; StartTime = [nullable[int]] $Null; EndTime = [nullable[int]]$Null; ExpectedMessage = 'Time range validation failed: DurationInMinutes must be specified for BEFORE_NOW'; },
        @{ TimeRangeType = 'BETWEEN_TIMES'; DurationInMinutes = [nullable[int]]$Null; StartTime = [nullable[int]]$Null; EndTime = [nullable[int]]$Null; ExpectedMessage = 'Time range validation failed: StartTime and EndTime must be specified for BETWEEN_TIMES'; },
        @{ TimeRangeType = 'BETWEEN_TIMES'; DurationInMinutes = [nullable[int]]$Null; StartTime = [nullable[int]]1; EndTime = [nullable[int]]$Null; ExpectedMessage = 'Time range validation failed: StartTime and EndTime must be specified for BETWEEN_TIMES'; },
        @{ TimeRangeType = 'BETWEEN_TIMES'; DurationInMinutes = [nullable[int]]$Null; StartTime = [nullable[int]]$Null; EndTime = [nullable[int]]2; ExpectedMessage = 'Time range validation failed: StartTime and EndTime must be specified for BETWEEN_TIMES'; },
        @{ TimeRangeType = 'BEFORE_TIME'; DurationInMinutes = [nullable[int]]$Null; StartTime = [nullable[int]]$Null; EndTime = [nullable[int]]$Null; ExpectedMessage = 'Time range validation failed: DurationInMinutes and EndTime must be specified for BEFORE_TIME' },
        @{ TimeRangeType = 'AFTER_TIME'; DurationInMinutes = [nullable[int]]$Null; StartTime = [nullable[int]]$Null; EndTime = [nullable[int]]$Null; ExpectedMessage = 'Time range validation failed: DurationInMinutes and StartTime must be specified for AFTER_TIME' }
    ) {
        { & $Global:MethodName -TimeRangeType $TimeRangeType -DurationInMinutes $DurationInMinutes -StartTIme $StartTime -EndTime $EndTime -ThrowException $true } | Should -Throw -ExpectedMessage $ExpectedMessage
    }
}