Author Archive

August 31st at 9PM eastern, we’re having a live IRC chat with author, developer, and Microsoft PowerShell team member Lee Holmes to celebrate the release of the 2nd edition of his book: Windows PowerShell Cookbook. There are more details on the Virtual PowerShell User Group page about joining IRC and about this chat in particular

I was trying to write the first real post for that series today, but I got really distracted, and instead …

• Created a Virtual Launch Party for Lee Holmes’ 2nd Edition Windows PowerShell Cookbook
• Updated my SharpSsh Module (which I wrote about ages ago in Scriptable SSH From PowerShell) to accept PSCredential objects or passwords, use CmdletBinding and have parameter set overrides
• Updated my JSON Module to support Pipeline binding in ConvertFrom-Json and to call out the fact that it properly supports dynamic objects if you specify PSObject as the type.
• Updated (and finally released) my Presentation module

• Updated (and finally released) my PowerTest Module (it now has setup/teardown and supports filtering tests by name and category). This module needs it’s own blog post too, but you can get an idea what it’s about in the first hour of the Live Meeting recording of my Testing with PowerShell presentation.

Now that I mention all that stuff, there’s a few things from last week that bear mentioning too:

• I wrote a sweet little function to wrap the LoreSoft.MathExpressions assembly, which lets you do all sorts of math inline in the PowerShell console.
• I also updated my HttpRest module to work with the latest 2.1 release of MindTouch Dream

• And published my current PowerShell Prompt and PowerShell Profile

And if you haven’t seen them … the week before that I also

• Published a function for invoking Generic Signature Methods from PowerShell which was something I had previously considered impossible.
• Made some very nice updated to ConvertFrom-PropertyString which parses ini files and anything like that…
• Published a trick for getting PowerShell.exe to run in .Net 4 and to allow PowerShell to load binary modules from network paths

• Wrote a function to generate proxy wrappers for OData Services which was closely followed by a full PowerShell OData Module from Doug Finke

So, I’m giving myself a break.

OK, I’m putting this out there to see if I’ve missed anything that would be useful. This is the list of metadata that we’ll be storing about Modules in the PoshCode repository. It duplicates most of the information in the PowerShell Manifests, but it adds more of information that we feel is important for searching, sorting and organizing … and in the PoshCode Module manifests, wildcards are not allowed for any of the “export” values. The export information in the module is intended to represent the initial state of the module after import: listing all the cmdlets, functions, variables and aliases …

PoshCode Module Manifest Format:

GUID

The globally unique identifier for this module. Helps us tell modules apart

Name

The name of this module. Helps us find modules, and helps you guess what they’re for.

ModuleVersion

The version of this module. Together with the GUID, this is the unique key for the module. It should be incremented whenever you release it.

Description

A short description of the module. What it is, what it does, what it’s for.

ModuleType

Tells whether the module is a Script module or a Binary module (if they are both, then they are Binary).

Author

The person(s) who created this module. No organizations here, just people.

Company

A company (if there is one) that created this module or provides support for it.

Copyright

The copyright statement. You should always fill this out and assign copyright to the correct author, group or corporation.

License

The software license(s) that this module can be licensed under. It’s enough to use an acronym like “GPL v2” or “MIT” or “Ms-PL” ... but if you have a custom license you can specify a description of it or the full text of it. Multiple entries are allowed.

LicenseUri

The url(s) for a full copy of the license. If you’re using an open source license you can link to it’s page on opensource.org

Category

We’ll publish our official category list later, but the category is intended to be an assignment to a single category in a hierarchical tree.

Tags

A collection of user-assigned free-text keywords that help to categorize the module and serve as additional search terms.

Homepage

If the module has a home page on the internet, this is the URL. You can use the link to the PoshCode Docs page (which our cmdlets will generate for you) if you don’t have your own page.

Download

This is the link to download the module. If you’re hosting it on PoshCode, we will fill this in. If you’re hosting it elsewhere, this must be a download link. If it’s a commercial module that requires payment, you should leave this link empty unless you have a free trial download. Note: I’m still working on the commercial angle. Would it be helpful to include the price here? If we offered a way to sell your modules through PoshCode, would you use it?

RequiredAssemblies

Assembly names (or relative paths, if the assemblies are included in the module folder) for assemblies that must be loaded before the module will work. These should be the Assembly FullName, not a partial name.

RequiredModules

The names and versions (and GUIDs) of any modules that this module depends on.

PowerShellVersion

The version of Powershell required (2.0, for now).

FrameworkVersion

The version of the .Net Framework required. The framework version implies the CLR version, so we’ll just stick to this. I’m still toying with the idea of saying the list is 2.0, 3.0, 3.5, 3.5.1, and 4.0 … rather than allowing the normal version with the full four digits.

VersionChanges

This is either the list of changes in this version, or a complete list of the changes in previous versions.

Exported Cmdlets

The list of (binary) cmdlets exported by this module.

Exported Functions

The list of script functions exported by this module.

Exported Aliases

The list of aliases exported by this module.

Exported Variables

The list of variables exported by this module.

Deprecated things …

I’m leaning against having these items in the PoshCode manifest — they don’t seem to be helpful for finding or sorting or understanding a module.

• ModuleFile
• ModuleToProcess
• FormatsToProcess

• TypesToProcess

Comments Requested

I’m hoping for feedback about this list, what I might be missing, or if there’s anything in here I should leave out … let me hear it!

In PowerShell the question of scope is too complicated and convoluted. I’m going to try to help you understand it, but I’m not guaranteeing that I will be able to make it seem any simpler than it actually is. Hopefully, I won’t make it more complicated than it inherently is

In PowerShell you always have three named variable scopes: script, local and global. The default scope is always the same as the local scope, so when you set a variable without specifying the scope, it’s always set at local scope. One thing to note is that you can access these named scopes through the $variable notation, or through the variable drive, so all of the following are equivalent:

A side note: the PSProvider drive notation means that when you’re in strict mode, if you want to test for the existence of a variable without causing an error, the simplest way to do it is with Test-Path Variable:Var…

What’s so hard about that?

Well, the question is: what scope are you in “right now” when a line of code is executing from a function or a script …

Sometimes local scope is ALSO script scope, and sometimes, script scope is also global scope. Specifically: when you’re typing at the console, all three scopes are the same.

Let’s write a function to determine what named scope we’re in:

By setting a variable, and then testing the named scopes, we can verify what scope we were in when we set the variable. Of course, there’s no point testing the Local scope, because we already know that is where we are… then we return a hashtable of booleans indicating which scopes are active.

If you dot-source that Get-Scope function, you’ll find the scope that you’re in where you dot-source it:

• if you do it at the interactive prompt it should tell you all three scopes are set
• if you do it in a script file it should tell you Local and Script
• but if you do it in a function, it will always just tell you “local” — and will not tell you if the function is in a script or not … nor how deep you are.

• and if you do it in a module, the results will depend on whether Find-Scope is defined in the module or not (this is very weird)

So are we done?

Not even remotely. On top of the named scopes, PowerShell also has nested scopes. Each script, function, scriptblock, etc. adds to the nested scopes, and takes you further from the global scope. On top of that, PowerShell has Modules. In a module, scope is flattened. Specifically, in a module, the default scope becomes the Script scope, which in this case is not actually reserved for a single file, but for any scripts, functions, etc that are executed from within that module’s context.

To determine nesting level of the scope, we must do something like this:

As long as modules aren’t involved, that will tell you how many scopes there are between you and global scope (and thus, return zero when dot-source from the console commandline).

This falls apart a bit if you’re in a module (in a module, you can’t get to global scope by increasing the scope value — effectively, the highest you can go is script scope, but in reality you can still access global scope by naming it). To determine if you’re in a module, you can simply check for the existence of the $PSScriptRoot variable, or verify that $Invocation.MyCommand.Module is set to something.

Additionally, if you’re in a module, you need to define this function in that module for it to work at all.

There’s one more thing you could use to help you learn what scope you’re in, and that is the Get-PSCallStack cmdlet. This will tell you how many commands have been called to get you where you are. It’s usually the same as the Scope Depth, but not when it’s in a script file, etc.

Here’s my finished scope digging function:

• Remember: modules sometimes flatten scope.

• Remember: when calling this function you should dot-source it, and pass it $MyInvocation

As as side note and counter-example, take for instance this module:

All three of those functions will return ScopeDepth = 2 (the test-scope function, and the module itself), but the StackDepth will increase correctly. I don’t know why. It’s late, so I’m going to stop writing before I get more confusing.

I’m starting a new series of blog posts about Best Practices for scripting in PowerShell, and I was going to start at the beginning with a requirement that you should use [CmdletBinding()], but the explanation of that will have to wait for the next post, because a bug in PowerShell 2.0 has surfaced which can only be avoided by carefully following a couple of rules … and I’m going to issue those rules as the prefix for the best practices.

Rule #1: Never use Get-Module -ListAvailable in a module.

You need to run the command outside of your module. The simplest way to do that is to use Invoke-Command { Get-Module -List Available } … that should give you the same output, but without the nasty side effects.

There is a bug in the ListAvailable parameter, which causes PowerShell to mark other modules which are already loaded as being “nested” in your module.

It does that to all modules which have correct manifests, and the problem is that if your module gets unloaded later (using Remove-Module), it removes these nested modules as well … even though the user had loaded them separately.

Edit: 2010-08-05

I should have mentioned this originally (so I’m adding it now): one of the reasons developers were using Get-Module with -ListAvailable was to get information about their own module during the initial load (such as to check module versions, or load data from the PrivateData). If you were doing that, you can use Test-ModuleManifest instead with the path to your manifest: Test-ModuleManifest $PSScriptRoot\ModuleName.psd1

Rule #2: Do not use Import-Module in a module.

If you have a dependency on another module, you should load it by specifying it as a NestedModules in your module manifest.

There is a bug in the way that Remove-Module unloads modules which causes modules which are loaded from inside your module (whether by Import-Module or by Get-Module -ListAvailable), to be unloaded completely even if they’ve been previously loaded in the console (global) scope interactively by the user (or via their profile).

You could possibly make an exception to this rule, if the module is actually in your module’s folder (and thus, not easily loadable from outside your module), but you’re making the assumption that no one will ever use that module outside of your module.

Modules loaded via the metadata file’s NestedModules property don’t have this problem, so you should always load nested modules that way.

Note: This is from a wiki page I just wrote on Importing Binary Modules from Network Shares which discusses not just the solution below that works for .Net 2.0 but also how to solve the problem on .Net 4.0 (e.g.: in PoshConsole). I will most likely not keep this page up to date, so you should refer to that wiki if you need more information.

Almost every author of a binary module has probably had someone ask about this at some point, because there’s always someone who has their user profiles stored on a network location, and therefore installed their modules on that network path and can’t get them to load because they get a warning that .Net “Failed to grant minimum permission requests.”

Before we get into this any further let me just say: by far the simplest thing to do is to create a local folder on your local hard drive, add that to your environment PSPathModules variable, and just install your modules there.

Other than that, the solution depends on the version of .Net that you’re using (you can tell by checking the $PSVersionTable.CLRVersion

The .Net 2.0 framework (and 3.0 and 3.5 and 3.5 SP1)

The problem is not a PowerShell problem at all, it’s a .Net problem. The .Net framework 2.0 (remember that PowerShell targets 2.0, and is actually based on .Net 1.1) didn’t trust assemblies loaded from network shares. You can fix that for an individual assembly or for a whole share using the Caspol tool.

A complete discussion of that tool and it’s myriad command-line options is beyond me, but for a simple solution, you can run this command specifying the server and share you want to load from (in my example the “Modules” share on the “ProfileServer” server).

Hopefully the only thing that needs explaning there is that 1.2 is the default “Local Intranet” group, and that CasPol.exe is in your Framework Runtime directory. Once you’ve run that, you’ll be able to import any modules that are in subdirectories of that share.

Note: You must run the version of CasPol.exe which is in the lcation defined by the GetRuntimeDirectory() command (it’s important to use the same version as the runtime you want to be affected).

You can read more about importing binary modules from network shares, including how it changed in .Net 3.5 SP1 and why it’s not automatically fixed in .Net 4 over on the PoshCode wiki.

Someone asked me this week about this old post about custom ICompareers, and wondered if I could rewrite it for PowerShell 2.0 and wrap it in an advanced function … and it made me think: I really should update some of my old posts from PowerShell 1 and the preview releases of 2 so that they are accurate and useful. I thought I’d throw this out there and let you guys who read my stuff tell me which ones I should update first — I’m likely to get sick of it after just a few of them, so it’s important that I update the ones you want the most first

Based on traffic I’m going to pre-select these three, but anything else is fair game too:

• Trap Exceptions in PowerShell
• Scriptable SSH in PowerShell

• PowerShell Modules

I’ve been working on a ton of new functionality for this next release of PowerBoots … and now that I’m getting close to ready to release, I thought it was time to work on the performance! Here’s a completely trivial example:

WPK:

Command : $boxes = 1..100 | % { New-TextBox -Text Foo -FontFamily Consolas -On_GotFocus { $_ } }
Duration : 5.25153s

Current PowerBoots 0.2:

Command : $boxes = 1..100 | % { TextBox -Text Foo -FontFamily Consolas -On_GotFocus { $_ } }
Average : 9.40994s

You can see why I thought I should probably work on improving that. It was bad.

PowerBoots 0.3 yesterday:

Command : $boxes = 1..100 | % { TextBox -Text Foo -FontFamily Consolas -On_GotFocus { $_ } }
Duration : 7.43874s

PowerBoots 0.3 tonight:

Command : $boxes = 1..100 | % { TextBox -Text Foo -FontFamily Consolas -On_GotFocus { $_ } }
Duration : 0.34103s

Now, if you’re like me, you’re probably thinking I screwed up something and that TextBox isn’t actually getting created right …

Postscript: ran another test. A little more useful. I have 248 fonts on my system. I have an “Samples” script which shows them all:

Old PowerBoots:

Duration : 19.39894s

New PowerBoots:

Duration : 3.53100s

If you’ve been writing advanced PowerShell 2.0 functions, you’ve probably used some of the Validate* attributes to enforce valid parameter values, and you may have noticed that their error messages leave a lot to be desired. For example, imagine that you have a parameter which takes a 10-digit phone number:

The problem

Mark Schill (Meson) brought this up at our virtual PowerShell User Group on IRC tonight: the error messages are confusing and not helpful. For instance, when you try that function and pass an invalid phone number (let’s say you forget to include the area code), you get this error message:

Test-PhoneNumber : Cannot validate argument on parameter 'number'. The argument "555-1212" does not match the "^\(?\d{3}\)?[-\s.]?\d{3}[-\s.]\d{4}$" pattern. Supply an argument that matches "^\(?\d{3}\)?[-\s.]?\d{3}[-\s.]\d{4}$" and try the command again.

There aren’t very many people who can read regular expressions, but only someone who can would really find the entirety of that error message useful. Everyone else is going to get (at most) this out of it: Cannot validate argument on parameter ‘number’. The argument “555-1212” does not match ... yadda, yadda.

That being the case, we’d like to hide the rest of that message … particularly the part that says: “Supply an argument that matches …” which is, frankly, just annoying or insulting depending on who your users are. In fact, as Mark suggested, I’d like to replace it with a custom message … something like: Cannot validate argument on parameter ‘number’. The supplied value is not a valid phone number. Please supply a full 10-digit number like: (123) 555-1212

Custom Validation Properties

So, this evening I decided to do something about it. It’s really pretty simple to write your own Validate*Attribute … you just have to derive from ValidateEnumeratedArgumentsAttribute, and override ValidateElement. Here’s an example ValidatePattern that supports a custom error message. I’ll paste the C# code separately, but basically you can just use Add-Type -TypeDefinition and pass this code as a here-string …

Using it in PowerShell

When you use that in PowerShell, assuming that you called Add-Type with that as-is, you only have to change your function slightly, using ValidatePatternEx instead of ValidatePattern, and passing named properties, including the message.

But once you do, you will get much better error messages:

Test-PhoneNumber : Cannot validate argument on parameter 'number'. Please enter a 10-digit phone number like: (123) 555-1212 ValidatePatternEx failure, the value didn't match the pattern: ^\(?\d{3}\)?[-\s.]?\d{3}[-\s.]\d{4}$

Other Applications

Of course, you may have noticed that this is really a completely custom parameter validator. You aren’t limited to just adding nice error messages to the validation error — you can create whatever validator you can dream up. Let me know what you come up with!

As a warm up to writing my best-practices posts, I decided to answer this frequently asked question on the PowerShell wiki at PoshCode. I’m not going to repeat the whole post here, but suffice it to say that there’s a good explanation on the How Do I Install a PowerShell Module page, along with this script: