Building PowerShell, its VS-Code extension and debugging it - Christoph Bergmeister - PSCONFEU 2020

welcome this is the session on how to build PowerShell it is good extension or peer script analyzer and how to debug things to figure out what the hell is going on here my name is Christopher Bergmeister I'll be not just only showing you how to build those tools but also what helpers are available for doing that and you can leverage some of those helpers in your binary power module development as low so some of the things I'll be showing is Visual Studio code spaces developing inside a docker container using Windows sandbox and many more things to come so first of all before we get started I would like to say a huge thank you to all the sponsors attempting to make this virtual conference still possible so thank you Microsoft System frontier script dreamer and devotion but one website I Tobias things also to the three organizers to by us himself Alexander and row thank you very much for making this event possible and that everyone can join for free I think this is very awesome so for already talked a bit about what things were going to look at so PowerShell itself also it's MSI installer will be quite Windows focused but what I'll be talking about in 80% of the cases you can also do on your Mac or Linux environment in fact amazing tools like for example code spaces or remote container development that are actually working in a Linux environment but me actually being a Linux and on Windows I mean so how does it work well we will see I will show you how to build the powerful extension for Visual Studio code that you probably use on a daily basis you might be thinking about extending it so you would want to know how to get your hands on with this extension which is quite special because it's in powershell with the modern web worlds will see typescript and order things via script analyzer as i mentioned before it's just a binary power module but can be used as a prime example of what kind of tricks one can do for building and debugging binary modules technologies which I think are the most important ones you might not be interested in building any of those but using those technologies could be used in various other areas so at first we will get started with developing inside a container now that I mean a doctor container specifically and build on top of this feature is the recently announced preview of Visual Studio code spaces and the similar product github code spaces but under the hood they are kind of the same thing some people might have seen developers using visual studio Pro Plus or not the modern Visual Studio code that is lightweight and you probably see all over the place no wishlist Thule has still some very enhanced and sophisticated feature that really makes an editor worthwhile for some scenarios and I want to take the fear away of this big developer focus editor that is a bit slow and tesco some of it advantages and disadvantages but I want to show you the things where we first studio really shines and where sometimes you might want to consider switching to it for a specific task and most importantly when things don't work out we have to debug so I will show you how to attach the debugger or some difficult scenarios like for example when things are just about to start and you don't even have to time for attaching the debugger okay without further ado let's start with PowerShell itself and since this is not a powerpoint summit I'll be switching now over to the demo so first of all where is the source code for power it's all on github so we can just navigate to a github that come slash polish shell and there we see all the repositories of the PowerShell team and of course the first one that is coming up is PowerShell itself so we can just click on it and presents it presents us with a visual view of all the files and folders displays they read me with a lot of information of how to install it some details very simple guidelines and around how to developing and getting started but I want to show you in an interactive session of how developers go ahead about doing it if you're not familiar with github yet the first thing that you would do if you want to make changes with the repository is the forked my case I've already done this and you have might have seen a change in a URL which changes the organization to your personal one so this is your personal version of PowerShell where you can take this URL or alternatively use the proper URL but it's a bit easier forget to use and copy to the clipboard and locally you can just add it clone of this URL and it will download this repository locally so I do assume that you have some familiarity with get if not have a read but for the moment don't worry too much about it I'll be driving and there won't be too many things specific but git itself we will need so i've already executed this command and it has given me a folder named partial which is the repo name so let's CD into this repo and you seen Michelle there's a couple of big helpers that show me for example branch and estate toes it's just some of the customizations that I have applied so if you start from scratch and not know anything you you read or read me yes and look around a technologies being used I can tell you it's mainly did not net SDK that is being used an indication of it is the global JSON file which shows us SDK that is being used and this is something it will become quite important as soon as we start to build it at the moment let's assume we know nothing and I will just guide you through how to do things so I came out with just the alias for import module so we're going to import to build module if we run the start piece bootstrap which is the very first command you want to run if you're new to it it's going to basically get you ready all you need is power shell itself for building and developing power shell which is quite nice in my case of running previously because it takes a few minutes and because it does download you that required for next claim and it's telling me we're ready to go so now if we start up PS build this will spilled it and I've already pre build it it's going to be slightly faster than the first time it will still take around half a minute even although I'm I'm on a four core machine just reasonably fast it is still heavy work that it is doing it's nearly finished it's showing me where the output is so in this publish folder there is the PRS PwC h2x that we just built right now so what I could do here is just execute it right away with invoke - attend net and there we go so this is our locally built version of PowerShell usually get indication that it is locally build my is it commit ID that is displayed here it's actually matching so now that we have spun up the local version of PowerShell and just to show you there's easier ways instead of having to cut the pasting that we could be just running a ie of a PS output with just the same thing because get PS output essentially just gives out the local path to the build executable you can also call start death PowerShell which is going to start this version in the local console so you can have a shell inside a shell that is possible you might prefer to use that it gives a warning about unknown issue as we hit exit here we'll see an error there's nothing to worry about that sometimes the nature of development you will see some of those artifacts and sometimes if they deal with errors and get things into the right state so don't be too scared if sometimes you see errors sometimes you need to rebuild what's important is understanding when an error is an actual error when can be ignored there's no straight answer to that but it will come over time so now we know how to build and start this version how do we debug it so let's open code and I've already opened one commandment here if we browse the source code in the left hand side we would usually go to the source folder SRC and have a look at the various projects so a lot of built-in commandlets are in the commands utility project and the command that I chose here is the new - temporary file command late because it's quite a simple and easy one so here is the source code and the source code here is written in C sharp so I'm assuming some familiarity with c-sharp but if you're not familiar with it I think it should be reasonably easy to cup and you can at least read kind of what is going on you're probably familiar with the end processing block in PowerShell in this case there is no begin processing or main processing block so this is the only block that is being run and how about we set a break point so break point essentially means when the code is passing a line it should pause and give them give us an opportunity to inspect the code and line by line go over it if you're probably used to it from deep ocean is e or Visual Studio code if you use that when you debug your potion script do coolant we can do with the source code of PowerShell itself we hover on the left hand pane this red dog starts to pop up so if we click on one of those the red dot start sticking to it if we go back or a shell and bring up this lovely built version of our show we can run new - temporary file and if there's a new temporary file so how do we need do we now make it a hit this breakpoint well first of all we need to get the process ID there is an automatically pouch that gives us this so to h.264 let's remember this for a second and let's go to the debugging pane here and it gives us a couple of options before one of the departure repo gives it certain core launch which would do what I've done here locally it builds it it gives you this local console we have already done this so in this case we want to attach to it so if we now hit f5 or just click on start debugging it's showing us processes to attach to so that's the process name called PD SH and it shows us also the path and the path gives us the hint already which process ID it is so it is the second one and if we hit enter it's a touching food and you briefly saw the break going away and coming back if for example break point was not fully read but slightly opaque it would be an indication that we haven't successfully attached to it and this is usually the case if source and build have gone out of sync so it should always look for the break point being fully read let me try to show you an example when it is not read and we attached the wrong process so what if I used this version of PowerShell you see it's actually not read because we're touching to my local install install of potion which is quite different because master has moved on in the meantime so always make sure your breakpoints are actually read now if we run the command again we now see the console here's blocked it hasn't returned yet we're in here and we can actually inspect the state we can hover over parables moment they are not defined yet so command keyboard shortcuts are f10 which means go to the next line we can step in to f11 which means we're going into this should process function we could step further or maybe actually it does not be interesting happening let's let this function finish and step out and then we can continue stepping and we can inspect our local variables we can also to operations if for example this variable was changed and want to know what the output of path victim coffees in a deeper console we can enter our commands and it gives us the results we can type the variables and if it wasn't a string and and a full object we could inspect the full object in all its details and this should be few an indication of what is going on stepping through the code inspecting the variables possibly executing some commands and then I think this is very useful you're probably used for this experience he would be bugging a binary powershell commandlets if not the end of the session one becomes the key script analyzer will do exactly this so big development experience for PowerShell actually very similar to a binary module of course when it comes to more sophisticated modifications of PowerShell like for example the parser you will go a bit have to go a bit deeper and where you would usually be working in is the SMA project system but management or automation which is the core project around the engine the partial compiler the parser but for this more specific domain knowledge is required you have to understand a bit of the architecture there have been a couple of videos around the architecture three years ago from dom go one around how to parse of work and work senti compiler itself last year and partial summit by matias jason you showed a simple modification as well as encourage you to check out those sessions if you want to dive a bit deeper into actually making modifications to it so now that we know how to debug it what build it what if we build a couple of different things we installed a couple different SDKs we probably don't want all the rubbish in our machines and maybe i've even conflicting environment requirements a feature that we can use for this and i'm going to introduce you to this is developing in a container with the remote development extension in visual studio it is called remote - containers and if you have it set up and I'm going to only briefly walk through basically consists of defining a deaf container folder where one defines a docker file which is usually either a PowerShell docker container or d-doesn't chorus the came in the deaf container Jason where he defined the extension sea with one to use I come out to run after the container has been initialized and there is other preferences that you could specify here there is commands for creating them and there's boilerplate templates in this case for this repository it has already been set up so I can just click here and have the option to reopen the same folder in a container container is spinning up now the seat here the very first time it will take quite a while because it's pulling down the image and building the container because this containers pre-built it will be much faster and we already have a partial instance here's one open with with like you name we see it's actually Linux and that is because the default docker container is Linux based and that is connect approved we are actually running within this docker container so what we can do is what we are used to doing and let me just demonstrate that is building from this docker container except for one small thing you have to do the first time and we should be able to build now and this is now happening again just in the container we see here it automatically detect us Linux is a long time and that allows us to play around in the sandbox essentially and not change our global state we can specify different versions of PowerShell or different modules and that is essentially the advantage using this from remote container feature there's a core some overhead involved with it that's why you see that the build is taking quite a while now speeding up a bit more as I'm recording right now it's slower than it usually is and it's going to finish soon as well so yes how is it working if we look in this that she installed it from news you have to specify also which extensions you would like to use the documentation you will find on the vs code website is quite extensive but it is relatively easy you install the extension make sure focus running and in Linux mode and in the settings docker you just need to share the drive on which your git repos tree is on settings share drives it's just a stick box to allow it to access to the drive you will need to give it a credentials the very first time you do that and this is how is it can be a setup you maybe a slightly different way of how you could for example build in a different environment we can also use wsl and just go here what I'm showing here is I'm going to my local C Drive on Windows and I've turned the partial refund on the top level the reason being is puff limitations but in double yourself which is Linux based I can do the same things I can do and windows if I want to debug something that is specific to Linux whilst I'm still on Windows so I can do all the building in the realm of tests locally here you see the remote wsl extension we could even attach to it but this is a bit more sophisticated as usually would be setting up some OpenSSH reloading for it and it has built it as well awesome so now that we know how to build and deep a powershell we can think about how can we package it up so there is a command called start PS package and there is a bit of helping there already on them up terminal and for a special case of packaging things up they have to be at the root so in this case here I had to clone to my C Drive Luckman you shall get folder this is just because of path length of limitations and in there I can use those commands were familiar with important about module we will be calling star PS build in a sophisticated way you can specifically release tag which is the motion that you were syncing for example but in our case we don't really need that it's going to take a bit longer or they look built here to scenically and it's also doing first generation which is which is an optimization to make partial run faster so fast forward it has built now so now it comes to packaging and my packaging folder there's a couple of modules many to packaging much the past this monthly start place package so this is going to make us an MSI package and anyone confuse a release tag so a requirement for this year is the weeks tools so weeks stands for windows install xml and it's basically tool that abstracts msi if you don't have it installed locally it would be funeral work to install it from electriss-- easiest that it takes a while as well so how are we going to test the inside we are going to use a feature called windows sandbox it is available in newer versions of Windows 10 think it was 18 or 9 or mention of 3 and remember exactly but if you relatively new version of Windows you should have this feature and it keeps getting better with each iteration of Windows so it does it's definitely worthwhile always staying on the latest version of Windows and what this gives us is a vm like environment that we can play with that is very similar to a local environment and the moment we go ahead and close everything is gone so we don't need to maintain a vm anymore in VirtualBox or hyper-v where the image could go out of date no this will be the actual image that you have locally of Windows which makes it very easy and you saw it was very fast to spin now so VMs is built in the meantime so let's have a look where it is in that local folder we see this in this MSI so we're just going to copy paste it into Windows sandbox which works reasonably quickly as well now it's around 100 megabyte and the four parameters were used and you see this a couple of hard-coded things that kids version 6 OB 2 3 that shouldn't worry you because the extreme solution path will be still like 7 we could tweak off that if we wanted to but just for the purpose of having a look at the options that we might want to change or trying to install it ourselves in a different system that is there is enough it's just packaging up the binaries and or a quick start that should finish relatively quickly and this is how we built and distributed our local version of PowerShell there's not something we would regularly do and there is some quotient we don't do everything is open source and there is the MIT license you shouldn't take it lightly to build your own version of PowerShell because it does come with a significant maintenance overhead this is more for demonstration purposes and we'll see we have got this version of PowerShell here locally but nicely and exit window sent books one of it is concerts and very easy way for us for trying things out that you could apply to a lot of different software ok so now that we've gone through different options we can do with the partial repository let's not build the PowerShell extension for visual studio code and because Visual Studio code is web-based it's basically an electron app we're going to need nodejs you can download it here from this webpage it doesn't matter too much in which version you were on you can use version 10 which I'm using or version 12 14 I've never tried but 12 definitely works you need Visual Studio code as well what I do recommend is to use the insiders version of it so you can have to two things side by side and also know about currently current things that are going on as this is for development purposes which means quite often best things that would be needed in the preview extension I can use both but is it's just my recommendation the code for it is in DB s code - partial repository but we actually for dependency on a different module called PowerShell need to serve is coming up here so what I did before is clone this repository called PowerShell and services enough built it locally and just before did this session there was a small breakage in the masterbuilt that's why I'm on a different branch here to show you actually working a version sometimes he might encounter the latest version on the master is broken so I was shifted from issues this is the nature of development that things are moving fast um sometimes need to understand those errors in this case it was just a simple fix the partial editors services repo is basically a PowerShell module and what you need for it is to have the powers on what shield build module installed so you would just run in store - module invoke build and what you would get is a module called invoke build but there's a command called - build she called just invoke - build it will run everything including tests if we were just trying to build bit it would just build it for us and that sort of it will do the first time after we have cloned this repository this repository is for the back end of the extension or the heavy lifting is happening and sometimes you might need to make modifications to it sometimes not sometimes it would be just e be escort - partial repository so if we open it in the insiders version of Mia's code and for a development of it I recommend to have the preview extension installed not the normal extension because it will clash once we build it it is actually quite easy so if we have noches installed and we have built palliative services for which we just empower shall itself if you don't have d required on domestically it will bootstrap it as as part of it the only requirement is this invoke our build module here we can just hit f5 and it will build it we could have run the walk build build as well that would have done the same thing hitting f5 here which is just a launch task which we see here us the same thing we can inspect what those tasks do if we go to DBS code folder look at launch Jason and effectively it's calling tasks of them all there we go it's coming up now so this version here is a version with the build version of the extension you see it's a slightly different color here so how we can test and debug it so show you an example I was thinking of debugging the pastor stop that is in place here so if we look at pastoralists PS expression of works registering commands which we see here grant pastoralists from file just being run initially here launch tests if we hit a breakpoint here I think later on because this is typescript once we start loading the extension it will hit so if we open a PowerShell file changed language more to PowerShell get a default pester test and save it the extension should start loading and now breakpoint is experiment ok so what if we try to run this test here and remember it's best for tests so we have to make sure we give it it tests the ps1 extension we should see the code lens for it coming up coming up here you click run tests we get a debugger in here and same thing at commands that are being used as before and so you can inspect your variables and debug your scenarios so this is how we debug the front-end how would we would we go about debugging the backend which is partially services I can show you that as well and I can show you tricks for it so let's first close down this window and let's navigate to powershell editor services in this case and continue see visual studio solution it will have some advantages and you will see in a second why I kind of stand using vs code and attach to it my dad by a process ID similar how I did with PowerShell finding the process ID and attaching very early on is sometimes quite hard so I'm actually going to show you a trick so is here enough open the lens provider say if we wanted to hit the breakpoint right when the lens is going to start we will have some code that is saying if the debugger is attached break it is not that launched debugger so this will allow us to get a window open to attach right now here without having to write some sleep coach to give us time to attach to it and possibly output the process ID and that's for visual studios coming in and that's why I want to show you where she stood you same in here you can click just build a solution once and then you have everything set up to work I've pasted this code in here so that means if I go back here I have made a code change and I see this in my it prompt here I need to run invoke - build in here actually but knowing what happens here if I press f5 it's going to run the same command that builds it for me so 5 behind the scenes we see it's building partial editor services as well in the north it's calling invoke build the only assumption that is being made between those two the trees is that they are in the same folder that is something very important when it alone those two repos the very first time so the extension should now spin up soon and essentially what we want is when we open our tests file again we want to hit the breakpoint as soon as the code starts to load so was he how shall I start in here so it should should soon hit the breakpoint and it did so a window comes up here and tells us an unhandled exception has occurred well the use an exception is a way of attaching the debugger or sending a notification of and we can just use our open version of Visual Studio to attach to it automatically it finds the process ID does the wiring for us and there we go so similar to vias code I can use now f10 and my my usual tools to step over my code inspect my variables and something very special with Visual Studio is see if you want to rewind you can put your breakpoint up which I find quite cool so this is a very cool trick if you want to debug things that start very early on and you want to capture it right at the start this is very useful tricks and just going to move the breakpoint here and it continue and stop the process and of course it comes up again will just cancel out and close the extension for now so that you know how to debug and run the front end and the back end of the powershell extension if you wanted to give someone a built version of the extension you can just run in bak build and i think there is a package command for it that would give you a file a vesl could give to someone else to install it locally if you want to try things out locally in an end-to-end scenario then this might be something you could look into okay so the next repository that we're going to take a look at is he a script analyzer it is a repository for which I am the main maintainer and we're going to use this as an example for demonstrating Visual Studio code spaces so I could show you how to clone it will little locally do all the setup how about we have it set up out of the box so go to online that is to do that come and sign in and it seems it just got signed out sign in and if you have an extra subscription you could just create a new plan there are a couple of locations it is currently in preview you can choose our subscription you can choose the plan name so I'm gonna call it something like hello PS month it will give you a resource called blame my creation of the plan is relatively fast and you can plan here and create the code space you can't just cut to name to get triple here is to get a people where we want to use my fork here you can actually use in an ash or f of three pool as well now Stefan instant instance types that determine how much you pay for it I've noticed much of a difference but because I have an estate subscription where pool are free credits I can actually afford to use the premium options and for saving costs will go down after a while so what this does is very similar to how I saw with PowerShell there is this remote container feature that we could have leveraged to remote him into our docker container into the development there it's doing the same setup except it is being hosted on a shore for us so that means a bit less maintenance it also means our left has to do much less work and again it's segregation of environments and even though it's just a docker container we don't end up with lots of containers locally that we need to clean up at some point within a sure your internet connection will be much faster so everything will usually work quite faster anyway so the very first time it takes around a minute to set up second time it will be much faster to spin up and you see here we will using a version of BS code in the browser but we can actually use it inside the editor as well I'll be showing that in a minute environment is ready it has cloned it now see it looks like a version of Mia's code if we go to the terminal we see again it's it's Linux based this is not an issue propelling PS script analyzer we can use the build a ps1 script that we have it's just going to build it for the current version of PowerShell if a look at dependencies it's again the dotnet chorus to Caleb were using and all we bootstrap is in Marshall called a DPS and investor plot GPS is just for a generation of the documentation and pestle mostly for running tests so what this has done is produced an out folder with old macho so with that version I could just import this version and voila and that will run my local field version of script analyzer auditor might have modified and how about we try to debug what is going on here maybe we write a new rule yes just the rule here that is being used and cuz I had to look at the code before if I didn't know I would always be looking for an instance where it returns a diagnostic red card there's only three instances where it returns it and this is the one that we will be looking at so now again we need to attach to a process so there's a couple of ways to it the first one is Dublin current - so we take a note of the process ID and we search for it here so easy here in the clutters only one version of partial running we have attached now and if we run the command again then we hit a breakpoint we can inspect and debug every base so far can attach to it something that should be set that is quite important and I were just demonstrate that by opening a PowerShell file a partial extension has this integrated console and in that integrated console it already has a version of via script analyzer running so it's never good at the air to develop peer script analyzer inside that extension as it will conflict I know remote you cannot be unloaded in PowerShell core that's why you should always be using a vanilla version of the terminal when you're developing disk analyzer just some details around it so this buildup ps1 script there is a or switch which is all partial versions this is the version that you would get it download from kiss gallery the conversion release would be done for a proper release build that is actually what you get at the end of the day there is of course some signing that is happening but in terms of building that is pretty much what you get on a PS Gallery if you wanted to run some tests locally we can just hit - test and what it's going to do it's going to spin up a new partial process so there's no from conflicting the current one and going to run all pester tests in there which takes around a minute for the whole test suite which is quite good you can also just run the tests individually so I'll just cancel out and look for the alias tests that's the PS one I can just right click copy estro against it it's a great way as well to iterate quicker over it should say in this special scenario for peer script analyzer we have to use this terminal here it is not integrated console if you have a very much room where you can you've seen the credit console I've added a menu called run pester tests or people pass a test whatever you prefer us all of this for you in the current concentrate enough to do what I did just now calling invoke their tests or copying the path to it it does it for you it does it also for you here in the explore menu it's the exact same functionality to run Petra ok with this I'm going to wrap up so what we have seen is horrible PowerShell tested out debug it potential installation window sandbox building the vias code extension attaching to it right when it starts building PA script analyzer using Visual Studio code spaces we have your environment set up in to work outside of the box out of the box I mean so hopefully this giving you some insights be very delighted to answer any of your questions hopefully it was a good overview for you to see you get an idea how it would be getting started in one of those repositories or help you develop your binary module better with better toolings so a bit about me my name is Christopher bag maestro I'm a divorce engineer or slash consultant at BTSs we are a global company were mainly uk-based but we also have offices in the US we're always hiring matter if you're developer test or a platform engineer like me or just trying to console businesses we're very open I myself am a Microsoft MVP mainly because of make contributions to PowerShell and the community and some of the talks that I'm giving one of my hobbies is contributing to peer script and an icer mainly because it helped me in the early days but also because I find it quite interesting project in terms of the technology being used I can use it as a test project for trying out new things like is to decode spaces cause it's a real-world project that is not too complicated you can find my profile on LinkedIn or check me out on github or Twitter and thank you very much for your attention and I'm looking forward to answer any of your questions

Channel: PowerShell Conference EU

Views: 418

Rating: 5 out of 5

Keywords: PowerShell, Core, psconf.eu, psconfeu, keynote, Jeffrey, Snover

Id: NJixozClEbU

Length: 50min 57sec (3057 seconds)

Published: Fri May 29 2020