r/PowerShell • • 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

112 Upvotes

47 comments sorted by

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!

7

u/dodexahedron 11d ago

They have even harmed some of the older documentation in their pass over everything with AI, and now some documents are actively worse than their previous versions - sometimes dangerously so.

4

u/Jeriath27 10d ago

You could also take out the word documentation and it would stay correct also.

1

u/dotnVO 8d ago

They also let go of some employees semi recently that did a lot to try and wrangle docs. I noticed an immediate decline when they left. I'm not saying it was great before but I could rely on people I met from the PS community that worked at MS to make tings better.

For example I've submitted a few really basic PRs to remove back tics out of ps code samples and they get no attention. I think I also read recently they are closing some of the public docs. Then they closed the blog for comments lol.

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

u/dodexahedron 11d ago

Plus that is cross-platform forever.

2

u/Paxxi 11d ago

This is the way. Adding a paging wrapper and recursive psobject converter isn't that much work and well worth it

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.Users to 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

u/That-Duck-7195 11d ago

At least it is not the IIS default page.

4

u/Proxiconn 11d ago

I've seen nginx error in ms docs pages. So definitely an improvement

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

u/kfreedom 10d ago

100% this. Ditch the mggraph cmdlets and do graph api calls

3

u/Jewba1 11d ago

I remember thinking back in 2019 "cant wait for the documentation to get better"

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

u/Pacers31Colts18 11d ago

The learn mcp server is a god send for Claude.

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/BlackV 11d ago

I feel your pain

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

u/Bademeiister 9d ago

Don't have any problems with it. And we've built huge interfaces to intune