Short description

Describes how PowerShell determines which command to run.

Long description

Command precedence describes how PowerShell determines which command to runwhen a session contains more than one command with the same name. Commandswithin a session can be hidden or replaced by commands with the same name. Thisarticle shows you how to run hidden commands and how to avoid command-nameconflicts.

Command precedence

When a PowerShell session includes more than one command that has the samename, PowerShell determines which command to run using the following rules.

If you specify the path to a command, PowerShell runs the command at thelocation specified by the path.

For example, the following command runs the FindDocs.ps1 script in theC:\TechDocs directory:

C:\TechDocs\FindDocs.ps1

You can run any executable command using its full path. As a security feature,PowerShell doesn't run executable commands, including PowerShell scripts andnative commands, unless the command is located in a path listed in the$Env:PATH environment variable.

To run an executable file that's in the current directory, specify the fullpath or use the relative path.\ to represent the current directory.

For example, to run theFindDocs.ps1 file in the current directory, type:

.\FindDocs.ps1

If you don't specify a path, PowerShell uses the following precedence orderwhen it runs commands.

1. Alias
2. Function
3. Cmdlet (seeCmdlet name resolution)
4. External executable files (including PowerShell script files)

Therefore, if you typehelp, PowerShell first looks for an alias namedhelp, then a function namedhelp, and finally a cmdlet namedhelp. Itruns the firsthelp item that it finds.

For example, if your session contains a cmdlet and a function, both namedGet-Map, when you typeGet-Map, PowerShell runs the function.

Resolve items with the same names

As a result of these rules, items can be replaced or hidden by items with thesame name.

Items arehidden orshadowed if you can still access the original item,such as by qualifying the item name with a module name.

For example, if you import a function that has the same name as a cmdlet in thesession, the cmdlet ishidden, but not replaced. You can run the cmdlet byspecifying its module-qualified name.

When items arereplaced oroverwritten, you can no longer access theoriginal item.

For example, if you import a variable that has the same name as a variable inthe session, the original variable is replaced. You can't qualify a variablewith a module name.

If you create a function at the command line and then import a function withthe same name, the original function is replaced.

Find hidden commands

TheAll parameter of theGet-Command cmdlet gets all commands withthe specified name, even if they're hidden or replaced. Beginning in PowerShell3.0, by default,Get-Command gets only the commands that run when you typethe command name.

In the following examples, the session includes aGet-Date function and aGet-Date cmdlet. You can useGet-Command to determine which command ischosen first.

Get-Command Get-Date

CommandType     Name                      ModuleName-----------     ----                      ----------Function        Get-Date

Uses theAll parameter to list availableGet-Date commands.

Get-Command Get-Date -All

CommandType     Name                 Version    Source-----------     ----                 -------    ------Function        Get-DateCmdlet          Get-Date             7.0.0.0    Microsoft.PowerShell.Utility

Get-Command where -All

CommandType Name                     Version      Source----------- ----                     -------      ------Alias       where -> Where-ObjectApplication where.exe                10.0.22621.1 C:\Windows\system32\where.exe

You can run particular commands by including qualifying information thatdistinguishes the command from other commands that might have the same name.For cmdlets, you can use the module-qualified name. For executables, you caninclude the file extension. For example, to run the executable version ofwhere usewhere.exe.

Use module-qualified names

Using the module-qualified name of a cmdlet allows you to run commands hiddenby an item with the same name. For example, you can run theGet-Date cmdletby qualifying it with its module nameMicrosoft.PowerShell.Utility or itspath. When you use module-qualified names, the module can be automaticallyimported into the session depending on the value of$PSModuleAutoLoadingPreference.

Using module-qualified names ensures that you are running the command that youintend to run. This is the recommended method of calling cmdlets when writingscripts that you intend to distribute.

The following example illustrates how to qualify a command by including itsmodule name.

New-Alias -Name "Get-Date" -Value "Get-ChildItem"Microsoft.PowerShell.Utility\Get-Date

Tuesday, May 16, 2023 1:32:51 PM

To run aNew-Map command from theMapFunctions module, use itsmodule-qualified name:

MapFunctions\New-Map

To find the module from which a command was imported, use theModuleNameproperty of commands.

(Get-Command <command-name>).ModuleName

For example, to find the source of theGet-Date cmdlet, type:

(Get-Command Get-Date).ModuleName

Microsoft.PowerShell.Utility

If you want to qualify the name of the command using the path to the module,you must use the forward slash (/) as the path separator and the backslashcharacter (\) before the command name. Use the following example to run theGet-Date cmdlet:

//localhost/c$/Progra~1/PowerShell/7-preview/Modules/Microsoft.PowerShell.Utility\Get-Date

The path can be a full path or a path that is relative to the current location.On Windows, you can't use a drive-qualified path. You must use a UNC path, asshown in the previous example, or a path that's relative to the current drive.The following example assumes that your current location is in theC: drive.

/Progra~1/PowerShell/7-preview/Modules/Microsoft.PowerShell.Utility\Get-Date

Use the call operator

You can also use the call operator (&) to run hidden commands by combining itwith a call toGet-ChildItem (the alias isdir),Get-Command orGet-Module.

The call operator executes strings and scriptblocks in a child scope. For moreinformation, seeabout_Operators.

For example, use the following command to run the function namedMap that'shidden by an alias namedMap.

& (Get-Command -Name Map -CommandType Function)

or

& (dir Function:\map)

You can also save your hidden command in a variable to make it easier to run.

For example, the following command saves theMap function in the$myMapvariable and then uses theCall operator to run it.

$myMap = (Get-Command -Name map -CommandType Function)& ($myMap)

Replaced items

Areplaced item is one that you can no longer access. You can replace itemsby importing items of the same name from a module.

For example, if you type aGet-Map function in your session, and you import afunction calledGet-Map, it replaces the original function. You can'tretrieve it in the current session.

Variables and aliases can't be hidden because you can't use a call operator ora qualified name to run them. When you import variables and aliases from amodule, they replace variables in the session with the same name.

Cmdlet name resolution

When you don't use the qualified name of a cmdlet, PowerShell checks to see ifthe cmdlet is loaded in the current session. If there are multiple modulesloaded that contain the same cmdlet name, PowerShell uses the cmdlet from thefirst module found alphabetically.

If the cmdlet isn't loaded, PowerShell searches the installed modules andautoloads the first module that contains the cmdlet and runs that cmdlet.PowerShell searches for modules in each path defined in the$Env:PSModulePathenvironment variable. The paths are searched in the order that they're listedin the variable. Within each path, the modules are searched in alphabeticalorder. PowerShell uses the cmdlet from the first match it finds.

Avoid name conflicts

The best way to manage command name conflicts is to prevent them. When you nameyour commands, use a unique name. For example, add your initials or companyname acronym to the nouns in your commands.

When you import commands into your session from a PowerShell module or fromanother session, you can use thePrefix parameter of theImport-ModuleorImport-PSSession cmdlet to add a prefix to the nouns in the names ofcommands.

For example, the following command avoids any conflict with theGet-Date andSet-Date cmdlets that come with PowerShell when you import theDateFunctions module.

Import-Module -Name DateFunctions -Prefix ZZ

Run external executables

On Windows. PowerShell treats the file extensions listed in the$Env:PATHEXTenvironment variable as executable files. Files that aren't Windows executablesare handed to Windows to process. Windows looks up the file association andexecutes the default Windows Shell verb for the extension. For Windows tosupport the execution by file extension, the association must be registeredwith the system.

You can register the executable engine for a file extension using theftypeandassoc commands of the CMD command shell. PowerShell has no direct methodto register the file handler. For more information, see the documentation fortheftype command.

For PowerShell to see a file extension as executable in the current session,you must add the extension to the$Env:PATHEXT environment variable.

See also

• about_Aliases
• about_Functions
• about_Path_Syntax
• Alias-Provider
• Function-Provider
• Get-Command
• Import-Module
• Import-PSSession