Of scripts and functions

The first thing to know is that in PowerShell, there’s really no difference between a script (just a file with a .ps1 ending) and a function as you’ll see written below. If you take a function Get-Square, and remove the first and last lines ( Function Get-Square { … } ) you could put them in a file called “Get-Square.ps1” in your PATH, you use them exactly the way you would the function that was pre-loaded into memory by dot-sourcing or pasting it on the command line. Of course, doing that easily requires writing the function parameters on their own line using PARAM(...) syntax, which is why I recommend doing that.

Of functions and the pipeline

When your script or function is used on the pipeline its begin block is called once when the pipeline starts up, and then the process block is called repeatedly: once to process each pipeline object, and finally, the end block is called after all the objects have been processed through the whole pipeline. If you don’t understand that, you should play with this function, try calling it by passing a series of numbers through multiple instances of it:

Incidentally, if you don’t specify the begin, process, or end blocks, the body of your function is treated as the end block. This is so that you can use the special $Input variable, which collects all the things passed in on the pipeline, and thus only works in the end block. That would allow the following function to behave the same way regardless of whether it was invoked on the pipeline or by passing an $InputObject. Notice, however, the difference between this, and the function above.

Our challenge

The basic idea here is to rewrite that function such that it can be used to process a set of numbers from either the pipeline or an argument, without interfering with the processing of other parameters. We require that the function process items as they come in, rather than waiting until it’s received all input before processing them the way Test-SquareEnd does.

In PowerShell 2.0 this would be easy

In the current CTP 3 of PowerShell 2, you just specify ValueFromPipeline=$true for the parameter you want to set from the pipeline, and the function will work the same way whether you pass the numbers as a parameter or along the pipeline — you can even control which attribute of the objects on the pipeline will be used, but that’s a whole other article.

Of course, PowerShell 2.0 is still in beta status, and even after it’s released you may need to write scripts that are backwards compatible to PowerShell 1.0, and the excercise of doing so may help you to understand more about how PowerShell functions work, and particularly how they behave in the pipeline.

Our solution

Since in a PowerShell 1.0 function it’s not really supported directly, we need to do some extra work:

An explanation

Of course, this is just an example method, squaring things isn’t that exciting — but what’s special about it is that the output is almost exactly the same whether you call it with parameters Get-Square 1,2,3,4 or on the pipeline: 1,2,3,4 | Get-Square.

The trick is that it actually executes the same way in either case:

1. If you call it by passing the int (or array of ints) as an argument ($InputObject), it calls itself and passes those values on the pipeline.
2. When the integers are passed on the pipeline, the special pipeline iterator variable $_ is set, and the process block is executed.

1. When it has to (re)invoke itself, it passes any other parameters as parameters, which means you need to have default values for them.

There is one tiny difference in the processing, which in real-world use is practically never noticeable (you can see it in our example if you call it like this):

You’ll see that unlike the PowerShell 2.0 pipeline function, when you pass the numbers as a parameter, the first one of them actually gets passed through the process block before the begin block of the second function on the pipeline is called. This usually doesn’t have any effect, but it’s something to keep in the back of your head.

A few precautions:

• You have to default values for parameters, because you’ll be passing them all as named parameters, in the re-invoke step, and $null can cause problems.
• If you need to do additional processing in the begin block, you should only do so in an ELSE case: when $InputObject is null. That way, the code will only execute once each time you call the function.
• The same goes for the end block: you have to keep your code in an If(!$InputObject) block to avoid executing it twice (when you pass the values as an argument, and it re-invokes itself).

• The test cases in the process block must wrap all of your process block code, so that you don’t process the arguments twice, and you shouldn’t refer to $InputObject, but instead should use the automatic $_ variable which is the value passed when the function is (re)invoked via the pipeline.

Here’s some sample output, in case you’re wondering:

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 functionName{Param(...)} syntax rather than functionName(...){}, then you will convert it to an advanced function by adding [CmdletBinding()] on a line right before the Param:

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).

Improvements to the underlying web search API

You’ve always been able to pass a LIST parameter to the API, and get more results by specifying a higher number. But it never worked with the “path” notation (until now).

That is, you used to be able to do:

• http://poshcode.org/api1?q=start&list=10

• http://poshcode.org/api1?q=start&list=100

To make the API a little easier to use I’ve enhanced it just now:

1. You can now page the search results.
2. You can use the word “limit” instead of “list”
3. If you specify limit=0 (or list=0) I’ll give you everything I’ve got. Please use a little precaution about that, as it could be a LOT of data. I’d much rather you retrieve, say … 25, and then get the second page if you want more.

1. You can use path notation.

So, you can use any of these URLs:

• http://poshcode.org/api1/start/list/25/page/1
• http://poshcode.org/api1/start/limit/25/page/2
• http://poshcode.org/api1?q=start&list=25&page=3

• http://poshcode.org/api1?q=start&limit=25&page=4

There are a lot of search results for “start” ... feel free to play with enhancing the PoshCode module, or incorporating this into your apps, etc.

I should add that you don’t have to specify the limit or page number. By default you’ll get the first 10 items, which should be enough.