A guide to PowerShell’s Advanced Functions

Someone asked on the PowerShell Newsgroup about writing Advanced Functions, and specifically:

looking for a … guide to putting together an advanced function that is visible and usable every time I start Powershell. By visible I mean that when I do a ‘get-command’ I want my [advanced function]s to be listed alongside all the regular cmdlets. What makes that possible? ... what do I need to do to make that happen? Whats the difference between an [advanced function] and a module?

There are lots of articles on the Microsoft PowerShell team blog about both topics, but it seems there’s not really been any sort of step-by-step written, so I posted this to the newsgroup, and since the person who asked the original question said he found it useful, I figured I’d share it here…

An Aside: Advanced Functions vs. Modules

Advanced functions and script modules are unrelated topics. A script module could have nothing but old PowerShell 1 -type functions, hypothetically, it could even not have any functions at all. Advanced functions can be defined in a plain .ps1 script, in your profile, or by typing them in on the command-line, etc. The two things are essentially unrelated except for both being new features in PowerShell 2.0.

How To write an Advanced Function

Step 1: Have something you want to do in a function.

I can’t emphasize enough how important it is that you should have a specific goal here. Writing a script for a specific purpose is much easier, because you don’t have to think about whether or not specific features are necessary, etc.

For the purposes of this example, I want a function to start executables and return me the process object (so I can wait for it to finish, or whatever). I will call it Start-Process.

Step 2: Write a first step for the logic of your function.

Be sure to specify the parameters using the function Name{Param(...)} syntax rather than function Name(...){}, then you will be able to easily convert it to an advanced function by adding [CmdletBinding()] on the line right before the Param like this:

Step 3: Start writing documentation and auto-help, including your parameters.

Step 4: Exploit advanced features by marking up your parameters.

In my case, I had a look at the signature of the start method by running [Diagnostics.Process]::Start.OverloadDefinitions and discovered that it can take credentials too. So I wanted an optional credential parameter. I specified it without a position, and made it part of a non-default parameter set.

I also wanted the params parameter to just take any additional parameters which I pass to the function, and pass them on to the process that I’m starting.

Finally, I wanted the “App” parameter to be able to come from the pipeline. Specifically, I wanted to be able to pass the output of Get-Command or Get-ChildItem to it. In order to enable that, I defined an alias on it to the relevant properties of the objects which come from those two commands

Hopefully you’re getting the idea of what’s possible here …

Bonus Step: Make the function be automatically defined

To be honest, there are a lot of ways to do this, here’s a few:

Option 1. Define it in your Profile.

Include the full text of the function in your Profile.ps1 script or Microsoft.PowerShell_profile.ps1 … just run notepad $Profile and paste the whole function in at the top, then save.

Option 2. Dot-source it in your Profile.

Save the function into a script file, e.g.: “StartProcessFunction.ps1” in your DocumentsWindowsPowerShell folder (next to your profile script) then put the line: . StartProcessFunction.ps1 into your profile script to dot-source it. Using the dot causes the script to be loaded into the context as though you had put the contents of the script in, instead of the dot-source line.

Option 3. Import this function from a script file.

This is basically the same as Option 2, except instead of “.” you can use Import-Module. The Import-Module cmdlet, when used on a file with the .ps1 extension, is basically the same as dot-sourcing it, so there’s not a whole lot of benefit over dot-sourcing in this case.

Option 4. Put the function in a module.

You should only do this if you think you might want to add additional functions to the module. For instance, lets say you want to write a few other functions for working with process objects. If you put them together in the same module (say: “ProcessUtility”) they can share script-scoped variables or private functions, and can be identified as being part of the same module using the Get-Command -Module ProcessUtility command.

If you just have the single function, there’s really no point in changing it to a Module, but I’m not aware of any downside, either.

Option 4a. Make a module by just saving as a .psm1

All you do is save the function into a module file, e.g.: “ProcessUtility.psm1” in your DocumentsWindowsPowerShell folder and then put the line: Import-Module ProcessUtility.psm1 into your profile script.

Option 4b. Make a module folder.

This is by far the most extensible way to create modules. You paste the function into “ProcessUtility.psm1” and then save it into a folder “ProcessUtility” which must be created in one of your module folders. You can figure out where the module folders are by checking $Env:PSMODULEPATH — the normal spot is your DocumentsWindowsPowerShellModules.

Once that’s done, you can import with the simpler command Import-Module ProcessUtility without any extension.

The nice thing about creating the folder is that you can put any additional resources in that folder with it, and get at them using the $PsScriptRoot to define the folder. You can even add additional functions by putting them in separate files (which you can Import-Module from the main file, or you can define using a .psd1, but that’s another article).

Similar Posts:

• Working with multiple versions of PowerShell Modules
• PowerShell Scripting Best Practices: Prefix A
• Rich formatting for PowerShell help
• More Custom Attributes for PowerShell (Parameter Transformation)
• What Scope Am I In?