The Dilemma

This post was inspired by a recent occurrence at work.  I have built a framework which constructs documents based on a lists of functions in a module specific to that kind of document.

I found myself running into an issue where even though I knew there was a command named a certain thing, and that the function was correctly exported from the module, PowerShell wasn’t finding the command.

My code looked something like this:

$module='Module1'
$Steps='Get-CustomerData','Get-MarketingData','New-CustomerMarketingDocument'
# each function takes a hashtable as a parameter and outputs a hashtable
$state=@{}
foreach($Step in $Steps){
    $stepCmd=Get-Command -Name $step -module $module
    $state=& $StepCmd -state @State
}

So why was PowerShell not working nicely for me? The problems has to do with how PowerShell loads functions. Let’s take a step back

PowerShell’s Command-Loading Procedure

For now, let’s assume we have a simple script module called Module1.

For a script module to be “discoverable” by PowerShell, it must exist in one of the folders listed in the PSModulePath environment variable.

This PowerShell will show you the folders that PowwerShell will look in:

$env:PSModulePath.Split(';')

Here are the results from a PowerShell 7 instance:

When you try to run a command (or use Get-Command), PowerShell will first look to see if the command is already loaded. IF so, then it just runs (or outputs) the command you asked for.

If it isn’t already present, PowerShell looks through valid modules for the function. As a reminder, valid modules:

• Exist in one of the folders in PSModulePath
• Have a “module file” named the same as the folder it’s in (for instance, module1\module1.psm1)
• Module Files extensions are psm1, psd1, dll, or cdxml.
• File is syntactically valid and not blocked

If the command is present, and exported (via Export-ModuleMember and Functions/CmdletsToExport in the manifest), then the module will be loaded silently and the command (now present) will be executed or output.

Pretty simple, right?

In my case, I had a valid module, in a valid folder, in the PSModulePath, with the named function exported from it.  What could have gone wrong?

PowerShell Command Hiding

The problem was that I had gotten used to naming functions somewhat generically, and had duplicated one.

I had two modules which contained a function called Get-DocumentData.  The command discovery procedure worked fine, it just found the wrong command.

Let’s see an example of what I’m talking about.

Consider two modules, module1 and module2.

Module1 has a single command, Get-Stuff

function Get-Stuff{
    'in module1'
}

Similarly, Module2 has a Get-Stuff command which outputs ‘in module2’.

If I were to open a new PowerShell session and type Get-Stuff, PowerShell would find module1’s copy of Get-Stuff first and load it (that is, module1).

If that were the only Get-Stuff, the story would be over.

In this case, I have two different modules with Get-Stuff functions.

To get to the second, I can import the module explicitly:

Import-Module module2

You can verify the output below:

Now, we’ve imported both modules and executed both functions. What does Get-Command tell us?

First, it only shows us the command from module2, that is, the most recently loaded.

If we ask for the command from module1, we won’t find it:

You might notice that the error is misleading.  There sure is a Get-Stuff command available, just not from module1 (or at least not available from module1).

But if we ask for “all” Get-Stuff commands, there it is:

So, why didn’t Get-Command show it?

The answer (which you can read in more detail here) is that the module1 version of the command has been hidden, and Get-Command (without -All) shows commands that aren’t hidden.

Adding -All to our earlier search for the command works like we had expected:

Note that there’s another way to get a module-specific command, and that’s by using a fully-qualified command reference like module1\get-stuff:

I beat my head against this one for quite a while.  I was even considering writing a blog post about it when I read the about_command_precedence help topic (for research) and figured out the “issue”.

Thanks for reading,

Mike

Have you ever been writing a PowerShell script and wanted verbose output to show up no matter what?

You may have thought of doing something like this:

#Save the preference variable so you can put it back later
$saveVerbosePreference=$VerbosePreference

#Override the preference variable to make the output show up
$VerbosePreference='Continue'
Write-Verbose 'This is an important message you need to see'

#Leave it like you found it
$VerbosePreference=$saveVerbosePreference

If you do that, you’ll get the verbose message every time, just like you wanted.

Fortunately for you, there’s a much easier way to get the message:

#By adding the -Verbose switch, you override the preference for this cmdlet
Write-Verbose 'This is an important message you need to see' -Verbose

Wasn’t that easy?

Just a quick note to mention a couple of things I’ve come across with PowerShell modules that encapsulate DSLs (Domain Specific Languages, specifically WPFBot3000).

PowerShell Command Name Warnings

PowerShell modules have always issued warnings if they contain commands that don’t use approved verbs.  What’s fun with modules for DSLs is that the commands in general don’t use verbs at all.  Since these commands aren’t “proper”, you might expect a warning.  You won’t get one, though.

PowerShell Module Autoloading

PowerShell modules have had autoloading since v3.0.  Simply put, if you use a cmdlet that isn’t present in your session PowerShell will look in all of the modules in the PSModulePath and try to find the cmdlet somewhere.  If it finds it, PowerShell imports the module quietly behind the scenes.

This doesn’t work out of the box with DSLs.  The reason is simple.

DSLs generally have commands that aren’t in the verb-noun form that PowerShell is expecting for a cmdlet, so it doesn’t try to look for the command at all.

The fix for this is simple (for WPFBot3000, at least).  All I’ve done is replace the two top-level commands (Window and Dialog) with well-formed cmdlet names (New-WPFBotWindow and Invoke-WPFBotDialog).  Then, I create aliases (Window and Dialog) pointing to these commands.

Now that I think of it, I’m not sure why that works.  If PowerShell is looking for the aliases, why wasn’t it finding the commands?  Nevertheless, it works.

That’s all for today, just a couple of oddities.

–Mike

Some Background

Before I start, I should probably take a minute to explain what a DSL is and why you would want to use one.

A DSL (domain-specific language) is a (usually small) language where the vocabulary comes from a specific problem domain (or subject).  Note that this has nothing to do with Active Directory domains, so that might have been confusing.

By using words that are naturally used in describing problems in this subject, it is possible to write using the DSL in ways that look less like programming and more like describing the solution.

For instance, in Pester, you might write part of a unit test like this (3.0 syntax):

It "Has a non-negative result" {
   $result | Should Be GreaterThan 0
}

There are some aspects of this that look like PowerShell (the $, the | and the {}), but in general it doesn’t look much like code. It looks more like a description of the test that we’re writing.

In the WPF DSL that I’m describing in these posts, I want to be able to write PowerShell scripts that create WPF applications in a way that the “WPF” part of the script is easy. At least, a lot easier than trying to generate XAML or automate the WPF classes using brute force. That being said, the code in my DSL is not some sort of magic, it’s just PowerShell code.

One interesting aspect of DSLs is that because they don’t look quite like code, they often ignore coding conventions. Note that the Pester example had a PowerShell cmdlet called “It”. No verb-noun convention followed there. Also, Using positional parameters is more common in a DSL. Not a problem, just something to be aware of.

Getting Control Values

One of the problems I listed at the end of the previous post (#3) was that reading the text property won’t work once we have other controls to think about besides textboxes.

My solution here has worked out really well. I decided to add a method to any control that I would want to get a value from. The method is called GetControlValue. It is responsible for knowing how to get the values from the control (which, as part of the control object it will have no problem with).

Here’s the updated Textbox function:

function TextBox {
    [CmdletBinding()]
    Param($Name)
    $Properties = @{ Name = $name ;MinWidth=100}
    New-Object System.Windows.Controls.TextBox -Property $properties | 
        Add-Member -Name GetControlValue -MemberType ScriptMethod -Value {$this.Text} -PassThru
}

Since it’s a ScriptMethod, we get to use $this to refer to the control, so $this.Text is the value we want.

With that in place, we need to update the If statement at the end of the Window function to use the ScriptMethod. Here’s what it looks like:

if($window.ShowDialog() -or $true){
if($window.ShowDialog() -or $true){
  $output=[Ordered]@{}
  foreach($item in $controls){
    $output[$item.Name]=$item.GetControlValue()
  }
  [PSCustomObject]$output
}

Conclusion

Here’s the checklist now:

1. Only textboxes? Need several other controls
2. OK/Cancel
3. With other controls, reading the text property won’t be a strategy
4. Nested controls
5. Populating controls
6. Events
7. ContextMenus
8. Setting control properties

Stay tuned for more…

–Mike