Why automation framework require proxy function for every powershell cmdlet?

1
votes

In my new project team, for each powershell cmdlet they have written proxy function. When i asked the reason for this practice, they said that it is a normal way that automation framework would be written. They also said that If powershell cmdlet is changed then we do not need to worry ,we can just change one function.

I never saw powershell cmdlets functionality or names changed.

For example, In SQL powershell module they previously used snapin then they changed to module. but still the cmdlets are same. No change in cmdlet signature. May be extra arguments would have added.

Because of this proxy functions , even small tasks taking long time. Is their fear baseless or correct? Is there any incident where powershell cmdlets name or parameter changed?

2
powershell

2 Answers

3
votes

I guess they want to be extra safe. Powershell would have breaking changes here and here sometimes but I doubt that what your team is doing would be impacted by those (given the rare nature of these events). For instance my several years old scripts continue to function properly up to present day (and they were mostly developed against PS 2-3).

I would say that this is overengineering, but I cant really blame them for that.

1
votes

4c74356b41 makes some good points, but I wonder if there's a simpler approach.

Bear with me while I restate the situation, just to ensure I understand it.

My understanding of the issue is that usage of a certain cmdlet may be strewn about the code base of your automation framework.

One day, in a new release of PowerShell or that module, the implementation changes; could be internal only, could be parameters (signature) or even cmdlet name that changes.

The problem then, is you would have to change the implementation all throughout your code.

So with proxy functions, you don't prevent this issue; a breaking change will break your framework, but the idea is that fixing it would be simpler because you can fix up your own proxy function implementation, in one place, and then all of the code will be fixed.

Other Options

Because of the way command discovery works in PowerShell, you can override existing commands by defining functions or aliases with the same name.

So for example let's say that Get-Service had a breaking change and you used it all over (no proxy functions).

Instead of changing all your code, you can define your own Get-Service function, and the code will use that instead. It's basically the same thing you're doing now, except you don't have to implement hundreds of "empty" proxy functions.

For better naming, you can name your function Get-FrameworkService (or something) and then just define an alias for Get-Service to Get-FrameworkService. It's a bit easier to test that way.

One disadvantage with this is that reading the code could be unclear, because when you see Get-Service somewhere it's not immediately obvious that it could have been overwritten, which makes it a bit less straightforward if you really wanted to call the current original version.

For that, I recommend importing all of the modules you'll be using with -Prefix and then making all (potentially) overridable calls use the prefix, so there's a clear demarcation.

This even works with a lot of the "built-in" commands, so you could re-import the module with a prefix:

Import-Module Microsoft.PowerShell.Utility -Prefix Overridable -Force

TL;DR

So the short answer:

  • avoid making lots and lots of pass-thru proxy functions
  • import all modules with prefix
  • when needed create a new function to override functionality of another
  • then add an alias for prefixed_name -> override_function 
Import-Module Microsoft.PowerShell.Utility -Prefix Overridable -Force
Compare-OverridableObject $a $b

No need for a proxy here; later when you want to override it:

function Compare-CanonicalObject { <# Stuff #> }
New-Alias Compare-OverridableObject Compare-CanonicalObject

Anywhere in the code that you see a direct call like:

Compare-Object $c $d

Then you know: either this intentionally calls the current implementation of that command (which in other places could be overridden), or this command should never be overridden.

Advantages:

  • Clarity: looking at the code tells you whether an override could exist.
  • Testability: writing tests is clearer and easier for overridden commands because they have their own unique name
  • Discoverability: all overridden commands can be discovered by searching for aliases with the right name pattern i.e. Get-Alias *-Overridable*
  • Much less code
  • All overrides and their aliases can be packaged into modules