Tyler Leonhardt - Visual Studio Code: deep dive into debugging your PowerShell scripts

[Music] hello everyone this is the deep dive into debugging your powershell scripts my name is Tyler that's me on top of the Space Needle in case you were wondering back in Seattle I'm a software engineer on the PowerShell team at Microsoft if you want to follow me on Twitter it's just my name it's also my username on twitch for those of you who don't know I do a bunch of live streaming live coding and stuff like that on Twitch so if you're interested in that stuff feel free to talk to me afterwards or check the session that we did earlier this week and that's also my username for that alright so this session what do you think thoughts it can even go backwards to it's nice that's a default PowerPoint transition to I had to do nothing to get that alright so this session is mainly about two big things the first how-to is how to be immediately effective with debugging PowerShell scripts envyus code and then the other thing that we want to do is is learn how to customize the powershell debugger for all of your needs so this is Joey and he's quite sad because he keeps hearing about vs code debugging but he doesn't know where to get started it and if you're like Joey please let's let's see a show of hands I see a few oh well ok all right well you're in the right spot because that's what this is all about we will be first diving into the zero configure Oh setup debugging this is literally right after you install the PowerShell extension we'll take a look at the the plug pain and what it can do we'll look at pester sake and invoke build debugging we'll dissect the launch Ehsan which we'll see later it's the debug configuration will look at remote development and what that means in terms of debugging and then we'll also be talking about how to debug c-sharp commandlets for those of you that have written C sharp Commandments all right so I'm not going to spend too too much time in slides we're just going to hop into the first demo here which is serie configs zero setup debugging and i look at the debug pane right so let me go ahead and open up vs code to my to my example script that I have here and let me change the theme because new version nice it happens every day and I get so excited about it alright switch over to the iousy theme so you can all see alright here's what my years of my awesome script does it calls out to this API called cat fax ninja cat fact inja and it returns a random cat fact it's a very simple script that takes in a single parameter if you want we've got our function get cat fact and then it just does some some write hosts and and calls the function so with with zero work here all I have is just this folder open envious code and in my debugging the ps1 script I can I can go ahead and place a breakpoint on like this line here and if I hit f5 we'll see that it just breaks and it stops right where I had that breakpoint very simple no configuration required you can do this sorry oh yeah sorry how's that is that better all you need is the powershell extension in order to get this and if you don't know how to get the powershell extension you can head on over to the extensions pane search for powershell here and grab it there's a PowerShell one and a partial preview which is like all of our new features coming so try out the preview if you like and that's how to get that I also did a talk at PowerShell summit on like getting started with Visual Studio code so go check out that talk a link will be at the end of the at the end of this talk on where to go see that anyway so the first thing I want to talk about is this thing this little bar up here you can see it it's got six buttons on there the first one here is continue and if you hit continue it's just gonna as the name implies continue executing the script until it reaches yet another breakpoint step over will step over to the next line that that is in your script so for example will step over and we see that it's now arrived the the bugger has now arrived to get cat fact okay the next button is step into and what this will do is this will actually step into the thing that it's currently looking at so this is a function so it's going to step into the function the debugger run that and now we're inside of the function we can go ahead and hit continue if you'd step over a few times if we'd like and then we have step out which will step out of the function or whatever that we're currently in and we'll end up down here at right host naturally restart and stop are pretty self-explanatory and we'll just stop the execution at that point this is pretty much all you need to know to be immediately effective in debugging these features that I just showed you are about 80% of the stuff that I personally use just setting breakpoints here and stepping through the next thing you want to do is is probably get an idea for for what's going on at the at the moment that you've broken so let me run this again and we'll kind of get a glimpse for what what's going on there so I'll set a breakpoint here at this at this URL at this variable and I will go ahead and hit continue which will run until it's that breakpoint so at this point I have a prompt at the bottom here my integrated console and I can actually do I can actually interact with the the PowerShell session at that break point so I could type URL here and it's not defined but then once I step over this line and type URL here we see that it does in fact have cat fact uh ninja slash fact so that's a really easy way to see kind of the state of your your your session in addition to using the terminal below you can use what what is called the debug pane which is what is showing up here on the left side of the screen and you'll notice here I already have one entry under Auto here which is the dollar URL fear variable and also what is defined there and so we can actually like go in here and change it so I like I can add an additional slash if I want and then if I like step over really quick do your L again we see that it now has the slash so I can like mutate the the state if I want if I need to like debug a certain scenario you can very easily do that using this variable section go ahead and collapse that the watch section is pretty cool because it allows you to - as the name implies watch when certain things kind of happen so as an example let me go ahead and say that I want to watch for when your l equals you can actually put like powershell expressions here so dollar euro equals HTTP colon slash slash cat fact that ninja slash fact close that and I added that other slash ransom and if I expand this here we see that it's set to true which is very nice and actually what I what's really cool about this is that I could change it up here in the variables pane and it will automatically change the watch as well and so this is really helpful if you're messing with a bunch of data and you just want to see some like some visual checks of like what certain values are that you would want to compute it also lets you since it runs like just pretty much any sort of script block in that expression we can do something like you know if let's edit this one if your l equals this then right host yes comfy you like that and and we see that since in fact this has the this has that slash in there we end up getting PS comfy you and if i change this to this nothing happens but then once i change this back it impacts logs this so this is this is one way to like for those of you that are familiar with the vs code feature of log points this is kind of a way to do that in in terms of setting up some things to watch for and then logging it to the to the console when that when that type of thing happens it's definitely a more like advanced scenario but it just kind of shows the the power of the the watch section how often is the question was how often is it evaluated what is it the watch is evaluated when variables change so you can trigger variable change by either changing it here or if you were to like step over or do something like that the variables would change and therefore the watch would get fired again it's a good question the next thing is the call stack here and we can see that I already have a call stack of get cat fact on the call stack and for those of you that the call stack is just like the the ordering of functions or whatever that is currently being called so since I'm within the get cab fact function that is at the top of my call stack at the top of my call stack and then thing below here the script block is in fact the whole the whole script itself and I can actually see here that when I click on that part of the call stack it can point me immediately to where where in the costs that are where in the script it's currently waiting at that given part in the call stack and then the last thing is kind of a more robust representation of what we see over here in the gutter except that it can do something that I find really really interesting and that you can add what's called a function breakpoint now let's say that I don't have any any breakpoints here and I'm just gonna like it continue to finish the script here let's say that I want to break once get catfac gets called and you can easily do this by just adding a new breakpoint and doing get cat fact just like this and so when you run the script again it will break once get cat fact is called so if you wanted to check any time like a certain function is called and check some sort of state you can go ahead and do that this way instead of instead of placing a breakpoint here for example they're equivalent but this is kind of more explicit which is kind of nice I did forget to mention though in the variables section over here we saw that that URL showed up in this auto section but there's also like these other sections if I minimize these other ones here there's also like globally scope variables so an example is like all right well we know dollar home as as an example is is equal to this and we could see that all throughout here as well while this one's kind of cool is Linux is Mac is Windows so there's tons of power here in terms of like really getting a sense for the state that you're that you're currently in when you debug your your scripts and your modules so now what I'm going to do is I'm going to switch over to the slides and and what we're gonna start gearing towards now is kind of how you can customize the debugger to do different kinds of scenarios are there any questions so far I want to take too many but yeah so I think the question is what happens when functions get like overridden and I okay so this is a your question is can the debugger stop at functions that are internal to a module that are not exposed the answer to that is probably but I haven't tried it out myself all of this uses the PowerShell debugger today so really if the PowerShell debugger can do it and I'm pretty sure that I could do something like that then it should just work but if you're if you want we can check it out after the after the talk okay so the next thing that we're gonna look at is a demo on debugging pester tests now who here uses pester at all it's a lot of hands awesome so this is a demo ish because it's actually my only recording that I have in this talk and it's essentially how you would debug a a pester script so here you could see let's see if this works now okay oh there we go sweet so here we can see that there's these little like run test debug test things that that appear above the describe block right so one of the features that we have in the PowerShell extension is the ability to detect these describe blocks and then run them and debug them with just like the click of a button so let's see there we go so in this example I'm just gonna run the tests and we see the output appear down in the integrated console and over here I place a breakpoint hit the bug tests and then boom it stops right at that break point so I don't know I personally use this feature quite a quite a lot when I'm writing pester tests so you know I hope that's something that you could find value in and that's that just comes pre-baked in the powerful extension the only thing you need is pester alright the next thing is sake and invoke build now these are probably not as widely used as pester but does anybody use sake or invoke build in their scripts okay there's a good a good amount of you so one of the things that I did when I was really procrastinating my talk at partial summit was that I I wrote this module and I threw it on the gallery and what it allows what it does is it exposes this feature in the extension this extensibility in the extension that allows those same kind of code lenses that we saw in pester appear for for anything really so let me just stop at the bugger here so I have this very very basic invoke build script and for those of you who don't know what that is it's kind of this like this way to define different tasks that you would do in like a build script or deploy scripts so I have here I have a task that's build it just says I'm building and then I have a task deploy and then it depends on the build task and then also it runs its own script block so today there's no sort of like code lens as you could see but I polish them all module in the gallery and all you have to do is install it and then import it build the tools build the runner vs code tools is the name of the module and you can even just add this import module to your your profile and if I just do a quick space there the code lines just appear which is really really quite nice so from there I can just like hit run tasks and Oh sad the rocket ship doesn't render oh well or I can debug the tasks if I want to just as I would anything else so over this all you have to do is install that module that I throw on the gallery and then make sure it's imported too to get these little code lenses again without any sort of configuration to the debugger the whole point is to is to try to keep that that the configuration is little too little to none as possible all right so now at this point we are going to shift focus and look at how how we can customize the PowerShell debugger and vs code to do different things and we do that by dissecting the launch dot JSON file now the launch thought JSON file exists under a directory called Dias code and this is typically created within the the workspace or within the folder that you've opened envious code so yep sits in the vias code folder in the root of your workspace and it contains an array of launch configs that control the behavior of the debugger and here's what one looks like now important things to take away from this is the request property which could either be launched or attached and then the type property which must be PowerShell if you want to use the powerful debugger pretty much everything else is optional but we're gonna dissect both the different kinds of launch configs and the attached config to get a sense for that I see a couple people taking pictures so I try to pause for a brief moment all right so watch and attach what do they mean launch is saying basically run something in the current powershell integrated console or start a new powershell integrated console and then run something in that so that would be like I've got a script that I'm looking at and I want to run that script that's a launch attached on the other hand is I have this power shell session that's running somewhere and I want to attach to that and debug something that's running and we'll look at that in in a moment going back to the launch requests we'll go through how to how to actually get that launched a JSON file but when you do get it feeis code actually supplies a whole bunch of intellisense on all the different all the different options and all the options have like this little dialogue to the right of it that explain what it does the important ones here in the launch one I think our our args which is going to be what gets passed down to the to the command that you're running so like let's say I have a script that has some parameters in it args would be used to pass certain parameters to that script other ones that are interesting the pre-launch tasks is pretty nice if you want to run something before you want to actually debug the script that you're currently looking at that's kind of nice and then there's also the create temporary integrated consul if you want to start in a fresh session yeah and a whole bunch of other options as well and then there's the attach request and the attach requests like I said before is the idea of attaching to a PowerShell session that already exists somewhere in the world and and debugging something within it so up at the table you have computer name if it's like a computer name on your network somewhere you can it will first enter PS session into that machine then like down at the bottom you'll see like process ID and that will be the process ID of the powershell instance that you want to attach to and then run space ID if that process has multiple powers will run spaces within it and you want to specifically attach to a certain run space ID you might notice there's there are some common settings that are just available in all launch configs like the Linux OS X and Windows ones and what you could do there is basically set any of these other things per operating system which is kind of nice gives you more flexibility all right so what we are going to do is we're just going to run through all the different built-in launch JSON templates and and go through them and see what they do has anybody learned something yet no one raises it awesome all right so to get started with that if I expand this debug pane a little bit you'll see that there's this like drop-down and it says no configurations which is sad if I click add configurations it's going to go ahead and create that launch thought JSON file and if we go back to the the Explorer pane here we'll see that it created that dot vyas code and that launch thought JSON file for us in our current workspace so from here it actually creates let me close this for now it creates just a ton of configurations these are all the built-in ones to the powerful extension but let's just delete them all and we'll start from start from scratch here so what you could do is just start typing PowerShell and you'll get these snippets of all the different ones that the PowerShell extension exposes so for example launch current file if I complete that it just gives me that that that config and this one's actually very similar this is actually basically the default behavior that the extension does today so this particular configuration isn't isn't all that useful but just so you get a sense for for what it's like we can see that it has a name the script is going to be the file that we're currently looking at this is like some magical vyas code syntax that means like basically the script that i'm currently looking at on my screen and then the the CWD is at what like folder that is going to be what folder the debugger is going to be launched from and you can specify file here and it will just say okay I want to launch this from the folder that this particular file is is in so we shouldn't see anything different but we can go ahead and hit this play button or we can hit f5 and it will do pretty much what we expect it to oh I think I still have that yeah they get the function breakpoints still available so like I said this one's pretty much the default behavior so we don't need to dive into it too deep but it does exactly what we saw before so the next thing we can look at is let's see let's look at the this one launch current file with with args if I hover over this will it show it okay well launch current file with arts prompt now this one shows a demo of the the ability to pass in arguments to your script so so here we're defining these args and here's a little bit more vias code magic here that says all right command the command that I want to run is specify script args and what this is gonna do is gonna give me a prompt with envious code where I can add any arguments that I want to add so let's take a look at what that means thankfully this the script that I wrote has this fact length so what we can do is we'll place a breakpoint here and make sure the launch file with args prompt is selected press the button and and we get a little dialog box here so I'm gonna go ahead and add fact lengths about 100 and if we see over here in the variables table we should see fact length of 100 there it is yeah so we see fact length of 100 so this is really cool if you have scripts that you you'd like to debug but you know they require a bunch of parameters to to input them so that one's kind of nice let me go ahead and continue through the rest of that cancel it with soldiers and trenches they killed my string or two yeah fun fact cat fact alright so the next one so we'll type PowerShell here so let's talk about the interactive session one so this one is intended to launch the debugger and have it just be constantly listening for when a breakpoint gets hit so let me go ahead and save that now I'm setting current working directory to nothing and what this is gonna do is say don't bother changing the current working directory leave it leave it the way it is so as an example of this config we could select PowerShell interactive session hit f5 or play and you notice nothing happens and that's kind of intentionally because we just want this to be sitting there waiting for something to happen and what is that something well it's me running this script that we're looking at so if I do if I run this script in the console now cat fact length 100 now it's gonna hit that break point so this is really nice because it's great if you want to put in your parameters via the via the terminal but it's also nice because this is great if you're working on a module and you need to import the module and then run a certain function within that that way you always have the debugger waiting listening and you're able to debug those functions within your module that way so that's a nice way to to debug modules what else is there Oh typo this is a great opportunity to tell you how to submit a bug report in the extension so I'm using a preview extension and what you're seeing here is an issue with with PS redline which is one of the flagship features of of the preview extension the way you submit a bug report here is opening up the command palette like so which is control shift P or I think it's also f1 typing bug and then hitting upload bug report to github and what this is going to do it's going to open your browser with a bunch of with a bunch of stuff like partial information extensions that you have installed and all the good stuff so so that we can better help you in in debugging the the issue and then the only thing you have to do at this point is just give us a little bit of a description of what happened here and then upload the logs which if we go back to vias code there's a open PowerShell extension logs folder like that at this point we can grab these logs copy or is it revealing Explorer that's what I was looking for zip these up actually I think we just copy these and paste them right into here huh anyway I will do this later but you get the idea true good idea yeah there we go good so I'll finish the details of that later but you get the idea very easy to submit issues all right let's get back to our demo I'm going to reload the extension which is using PowerShell restart current session and we're back on track where we're we interactive session so we went through that one what else do we have is an example of the attach request so this one is partial attach to host process and what this is going to do is give us the ability to attach to any powershell process that is currently running so what I'm going to do is I'm going to go over to my PowerShell instance running here grab its PID so it's 14 4 6 8 we'll SEC select PowerShell attach to host process and run it and what this is going to do is tell you all the different PowerShell instances that are running our machine and we know it's 14 4 6 8 so we'll select that one and at this point we're actually debugging that other run space now so you can put us the question was can you use someone else's credentials for that it's a good question I'll take it back to you on that one you could specify computer name but that doesn't necessarily imply credentials yeah Oh as admin yeah yeah you could do it as admin but but yeah I'm not sure if supplying credentials is a part of the config and if it's not it should be so potentially should be so let's talk about that afterwards and we can open a feature request for something like that potentially an argument yeah all right so at this point we're attached to this other session now there's one weird thing that's going to happen when I hit enter here the debugger breaks and this is because of a feature within the PowerShell debugger called break all which is I'm going to break as soon as possible and the way this was done there the reason why this was done is to streamline the debugging experience in the console so imagine you were like at the console and you're trying to debug I don't know if many of you have used the debugging commandlets that are available in PowerShell but the idea is you wouldn't be able to set your breakpoints until you've actually attached to that other session so the break all is there you break as soon as possible so that you can set up all your breakpoints at that point all you have to do in the vs code extension though is just continue because it's not very important and so at this point we have our our breakpoint here we can go ahead and run that debugging script here and we see that it has stopped at a breakpoint but the question is what breakpoint has it stopped at mm sorry you know what is L thank you okay so it's at this this point there seems to be an issue with vs code actually rendering that I'm gonna take a quick I'm gonna do a quick blame on the fact that I'm running vs code insiders instead of the stable version but we could continue as planned at this point I can go ahead and run like dollar PID and I see that the PID is actually 14 4 6 8 which is what it was over here and that's just to prove that I'm in fact attached to this other process and I'm debugging that run space 1 that was set in the original launch config here and so from here if you wanted to like specify other things you could specify the computer name in 6 - there's this ability to specify a custom pipe name but if you're not too familiar with that don't worry about it and process ID run space name etc okay so those are all the defaults configs that that ship in the in the extension so let me go ahead and quit out of this okay so back at the slides the next thing that i want to talk about is remote development now there's a current experience and a future experience the current experience is built into the powershell extension the future experience is is using the new vs code remote development extension the current remote development experience as I mentioned is built into power so extension and it leverages PowerShell remoting via enter PS session it also works cross-platform so the idea here is that you run enter PS session inside of the integrated console which then connects to some other machine or or even locally and then at that point the powershell extension is able to it sorry it exposes a command called PS edit or open editor file and you're able to open up the files that are in that remote session right in front of you as if they were local files on your machine it's nice but this is nicer the future remote development experience vyas code about a few months ago released a feature called released a new extension called remote development and what it allows is a few different things one it supports remoting over ssh the way it works is that you have this other machine and it's going to use SSH to communicate back and forth between a process that runs in the remote machine to essentially emulate this idea that you're that you're opening up the files on your local machine however they are all on the remote machine it also supports stuff like containers and wso which is really really cool for those of you that were here at the keynotes Joey gave a demo of the WS cell support and I will show you a demo of the docker containers okay so if you want the remote development extension all you have to do is search for remote development in the store here and if you grab this one this is the pack that contains all of the different extensions containers SSH WS so we're gonna be looking at the containers one today but I've also installed the pack just because I use I use a few of them quite a bit so I've got my my scripts here and what I want to do is I want to run them in a in a bun to container and in order to do that all I have to do is click on this little button that becomes available when you install the remote development extension and then click this remote containers reopen folder in container from here you could search for a particular container that you want to use right now there's power show which which uses the official powershell ubuntu container and what this is gonna do is it's gonna spin up the container it's gonna install the the other process that vs code uses to communicate on the container and then once that's done we'll be able to see all of our files as if they were local on our machine but they're actually all living within the container and the BS code team has done this in a seamless way where all basically all the extensions that you could ever use anyway we just worked the same as they would in as if they were local on your machine so for example I open up my debugging ps1 script here and we'll see that the the integrated console pops up just as it would locally and to verify that this is in fact not what you think it is I can run PS version table and see them running on Linux within that docker container and I could still debug just as I would before by hitting f5 and and all the debug fun stuff right this is super useful if you want to verify that your scripts are cross-platform just as you would if you wanted to use WSL you could use use this as well and this one's also supported on on Mac and on Linux so so if you were not running on Windows so you don't have WSL you could do it that way as well yeah correct so the PowerShell extension is actually running within the container as well which is how it has access to to the file system and all that stuff the question was how does it switch over from local to to remote and the idea is that a folder can only really be open in local or remote and so at this point what I could do is click on this and say ok reopen folder locally and that would switch this current window back to locally on on Windows vs. within the container ok I'm running low on time the last thing I want to show you is debugging c-sharp command once all you have to do for that is see ok there we go awesome so I got my awesome c-sharp commandlets all you need for this is the C sharp extension because for this we're actually debugging C shop code right so you can stall the C sharp extension and you have your your command lit here and then what you could do is pop them in the debug pane and I've actually already got it here but you can add a configuration for net score and you want something like this attached to local dotnet core attached to local process and what we're gonna do is when you use this launch config to attach to the powershell process that has our our binary module loaded into it okay so I've already built this so this is ready to go I need to run power shown here let me import this okay and this gets me the command test sample commandlets so before I run this I'll hop over to this to the two vias code run it and I'm going to attach to the power shell process I should probably get the PID before I run this 18 - 4 8 eighteen two four eight all right attach I'm like sample I forgot to set a breakpoint will set one here my hourglass has run low favorite number this is just imports and boom debugging so there we're actually debugging my very basic but debugging this sample commandlets and all it takes it to the c-sharp extension and just attaching to the powershell process that you want to debug okay right so we're using the c-sharp extension attaches to the partial process you want to run your command lid in and as a bonus you should check out Thomas trainers talk from powershell summit he did an awesome talk on writing c-sharp commandlets if you're curious about that I already did the demo and that's pretty much it now time for the summary slide since my hourglass is empty so we did a bunch in this talk but we did how to get started with debugging in PowerShell scripts and vias code how to debug pester tests and sake and in both build tasks how to configure the debugger for advanced use cases how to do remote editing and debugging how to debug c-sharp commandlets lots of stuff one last slide it's the big slide of links that you all probably want to take a picture of there are relevant talks on from powershell summit including Thomases that i mentioned before and also my talk using vs code is your default powershell editor there's also powershell vs code docs and then links to all the different extensions that i talked about in this in this talk thank you all for staying a few minutes extra and I hope you got something out of this thank you oh yeah if you have questions just come find me [Music] [Applause]

Channel: PowerShell Conference EU

Views: 1,906

Rating: 5 out of 5

Keywords: PowerShell, Monad

Id: cSbIXmlkr8o

Length: 48min 55sec (2935 seconds)

Published: Sat Jul 20 2019