microsoftgraph
Quality of life suggestion on Get-Mg* cmdlets that use $select
Personally, I like how the ActiveDirectory cmdlets operate when it comes to returning certain attributes. By default there is a minimal set of attributes returned and when a property is passed to the -Properties parameter, that property is added to the existing minimal set of properties.
As an example, if I run:
Get-ADUser ThePoShWolf
The return would look something like:
DistinguishedName : CN=Anthony Howell,DC=domain,DC=com
Enabled : True
GivenName : Anthony
Name : Anthony Howell
ObjectClass : user
ObjectGUID : <guid>
SamAccountName : theposhwolf
SID : <sid>
Surname : Howell
UserPrincipalName : [email protected]
If I then run:
Get-ADUser ThePoShWolf -Properties Title
It would return:
DistinguishedName : CN=Anthony Howell,DC=domain,DC=com
Enabled : True
GivenName : Anthony
Name : Anthony Howell
ObjectClass : user
ObjectGUID : <guid>
SamAccountName : theposhwolf
SID : <sid>
Surname : Howell
Title : Powershell Dude
UserPrincipalName : [email protected]
If I look at the Graph module, specifically Get-MgUser, it operates a bit differently. If I pass a property to -Properties, only that property is returned:
Get-MgUser -UserId [email protected] -Property Department
Id DisplayName Mail UserPrincipalName UserType
-- ----------- ---- ----------------- --------
I understand that this is how the API operates, but I think it would be extremely useful to be able select properties to add to the default as well as the existing function of exclusivity.
Maybe rename the current -Property feature to -Select and when -Property is used, add the property to the default set of properties that are returned. So if -Select is used, only return the passed properties, but if -Property is used, pass a $select array to the API that includes the default properties and adds whatever is passed to them. So take this command, for example:
Get-MgUser -UserId [email protected] -Property Departmet
With my suggestion, I would expect this to pass the following to the API:
GET /v1.0/users/theposhwolf%40domain.com?$Select=businessPhones%2CdisplayName%2CgivenName%2Cid%2CjobTitle%2Cmail%2CmobilePhone%2CofficeLocation%2CpreferredLanguage%2Csurname%2CuserPrincipalName%2CDepartment
The default list of properties is pulled from https://docs.microsoft.com/en-us/graph/api/user-get?view=graph-rest-1.0&tabs=http#optional-query-parameters.
Rather than define both -Property and -Select parameters as you suggest @ThePoShWolf, which would be a breaking change because -Select is an alias for -Property so suddenly you would be changing how the code functions behind the scenes for existing scripts, maybe this could be covered via a -IncludeDefaultProperties switch parameter that is only used when invoking a command with -Property.
i.e. If you invoke Get-MgUser -Property RefreshTokensValidFromDateTime, you only get back the RefreshTokensValidFromDateTime value, as it works today, but if you invoke Get-MgUser -Property RefreshTokensValidFromDateTime -IncludeDefaultProperties, you would get back the default properties as well as the RefreshTokensValidFromDateTime property.
Otherwise, the proposal described in the OP would introduce a breaking change, which I would be strongly opposed to.
I like @KirkMunro's suggestion. We can consider adding this for top level entities, which we know their default properties. This will be an opt-in behavior via a switch parameter.
I absolutely did not intend to suggest a breaking change! Thank you @KirkMunro for your suggestion. I believe that to be a much better idea as I am also opposed to breaking changes for something so minor.
This is a great idea, provide good developer experience and would be useful on the long run. I would be interested in this capability only if these properties are documented in our CSDL. @timayabi2020 and @calebkiage, can you research if we have some annotation capability for that? Other SDKs could also benefit of this.
For now I will keep it as a P3 and see based on more customer feedback if we bump it up.
