internal/Test-DbaDeprecation.ps1
|
function Test-DbaDeprecation { <# .SYNOPSIS Tests whether a function or one of its parameters was called by a bad name. .DESCRIPTION Tests whether a function or one of its parameters was called by a bad name. This allows giving deprecation warnings - once per session - whenever a user uses something we are planning on removing. For example, when renaming a function, we give a grace period by adding an Alias for that function with its old name. However, we do not want to carry along this alias forever, so we give warning ahead of time using this function. When reaching the specified version, we then can safely remove the alias. Furthermore, this function is used for testing, whether such a removal was properly done. .PARAMETER DeprecatedOn The version this parameter or alias will be removed in. Generally, deprecated parameters and aliases should only be removed on major releases. .PARAMETER FunctionName Automatically filled with the calling function. The name of the function that contains either a deprecated alias or parameter. .PARAMETER Call The InvocationInfo of the calling function. Automatically filled. .PARAMETER Parameter The parameter that has become deprecated. On renamed parameters, keep a parameter-alias. This function will notice, when the alias is used. .PARAMETER Alias The alias of the command that will be deprecated. .PARAMETER CustomMessage This function will generate a default message. However, this may not always be appropriate. Use CustomMessage to tailor a response to the necessity of the moment. .PARAMETER Silent Replaces user friendly yellow warnings with bloody red exceptions of doom! Use this if you want the function to throw terminating errors you want to catch. .EXAMPLE PS C:\> Test-DbaDeprecation -DeprecatedOn "1.0.0.0" -Parameter 'Details' Will - once per session - complain if the parameter 'Details' is used. Will cause tests to fail, if it's still in the code after release 1.0.0.0. .EXAMPLE PS C:\> Test-DbaDeprecation -DeprecatedOn "1.0.0.0" -Alias Copy-SqlDatabase Will - once per session - complain if the alias 'Copy-SqlDatabase' is used. Will cause tests to fail, if it's still in the code after release 1.0.0.0. #> [CmdletBinding()] Param ( [Parameter(Mandatory = $true)] [Version] $DeprecatedOn, [string] $FunctionName = (Get-PSCallStack)[0].Command, [object] $Call = (Get-PSCallStack)[0].InvocationInfo, [Parameter(ParameterSetName = "Param", Mandatory = $true)] [string] $Parameter, [Parameter(ParameterSetName = "Alias", Mandatory = $true)] [string] $Alias, [string] $CustomMessage, [bool] $Silent = $Silent ) switch ($PSCmdlet.ParameterSetName) { "Param" { $ast = [System.Management.Automation.Language.Parser]::ParseInput($Call.Line, [ref]$null, [ref]$null) $objects = $ast.FindAll({ $args[0] -is [System.Management.Automation.Language.CommandAst] }, $true) $sub = $objects | Where-Object Parent -Like "$($Call.InvocationName)*" | Select-Object -First 1 if ($sub.CommandElements | Where-Object ParameterName -EQ $Parameter) { if ($CustomMessage) { $Message = $CustomMessage } else { $Message = "Using the parameter $Parameter is deprecated. This parameter will be removed in version $DeprecatedOn, check in the documentation what parameter to use instead" } Write-Message -Message $Message -Level Warning -Silent $Silent -FunctionName $FunctionName -Once "Deprecated.Alias.$Alias" } } "Alias" { if ($Alias -eq $Call.InvocationName) { if ($CustomMessage) { $Message = $CustomMessage } else { $Message = "Using the alias $Alias is deprecated. This alias will be removed in version $DeprecatedOn, use $FunctionName instead" } Write-Message -Message $Message -Level Warning -Silent $Silent -FunctionName $FunctionName -Once "Deprecated.Alias.$Alias" } } } } |