[Tracking] Document The SDK

[peombwa]

We need to:

1. Add examples to generated cmldet docs.
2. Publish docs to PowerShell Module Browser.
3. Provide readme/docs on topics such as installation, authentication, query options, and paging. AB#7411

• [x] #876
• [x] #1302

[peombwa]

Investigate extensibility options for adding custom elements such as links to docs.

[peombwa]

Related to #61.

[Licantrop0]

@peombwa how's the investigation for added links is going?

as you know, we would like to add a link in the "Related Links" section that points to a Dev Survey for the specific cmdlet.

[PsychoData]

The help links not-being accessible makes this very difficult to reference and troubleshoot issues.

The fact that we cannot link to documentation, or reference the source, means we are stuck inferring and guessing from the Vanilla Graph Documentation, and sometimes Parameter Set notation how to do what we want. Or falling back to Invoke-MgGraphRequest

As someone trying to write articles and documentation for my employer to use this module, the documentation is probably one of the most core things that we need to write the content to use the module, and thereby drive adoption.

This needs to be a top priority, and should probably have been done before a 1.0 release in the first place.

Is there anything particular we can do to further this along?

[maisarissi]

we would like to add a link in the "Related Links" section that points to a Dev Survey for the specific cmdlet.

@Licantrop0 this request will be tracked through #737

[peombwa]

Depends on https://github.com/microsoftgraph/microsoft-graph-devx-api/issues/615

[cparkerx]

Just wanting to draw attention to this. Please add some documentation. Its incredibly hard to get going with this SDK because of the lack of documentation/examples.

[maisarissi]

Hello @cparkerx. We have been working on the Microsoft Graph PowerShell SDK documentation and have already released the first version. You could already check some content like how to install the SDK, a quick walkthrough on how to get started and authentication via the Microsoft Graph docs site. And now, we are also providing documentation on the PowerShell Module Browser which contains topics such as overview, getting started, learn, migrate from Azure AD PowerShell SDK to Microsoft Graph PowerShell SDK and all the reference documentation.

As a second step, we are working to improve the reference docs and to add code snippets.

Hope you will find this helpful.

[PsychoData]

@maisarissi, thank you for the update! I believe most of the documentation that we are looking for is things more along the lines of your second item. For example, what sort of parameters would Get-MgGroupEvent take? Well if you know that it is in Microsoft.Graph.Calendar - then you might go to https://docs.microsoft.com/en-us/powershell/module/microsoft.graph.calendar/get-mggroupevent?view=graph-powershell-beta

And this I believe is fairly new as well - and this is a huge improvement! Now the documentation that there is so far is at least easily publicly accessible!

Previously, you could only try the help provided with the installed modules, hope someone had manually added an example or details (and find them in GitHub), download and run the documentation creation scripts yourself (From GitHub), or just sort of guess and check with the Graph REST Documentation

Even now, there is no page I can find that introduces you to the Modules and that you might be able to search for a cmdlet, unless you expand out the whole page and Ctrl-F, so finding the command to accomplish a task for you is rather difficult unless you already know the command you want.

As far as I can tell, the Docs.microsoft.com search won't find the commands. If you know which module you should be looking in, and the command name, and where to get to the Module Page, you could find the right documentation pretty easily through browser Ctrl-F

I thoroughly appreciate the progress so far! and this module is BY FAR my most preferred way to consume the Graph API - I'm just heavily hindered and forced to fall back to the generic methods like Invoke-MgGraphRequest.

[PsychoData]

For another example, after some confusion just now, I realized Invoke-MgGraphRequest isn't on that new Module Browser pages either! I think it may just be the whole "Authentication" module that is not included. But that just demonstrates that you either had to understand how the code is structured and find it in GitHub, and to search for InvokeMgGraphRequest instead of Invoke-MgGraphReqeuest, or you wouldn't be able to find InvokeMgGraphRequest.cs - because it doesn't show up basically anywhere in Docs.microsoft.com and the filter within the page/category/module browser is very particular

[maisarissi]

Hi @PsychoData. You are right, the Invoke-MgGraphRequest is not officially documented. And we can certainly add something about it. I have created a new issue to track this: https://github.com/microsoftgraph/msgraph-sdk-powershell/issues/972

And I'm not sure why you are having issues searching for commands, I could easily find AppRoleAssignment commands by typing just "AppRole":

It's also possible to Now if you want to discuss further why you are using Invoke-MgGraphRequest so heavily, I would love to understand why. It should be possible to use specific commands to call the APIs instead of appealing to Invoke-MgGraphRequest.

Please, feel free to open a new issue if you want to discuss it.

[PsychoData]

Primarily the reason I have been falling back to Invoke-MGGraphRequest is because I could use it largely as I would the Graph REST API, on basically any Graph endpoint, but with your backend doing the authentication for me.

So, since I was sometimes having difficulty with finding or using the cmdlets because there was no readily accessible documentation, I fell back to the more generic Invoke-MgGraphRequest that I could largely use with just the Graph REST API documentation.

[PsychoData]

And I'm not sure why you are having issues searching for commands, I could easily find AppRoleAssignment commands by typing just "AppRole": < snipped image >

Ahh, you are at a different root article than I am. Not sure what it considers different between the top section and the "reference" section, but you can see how I was having issues searching from Microsoft.Graph.Applications in this Gif.

perhaps this is something that needs to be adjusted in a config? I would have thought the Search would be searching the whole array of items that I could have expanded from the left side menus

[maisarissi]

So, since I was sometimes having difficulty with finding or using the cmdlets because there was no readily accessible documentation, I fell back to the more generic Invoke-MgGraphRequest that I could largely use with just the Graph REST API documentation.

The PowerShell SDK only mirrors the API behavior so, because of that, the API team is responsible for creating the official documentation on how to use the API. Knowing which API you will use makes it easier to find the right cmdlet to use. Starting on version 1.7.0 we added a new command Find-MgGraphCommand that allows you to find commands given a URI. We are working to create an official documentation about the Find-MgGraphCommand but it's possible to see how to use it here.

but you can see how I was having issues searching from Microsoft.Graph.Applications in this Gif.

perhaps this is something that needs to be adjusted in a config?

I will talk to the docs team to understand why we have different behaviors between the conceptual doc section and the reference section. Thanks for your feedback, we truly appreciate that.

[PsychoData]

Easier to find, yes, but I've compiled the modules and the documentation myself and seen how the PowerShell graph SDK has to sometimes fix the Auto rest interpretation, or correct a data type that doesn't have a direct mapping.

In those cases maybe instead of accepting only an object ID for a user, you accept other forms as well, like a UPN. That may not be documented anywhere, but be apparent from the code or from get-help.

Or the reverse might be true. For a hypothetical - The graph API says "send me an email and use this format."

But the graph PowerShell SDK does not accept that specific format, or tries to separate it out into various components like body and recipients and copied recipients. The body and recipient might be plain text straing, or maybe the body still needs to be JSON, or maybe it can take rich text, et cetera.

If you back off from the email function, you may be able to use invoke-mggraphrequest to make your API call successfully even if the function doesn't accept the type of input your making, or has a bug around it.

That absolutely should still have a issue raised on GitHub, but often the issue is just that it wasn't documented that it needed it in a specific format, or rather a more general format sometimes. Now that we have more documentation, that will hopefully be better then it has been.

Now, thankfully all my implementations of this so far have been running fine for months and I haven't needed to dig into the documentation as much lately - I hope the next time I do need to everything is just right where I need it! I am truly looking forward to it being more easily accessible, because last time that I had to compile it for myself it took several hours for my computer to run through all of the compilation of the dozens of modules and documentation.

The next time I go to use the module, I will definitely be trying out that find command because it sounds extremely useful!

On Fri, Dec 10, 2021, 1:48 PM Maísa Rissi @.***> wrote:

So, since I was sometimes having difficulty with finding or using the cmdlets because there was no readily accessible documentation, I fell back to the more generic Invoke-MgGraphRequest that I could largely use with just the Graph REST API documentation.

The PowerShell SDK only mirrors the API behavior so, because of that, the API team is responsible for creating the official documentation on how to use the API. Knowing which API you will use makes it easier to find the right cmdlet to use. Starting on version 1.7.0 we added a new command Find-MgGraphCommand https://github.com/microsoftgraph/msgraph-sdk-powershell/issues/682 that allows you to find commands given a URI. We are working to create an official documentation about the Find-MgGraphCommand but it's possible to see how to use it here https://github.com/microsoftgraph/msgraph-sdk-powershell/pull/816.

but you can see how I was having issues searching from Microsoft.Graph.Applications in this Gif.

perhaps this is something that needs to be adjusted in a config?

I will talk to the docs team to understand why we have different behaviors between the conceptual doc section and the reference section. Thanks for your feedback, we truly appreciate that.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/microsoftgraph/msgraph-sdk-powershell/issues/257#issuecomment-991211818, or unsubscribe https://github.com/notifications/unsubscribe-auth/AA4L7TFF7VWXHWXIWWU3OADUQJDPNANCNFSM4N2Z5OVA .

[cparkerx]

To further the conversation on this, Ill give an example of my own. I am needing to upload files to team drives, and it is rather difficult to find the cmdlet to use for this. I understand the verb/noun naming scheme of Powershell cmdlets, but its still difficult to find the cmdlet to simply upload a file.

I logically think that "New-MgDriveItem" would be the cmdlet for this, however it states "All items contained in the drive. Read-only. Nullable.". So if this is read only, how can I upload/write to it?

[maisarissi]

Hi @PsychoData . Sorry for the late response. I thought I had replied it already.

In those cases maybe instead of accepting only an object ID for a user, you accept other forms as well, like a UPN. That may not be documented anywhere, but be apparent from the code or from get-help.

This is an API functionality, and not PowerShell specifics. You can find which kind of value you can use by accessing the API reference documentation, for example, https://docs.microsoft.com/en-us/graph/api/user-get?view=graph-rest-1.0&tabs=powershell#http-request

As a second step, we are working to improve the reference docs and to add code snippets.

I had mentioned before that we were working on adding support for PowerShell code snippets. They are now completed, as you can see in the issue, and I mentioned that in my last tweet. And if you look at the snippets, we are adding a comment too, even though this is documented in the HTTP request in the same page.

But the graph PowerShell SDK does not accept that specific format, or tries to separate it out into various components like body and recipients and copied recipients. The body and recipient might be plain text straing, or maybe the body still needs to be JSON, or maybe it can take rich text, et cetera.

But this should be possible to find it using Get-Help command, right?

If you back off from the email function, you may be able to use invoke-mggraphrequest to make your API call successfully even if the function doesn't accept the type of input your making, or has a bug around it.

For some cmdlets, we have known issues, and the workaround is to use the Invoke-MgGraphRequest, and you are totally right about that. What I was trying to understand is why you would choose to use the Invoke command for scenario we do provide a cmdlet that just works fine. Also, it's super important, as you mentioned, to open a GitHub issue, so our team can know about it. Unfortunately, as the SDK uses other tools in its generation, sometimes it is not even possible for us to fix it.

The next time I go to use the module, I will definitely be trying out that find command because it sounds extremely useful!

Super happy to hear that. And please, keep the feedback coming, so we can make the product even better for you'all.

[PsychoData]

Historically, the only reason I would choose to use the invoke- command is because it actually had documentation, in the form of using the actual API documentation.

I haven't had a chance to look through all of the new examples, but many of the old ones and autogenerated ones were not specific enough to show you how to have an actual working command.

Instead, I give an example of what would happen due to the PowerShell commands help being auto generated. You would try to create something in a SharePoint location, find the command by kind of guessing and checking (search is now much better, and exists), and instead of providing the SharePoint site by the HTTPS URL that you wanted to create it at, and the file path, it actually needed it multiple parts by SharePoint site Id, document library ID (perhaps both by GUID, where the auto-generated documentation just specified it as "string FileURL", And then the file path within the document library, and then the file name.

But, since all of those could have been specified through multiple parameters they might all be marked as optional, because that graph API endpoint might be able to make files, or calendars and both of those don't need document libraries. So a whole bunch of parameters are marked optional, when you actually needed several of them to have a working command.

It was far easier just to skip all of that, fall back to invoke- And use the API documentation and know that it was working without having to post new issues on GitHub, or find someone else that had posted about the same issue on GitHub.

If the documentation is as good as your messages and tweet make it seem now, then I won't run into any problems, and maybe with this search that actually works now I won't have trouble finding the name of the PowerShell command that ties to a specific rest endpoint or function.

I hope that's the case! If not, I'll be back to ask questions again :)

Ps, just as an aside

This is an API functionality, and not PowerShell specifics. You can find which kind of value you can use by accessing the API reference documentation

If you are writing documentation on how to take care of your pet, you don't say "now be sure to feed the pet exactly how much kibble is specified in the Purina documentation for this breed, animal type, and age" you just say "The dog gets one cup of food at night and one in the morning"

Hiding behind "oh, you should have checked the API to see how you should use our SDK" defeats the whole point of having the SDK.

If I have to use the actual API reference documents, it's just easier to only take the benefits from the authentication, and use the API reference documentation directly.

[maisarissi]

If you are writing documentation on how to take care of your pet, you don't say "now be sure to feed the pet exactly how much kibble is specified in the Purina documentation for this breed, animal type, and age" you just say "The dog gets one cup of food at night and one in the morning"

@PsychoData To be honest, I normally see "check Pet Food Manufacturer's specification" since how you should feed them changes depending on its size, age, and many other factors.

Joking apart, I do hear you and it's not an easy situation. One of the reasons we keep telling people that the API reference docs is the right place to learn how to use that API is because the SDKs mirror the APIs behavior, and APIs do change, add new functionalities, change parameters, etc, and we are two different teams. Having multiple places that need human maintenance every time they change something is complicated and can introduce different issues, such as divergente information. That's why we are working on an automated process as we speak, to have the API content on the PowerShell reference documentation, that way we will not introduce issues on outdated documentation for example.

I'll update this thread when the work we are doing is available.

Thank you for all the feedback.

[maisarissi]

Hello everyone. We have released the new docs. You can find documentation around the Authentication module as well as descriptions, operation descriptions and examples: https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.applications/add-mgapplicationkey?view=graph-powershell-1.0#description