Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add cmdlet prefix #32

Open
michevnew opened this issue Oct 17, 2019 · 15 comments
Open

Add cmdlet prefix #32

michevnew opened this issue Oct 17, 2019 · 15 comments

Comments

@michevnew
Copy link

@michevnew michevnew commented Oct 17, 2019

As discussed briefly the other day on the call, you should consider adding an unique prefix to all the cmdlets. This will not only make them easier to identify with the module, but avoid clashes with existing cmdlets. Prime examples being Get-User and Get-Group - both of these are heavily used in Exchange/Exchange Online PowerShell. And since support for Exchange management tasks in the Graph is still non-existent, it's very likely that people will use both the ExO cmdlets and the Graph module in the same PS session.

Considering the sheer number of cmdlets in the module, you're bound to have other duplicates as well.

@msftbot msftbot bot added the ToTriage label Oct 17, 2019
@msftbot msftbot bot added this to Issues to triage in Graph SDK - Triage Oct 17, 2019
@bschlintz

This comment has been minimized.

Copy link

@bschlintz bschlintz commented Oct 23, 2019

Completely agree.

Adding a prefix to the module will...

  • Make it easier to share scripts in a consistent manner
  • Avoid confusion by requiring folks who aren't as familiar with Import-Module using -Prefix parameter
  • Be consistent with other PowerShell modules such as "Verb-AzureRM", "Verb-SPO", "Verb-PowerApps", etc.

Perhaps a short acronym like "MSG" and "MSGBeta", short for Microsoft Graph and Microsoft Graph Beta, would be unique-enough to avoid conflicts and still be easy to type.

@darrelmiller

This comment has been minimized.

Copy link
Contributor

@darrelmiller darrelmiller commented Oct 31, 2019

We have received this feedback from a few people, however for the moment, we are continuing to recommend that people use the -prefix option of Import-Module if they want to add a unique prefix to the cmdLets.

We understand there are pros and cons to this approach. However, PowerShell has introduced a feature to specifically avoid namespace clashes and rather than do a land grab on a prefix and hope no-one else ever uses it, we are going to push towards using the built in capability.

@chrisgardnersage

This comment has been minimized.

Copy link

@chrisgardnersage chrisgardnersage commented Nov 6, 2019

We have received this feedback from a few people, however for the moment, we are continuing to recommend that people use the -prefix option of Import-Module if they want to add a unique prefix to the cmdLets.

We understand there are pros and cons to this approach. However, PowerShell has introduced a feature to specifically avoid namespace clashes and rather than do a land grab on a prefix and hope no-one else ever uses it, we are going to push towards using the built in capability.

The likelihood of someone else using Msg or something for their prefix is much much lower than someone having a Get-User cmdlet/function. At the very least you should specify a default prefix in the manifest so that you don't have to update the command definitions themselves.

The fact this clashes with existing modules produced by MSFT should be enough to require a prefix, future authors will deal with the coming up with their own prefix but those other commands were there first (and should probably have their own prefixes as well) and therefore it's up to you to prefix your commands to prevent clashes for existing users, especially users who might want to trial these and run them side by side.

The Import-Module -Prefix approach isn't a great suggestion, it's little known by most PowerShell users, especially the average admin who's looking to use this module, and therefore should only be recommended should someone come out with a module with the same default prefix (there are a few I've seen). We really don't want a repeat of the Get-VM issues people have when having Hyper-V and VMWare installed side by side.

@Shoisk

This comment has been minimized.

Copy link

@Shoisk Shoisk commented Nov 6, 2019

Completely agree with this. There's so many potential conflicts that could easily be avoided.

we are going to push towards using the built in capability

Manifests support a prefix, so that too is a built in capability I would assume? It seems arbitrary not to do it, when most other MSFT modules have done it recently. Sure, most of the clashes here are because some modules do not have prefixes, but we can't really fix the mistakes of the past, only make sure we don't mess up the future. Using Import-Module -Prefix is generally unhelpful if you're seeking help from the community aswell. It'd be a lot easier to

  1. Share scripts
  2. Get help from the PS slack / discord / reddit / whatever else exists

And probably more, if everyone has the same naming convention for these cmdlets, it's a mess to help people and to use scripts shared by others if they don't fit the same naming convention. Imagine a team using several shared scripts that utilize this module, and having written a few of their own. They'll have an internal naming standard for the prefix on this module, but anything they import they'll have to either just live with the fact that it doesn't use the same naming convention, or change it throughout the script so it does fit internal standards.
That seems like unnecessary work that could easily be avoided.

@colinrippeyfinarne

This comment has been minimized.

Copy link

@colinrippeyfinarne colinrippeyfinarne commented Nov 6, 2019

I would suggest that the team behind this effort make contact with the Power Platform team who developed that technology's Powershell module. The first release had commandlets such as Get-App and the team received (a tad harsh IMHO) feedback to "please change the commandlets to be unique".

The team quickly pivoted to use a more specific nomenclature and none of us batted an eyelid, we were all very happy to move on with the new commandlet names even though they were far more verbose.

As for using Import-Module -Prefix I cannot remember the last time I added Import-Module to any of my scripts, modern Powershell really doesn't need it does it. I really think about the -Prefix feature to be used to help with any "internal name clashes" I might have with my own and/or 3rd party modules, not a feature that I'd have to use with a Microsoft module.

Finally as mentioned above, we'll (hopefully) see this module get widely adopted and used, this will no doubt give rise to blog posts, stackoverflow answers with sample scripts - but we'll quickly end up with adding disclaimers to every post with "for the following scripts to work please use Import-Module -Prefix XYZ".

@kilasuit

This comment has been minimized.

Copy link

@kilasuit kilasuit commented Nov 7, 2019

@darrelmiller lets chat at Ignite (I know you mentioned you wanted to anyway) but please lets use a Prefix that's defined at the module manifest level to keep everyone happy particularly as just like @chrisgardnersage mentioned we have had many different historical issues because of a lack of prefix being added to cmdlets/functions being exported from a module.

The fact you also stated for the moment reads to me that you'd be open to taking this feedback onboard / possibly accepting a PR implementing it in future.

But again please please take on the feedback of those above

However this comment confuses me

However, PowerShell has introduced a feature to specifically avoid namespace clashes

The only feature I can think of (knowing PowerShell as well as I do) that you could mean is to fully module qualify a command like this
Microsoft.PowerShell.Management\Get-Item which breaks down to <modulename>\<cmdletName>
Which is an awful authoring and usability experience and should be avoided unless you really need that level of defensiveness (which you often really don't)

Like I said, happy to further discuss this in person this week at Ignite

@ToddKlindt

This comment has been minimized.

Copy link

@ToddKlindt ToddKlindt commented Nov 8, 2019

I would also like to see a Prefix used in these cmdlets. I'm experiencing a conflict with the Sharegate cmdlets, who also refuses to use a Prefix. The only way I could get the the Graph Get-Group cmdlet to work was to completely uninstall the Sharegate product. That barrier is way too high for admins. I talked to @darrelmiller a bit about this at Ignite and after trying the -Prefix method I couldn't get that to work either. I'm not sure why the team is reluctant to add a prefix. Maybe if they explain that we could find a solution.
Not having a prefix is really killing my excitement for this module.

@ToddKlindt

This comment has been minimized.

Copy link

@ToddKlindt ToddKlindt commented Nov 8, 2019

The other thing I'd like to add is that the current instruction for this module use the Install-Module cmdlet to install it, which does not support a Prefix parameter like Import-Module does. I'm not sure how to resolve the two sets of instructions, "Use Install-Module to get these cmdlets, but use Import-Module -Prefix to fix the collision."

@darrelmiller

This comment has been minimized.

Copy link
Contributor

@darrelmiller darrelmiller commented Nov 10, 2019

Hey folks. I really appreciate your input on this. There is a reason I didn't close this issue and just labeled it as a NotPlanned. :-)
The community has been 100% consistent on this feedback and I will be meeting with the team this week to reconsider our previous decision based on this feedback.

@MIchaelMainer MIchaelMainer moved this from Issues to triage to Active in Graph SDK - Triage Nov 11, 2019
@michevnew

This comment has been minimized.

Copy link
Author

@michevnew michevnew commented Nov 13, 2019

On a related note, here's what happens currently if you try to install the module on a machine that has the Teams module installed already:

image

@rjmholt

This comment has been minimized.

Copy link

@rjmholt rjmholt commented Nov 19, 2019

Just to add to the feedback here, the scenarios broken by the lack of a prefix are:

  • Module installation (where conflicts will inevitably occur)
  • Autoloading (far and away the most common way to load a module in PowerShell)
  • Future extensions to PowerShell; PowerShell "builtins" don't have a namespace since they're core to the experience. For example PowerShell 7 is adding a Get-Error after much verb discussion. One of the reasons to avoid Resolve-Error was that Az.Accounts did not prefix a command they export by that name.
  • Having a common reference for identifying a command across environments or in discussions. Forcing imports with -Prefix means it's much harder to recognise, discuss, debug and search for Graph cmdlets, whether that's in code reviews, in web search or in forums like StackOverflow.

PowerShell being a shell, the default interactive experience is to show all commands globally and load them on demand, like cmd or bash does with utilities rather than the way e.g. Python requires explicit module imports. As a result, manually calling Import-Module is not a normal part of the interactive UX for PowerShell. In addition to that, Import-Module -Prefix MyPrefix is a little-known parameter on Import-Module and only really exists as a get-out-of-jail-free card in situations where a module that should have specified a prefix didn't; it's for exceptional circumstances, rather than the default scenario.

Without the prefix, just installing this module without loading it is something that will break normal workflows, since it will collide with other modules. That means the only safe way to install it is to Save-Module it somewhere and import it manually in the profile, adding several friction points and lowering discoverability significantly (one of PowerShell's key features).

@SQLvariant

This comment has been minimized.

Copy link

@SQLvariant SQLvariant commented Nov 22, 2019

The only feature I can think of (knowing PowerShell as well as I do) that you could mean is to fully module qualify a command like this
Microsoft.PowerShell.Management\Get-Item which breaks down to <modulename>\<cmdletName>
Which is an awful authoring and usability experience

I'm confused by how this could be "an awful authoring and usability experience"? As a data professional, I use schema.object naming to call every database object I work with. I have used this, as well as 3-part (database.schema.object) & 4-part (server\instance.database.schema.object) naming throughout my career. Millions of other data professionals are used to calling code to be executed using schema.object naming convention on a daily basis, so I don't see how this is "awful" in any way? In fact, it's quite straight-forward & intuitive to me. When I learned PowerShell allowed you to call cmdlets using <modulename>\<cmdletName> I was literally excited by the feature.

Candidly, if you're writing a article to show new users how to pipe input from a cmdlet in one module, into a cmdlet from another module: using the full <modulename>\<cmdletName> in the code sample would more clearly communicate where these commands come from.

@essentialexch

This comment has been minimized.

Copy link

@essentialexch essentialexch commented Nov 22, 2019

PLEASE use Gr or GRX or MSG as previously suggested.

The conflicts I have are ongoing and NOT easily resolvable, as Todd pointed out.

@kilasuit

This comment has been minimized.

Copy link

@kilasuit kilasuit commented Nov 23, 2019

@SQLvariant

I'm confused by how this could be "an awful authoring and usability experience"?

PowerShell has many defensive scripting techniques with Fully Module Qualifying commands being one of them, Import-Module with prefix another, but the mass majority of PowerShell writers are using the Command Name only in their writing of scripts, mostly because it's so much additional overhead adding the module name to commands that many will not do this unless they absolutely have to.
It also reduces readability and increases the maintenance burden of scripts/modules because if the module name were to ever change you need to change it in 10's,100's, perhaps thousands of places instead of just a few.

@darrelmiller darrelmiller added this to the 0.1.1 milestone Nov 29, 2019
@peombwa peombwa self-assigned this Dec 5, 2019
@peombwa peombwa added this to To do in Graph SDK - Powershell via automation Dec 5, 2019
@darrelmiller

This comment has been minimized.

Copy link
Contributor

@darrelmiller darrelmiller commented Dec 6, 2019

We will be adding Mg prefixes to all the cmdlets in our 0.1.1 release which we expect to publish to PowerShell Gallery. Stay tuned and THANK YOU for your enthusiastic feedback.

@peombwa peombwa moved this from To do to In progress in Graph SDK - Powershell Dec 9, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Graph SDK - Powershell
  
In progress
You can’t perform that action at this time.