Using Module-Qualified Cmdlet Names

• PowerShell Studio

Open-source projects and new methods of distributing modules, such as PowerShellGet and the PowerShell Gallery, have significantly increased the availability of Windows PowerShell modules. While we once relied on modules from Microsoft, we now can select from hundreds of new modules developed in the community.

The upside of having so many modules is vastly increased utility. But, all of those new modules make cmdlet and function name conflicts more likely. Many modules use prefixes, but some are likely to slip through.

To be sure that you’re using the cmdlet or function that you selected, and not a different one with the same name, use a module-qualified cmdlet name. This is valuable if you write scripts and modules, and critical if you share them, where they might run on a system with a module set that you cannot anticipate.

PowerShell Studio has a new feature that qualifies all of the command names in your script. You can turn it on before you share a script and, if you choose, turn it off. PowerShell Studio also recognizes module-qualified names and uses syntax coloring to indicate when a command is correctly qualified.

Module-qualified names were introduced in Windows PowerShell 3.0.

Module-Qualified Cmdlet Names

To specify the module of a function or cmdlet, use the following syntax:

[ModuleName]\[Cmdlet_or_Function_Name]

For example, to specify the Get-Process cmdlet in Microsoft.PowerShell.Management, type:

Microsoft.PowerShell.Management\Get-Process

The module prefix is valid in any command. For example:

Microsoft.PowerShell.Core\Invoke-Command -Session $s -ScriptBlock {Microsoft.PowerShellCore\Save-Help -Path D:\HelpFiles}

You can also use module-qualified commands in splatted parameters. For example:

$s = Microsoft.PowerShell.Core\New-PSSession -ComputerName VMSvr01
 
$Params = @{Session=$s; ScriptBlock={Microsoft.PowerShell.Management\Get-Process}}
 
Microsoft.PowerShell.Core\Invoke-Command @Params

PowerShell Studio Support for Module-Qualified Commands

Beginning in Version 4.2.90, PowerShell Studio recognizes and supports module-qualified commands.

• To qualify all of the commands in your script, type Ctrl + Shift + H.

• To remove the module qualification from all commands in your script, type Ctrl + Alt + H.

Also, if you type a module qualified name for a particular cmdlet, and that module does not have a cmdlet with that name, such as a Get-Command command in the Microsoft.PowerShell.Utility module, PowerShell Studio labels it as “unknown.”

If you type a correct module qualification, PowerShell Studio recognizes it and colors it blue (or the color specified for cmdlets names in your Option settings).

Name Conflicts in Windows PowerShell

When two commands have the same name (and neither is module-qualified), the Windows Powershell command precedence rules determine which command runs. The precedence rules are documented in about_Command_Precedence, but, in short, the precedence order is:

1. Alias
2. Function
3. Cmdlet
4. Native Windows command

When commands with the same name have the same type, Windows PowerShell runs the command that was added to the session last. Because that is arbitrary and not predictable, it’s best to qualify the command name.

In Windows PowerShell 5.0, you can also install different versions of the same module in the same or different directories (and scope) on the same computer. It would be very useful to be able to qualify the version, as well as the module, of a command, but that’s a subject for a different blog post.

June Blender is a technology evangelist at SAPIEN Technologies, Inc. You can reach her at This email address is being protected from spambots. You need JavaScript enabled to view it. or follow her on Twitter at @juneb_get_help.

• Prev
• Next