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

Thanks to Oisin’s discovery, I’ve written a module to make it trivially easy to create your own custom type accelerators in PowerShell 2. I’ll add a few more details here in the morning, and I’ll probably add a simulation of a “using” statement to the script (although you’ll practically never want to use it), but for now, here’s the script … the new CTP3 Get-Help will tell you everything you need to know.

Maybe I should try that New-CommandBlogPost thing that James has been hawking over on the PowerShell team blog…

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.

Get-Command returns functions

By default Get-Command used to return only apps, scripts in your path, and cmdlets… The new CTP3 default invocation includes functions. This is mostly a recognition of the increased power of functions with the arrival of that advanced function features (formerly known as script cmdlets).

Advanced Functions

Advanced Functions is the new name for what was called “Script Cmdlets” in CTP2. Instead of adding a CMDLET keyword to the language, we now have a [CmdletBinding()] attribute which can be specified in your functions —just before the PARAM block— which will enable all of the features which were exclusive to CMDLETs in CTP2. NOTE: Unlike in C#, the parentheses in [CmdletBinding()] are REQUIRED to differentiate it from PowerShell’s type notation.

I will write an entire article about Advanced Functions soon, because there is a lot to write about, and after struggling with them for several hours today, it’s clear that the about * documentation for them is mostly wrong and misleading. The PowerShell team blog post about Advanced Functions has some working examples, so start there and in the release notes (none of the about_functions_advanced samples will run — I wrote a bug about this, please vote for it if you agree).

Functions have help!

This is, without a doubt, my favorite feature so far. You can embed help for functions in comments inside the function block, and Get-Help will find and parse it. Not only that, but your functions get automatic implementation of the -? parameter, bringing script functions closer to equality with compiled cmdlets, in terms of user experience.

Cmdlet name collisions

You can now have two snapins or modules loaded which export the same cmdlets (or different ones with the same name). PowerShell resolves to the last one loaded by default. You can run previously loaded ones that have been hidden by specifying the full namespace\cmdlet path.

Modules

There has been a complete refactoring of the module system such that the environment variable and default Module folders have been renamed, and the cmdlets as well (Add-Module becomes Import-Module and New-Module). The “Module Metadata” support has been finished, so you can create .psd1 metadata files which wrap modules and expose additional features. Thanks to the data in those Metadata files, Get-Module now returns much more information about modules, including the author’s name, copyright info, etc. This is another area where I’ll have a whole article about the new functionality up soon, as an update to my former article about modules.

Lots of other things

It’s not my intention to rewrite the release notes here… I just wanted to call attention to some of the stuff that’s most interesting to me. You should definitely read the release notes

Other improvements

Eventing

In a sense, we had PSEvents in CTP2. But in this release they’ve been beefed up, renamed a little, and are become a very useful way for cmdlet authors to expose functionality (you can create your own system-level events which users can write scripts to handle and target).

Exception Handling

I’m not really sure this counts as improved over CTP2, but a lot of people seem to be unaware that PowerShell v2 now supports the C#-like try{ ... } catch { ... } finally { ... } block, and allows you to specify multiple exceptions to be trapped by a single catch statement (I wish C# would implement that).

Command-line Parameters

There are two new parameters to PowerShell:

-WindowStyle

This lets you execute PowerShell “Hidden” or at least “Minimized” so that your startup or scheduled tasks don’t need to pop up windows that interrupt the user! Hurray! In fact, not only can you launch PowerShell hidden, you can hide the running host window by just running a PowerShell instance in it (it stays hidden even after PowerShell exits — that might be considered a bug, but I’m not really sure what I think of it). This would be most useful if you were trying to do GUI stuff in your scripts, but I’m sure you can think of other uses… here’s an example (IAA= is just a space, encoded).

It even works in DOS:

-ExecutionPolicy

You can override the ExecutionPolicy on the command line. This is very interesting (and rather worrying). It’s my opinion that this option completely breaks the Execution Policy system because you don’t have to be elevated/administrator to use the flag.

What I’m trying to say is that in a business environment, where users are not administrators on their own systems, this flag seems to allow users to ignore the administrator’s script execution policy, and even modify their default shortcuts to just start with whatever setting they prefer. Currently (in v1 and v2) the Set-ExecutionPolicy cmdlet requires administrative rights (and an elevated console, on Vista), but this commandline argument means that anyone can just run PowerShell -EP Unrestricted to get around that.

This seems to render the setting a lot less useful, since it only applies if the user doesn’t know they can override it, or if the setting is unrestricted enough that the user doesn’t feel constrained by it. My guess is that the ExecutionPolicy parameter should either disappear, or be constrained to making the policy more restrictive than the default. Here’s my scary batch/vbs script:

If you have an opinion, vote here

Possible bugs?

[char] comparisons are supposed to be alphabetical

Formerly, comparisons of objects of type [char] (characters) were done as integers (against the unicode character value), but in CTP3 characters are supposed to behave as text, basically the same way strings do when it comes to case-insensitive comparison (except that, to keep them compatible, you must specify -IEQ to compare insensitive). This works fine in a case like: ([char]'a') -ieq 'A' but inexplicably fails for ([char]'a') -ieq ([char]'A') … which leads me to believe the team has simply hard-coded an exception for the CHAR-to-STRING comparison, and missed CHAR-to-CHAR. I wrote that up too, and hope you’ll take the time to agree or disagree (a couple of people in IRC mentioned that after this strangeness they just want it back the way it was).

I’m sure I’ll have more to write here tomorrow …

Disclaimer: it wasn’t really my idea.

Edit: Someone suggested I should link to the required PoshCode scripts:

• Invoke-Http and Receive-Http are in the HttpRest script
• Out-Voice

• Start is originally from PSCX"

Wouldn’t it be cool to be able to “require” those like a ruby GEM?