Microsoft 365 Community PnP Virtual Conference, 8 Sep 2020

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: PnP Virtual Conference - 09/2020 - PnPJS and Async/Await: A Powerful Combination

Description

Do Promises make async code look like spaghetti? Is it painful to build REST URLs to read and write data to Office 365? Maybe it’s time for some updated coding practices. This session will cover the use of the fluent programming style with the PnPJS library and how to make asynchronous code look synchronous by leveraging the async/await pattern with try..catch blocks instead of promise chaining and error blocks. The result is a lot less code that is simpler and easier to follow, and much easier to maintain.

Speaker: Julie Turner (Sympraxis Consulting) | @jfj1997

Supporting materials:
• PnPjs documentation - https://pnp.github.io/pnpjs/
• Using PnPJS and Async/Await to Really Simplify Your API Call - https://sympmarc.com/2018/12/12/using-pnpjs-and-async-await-to-really-simplify-your-api-calls/

Learn more:
• Learn more about the Microsoft 365 Patterns and Practices community at: http://aka.ms/m365pnp
• Visit the Microsoft 365 Patterns and Practices community YouTube channel: https://aka.ms/m365pnp-videos

A

Hi everyone, my name, is julie: turner, welcome to the pmp virtual conference today, we're going to talk about the pmpjs library and async await a way to use those two things together to make your sharepoint framework code same so a little quick intro about myself. Like I said, my name is julie turner. I am the partner and cto with some praxis consulting we're, a small six-person, consulting firm in the northeast section of the united states.

A

I personally have been working with sharepoint since the 2007 version and I've been a microsoft mvp in the office apps and services area since 2017, and also a pnp team member. Since 2019 I have a couple links here.

A

One is to my github repo uh there's a public samples uh folder in my repo that um will have copies of all the code that I'm going to share today and and copies of code from all my previous demos ever given and and blog posts and all of those things and speaking of my blog, my blog is at julie turner.net, which I haven't posted to recently, but I'll probably be doing some new content soon so to dive. Right in.

A

um When I give this presentation in person, I would often like to sort of set the tone, so people can run away quickly if they need to. um So are you in the right spot? Basically, I want to set the tone that this content is going to be for developers, who've done some client side dev in sharepoint and that are very familiar with javascript and typescript and hopefully understand promises at some basic level.

A

I am going to go through promises fairly thoroughly, so, if you don't don't necessarily run away but understand that we're going to be talking at that level today, so I just want to level set, make sure everybody's ready to go.

A

Okay, our agenda, it's short and sweet 30 minutes today, so we're going to start with going over what pmpjs is and hopefully give you a flavor of what that library is and what it can do for you and then we'll talk about what async await is specifically and and how that relates to promises and then we're going to spend the bulk of our time. Doing. A very in-depth demo of the async await uh uh pattern using the pmpjs library so putting those two things together.

A

So, let's start by just quickly giving a overview of what the pmp js library is. So it's an open source initiative. It is wholly created and maintained by the community, and uh you know it's a it's a work of love. uh There's a few of us who try to maintain the code base, maintain the documentation, answer, questions in the issues list in the github repo, um and you know we do that uh as as best we can and hopefully we're able to help anyone who needs assistance.

A

The document, the library itself is a fluent library for accessing sharepoint and office. 365 rest apis in a type safe way. So it makes it a little simpler by providing this fluent style of programming that I'll sort of show you in a few minutes uh to access those rest end points with without actually having to necessarily know what the next thing is, which can be arduous.

A

um In general, the library is used by more than uh 12 000 tenants and it's generating over four billion requests each month. So that's a lot of use and we're really excited that it's taken on such a life of its own and then it's really helping people out there get get their work done.

A

We absolutely accept and encourage contributions from the community and constructive feedback when necessary, and we do the best we can, but obviously your contributions can go a long way and if you have suggestions, we're absolutely open to to hearing those.

A

Okay, so pmpjs can be used in a bunch of different ways. Not only can it be used in your sharepoint framework projects, which could include things that would be deployed into sharepoint or teams or now as a outlook add-in, but it also so can be used in your server-side code when you're using node.js, and it also can be used in your spa applications that are outside of the sharepoint or office 365 landscape and just your straight up web applications that are written in javascript or typescript.

A

So it has a breadth of uses, but it basically gives you access to all of the office 365 apis, but primarily to the sharepoint ones.

A

So when I say fluent api and what that really gives you is in general, if you're going to access the restful endpoints, you need to be able to submit a post request or a get request or a patch request to a particular url, including some configuration in that. And then you would get back a payload that you would have to then uh convert into json. And then you would be able to work forward from there.

A

And it takes a lot of effort to sort of remember what those urls are to format those urls and then to deal with the requests and the responses, and so what this library intends to do is make that significantly simpler by providing you this fluent methodology for accessing the content. So you can see here on the screen. It's you know your web.

A

Your list, your list by a title, your items and then once you request what you want, you get those results back in a json format without having to do that extra step of converting it to json.

A

um So if you want to start trying to use the pmpjs library highly encouraged, you can go to the documentation which is at pmp.github.io pnpjs, and I highly encourage you to go through at least the getting started information.

A

um There's we work really hard in the documentation, we're constantly improving it and by going through that getting started documentation. It's going to help you make sure you start things off on the right foot and then, when you need more assistance, if the documentation under the packages area or the library concepts, don't get you where you need to go. You at least know that you've started off on the right foot and you are able to ask more concise questions in our issues list and that can help you help us help you more easily.

A

So when we talk about async await if you're familiar with programming in javascript, then you're definitely familiar with programming using promises, because the browser is an asynchronous uh interface for restful endpoints on the server, and so you need to basically submit a a request via a promise and then have code. That's going to execute on the return. So a good example of this is in the sharepoint framework.

A

We often use the on init um protected method and that on init method returns a promise, and so we would then um say that we are going to return a promise that once the uh the on it on it. Excuse me once the on init function completes.

A

Then we want to set up our set up our pmp js library by using the sp setup method, and then we might use uh do some calls against that. But we need to wait for that on init function to happen, and this is super. It works great, but it's a little bit hard to read and it's a little bit hard to consume. So a different pattern is the async a weight pattern, and so this is, if anybody's written, c, sharp you're, probably already familiar with this, but by adding the decorator async before our function name.

A

You can then use the await keyword and by putting that await keyword in there. It turns what appears to be asynchronous code into synchronous code and, and it actually is still running asynchronously, but it appears and is visual to us and it we understand the logic in more of a synchronous way.

A

So we know that by putting this a weight uh keyword in front of our call that it's not going to move on to make the sp setup call until this promise is returned, and so you can see by looking at this that this is significantly more uh simple to understand and consume and to debug honestly.

A

So that's that's. Our our goal for today is to sort of switch. Our mindset from using traditional promises into using this async await pattern, and so uh next we're going to dive in and do a pretty in-depth demo about how we can build with async await versus using promises.

A

Okay, so what we've done so far is to create our sharepoint framework solution. So we just did a vanilla, plain old uh yo at microsoft, sharepoint and created that sharepoint framework web part project and now we're going to do one extra step and that is to npm install the at pnp sp library and so that installs, the entire library um into our package.json.

A

And so, if we open our package.json file up, you can see now uh right there on line 20, that we have the latest at pmp sp library installed. So we need to do that first and foremost, so that we can use the library okay. So then next we're going to just do some setup stuff. So I'm going to add um so we we have this component by default built in so we have the async await demo web part, which is the the main file that uh the uh the code starts from.

A

But we have this by default, one component in there, and so that component is just gonna, be our measly ui with a button in it. But I do need to set it up slightly. So I'm going to start by setting up some properties for my component, so I'll come in here and I'll change this so that I have a type which is just going to be a string.

A

That tells me if I'm doing promises or async a time which, in a more elaborate demo, I would be showing you the timing, differences that they're very similar between promises and async await. uh We won't be doing that in this demo, but that's what that's for and then a start function that just launches our code, which is in our main web part file.

A

We just need a way to pass that back the the command that we've clicked the button back up through, and so that's what that property is for. So then we'll quickly go into our a sync away, demo file and we're going to just swap out the default demo code.

A

That comes with uh the solution for our really simple basic ui, which just has you know a label on it with that type and then the time if we were passing it through plus a start button and we'll take out this extra escape line just to clean things up. Okay, so now we're back in our main async await web part.

A

Okay, so obviously we need to do our imports at this point, so I'm going to import the sp object from the pmp sp root library, but our library import in supports selective imports, and so, in addition, I'm going to include some other imports for webs fields, lists views, etc.

A

Then I'm going to set up the time variable that I would need and set up the call for my on init function, which then calls my sp setup and that's the what we call establishing context for the sp library and how it knows uh what web you're in and what site you're on, etc, so that it knows how to communicate with sharepoint effectively.

A

And so then. The last thing we want to do is uh that component that we set up. We now have to feed it the right pieces of information to the properties that we define so instead of description.

A

We now have, as we said before, the type and the time and the type I'm just going to set to async, because I'm only going to show the async example as a demo and the time is the time variable, but we're not going to use that today and then. Last but not least, I need to have a function and in this case, just a dummy function to get started for the start function. Okay.

A

So now, if I come back over to my command window, then I'm just going to do a gulp serve with the no browser option and then come on over to my browser, where I have the workbench set up in a particular site, because I'm going to be using pmpjs to affect what um effectively create lists and fields and views etc in a site. I need to actually have a workbench, that's in a site, so that I can do that. I can't use the local workbench because there is no.

A

You I'd have to mock everything, because there is really no sharepoint uh exist in existence that we can uh effectively act against. So we have the workbench running in a site collection that I have called demos and I've already, because I've served my solution up. I've already got it added into the workbench and our incredibly ugly, but uh simple and effective ui here with our start button that calls our start function.

A

So I'm going to start by creating method that I'm going to call step one promise and I'm going to pass in a list name that way later I can, when I want to call this method a bunch of times. I can change the list name, so I'm going to start creating this method and then I'm going to start by returning a new promise, and so I'm going to just have a resolve method and inside of that resolve method. I'm going to start by calling.

A

Well, for actually first, I need to start by creating some extra variables. So let me get the imports in for those variables so now we're going to make the calls to sharepoint to create our list.

A

So, let's start by making the call to sp.web.list to add the list name and since we're using the promises method, we're going to call the dot then to get our list results, and so what we would do next is inside of that promise then function we're we're going to check to see if our list results has a value if it doesn't we're going to resolve false.

A

The next step is to then put the list results list on the l variable so that we can use it later in one of the other promis chains in the promise we're going to create the text field by returning the promise. That is, the text, adding the text field so on our list: l, dot field, so the fields on the list.

A

I want to add a new text field to that and I'm going to call that field step, one text field, and so then, if we had an error on our promise that we called it's going to come out in the second section of this, so we have to add another method for list, reject and so list reject, then, is just going to simply console log and error and resolve false.

A

So our next step is to deal with the field results. So from our previous step on line 47, we return to promise, and so this entire then function needs to have another then to chain the promises together for the field result. So we have. The field result we're going to do something extremely similar, we're going to say. If I don't have a field result at all, then I'm going to assume there was some sort of problem I'm going to resolve to false.

A

Then I'm going to set our f variable to the field result: data which is the type partial field info, and then I want to create the view. So I'm now creating the view by returning the l for our list. L dot views. I want to add a view called step, one view and I'm returning that promise. Then the next step is the view result I gotta have I gotta handle the view being added. So then, if the view result happens, I wanna again check. If I didn't get a view result value. I'm gonna resolve false.

A

If I do, I'm gonna elevate it to the v variable so that I can use it later and then I'm going to add the field to the view and the way I'm going to do that is I'm going to return a promise using the view, dot fields, dot, add and then I'm going to use the f variable.

A

That was the field info dot internal name, because I want to add that uh field that I created to the fields of the view and then finally, I need to re, handle the rejection of the promise and then uh last but not least, I need to handle the promise of adding the fee, uh the feel to the view, and so then I'm just gonna say that it resolves true so because the whole thing is successful and finally handle it. If that was rejected, so you can see.

A

This is a long string of code that I had to put together to do that promise chaining to do that set of steps.

A

So now what we want to do is do the same thing, but use the async await method. So I'm going to start again by creating a new method and this time you're going to notice that I have that async decorator before my method name. So this one's called step, 1 async again, I want to pass in the list name and then what I'm going to do is what I kind of consider the standard shell of an async await function. I'm going to define my return variable in this case.

A

My return, var value is a boolean and it's going to be by default, false and then I'm going to add a try catch and so that try catch is how we do error handling in async await, instead of the various instead of the various reject functions, so the try catch will catch any rejected promises and throw them to the catch um and then, after everything, we're going to return the return val, and so this is why my return val is going to be false by default, because if the, if anything is trapped in here, the catch is just going to include a console log.

A

But it doesn't need to do anything else, because the error will the value of return valve will still be false, because I'm going to wait until all of my steps are complete before I set return val to true okay. So now, let's start to walk through what we need we're going to create the list first, and so I'm going to say let my list result equal await and then the sp.web.list dot add list name.

A

And then just the semicolon is only needed, so you could see how much more simple that's going to be than the dot then so now all we have to do because it's going to wait this this list result isn't going to have a value until till this promise returns. So we know that on line 88 list result is going to have a value, so I can just test it. So I'm going to say if list result then continue.

A

So here we are with listresult.list, has a value and then I'm going to say: okay, if it has a value, then create the text field. So now we have to say let the field result equal a weight and then we're going to just use the list result dot list here.

A

Instead of the l variable right, dot fields, dot, add.

A

Text and then the field name that I want to call it.

A

Okay and then, let's check if field result, has a value because again we know that field result won't have a value until the promise returns. If it does and then we're going to let the view result e wait. The list result, dot list, dot views, dot, add and then we're going to just give the view a name.

A

So now, let's say if the view result, dot view has a value.

A

Then. Finally, let's add the text field to the view, and so our final call is just to await view, result, dot view dot, fields, dot, add and then our internal name from our field result data internal name.

A

There we go and again we're just awaiting that, because it doesn't return an actual any object. It's just a 200 error or 200 result. So there we go with our asynchronous version of the function. You can see just looking at it, how much more simple and easy and obvious the what is happening is compared to the promise chaining version of the code. So now, let's just go, take a look at it. So we'll start by first coming down here and modifying our start function so that it actually calls our async method just like that.

A

But what we need to do is to put a list name in here, so I'm going to just call it test async and then we're going to go over to our browser and we're going to click the start button. And now, if I come over to my site contents- and we refresh our page.

A

We're going to see our test, async 1 list is in our site contents and then, if we look at our views, we have step one view low and behold and our field, so that was awesome. Okay, so we've pasted our step two promise in here right away. So let me just go over this. Basically, um our step two is going to be that we want to create three instances of the list, and so the reason I wanted to include this is to sort of show you parallel processing from a promise perspective.

A

So this is a common pattern where you have three things that can happen simultaneously um and as long as they're all finished, you know you can move on.

A

So that's a common pattern, and so I just want to quickly show how this would be written asynchronously so that it's understood, but it's not going to be as much of an improvement, as our first example was so, let's come down here and start writing our ace, a single weight version of the same method, so we're going to start by doing a step, two, a sink method where we're going to return a promise, that's a boolean and then we're going to do a similar thing here.

A

um I said before this is a pattern I like to use. So I'm going to let the return vowel equal, true, I'm going to put a try catch in and then I'm going to set my return val to return. My return, val and I'll put my console log in my catch there we are and finally we'll start writing our code. So this is going to look really similar, we're going to need an array of promises and then we're going to push onto that array.

A

The call to the step one, although we'll use the async version of this, and since we have that list name, we can pass in we're just gonna put those names in there and we'll call that three times and then change our call, 2 and 3.. There we go and then what we want to do instead is we're going to do const results and then we're going to await the promises.all with our array in it, and I forgot to put the async decorator on there.

A

So let me go back and type that there we go and now now I know that results is going to have a value of an array of boolean values already so now I just have to operate on those boolean values, there's probably better ways to do that, but for clarity of code. Let me just do a quick for loop. It's probably a little bit of overkill here. There's definitely better ways to do this, but I just wanted to be clear.

A

So I'm just going to loop through the results and um if any of the results oops not o. I are false, then I'll set the return vowel to false there, and so that gives us exactly the same functionality.

A

That the other one did just in an async await pattern and again this isn't significantly improved from an understandability perspective, but I wanted to definitely show how you would do it that way. So now, all we need to do is go down and change our call. So, instead of doing the step, one async we're gonna do step two async and we don't need the list name anymore and then we'll come over here and I'll refresh and now, when I click start here,.

A

It's going to create all of those libraries and let our lists excuse me, and so there we can see it one two three lists.

A

So let's come back over here and check our view and lo and behold we have exactly what we expected so that wraps up my demo portion of my presentation uh and my presentation altogether. I really hope you enjoyed it got something out of it. If you would like to provide us feedback, we'd love to have it, so you can use uh this nice little character code, thingy here or go to aka dot.

A

Ms slash pnpvc feedback and give us feedback on the conference really appreciate you joining me here today, and I thank you for your participation and I hope you have a wonderful day.

A