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

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.

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.

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..

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;

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

@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) 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"

👋 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...).

👋 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

…rdingly

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

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

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.

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

René Vaessen (genXdev) added 3 commits August 19, 2025 03:43

Added UseFullyQualifiedCmdletNames rule

e73df6d

Missing Strings.resx

dc90c53

Added UseFullyQualifiedCmdletNames rule

71cbf21

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) and others added 3 commits August 19, 2025 06:20

Update Rules/UseFullyQualifiedCmdletNames.cs

63e9bf5

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update Rules/UseFullyQualifiedCmdletNames.cs

26dfa4e

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Added UseFullyQualifiedCmdletNames rule

69a2690

Added Docs and Test for UseFullyQualifiedCmdletNames rule

971f02b

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

Also added 'IgnoredModules' parameter and updated tests and docs acco…

33fad88

…rdingly

Merge upstream/main into main - resolve Strings.resx conflict

f6d123d

Merge branch 'main' into main

51e52b6

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

Merge branch 'main' into main

fe2d569


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

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

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

Uh oh!

Added PSUseFullyQualifiedCmdletNames rule with fix capabilities - #2122

Added PSUseFullyQualifiedCmdletNames rule with fix capabilities#2122René Vaessen (genXdev) wants to merge 11 commits intoPowerShell:mainPowerShell/PSScriptAnalyzer:mainfrom genXdev:maingenXdev/PSScriptAnalyzer:mainCopy head branch name to clipboard

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Added PSUseFullyQualifiedCmdletNames rule with fix capabilities#2122
René Vaessen (genXdev) wants to merge 11 commits into
PowerShell:mainfrom
genXdev:main

Christoph Bergmeister (bergmeister) commented Jan 30, 2026 •
edited
Loading