.Net Foundation On .NET, 29 Jan 2019

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Exploring the Microsoft Graph SDK

Description

Microsoft Graph is a gateway to the data and intelligence in Microsoft 365. It provides a unified programming model that you can use to take advantage of the data in Office 365, Enterprise Mobility + Security, and Windows 10.

In this episode we're joined by Darrel Miller (@darrel_miller), PM for Microsoft Graph developer tooling. Darrel gives us an overview of what Microsoft Graph is, and also shows us how to get started with the .NET SDK.

[T00:54] - What is Microsoft Graph?
[T02:25] - Getting started
[T06:34] - Graph .NET SDK demo
[T13:45] - Providing a token to the SDK
[T16:58] - Reading information with the fluent API
[T19:40] - Sending email via the SDK
[T21:32] - Customizing the underlying API request
[T23:39] - How does Microsoft Graph and the SDK get versioned?

Useful Links

Microsoft Graph Homepage
https://developer.microsoft.com/graph?WT.mc_id=ondotnet-channel9-cephilli

Microsoft Graph Documentation
https://docs.microsoft.com/en-us/graph/overview?WT.mc_id=ondotnet-channel9-cephilli

Microsoft Graph NuGet
https://www.nuget.org/packages/Microsoft.Graph?WT.mc_id=ondotnet-channel9-cephilli

Microsoft Graph Client Library for .NET
https://github.com/microsoftgraph/msgraph-sdk-dotnet

A

Hi,, I'm jeremy likness with on.net., I'm here with darryl miller., we're talking about microsoft, graph,, which is a gateway to pretty much the universe,. If you will.

A

B

Yes., if you want to get access to your data,, it's the place to go.

A

Sounds great. check out the show,, we'll give you more details. Then.

A

Hello and welcome to another episode of on.net.

A

My name is jeremy likness, and today we're going to talk about microsoft, graph., I'm here with darryl miller, welcome.. Thank you very much.. Thanks for having me.

A

darryl, tell us a little bit about what you do with microsoft and what team you're on, et cetera.

B

So,, I'm on the microsoft graph developer experience teams,.

B

I'm a program manager on that team,.

A

As of just this year. great, and that's the topic of our show today is microsoft. Graph, so tell me, what is microsoft, graph?

A

so,, microsoft graph is a large http api.

B

Well,, technically it's not exactly an api,.

B

It really is an api gateway to a lot of back-end services.

B

So, many of the microsoft 365 apis is.

B

A surface through the microsoft graph or azure apis is a surface through the graph, and now we're starting to onboard a bunch of functionality.

B

From windows, services also onto the microsoft graph.

B

So,, it's a one-stop shop where, if you want to make requests and get data, specifically data about you and your organization,.

B

You can get that through calls the microsoft graph.

A

Just to clarify, some people,.

A

There's a lot of overloaded terms, graph ql for graph query language.

A

So,, when we're talking about graph, we're not talking about the graph query, language specifically,, but more of graph of navigating through entities objects,.

A

Service calls,, what have you? absolutely,? It's not graph ql at all,.

B

But it has similar type of characteristics.

B

In actual fact,, the microsoft graph follows a lot of the conventions of odata,.

B

I'm sure a lot of people are familiar with odata. so,, a lot of the conventions for making requests for selecting subsets of things,.

B

For being able to navigate to other entities,, a lot of those conventions are carried over from odata, although,.

B

It is not a strict odata protocol based service,.

B

It does use a lot of those conventions.

A

Okay, great. is there a way I can look into and get started with. Graph, see-.

B

Absolutely. -what's it about? so,, the homepage,. The starting page is just graph.microsoft.com,.

B

And this is our landing page where you.

B

Can find all information about the graph.

B

Some of the really cool stuff is you're trying to decide, well,. Why should I care??

B

What can this do for me?? We have a whole bunch of scenarios here with regards to onboarding users within an organization,.

B

That process, where you've been hired by an organization and.

B

You've got to do a lot of provisioning of a whole bunch of different things,, maybe security, accounts, mailing list..

B

We talk about the different things that you could do to automate those workflows, here on the site..

B

We also talk about integrating with excel.

B

You can actually update, manipulate, create excel files directly through the graph that.

B

Live in the sharepoint or onedrive, managing employee profiles.

B

Now, more recently,, it was announced to ignite access all of the security alerts.

B

So, we're now pulling in a lot of the security alerts that are across azure, and you can access them through a simple http api directly from here.

B

If you keep scrolling down in this site,.

B

You can see here the different services- intune, outlook,, onedrive,, onenote, sharepoint,- and this isn't exhaustive of all the services that are behind the graph api, and the services that are available are growing. All the time.

B

We support a wide range of languages,, either via specific sdks for c-sharp, java, javascript, php,.

B

We've a preview of ios,, we have a ruby, sdk,.

B

And we also have a ton of samples and.

B

Training documentation in order to help you get started.

B

So,: here's really a great landing page that you can.

B

Go and try to find out more about the graph.

A

So, now I'm looking at all those different services,.

A

Office 365, outlook,, onedrive, et cetera.

A

So,, this is something that, as opposed to grabbing, for example,.

A

Onedrive's specific sdk or set of services,.

A

This is a unified gateway that I can use to access all of these different resources and maybe even orchestrate transactions that go between different assets in my organization, if you will?.

B

Yeah., this is why we're in the developer, experience team and as far as we're trying to just make the experience, much better, one place to go and deal with authentication,.

B

One set of sdks to deal with, one set of conventions across all these different services that are produced by many many teams across microsoft, and as the services actually come on board the graph..

B

They go through a review board. Process,.

B

Where we sit down with the teams- and we talk about, "oh, look,, you call that thing a slightly different name than what other teams have called it?" and, "oh, you've created another enum type for this- that some other team already created that,.

B

So let's not create a duplicate". so,, it's all about taking all the rough edges off working with apis,.

B

So it's not dealt by a thousand dollars.

A

So, I have some consistency, and if I've worked with one set of data, when I'm doing something else in graph,, that should be familiar to me. If I'm working with that similar set of attributes or properties?

A

yes, and on top of that,.

B

We get to define a lot of common capabilities like being able to do what we call "delta queries". so,. You can say, "well, go and get me the messages that I received in.

B

My inbox, since the last time that I asked you for it".

B

We have the whole webhook notification mechanism,, so you can listen for changes.. Tell me when somebody is added to the security group and you can get a webhook callback.

B

so,. The graph has those cross-cutting features that are available at many different points within the graphs services. Also.

A

So,'s not just set apis that I can call,.

A

It manages a little bit as state remembers what I looked at before it has callbacks into my system..

A

Yep. so, we've talked a little bit about concepts as their way.

A

To drill down the next level and see it in action?.

B

We certainly can., let's just do simple.

B

the simpler, the better for me. so,. Just let's do a console. Application.

B

okay. so,, I'm going to fire up visual studio and create a new project here in visual studio.

B

We'll use.net core,, you can use full framework,.

B

You can use.net core where.net standard 1.3,, so we're on.net.

A

So,, this is great, because of that support,. Whatever I built here is going to be able to run on windows, 1x,.

A

Mac os,, basically wherever I want.

A

on mobile xamarin,,.

B

So we can use mobile, sport? yep. great., whatever you want to do.

B

So, we have our dead, simple console, app,.

B

And I always like to make sure that it actually works before I do anything,.

B

Just that. I don't blame myself for what I typed,.

B

And we have a running console: app. excellent.

A

Hello world., it's my favorite application, right?.

A

After that everything gets lot more complicated.

A

So,, if we want to start working in the graph,.

B

We will going to use our sdk., but really when I say sdk,, it's just a nuget package. so, we go over to dependencies,, we say, manage new, get packages,.

B

Let's click over on to "browse" over here,.

B

And we're going to say microsoft.graphs.

B

Remember the dot is little picky. If you don't say, say dot.

A

It's a little bit of a sensitive searches, here.

B

So,, there are two main packages as core and graph,: we actually code-gen a bunch of the model types and what we call request: builders for the fluent interface,, so they live in the microsoft graph. Sdk.

B

Which takes a dependency on the core stuff, which has all the cross workload type capabilities., so, really,. You just need to take a dependency on that package and it will pull in the other one.

B

Latest stable is 112th, there's. Actually a 113 preview is available, also,.

B

And that should be coming out to become ga within the next couple of days..

A

We're starting to try and get a real, regular cadence,.

B

Because they say there's new capabilities being added into the graph, all the time.

A

What is the cadence right now??

A

Is it closer to monthly,, quarterly, yearly?.

B

Not to lock you in the calendar.

B

we're trying to get to monthly. okay., it's been quarterly. The last little while.

A

B

We've gotten a lot of ci processes that we've been building up and mechanisms.

B

Where we're pulling that metadata and doing the code-gen,, there was a lot of manual steps. Before. so, we've got that all cleaned, up. so,. Now literally, what happens on a tuesday morning when the metadata gets pushed onto the graph,.

B

We trigger our ci process and it does a pr against across all of.

B

Our different languages and there's the changes that are going to go into the next release of the sdk.

A

Good, with devops to the rescue?.

B

We're trying to get there.

B

so,. I have taken a dependency on that package.

B

Now,, I can go and create myself client.

B

new graph service, client.

B

Let's pull it in that namespace.

B

So, by the way, one of the most time-saving features,.

A

I think there was added individual studio.

B

Is going in the using automatically.

B

yes.? It's got a red squiggly on there,, we're going to ignore that red squiggly just for a moment and we're going to move on, so we'll come back to it in a moment.

B

so,. When I hit dot on that client, you'll start to see device, management, devices directory, directory objects,.

B

These are all capabilities that are organization-wide,.

B

Usually, where people want to go is to me,.

B

Because the graph is, a lot of it, is about my data,, as in the user who's been signed, in, is user, who's running your application., you get delegated authority, so your app can access the data that belongs to a particular user.

B

okay. so,. If we look here,, we've got the calendar, calendar. View, we've got change passwords, and we've got functions as well as data that are available.

B

Here at ryan's to go and get your onedrive data,.

B

Here's how you can go and manipulate excel files and access your word documents, here, events from your calendar,, all information that is available, insights.

B

If you've ever played with delve and you'll see that list of trending documents of the people around you who are working on those documents,, you can get at those insights directly through this api.

B

So, we're going to make a call to messages.

B

we're going to go and look at our inbox.

B

so,. We have. This message is entity that we're referencing.

B

We want to make a request to it,, so we do dot request, and then the simplest thing is. I can just say, I'm going to do get on that thing, and what's that going to do, is it's going to return to me a list of messages.

B

Well, technically,, it's not because it's an async, call,.

B

So really, you need to do in a weight on that.

B

so,, I'm going to cheat, and never tell anybody to do this in a real application.

B

Blocking that result.

A

That's right.. I actually went and tried it. How do we.

B

Actually committed to do async on main in core yet,, but it didn't work for me. so, hopefully,. One day we can do async menu.

B

So,, I would be able to run this now, except for the fact,.

B

And it would go and get my mailbox messages, except graph service clients, unhappy.

B

so,. Why is graph service client unhappy??

B

If we look at its constructor in these authentication provider,, because security is paramount,, we need to prove who you are, because I don't want anybody accessing my messages.

B

so,, the absolute easiest things for just- because of time,.

B

I'm going to use what we call the delegatedauthenticationprovider(),.

B

Which is a glorified name? For,, here's an action, that's going to give you a token.

B

okay.. I better ask a request message into it..

B

Intellisense is wonderful. Sometimes,.

B

And then sometimes it's not.

B

request,- and this is just an hp request. Message,.

B

And we're going to set the header,, the authentication,.

B

Authorization header with the new authentication header value,, this one.

B

But let's make it a little shorter.

B

Bringing that namespace, and it has a bearer.

B

Now, obviously,: this is not what you would do in a real application,. You need an authentication provider or you need to provide code here that would go out and make the request to authorize you to go. Get the token,.

B

Pop up a dialog, and you can use any oauth2 provider,, it's just a standard. Oauth2 flow against the graph,.

B

And identity provide saml or [inaudible].

B

You can use either of those libraries here..

B

We have a library coming up soon.

B

Where we will have a whole bunch of authentication providers for you.

B

so,, if you want to do device code flow, or you want to do, username, password or windows, oauth,, we'll give you a set of providers and you'll just be able to plug that in here..

A

We're keeping it simple, though, we're putting a token in the header and we're done.

B

Right. the thing is: we've got to get a token. so, we're going to cheat again. we're going to go to, actually,. We can go back up to the microsoft graph homepage.

B

on the top of here is a tool called graph explorer.

B

Now, graph explorer is just an interactive way of working with the graph and trying out different things and finding what information is available, but handily,. It has a sign-in, process.

B

so,, I'm going to sign in with my own personal office, 365 account here..

B

If you don't happen to have one,, you can go to aka.ms/officedev,.

B

And you can get a developer subscription there or if you have msdn,, you get an office licensed along with.

B

okay. so,. I've now signed in here.

B

I'm going to hit the magic f12 and pull up developer tools, here,.

B

And I'm going to ask very nicely and say, token please, and it's going to give me a token.

B

Nice. I have to copy all of it. there. We go.

A

Token please,, I have to remember that.

B

Should always be polite to our software., you never know when it's going to not work for us.

A

Is a closed-off? yeah.

B

I think I put the double quotes to the end,.

B

Let me make sure, little quotes first.

B

Okay. so, we're going to go off and get messages, here,.

B

Although I could end up with an absolute ton of messages,.

B

So how about we just limit that to just the top 10?.

B

So,, we don't end up with too much stuff, and if we want to actually see some results, here,.

B

Let's just go through this collection and write.

B

Something out to the console, so we can actually see it.

B

Item.Subject, and the date it was sent, sent datetime.

B

Okay. say it will, prior to the demo gods..

A

Yeah, see the red squiggly under here.

B

A

Yeah., you know why?.

B

Because going and getting.

B

An authentication token is potentially a long running operation.

B

So, that action is actually async.

B

There we go. that will now turn to green, telling me, "hey you're not doing any waiting".

A

Async method, sure. all right.

A

So,, that was pretty straightforward, pulling in the package,.

A

Adding some authentication, and now we're going to get to see all your email, message.

A

yeah,, that's right, which is.

B

Always a dangerous thing to do, right.

B

dear bmw,, your secret pin number is.

B

Luckily,, I don't have a bmw.

B

so,, we're all good there. so, there we go.

B

I've just pulled email,. My email thread messages directly from my office, 365 account.

B

Now, I mean one of the values of the sdks is.

B

Because we're trying to make it easier to construct these requests,, so there's a bunch of other things that I can do.. I mean, I'm pulling the entire message: object, there,.

B

But then I'm only writing out a couple of properties..

B

It will be nice if I can just say, "well,. I only want some of that information." so,. I have to select "concept." it's a little bit like link,, but I could put a comma delimited list,.

B

But that would really be sad if I had to do that.

B

how about we just use a little lambda expression here and we create a new anonymous object, and we say, "well,.

B

I only want the subject and the sentdatetime.

B

Now,, when you do this,.

A

If I look at the wire,, it's going to parse this request to understand what you want,.

A

And make their requests over the wire. so,. It's not just a question of what's filtered to print,.

A

It's a question of what comes down from that api call behind the scenes.

A

well,. This request, builder concept,.

B

This fluent request builder will construct that http request,.

B

And create all of that select information is just going to go into the uri.

B

okay.. Then it will go over the wire as a uri, and the backend will know what to do and just return me a subset of those results.

B

nice.. There's a bunch of other things. I can do. for example,. Let's say,, I want to also get the attachments.

B

I don't want to go back multiple times for each email and go and get the attachments.

B

So,, I can also say, "expand and include the attachments in it.".

B

So,, this is a little bit like what graph ql doesn't look the way you describe the shape of the object that you want to return. Back., I'm saying, "well,, I don't want just want the message,.

B

I also want the attachments that belong to the message.".

B

okay.. I can actually further filter, that, and say, "we'll,.

B

Only bring back the ones where has attachments equals true.".

B

Now, that, unfortunately, is text-based,, and we need to do some work on making that strongly. Typed.

B

But, that will now allow me to return back just a smaller set of messages and only bring back the messages that have attachments,.

B

And it will actually bring me back the attachment results.

B

So,, if you should see a different set of messages that are returned here, and if we actually went and looked at that object model,, we would see that there are attachments associated to those links.

B

Nice. now,, it's not just about read..

B

We can also write. so,. We can easily do client.me.sendmail.

B

What could go wrong? Here?.

A

B

Sendmail takes a parameter which needs to be a message: object.

B

So, we're going to go and create ourselves a message: object in a moment., then the same process again,.

B

We create ourselves request, and in this case, because it's an unsafe operation,, we use a post method in order to send that.

B

now,. We need to create a message object and we have a strongly type thing., I'm not going to make.

B

You wait and watch me type that message: structure, here,.

B

So I have it over here, so I can just copy it. Over,.

B

And we'll paste in that message and I call that mymessage.

B

Here,, we don't need to loop through the results. Anymore.

B

Then, its wanting you to pull in,.

A

I think, system.generic or collections.generic.

B

Absolutely right. yeah. all right. okay. so,, I'm sending.

B

An email from my personal account to my company account.

B

If all goes well,.

B

I go load up my email client,.

B

I go look at my personal and look in sent items..

B

I should see there. You go. hit on.net. it's there, and if we do a little refresh.

B

It didn't send it.

B

We saw it send. right. momentarily,. It should appear in here.

B

so,, while we're waiting for it to appear,. Let me just talk about a couple of things that are really important for people working with sdks.

B

sometimes, people will only work with sdk's. It's a wrapper around making those http calls,.

B

And people were often familiar with the native library of how to make those calls.

B

so,, they use the sdk and then they run into brick. Walls and say,.

B

"But this thing isn't supported.. I want to put my own custom headers in here.. I want to do something special with the response.".

B

They sometimes, if the sdk doesn't support,.

B

They're like, "I'll just do it myself" and throw it away..

B

What we want to make sure with the sdk is that there's opportunities to peel away the layers at every step of the way.

B

Sure. so,, if you go back to here where we created that request,.

B

You can then say: gethttprequestmessage here,.

B

And we will return,, we will construct that http request. Message.

B

Then I can manipulate that., then you can manipulate it, and then you can just create your own http client library, like this,, httpclient,, new httpclient and just send that request,.sendasync.

B

With the request,, that's nice.

A

With the request.

B

I'm going to actually pull out in.

B

So, now you send the request off, and he said, "but hold on a second,, though I've just opened new http client though..

B

What about all the authentication mechanisms?

B

That's built into the sdk?? What about the rate-limiting capabilities we have there?!

B

We want to build caching layer,, there's a whole bunch of cross-cutting concerns that we're building into the sdk..

B

If I knew what the new http client, I'm going to lose that capability. well,. This is why we are playing or prototyping a graphclientfactory.

B

You say, createclient, and we'll pre-build you.

B

An http client with all those pieces of middle-ware already in there.

B

so,, then you will still get all of cross-cutting concern. Goodness,.

B

And then you can take that response back and then you can still use our regular deserializer and our regular error. Handling.

B

So, at every step of the way,, we want people to be able to just peel off the layer and get under the covers and do their own thing, and then going back to being able to use the rest of our sdk goodness..

B

Is there an extensible model, here,.

A

So we were looking at releases,.

A

Let's say the one comes five months from now., but there's a new service, that's being on-boarded into graph in the n-term.

A

so,. That's the sdk is not available,, but I'm assuming that there's a convention,.

A

A set of api end points that I can call- and I could,, for example, use this factory to get the client to change the uri and still access that service.

A

yeah,. You still should be able to.

B

Use all of our regular crosscutting thing., the only thing you wouldn't have necessarily are the models and the actual request builder..

B

But having said that, all of graph mainly is on version 1.0.

B

We're a little bit different than the way azure,.

B

Where azure versions, all of the services,, the azure management apis, are all versioned independently.

B

A

Graph,, all the services are old version, together.

B

There's a v1 of the api, and if you actually go and look in the docs and we scroll down to the reference things,, because the docs now on docs.microsoft.com,, we have the v1 reference,.

B

We also have the beta reference. so,, the really there's the g8 stuff,.

B

And then there's the stuff, that's coming., if beta stuff can make it into v1 without being a breaking change,.

B

It will migrate, there, and we're getting very close to being able to start shipping a set of beta sdks too.

B

so, you'll have the full set of models in order to play around with stuff. That's going to come,.

B

And then, when it moves into v1, those types and those requests, builders will automatically appear in the v1 sdks.

A

Nice,, so this actually answers the next question. I was going.

A

To ask questions, which is where the documentation is.

A

Sounds like there's a lot to graph to navigate,.

A

And we've got it on our centralized docs.microsoft.com site.

A

Yes, we just moved there recently,.

B

And it's great now because you can just go into here and.

B

Using the filter here, if you want to find out about sendmail,.

B

And I think, if you do send mail, immediately, it will pull up.. Here's the reference for it.

B

when you're setting up security, you're going to know what scopes or what scopes to use to be able to make those calls. So that information is all here and we show the requests, and we're working.

B

Hopefully, very soon, we'll actually have our code snippets in here.

B

so,. We have at the moment the http requests,, but you should be able to see soon. C-Sharp, snippets and other language snippets in here.

B

It's nice., it's all coming soon.

A

It's great. all coming., that's right., so,, I'm thinking we talked about office-azure integrations,,.

A

And I'm assuming you just refer to the docs that'll, continue to update what, entities and objects. You have access to.

A

yes.. We saw a huge list of sdks,, that's pretty exciting.

A

So, pretty much any platform you want to develop on,.

A

This is available, and you said there are some providers coming out as well.

A

so,. We've got some baked-in support right now for some things like active directory, of course., but there will be other provider models that we can tap. Into.

A

well, there'll be provided for.

B

Different scenarios of all, because there's all the different auth flows,. sure., if you're on xamarin, the way the ui works, is a little bit different..

B

If you were trying to do a plug-in for text-based things,.

B

You want to use the device code, flow. so,, there's a bunch of different scenarios and we'll have authentication providers which really are just wrappers around mcl.net, which is the identity-authentication library.

B

we're not doing the heavy lifting, we're just adapting those identity. Libraries.

B

To the microsoft graph.

B

okay. sounds great.

A

Anything else we want to touch on before we wrap up..

A

I don't think so.

B

I think we've covered it pretty thoroughly, at the time that we had.

A

All right. that sounds great.. We will get all of the links that we discussed about on the show posted to the show notes.

A

Thank you so much for coming in and sharing with us.

A

microsoft graph looks very incredible.

A

thanks for having me.