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

[MarkDomansky]

Prerequisites

• I have written a descriptive issue title.
• I have searched all issues to ensure it has not already been reported.

Summary

Currently, with the code formatter, if you have a cmdlet call such as MicrosoftTeams\Get-CsLisCivicAddress, and run the formatter, it will remove the module name resulting in Get-CsLisCivicAddress. Including the module name gives specificity with clobbered cmdlets, as in my case. Get-CsLisCivicAddress is a valid function in two different modules.

As I understand it, including the module name in functions/modules is actually a best practice.

I've been through all the code formatting settings and none seem to relate to the above experience, including 'Auto Correct Aliases'. Disabling this did not change the behavior.

Proposed Design

At a minimum, I would like an option to enable/disable this, perhaps "Auto Remove Module Name from Cmdlets".

Even better would be expanding this to automatically add the module name to cmdlets when possible. So writing Get-CsLisCivicAddress would be converted to MicrosoftTeams\Get-CsLisCivicAddress. The option could be a drop down with Remove/Do Nothing/Add.

[JustinGrote]

Thanks for the submission! Most of the "refactors" for the code formatter are actually currently provided by PSScriptAnalyzer, can you verify that this isn't specific to PSScriptAnalyzer? If it is then it needs to be handled there.

[MarkDomansky]

I'm unable to reproduce with Invoke-ScriptAnalyzer -path test.ps1 (with or without -fix). It doesn't change the file and doesn't throw any output.

VSCode also does not list it as a Problem in the UI but only fixes it during formatting.

[JustinGrote]

So I can't reproduce using either "Format Document", "Format on Paste", or "Format on Save"

$x = Microsoft.PowerShell.Management\Get-Service -Name 'wuauserv'
$x.status

This does not get shortened to Get-Service

Can you provide a reproducible example? Maybe record a gif using something like ScreenToGif?

EDIT: Apologies, it appears your use case is when there is a specific clobber conflict. My guess is what's happening is the normal module resolve is happening and not realizing you have two cmdlets for whatever reason, so I agree this should defer to the fully qualified and have a option checkbox for whether to preserve fully qualified or shorten if possible. I haven't looked at the code that actually does this work, maybe Andy Jordan (@andyleejordan) or Patrick Meinecke (@SeeminglyScience) have more input.

[MarkDomansky]

Here's the screen cap. As it shows, the only module that I can find affected is MicrosoftTeams (though I certainly haven't tested all modules). It also shows PSSA is working with the Problems tab pulled up.

To be clear, this isn't specifically a clobbering issue, that was just how I encountered it. In this case, the Get-CsOnlineLisCivicAddress cmdlet only exists in one module (though I have 2 versions, only 1 is loaded. Pester and PowerShellGet both have multiple versions but are not affected).

I honestly have no idea why just the MicrosoftTeams module is affected. I don't have any snippets or anything I'm aware of that I've done that would cause this.

[genXdev]

This has caused me so much pain,
a solution wide search-replace, caused all those files to be auto-formatted,
and all those fully qualified names, gone.

This problem can cause:

• Loss of explicit module context
• Modules not being auto imported and causing runtime errors
• Incorrect cmdlet resolution if multiple modules define that same cmdlet

Not a feature request, should have much higher prio

[genXdev]

I created this pull request that offers a solution for those who discovered the mutation of removing all the ModuleName prefixes from their scripts, too late.

It adds the PSUseFullyQualifiedCmdletNames rule to PSScriptAnalyzer

It replaces all cmdlet calls aliases or not, with fully qualified names.

PSScriptAnalyzer\Invoke-ScriptAnalyzer  -Path ".\" -Recurse -Fix -IncludeRule @('PSUseFullyQualifiedCmdletNames')

#2122

[liamjpeters]

I can repro this. The erroneous behaviour is coming from UseCorrectCasing's CheckCommands option (doing my best to ignore that setting name being plural and the rest singular 😅).

With the MicrosoftTeams module installed:

Invoke-ScriptAnalyzer -ScriptDefinition "MicrosoftTeams\Get-CsOnlineLisCivicAddress" -Settings @{
    Rules = @{
        'PSUseCorrectCasing'= @{
            Enable=$true;
            CheckOperator=$false;
            CheckKeyword=$false;
            CheckCommands=$true
        }
    }
} -IncludeRule @('PSUseCorrectCasing')

In PS 7.4.11 and PS 5.1 I get:

RuleName                            Severity     ScriptName Line  Message
--------                            --------     ---------- ----  -------
PSUseCorrectCasing                  Information             1     Function/Cmdlet
                                                                  'MicrosoftTeams\Get-CsOnlineLisCivicAddress' does not match
                                                                  its exact casing 'Get-CsOnlineLisCivicAddress'.

The issue is arising here:

PSScriptAnalyzer/Rules/UseCorrectCasing.cs

Lines 93 to 107 in ea70855

	var commandInfo = Helper.Instance.GetCommandInfo(commandName);
	if (commandInfo == null || commandInfo.CommandType == CommandTypes.ExternalScript || commandInfo.CommandType == CommandTypes.Application)
	{
	continue;
	}
	var shortName = commandInfo.Name;
	var fullyqualifiedName = $"{commandInfo.ModuleName}\\{shortName}";
	var isFullyQualified = commandName.Equals(fullyqualifiedName, StringComparison.OrdinalIgnoreCase);
	var correctlyCasedCommandName = isFullyQualified ? fullyqualifiedName : shortName;
	if (!commandName.Equals(correctlyCasedCommandName, StringComparison.Ordinal))
	{
	yield return GetDiagnosticRecord(commandAst, fileName, correctlyCasedCommandName, Strings.UseCorrectCasingError);
	}

Inspecting the commandInfo it gets on line 93, we see that it get's back Microsoft.Teams.ConfigAPI.Cmdlets as the module name.

So when it checks if it's dealing with the fully-qualified name, they don't match so it assumes it isn't. Hence the correction down to just the command name.

The CommandInfo Helper is simply running Get-Command for the command name supplied. Interestingly if you were to run:

Get-Command 'Get-CsOnlineLisCivicAddress' | Select-Object Name, ModuleName

Gets you:

Name                        ModuleName
----                        ----------
Get-CsOnlineLisCivicAddress MicrosoftTeams

vs running (what ScriptAnalyzer is)

Get-Command 'MicrosoftTeams\Get-CsOnlineLisCivicAddress' | Select-Object Name, ModuleName

Gets you:

Name                        ModuleName
----                        ----------
Get-CsOnlineLisCivicAddress Microsoft.Teams.ConfigAPI.Cmdlets

I'm not quite sure why this is. The structure of the MicrosoftTeams module is somewhat complex. The module folder does have a few module manifest files.

Perhaps the CommandInfoCache needs to take the \ in the command name as a hint. Using the text before the \ as a FullyQualifiedModule identifier and the text after the \ as the command name.

So when it sees a command such as MicrosoftTeams\Get-CsOnlineLisCivicAddress, instead of passing that straight to Get-Command, it should call:

Get-Command 'Get-CsOnlineLisCivicAddress' -FullyQualifiedModule 'MicrosoftTeams'

Either way - this issue is with PSSA - Justin Grote (@JustinGrote), Andy Jordan (@andyleejordan) - feel free to transfer it.