r/PowerShell • u/Taavi179 • 11d ago
Misc Microsoft Graph documentation really is bad
Despite its reputation for poor documentation, I decided to give the Microsoft Graph PowerShell module a try for a few basic license related tasks. I reviewed the Microsoft Graph PowerShell SDK overview page and clicked Get-started only to be greeted by 404 - Page not found.
Feels like they've completely given up on documentation, huh
33
u/Ecrofirt 11d ago
For a long time I read on here about people just saying screw it and using
Invoke-MgGraphRequest. Took me a long time to finally drink the flavor aid but now I'm doing this more and more.
It means the only module you need to load is Microsoft.Graph.Authentication so it's much faster. The calls return lightning fast. The REST API seems to be much better documented. Biggest downside I've hit is you've got to handle more things yourself: constructing objects, paging results, etc.
11
u/commiecat 11d ago
I use the API directly without any of the SDK modules. It took some time to learn at the start but now I've found it much easier to deal with. The Graph Explorer is a great way to find endpoints and test syntax, and it'll show you the Graph permissions needed.
5
u/Ecrofirt 11d ago
Biggest benefit is being able to log in easily with the baked in stuff that's part of connect-mggraph.
And since we're connecting easily with that, invoke-mggraphrequest adds such a minimal layer on top of invoke-restmethod while being graph friendly, sticking with it was a no-brainer.
1
u/commiecat 11d ago
baked in stuff that's part of connect-mggraph
Yeah, the "baked in" bit is what gives me pause. At some point that module will update and/or the auth mechanism will change. Recently an SDK update caused Connect-MgGraph to conflict with Connect-ExchangeOnline.
I made my own functions that can connect to Graph using an app registration or as a specific user with a device code.
2
u/Ecrofirt 11d ago
Yep, I webt the same route at one point, using an HTTP listener to get an auth code sent to localhost, and we already have device codexblocked. Then we had a cyber security audit and we needed to move away from http://localhost. I wasn't going to put the work into migrating to something that could work with HTTPS without administrator access, and getting WAM baked into PowerShell was a chore I didn't want to go down. Eventually decided to stop swimming upstream and save myself the headaches lol.
But I hear you, I did a full implementation at one point (with a cute pacman animation in the terminal while waiting on the token).
1
u/titlrequired 11d ago
So much easier. No need to install all the other modules. No stupid version conflicts.
2
2
2
u/ViperThunder 11d ago
I don't even do that, I just use invoke-restmethod. I don't really see the point for invoke-mggraphrequest unless maybe you aren't automating ?
23
u/BrettStah 11d ago
At least that 404 page has a link to the Get Started page! Usually the 404 pages are less useful than that.
1
u/dodexahedron 11d ago
Also that incredibly useful banner on old docs that links to the current version.
...which is invariably just the base product page for windows/windows server/etc...
14
u/sarge21 11d ago
It's the worst. graph is fucking hell and some things just don't work
6
u/JNikolaj 11d ago
I love how Graph has something fully documented and then i'll be spending 4 hours on something which blatantly isn't working
5
u/Alaknar 11d ago
My favourite are the filters. Sometimes they work a bit like proper PowerShell filters should, sometimes it's just a literal filter string from the API call. You get to discover which is which via trial and error! Fun!
Fake edit: actually, I lied. My FAVOURITE PowerShell Graph feature is:
The 'Get-MgUser' command was found in the module 'Microsoft.Graph.Users', but the module could not be loaded due to the following error: [Assembly with same name is already loaded]
For more information, run 'Import-Module Microsoft.Graph.Users'.
And then you run
Import-Module Microsoft.Graph.Usersto get the ever so helpful information:Import-Module: Assembly with same name is already loaded
!FUN!
1
u/Fallingdamage 11d ago
Especially this week. Taking hours to return full data sets that usually only took maybe 3 minutes.
12
u/MalwareDork 11d ago
Nothing will ever beat Salesforce documentation in terms of shit.
"Here's a vague article on what we think we do. If you can't figure it out, tough shit and it'll always be your fault."
"We also hide our support tickets and give out the vaguest reason why it's happening to gaslight you into thinking it's still your fault."
"We also ignore all of your emails unless you pay us our Signature Support Plan which we send you AI responses anyways."
Graph sucks but it at least points you in the right direction even if at the end you need to contact MS; but it'll never be as bad as Salesforce CRM. The dev articles are top-tier though, way above what Cisco and Microsoft produces.
3
u/Andrew-Powershell 11d ago
you know we're in a bad spot when we're all arguing about what's the worst place for documentation . it's a race to the bottom with those expectations from big companies these days
3
u/MalwareDork 11d ago
And it's a real bummer, too. I've seen some amazing documentation from small companies and even older programs that spit out 20 separate instances of log files.
Cisco should be the most embarrassed with their expected level of complexity.
9
9
u/Ecrofirt 11d ago
Microsoft and poor documentation. The most prolific duo since peanut butter and jelly.
6
u/Modify- 11d ago
This, by muddermanden in the other Graph post today:
You can use F12 and copy Graph API URI from network tab while navigating or performing actions in the portals in the browser. Then use the Find-MgGraphCommand -Uri <paste URI here>
It helps you discover commands and their associated permissions.
PowerShell module is just wrapping the API.
However, when a command is not generated for PowerShell Microsoft.Graph module (when API is ahead), you can use Invoke-MgGraphRequest -Method <GET|PATCH|POST|DELETE> -Uri <Paste your URI here>*, to act as the low-level interface*
to Microsoft Graph REST API.
Graph X-Ray extentsion makes it even easier.
Also Merill has a good video on the Powershell.org YouTube channel.
4
u/maxfischa 11d ago
The backbone of graph is the gui admin portal combined with a browser extension that shows the backend graph call.
3
u/x0n 11d ago
Documentation aside, I find the graph explorer invaluable: Graph Explorer | Try Microsoft Graph APIs - Microsoft Graph
1
3
u/toddklindt 11d ago
The Graph PowerShell SDK had such promise. I was really looking forward to it. But they dropped the ball at almost every step. I kept hoping it would get the attention it deserved, but it never did. My normal technique now is a combination of Graph Explorer and Invoke-PnPGraphMethod. It shouldn't be this way.
3
u/Jeriath27 10d ago
Not it's get-theVerySpecificThingThisSuperLongU readableComplicatedCmdletThatYouWouldNeverGuessDoes
5
u/rtuite81 11d ago
Yes, it is. I have had to use Claude to figure it out. Once you get the information you need, document it yourself. You can actually give it access to Graph with a basically zero permission service principal and it will go out and crawl the API and get you what you need.
2
2
u/purplemonkeymad 11d ago
Yes.
Don't forget the massive pre-formatted text sections that have had all formatting removed, and have huge amounts of duplicated info.
2
u/LookAtMeInMyEyeball 11d ago
Most of learn.microsoft.com is AI generated. There’s too much content to have someone update in a meaningful way.
I have a friend that used to moderate feedback for the learn site and the feedback was all similar. No good examples and too vague.
2
u/Andrew-Powershell 11d ago
They just laid off a lot of their docs writers a couple weeks ago. Expect it to get worse
2
u/Fatality 11d ago
Honestly just use the API, they don't even use AI for the powershell module it's just scripted.
2
u/slullyman 8d ago
1
u/slullyman 8d ago
I post this feeling proficient in PS and Graph (go read the API docs is what I’m getting at)
1
u/guardianz 10d ago
I have been trying to do some more things in Microsoft recently for products. And every single little thing is grinding away at my sanity. The more I use their products the more I hate them. Even opening a support ticket today took about 10 minutes and had me answer 20 questions. Which none of their pre filled options were my problem so i basically just had to keep lying to them to just open a ticket. I hate Microsoft.
1
u/VirtualDenzel 7d ago
Hahaha. So true. They were even denying the current outlook and hotmail.com issues. In 1 minute we got the basic autoreply
1
u/guardianz 7d ago
They told us those were fixed and then we got another ticket from a user having the too many objects issue. Supposedly a windows update broke it. Maybe get it together Microsoft.
1
38
u/banduraj 11d ago
Take the word "Graph" out of the title of this post and you'd still be right. I have doing this a long time, and at one point in history, Microsoft documentation used to be really good. They even had a public KB. Now, things change so fast, they don't QA anything and probably don't even pay for legitimate documentation employees. The result? ALL of their documentation sucks!