Added PSUseFullyQualifiedCmdletNames rule with fix capabilities by genXdev · Pull Request #2122 · PowerShell/PSScriptAnalyzer

René Vaessen (genXdev) · 2025-08-19T04:07:26Z

PR Summary

Add new diagnostic rule PSUseFullyQualifiedCmdletNames to replace aliases and unqualified cmdlet names with fully qualified versions (e.g., ModuleName\CmdletName).

This rule addresses a common pain point in PowerShell scripting where cmdlet names without module prefixes can lead to ambiguity, especially in environments with multiple modules exporting similarly named cmdlets. By enforcing fully qualified names, the rule provides the following benefits:

Automatic module loading: PowerShell will auto-load the specified module if it's not already loaded when the qualified cmdlet is invoked.
Enhanced safety: Prevents accidental execution of the wrong cmdlet due to name conflicts across modules, reducing runtime errors.
Improved readability and maintainability: Explicit module references make the code's intent clearer, aiding in code reviews and long-term upkeep.
Better portability: Scripts become more reliable across different PowerShell environments or versions where module availability might vary.
Reduced ambiguity: Helps avoid issues with alias resolution or unqualified names that might resolve differently based on session state.
Facilitates advanced editor features: Supports better IntelliSense, auto-completion, and static analysis in tools like VS Code.

This change directly relates to PowerShell/PSScriptAnalyzer#2123, where the PowerShell extension for VS Code has been reported to unexpectedly remove module prefixes (e.g., converting MicrosoftTeams\Get-CsLisCivicAddress to Get-CsLisCivicAddress) during code formatting, potentially introducing ambiguities and runtime issues in scripts. This new rule enables users to automatically add or restore fully qualified cmdlet names during analysis or formatting, helping to repair the damage caused by such removals and promoting safer, more explicit scripting practices.

Implemented in Rules/UseFullyQualifiedCmdletNames.cs, with accompanying tests in the test suite to verify replacement logic for aliases (e.g., ls → Microsoft.PowerShell.Management\Get-ChildItem) and unqualified cmdlets.

PR Checklist

PR has a meaningful title
- Use the present tense and imperative mood when describing your changes
Summarized changes
Change is not breaking
Make sure all .cs, .ps1 and .psm1 files have the correct copyright header
Make sure you've added a new test if existing tests do not effectively test the code changed and/or updated documentation
This PR is ready to merge and is not Work in Progress.
- If the PR is work in progress, please add the prefix WIP: to the beginning of the title and remove the prefix when the PR is ready.

Copilot

Pull Request Overview

This PR introduces a new PowerShell Script Analyzer rule PSUseFullQualifiedCmdletNames that enforces the use of fully qualified cmdlet names (e.g., ModuleName\CmdletName) instead of aliases or unqualified names to improve script reliability and prevent ambiguity.

Implements diagnostic rule with automatic fix capabilities for replacing aliases and unqualified cmdlets
Adds caching mechanism for command resolution to improve performance
Provides localized error messages and correction descriptions

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
Rules/UseFullyQualifiedCmdletNames.cs	Core implementation of the new diagnostic rule with command resolution and fix suggestions
Rules/Strings.resx	Localized string resources for error messages and rule descriptions

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-08-19T04:08:47Z

+
+                var extent = commandAst.CommandElements[0].Extent;
+
+                bool isAlias = commandName != fullyQualifiedName.Split('\\')[1];


The logic for determining if a command is an alias is incorrect. This will incorrectly identify unqualified cmdlets as aliases when the command name matches the actual cmdlet name. Consider checking the resolved command type instead: bool isAlias = resolvedCommand.CommandType == CommandTypes.Alias;

Suggested change

bool isAlias = commandName != fullyQualifiedName.Split('\\')[1];

Not following..

Copilot · 2025-08-19T04:08:48Z

+
+                var extent = commandAst.CommandElements[0].Extent;
+
+                bool isAlias = commandName != fullyQualifiedName.Split('\\')[1];


The Split('\\')[1] operation is performed for every command analysis. Since the actual cmdlet name is already available from the resolution logic above (line 99), consider storing it in a variable to avoid redundant string operations.

Suggested change

bool isAlias = commandName != fullyQualifiedName.Split('\\')[1];

else

{

// Extract actualCmdletName from the cached fullyQualifiedName

int idx = fullyQualifiedName.IndexOf('\\');

actualCmdletName = (idx >= 0 && idx < fullyQualifiedName.Length - 1)

? fullyQualifiedName.Substring(idx + 1)

: fullyQualifiedName;

}

var extent = commandAst.CommandElements[0].Extent;

bool isAlias = commandName != actualCmdletName;

René Vaessen (genXdev) · 2025-08-19T07:01:48Z

@microsoft-github-policy-service agree

I have sole ownership of intellectual property rights to my Submissions and I am not making Submissions in the course of work for my employer.

@microsoft-github-policy-service agree company="Microsoft"

René Vaessen (genXdev) · 2025-08-19T07:03:06Z

René Vaessen (@genXdev) please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.
@microsoft-github-policy-service agree [company="{your company}"]
Options:

(default - no company specified) I have sole ownership of intellectual property rights to my Submissions and I am not making Submissions in the course of work for my employer.
@microsoft-github-policy-service agree
(when company given) I am making Submissions in the course of work for my employer (or my employer has intellectual property rights in my Submissions by contract or applicable law). I have permission from my employer to make Submissions and enter into this Agreement on behalf of my employer. By signing below, the defined term “You” includes me and my employer.
@microsoft-github-policy-service agree company="Microsoft"
Contributor License Agreement

@microsoft-github-policy-service agree

I have sole ownership of intellectual property rights to my Submissions and I am not making Submissions in the course of work for my employer.

@microsoft-github-policy-service agree company="Microsoft"

Liam Peters (liamjpeters) · 2025-08-19T09:10:02Z

👋 Hey René Vaessen (@genXdev), could you please add your tests and docs to the PR for your new rule? If you're still working on it, please title the PR as WIP and mark as draft.

My initial thoughts on this:

This shouldn't be a default rule. I would expect most people would find this behaviour undesirable - it makes even simple scripts incredibly verbose. My suggestion would be to make it a configurable rule, disabled by default. This allows those that want this behaviour to opt into it and still benefit from your hard work. See something like UseSingularNouns as an example for making a rule configurable and offering settings.
If you made the rule configurable, you could add a setting for something like IgnoredModules \ IgnoredNamespaces. For commands in those modules (i.e. Microsoft.PowerShell.Management and Microsoft.PowerShell.Utility) the rule would not expand them into their fully qualified names. This could help with some of the verbosity while still retaining the value you're after.
Looking through the context of the issue raised in the VSCode-PowerShell project, I'm not sure that this rule resolves that original issue (not that that's your stated goal). I think that, depending on order of rule execution/formatting, if your rule runs first to expand the command names to their fully qualified names - then the faulty rule runs to "correct" them - your hard work is undone. If it runs afterward it's simply masking that erroneous behaviour which will still be happening.
The rule name is inconsistent in the PR title (...FullQualified... vs ...FullyQualified...).

René Vaessen (genXdev) · 2025-08-19T22:31:41Z

👋 Hey René Vaessen (@genXdev), could you please add your tests and docs to the PR for your new rule? If you're still working on it, please title the PR as WIP and mark as draft.

I have committed them;
971f02b

My initial thoughts on this:

This shouldn't be a default rule. I would expect most people would find this behaviour undesirable - it makes even simple scripts incredibly verbose. My suggestion would be to make it a configurable rule, disabled by default. This allows those that want this behaviour to opt into it and still benefit from your hard work. See something like UseSingularNouns as an example for making a rule configurable and offering settings.

Whatever you think is best.

If you made the rule configurable, you could add a setting for something like IgnoredModules \ IgnoredNamespaces. For commands in those modules (i.e. Microsoft.PowerShell.Management and Microsoft.PowerShell.Utility) the rule would not expand them into their fully qualified names. This could help with some of the verbosity while still retaining the value you're after.

If this still desirable, I'll add them, let me know.

Looking through the context of the issue raised in the VSCode-PowerShell project, I'm not sure that this rule resolves that original issue (not that that's your stated goal). I think that, depending on order of rule execution/formatting, if your rule runs first to expand the command names to their fully qualified names - then the faulty rule runs to "correct" them - your hard work is undone. If it runs afterward it's simply masking that erroneous behaviour which will still be happening.

Haven't tested that, for fixing damage, I only enabled my new rule with -Fix

Maybe not the place to mention it, but analyzing 100+ script files at once, I sometimes see 'Collection modified' concurrency exceptions.
I think it is because of SSADictionary, VariablesDictionary, VariableAnalysisDetails in .\Engine\VariableAnalysisBase.cs

René Vaessen (genXdev) · 2025-08-21T18:33:41Z

Also added 'IgnoredModules' parameter and updated tests and docs accordingly

Christoph Bergmeister (bergmeister) · 2025-12-02T22:28:37Z

Sorry it's taken so long. Agree to not enable it by default but otherwise happy to have it. I know some module owners do this for performance reasons and replace commands with the full version as part of their build process. René Vaessen (@genXdev) can you resolve the merge conflict please, I will then greenlight the running of the CI test suite

René Vaessen (genXdev) · 2025-12-03T09:05:32Z

Sorry it's taken so long. Agree to not enable it by default but otherwise happy to have it. I know some module owners do this for performance reasons and replace commands with the full version as part of their build process. René Vaessen (@genXdev) can you resolve the merge conflict please, I will then greenlight the running of the CI test suite

Hi Christoph Bergmeister (@bergmeister),

I've resolved the merge conflict. The conflict was in Strings.resx where my UseFullyQualifiedCmdletNames resource entries overlapped with the new AvoidReservedWordsAsFunctionNames entries from main. I kept both sets of changes.

Merge commit: f6d123d

The branch should now be ready for CI tests to run.

Christoph Bergmeister (bergmeister) · 2026-01-30T17:07:00Z

René Vaessen (@genXdev) There was one test failure, can you look into resolving it please. In the meantime I updated branch again and kicked off new test run, which shows failure still happens there as well

Christoph Bergmeister (bergmeister) · 2026-09-14T20:07:31Z

René Vaessen (@genXdev) kind reminder and please resolve merge conflict again please and review new Copilot comments, sorry for delay

Copilot

🟡 Changes recommended

The fixer can change calls to locally declared functions, and several diagnostics, tests, and documentation details are inaccurate.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (1)

Rules/UseFullyQualifiedCmdletNames.cs:151

Alias detection is case-sensitive, so an ordinary differently-cased cmdlet such as get-command is reported as an alias because its canonical name is Get-Command. Preserve whether the resolved command was an alias, or at least compare these names case-insensitively.

                bool isAlias = commandName != fullyQualifiedName.Split('\\')[1];

Files reviewed: 5/5 changed files
Comments generated: 6
Review effort level: Balanced

+        It "ignores native commands" {
+            $scriptDefinition = @'
+where.exe notepad
+cmd /c dir
+'@
+            $violations = Invoke-ScriptAnalyzer -ScriptDefinition $scriptDefinition -IncludeRule $violationName
+            $violations.Count | Should -Be 0
+        }


René Vaessen (genXdev) · 2026-09-15T23:01:33Z

Christoph Bergmeister (@bergmeister) , sorry for the very long delay!

I've done a full cleanup of this PR:

Rebased onto the latest main and resolved the merge conflict (the usual Strings.resx overlap — my rule's entries now coexist with the other new rules).
Addressed all the Copilot review comments — alias detection is now based on the resolved command type instead of a case-sensitive string comparison; calls to locally-declared functions are skipped; function violations get a function-specific message; the native-command test now actually enables the rule; and the docs/description inaccuracies are fixed.
Investigated the failing test (GetScriptAnalyzerRule's "get Rules with no parameters supplied") — it now passes.
Squashed the history from 11 commits down to a single clean commit.

Could you please trigger the CI run when you get a chance?
Thanks for your patience!

Sean Wheeler (sdwheeler)

We have a new format for the documentation. Please see the template and related documentation. Update your rule documentation to conform to the guidance.

René Vaessen (genXdev) · 2026-09-19T14:30:01Z

Hi Sean Wheeler (@sdwheeler), — I've updated the rule documentation to the new template. Could you take another look?

Christoph Bergmeister (bergmeister) · 2026-09-22T18:54:55Z

René Vaessen (@genXdev) thanks so much but it seems there is still (or again) a merge conflict, should hopefully not be a difficult one

René Vaessen (genXdev) · 2026-09-22T20:07:25Z

Christoph Bergmeister (@bergmeister) Resolved, thanks — rebased onto latest main.

Copilot

Copilot review overview

🟡 Changes recommended

Alias-shadow handling can produce behavior-changing corrections, and the remaining resolution and coverage issues must be addressed.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 · 1

Open (2)

Account for statically declared aliases · New
This test runs the rule with its default Enable = $false, so it passes without exercising…

Resolved since last review (5)

The lookup does not account for functions declared in the analyzed AST. For example, in `function…
The rule explicitly accepts module functions, but every non-alias is formatted with the “cmdlet”…
Module qualification selects a module name, not a module version, so it cannot ensure which…
The columns are reversed for this rule: ConfigurableRule.Enable defaults to false, and…
This public rule description omits the main behavior: fully spelled but unqualified names such as…

Christoph Bergmeister (bergmeister) · 2026-09-22T20:58:54Z

+                // Skip commands that resolve to a locally declared function, since qualifying them would change behavior.
+                if (IsShadowedByLocalFunction(commandAst, commandName, functionDefinitions))


With PowerShell's dynamic nature, one will never be done. current, simple behaviour is good enough

genxDev has addressed it and tests pass now

Copilot AI review requested due to automatic review settings August 19, 2025 04:07

René Vaessen (genXdev) requested review from Andy Jordan (andyleejordan) and Christoph Bergmeister (bergmeister) as code owners August 19, 2025 04:07

Copilot AI reviewed Aug 19, 2025

View reviewed changes

René Vaessen (genXdev) mentioned this pull request Aug 19, 2025

Code Formatter: Don't remove module names from cmdlet calls #2123

Closed

2 tasks

René Vaessen (genXdev) requested review from Mikey Lombardi (He/Him) (michaeltlombardi) and Sean Wheeler (sdwheeler) as code owners August 19, 2025 22:21

René Vaessen (genXdev) changed the title ~~Added PSUseFullQualifiedCmdletNames rule with fix capabilities~~ Added PSUseFullyQualifiedCmdletNames rule with fix capabilities Aug 19, 2025

Christoph Bergmeister (bergmeister) requested a review from a team as a code owner January 30, 2026 17:05

Christoph Bergmeister (bergmeister) requested a balanced review from Copilot September 14, 2026 20:08

Copilot started reviewing on behalf of Christoph Bergmeister (bergmeister) September 14, 2026 20:08 View session

Copilot AI reviewed Sep 14, 2026

View reviewed changes

René Vaessen (genXdev) force-pushed the main branch from fe2d569 to a7b32a6 Compare September 15, 2026 22:42

René Vaessen (genXdev) force-pushed the main branch from a7b32a6 to 35b1b39 Compare September 19, 2026 08:35

Sean Wheeler (sdwheeler) previously requested changes Sep 19, 2026

View reviewed changes

René Vaessen (genXdev) force-pushed the main branch 2 times, most recently from 095a8cb to 49446db Compare September 19, 2026 14:27

Add PSUseFullyQualifiedCmdletNames rule

b5a838e

René Vaessen (genXdev) force-pushed the main branch from 49446db to b5a838e Compare September 22, 2026 20:05

Christoph Bergmeister (bergmeister) requested a balanced review from Copilot September 22, 2026 20:41

Copilot started reviewing on behalf of Christoph Bergmeister (bergmeister) September 22, 2026 20:44 View session

Copilot AI reviewed Sep 22, 2026

View reviewed changes

Christoph Bergmeister (bergmeister) approved these changes Sep 22, 2026

View reviewed changes

Christoph Bergmeister (bergmeister) enabled auto-merge (squash) September 22, 2026 21:04

Christoph Bergmeister (bergmeister) requested a review from Sean Wheeler (sdwheeler) September 22, 2026 21:04


		var extent = commandAst.CommandElements[0].Extent;

		bool isAlias = commandName != fullyQualifiedName.Split('\\')[1];

-                bool isAlias = commandName != fullyQualifiedName.Split('\\')[1];
+                else
+                {
+                    // Extract actualCmdletName from the cached fullyQualifiedName
+                    int idx = fullyQualifiedName.IndexOf('\\');
+                    actualCmdletName = (idx >= 0 && idx < fullyQualifiedName.Length - 1)
+                        ? fullyQualifiedName.Substring(idx + 1)
+                        : fullyQualifiedName;
+                }
+                var extent = commandAst.CommandElements[0].Extent;
+                bool isAlias = commandName != actualCmdletName;

		// Skip commands that resolve to a locally declared function, since qualifying them would change behavior.
		if (IsShadowedByLocalFunction(commandAst, commandName, functionDefinitions))

Conversation

René Vaessen (genXdev) commented Aug 19, 2025

PR Summary

PR Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Aug 19, 2025

Choose a reason for hiding this comment

Uh oh!

René Vaessen (genXdev) Aug 19, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Aug 19, 2025

Choose a reason for hiding this comment

Uh oh!

René Vaessen (genXdev) commented Aug 19, 2025

Uh oh!

René Vaessen (genXdev) commented Aug 19, 2025

Uh oh!

Liam Peters (liamjpeters) commented Aug 19, 2025

Uh oh!

René Vaessen (genXdev) commented Aug 19, 2025

Uh oh!

René Vaessen (genXdev) commented Aug 21, 2025

Uh oh!

Christoph Bergmeister (bergmeister) commented Dec 2, 2025

Uh oh!

René Vaessen (genXdev) commented Dec 3, 2025

Uh oh!

Christoph Bergmeister (bergmeister) commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Christoph Bergmeister (bergmeister) commented Sep 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Suppressed comments (1)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

René Vaessen (genXdev) commented Sep 15, 2026

Uh oh!

Sean Wheeler (sdwheeler) left a comment

Choose a reason for hiding this comment

Uh oh!

René Vaessen (genXdev) commented Sep 19, 2026

Uh oh!

Christoph Bergmeister (bergmeister) commented Sep 22, 2026

Uh oh!

René Vaessen (genXdev) commented Sep 22, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Christoph Bergmeister (bergmeister) Sep 22, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Christoph Bergmeister (bergmeister) commented Jan 30, 2026 •

edited

Loading

Christoph Bergmeister (bergmeister) commented Sep 14, 2026 •

edited

Loading