1+ function Test-AliasDeprecation {
2+ <#
3+ . SYNOPSIS
4+ Tests whether a function or one of its parameters was called by a bad name.
5+ Taken from dbatools.io
6+ . DESCRIPTION
7+ Tests whether a function or one of its parameters was called by a bad name.
8+ This allows giving deprecation warnings - once per session - whenever a user uses something we are planning on removing.
9+ For example, when renaming a function, we give a grace period by adding an Alias for that function with its old name.
10+ However, we do not want to carry along this alias forever, so we give warning ahead of time using this function.
11+ When reaching the specified version, we then can safely remove the alias.
12+ Furthermore, this function is used for testing, whether such a removal was properly done.
13+ . PARAMETER DeprecatedOn
14+ The version this parameter or alias will be removed in.
15+ Generally, deprecated parameters and aliases should only be removed on major releases.
16+ . PARAMETER FunctionName
17+ Automatically filled with the calling function.
18+ The name of the function that contains either a deprecated alias or parameter.
19+ . PARAMETER Call
20+ The InvocationInfo of the calling function.
21+ Automatically filled.
22+ . PARAMETER Parameter
23+ The parameter that has become deprecated.
24+ On renamed parameters, keep a parameter-alias. This function will notice, when the alias is used.
25+ . PARAMETER Alias
26+ The alias of the command that will be deprecated.
27+ . PARAMETER CustomMessage
28+ This function will generate a default message. However, this may not always be appropriate.
29+ Use CustomMessage to tailor a response to the necessity of the moment.
30+ . PARAMETER EnableException
31+ By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message.
32+ This avoids overwhelming you with "sea of red" exceptions, but is inconvenient because it basically disables advanced scripting.
33+ Using this switch turns this "nice by default" feature off and enables you to catch exceptions with your own try/catch.
34+ . EXAMPLE
35+ PS C:\> Alias-DbaDeprecation -DeprecatedOn "1.0.0.0" -Parameter 'Details'
36+ Will - once per session - complain if the parameter 'Details' is used.
37+ Will cause tests to fail, if it's still in the code after release 1.0.0.0.
38+ . EXAMPLE
39+ PS C:\> Alias-DbaDeprecationn -DeprecatedOn "1.0.0.0" -Alias Copy-SqlDatabase
40+ Will - once per session - complain if the alias 'Copy-SqlDatabase' is used.
41+ Will cause tests to fail, if it's still in the code after release 1.0.0.0.
42+ #>
43+ [CmdletBinding ()]
44+ param (
45+ [Parameter (Mandatory )]
46+ [Version ]
47+ $DeprecatedOn ,
48+
49+ [string ]
50+ $FunctionName = (Get-PSCallStack )[0 ].Command,
51+
52+ [object ]
53+ $Call = (Get-PSCallStack )[0 ].InvocationInfo,
54+
55+ [Parameter (ParameterSetName = " Param" , Mandatory )]
56+ [string ]
57+ $Parameter ,
58+
59+ [Parameter (ParameterSetName = " Alias" , Mandatory )]
60+ [string ]
61+ $Alias ,
62+
63+ [string ]
64+ $CustomMessage ,
65+
66+ [bool ]
67+ $EnableException = $EnableException
68+ )
69+
70+ switch ($PSCmdlet.ParameterSetName ) {
71+ " Param"
72+ $ast = [System.Management.Automation.Language.Parser ]::ParseInput($Call.Line , [ref ]$null , [ref ]$null )
73+ $objects = $ast.FindAll ( { $args [0 ] -is [System.Management.Automation.Language.CommandAst ] }, $true )
74+ $sub = $objects | Where-Object Parent -Like " $ ( $Call.InvocationName ) *" | Select-Object - First 1
75+
76+ if ($sub.CommandElements | Where-Object ParameterName -eq $Parameter ) {
77+ if ($CustomMessage ) { $Message = $CustomMessage }
78+ else { $Message = " Using the parameter $Parameter is deprecated. This parameter will be removed in version $DeprecatedOn or before, check in the documentation what parameter to use instead"
79+
80+ Write-PSFMessage - Message $Message - Level Warning - FunctionName $FunctionName - Once " Deprecated.Alias.$Alias "
81+ }
82+ }
83+
84+ " Alias"
85+ if ($Alias -eq $Call.InvocationName ) {
86+ if ($CustomMessage ) { $Message = $CustomMessage }
87+ else { $Message = " Using the alias $Alias is deprecated. This alias will be removed in version $DeprecatedOn or before, use $FunctionName instead."
88+
89+ Write-PSFMessage - Message $Message - Level Warning - FunctionName $FunctionName - Once " Deprecated.Alias.$Alias "
90+ }
91+ }
92+ }
93+ }
0 commit comments