Forem: Microsoft Developer UK

Using open source software to boost your PowerShell skills

Chris Walden — Fri, 25 Jun 2021 15:20:23 +0000

I was never really looking to get into software development, at least in the beginning, but I was always interested in technology and computers. Growing up I picked up a really old QuickBASIC book and tinkered around for a while, but it never really led anywhere. A while later on I’d tinker with modding a few video games here and there. I wrote a mod for Spore for a handful of months, and I was always at least a little curious in tinkering with web design. In 2016 I moved to Florida to meet my now-wife, and needed to work somewhere. Having been pretty disillusioned with college and university even before I left Australia, I hadn’t made it very far in that regard, so my options there were limited.

I worked at a couple places before getting a job as low-level tech support for a flooring company. They had… a lot of tech problems. People problems too; those seem to go hand in hand quite a lot.

For a while I just helped out where I could, but the lack of a mature IT department eventually forced me to look around for tools I could use to make the job easier. PowerShell happened to come in the box, which was very convenient; most of these systems were Windows 10 or being replaced with Windows 10 as they fell apart, primarily workstations.

Eventually I stumbled on the /r/PowerShell subreddit and started picking up what I could, helping folks out where I was able. After a while, I found the Discord/Slack channels and stayed plugged in. I don’t really remember how long it took, but after a while you start to recognise the common questions that come up, which is what motivated me to create PSKoans. After all, why answer the same question over and over when I can just point to something I built which explains it better than I can after the 20th time that day?

Creating PowerShell Koans

PowerShell Koans are a series of Pester tests with extensive comments that are designed to illustrate how PowerShell features work, including a lot of the lesser-known edge case details that tend to trip folks up. It’s packaged up as a module to help newer folks make sense of the somewhat confusing display of errors at times. Feel free to download it from the PowerShell Gallery and give it a look!

# The first step's only needed for Windows PowerShell users (v5.1)
Install-Module Pester -Force -SkipPublisherCheck -MaximumVersion 4.99.99
Install-Module PSKoans
Show-Karma

Developing PowerShell Koans was an investment; I can’t be everywhere and help everyone I might want to, so I built something that is suitably well-equipped for people to be able to help themselves.

I utilise Pester to write the koans in a way that (hopefully) makes a decent amount of sense to newer folks and experienced folks alike; Pester’s base syntax for tests and assertions lends itself very well to explaining as you go, and any gaps are filled in with pretty extensive comments in the code. They’re written as a series of Pester test files, and you have the module commands there to prompt you when you get lost or want to check your answers.

The Show-Karma command will have the module invoke Pester to check your progress and report back, with some pretty console formatting and some additional flavour-text because the bare Pester output can be a bit daunting, especially if you’re not used to it.

In this way you can take it at your own pace, checking in with Show-Karma whenever you need to verify your answers and/or get pointers on which section to attack next. If you prefer, Show-Karma also takes a -Topic parameter so you can just jump directly to the topic(s) you’re interested in. You can also tab-complete topic names, so you needn’t worry about remembering any of them.

After some months tinkering away at that and poking at other projects, a few people encouraged me to contribute to PowerShell itself. It was a new language for me, though with familiar roots, and I had a little bit of prior experience with C# from my brief time in university. It took… about a month to finish that first pull request, although including a lengthy (but very necessary) review process it ended up taking about 3-5 months. Definitely not the typical case, as I was trying to change some fundamentals in the parsing engine to add some more number types (see this docs page that I helped write to explain the vast extent of the feature). I have a habit of diving in the deep end, I suppose.

Many PRs later, I’ve picked up quite a lot during this process, and working on new PRs has become my primary way of learning new concepts. I’ll often seek out help from more knowledgeable folks in the community when I’m working out of my depth, and there has been a lot I’ve learned that way too. After a while, some friends and I put together a portfolio site to see if I could get a better job. A few folks reached out, but eventually I ended up in my current job at Chocolatey Software.

Going Open Source

Initially the only things I put on Github were a loose collection of scripts, some things I found useful for work, and examples I’d written to answer a question on Reddit or the community Discord channels. So a few odds and ends, as well as a little bit of Git experience. I also knew I’d have trouble keeping track of everything I wanted to incorporate into PSKoans unless I had some kind of version history, so it was a good fit to get it on Github. Plenty of folks knew the platform well, so I had people around to ask if I ever got lost.

It also served as an open invitation as an open source project; if anything’s lacking, people are more than welcome to file issues or just outright write their own set of koans and we’ll do some code review and help incorporate them where they fit best. That was a pretty big appeal; writing a project solo is always daunting, and the PowerShell community is always happy to lend a hand, especially if your intent is to give back to that community.

Getting started is always a challenge. I think I had only a handful of topics I wanted to cover to begin with. It was, and is, ongoing work to expand that to cover as much as possible. Designing the framework around it was also quite challenging; since PSKoans needs to utilise Pester and also relies somewhat on interactive console sessions, I had to do some work to decouple it from the usual console session, so that it wouldn’t (seemingly) randomly fail when you restart the console session and (for example) some module you had used last time that isn’t loaded yet.

That took some months to sort out properly, and I’ve had to revisit it recently with some of the changes that came with the recently released Pester v5. I have most of that code all sorted out, but as it happens, trying to test code in Pester that’s running Pester itself is a bit of a tricky proposition at best!

Currently I’m working on the Advanced Functions topic and attempting to cover that thoroughly. There’s lots of parameter binding and fun things to cover, as well as some of the less-used bits and pieces that come with it. I’m also working on ensuring the module works correctly with v5 of Pester. I’m thinking I’ll probably do one more release in Pester v4, and then move things along and finish the move to Pester v5. Thankfully, very few of the koan topics themselves need to be altered for Pester v5 to work, it’s mainly module functionality that has to be adjusted for the new result formats and taking advantage of Pester’s discovery features properly.

The importance of open source software

In my opinion, open source software is critical. You can only learn so much in a closed space. If your code isn’t open to critique, you won’t write it nearly as well, and it’s also harder to seek help when you need it if you’re not in a position to actually share the code. It also gives others a chance to learn from you, as well as help you learn.

Being able to learn from open source projects is also hugely valuable; you can see how others have solved real-world problems, which is massively more valuable than trying to learn from a theoretical or contrived scenario.

It’s a good guard against getting too accustomed to a single code style or methodology as well; if all you ever write is code for your workplace you tend to adopt the common habits, both good and bad. Having some awareness of the wider community and how different people code makes it easier to drop and refactor out the bad patterns and keep the good ones.

My advice when it comes to open source? Get started. Throw your code on Github or wherever you want, there’s a few options out there. But include documentation! That doesn’t necessarily mean documentation for the code itself, it might not be at that stage yet, and that’s OK! But you should be including documentation for your projects so that others in the community know how they can interact with it. That means:

A proper license, so folks know if you’re okay with them deriving your work.
A contributing document explaining what processes you’d like to use for issues, feature requests, pull requests, etc.
A basic issue template, so people know what information you need to be able to address any concerns/problems they may have. These can get pretty detailed, and you can have multiple types, but if you’re just getting started at least include a basic one.
If/When you have a public version release, especially if you’re distributing it on another platform (for example, as a package on some other service like the PowerShell Gallery), include notes on how that’s actually done, so that if you ever want someone else to take over, they can.

Feel free to look at other open source projects for inspiration for those as well! You may not need all the detail embedded in the project documentation of a mature project, but you really should include some. Without any of that, people who may want to help out will have a really hard time figuring out how you want them to help! Remember that open source projects can and often do have multiple owners and maintainers. Part of enabling that is ensuring you have decent documentation for the processes you want to use in your repo. If you’re not sure yet, it’s OK to leave some things out, but don’t leave people guessing on the day to day things!

More from the author

I’m Joel Sallow, and I’m currently a software engineer at Chocolatey Software. You’ll often find me around the PowerShell Slack and Discord channels, but you can also follow me on Twitter or Github, and you can keep tabs on my blog that I’ll post to once in a while if I find something interesting and feel the need to write about it!

-=-

If you’d like to know more about Microsoft and open source, you can find more stories and info here.

Creating a bionic arm with open source software

Chris Walden — Fri, 14 May 2021 15:05:38 +0000

When open source is paired with passionate people, we get innovative, creative solutions to help others. Meet Cliff Agius, who created a fully-functioning bionic arm.

Tell us a bit about yourself.

I currently work as a pilot for a major UK airline, flying the plastic fantastic Boeing 787 around the world. Previously I was an electrical mechanical engineer for Ford, focussing on PLC Programming and Robotics.

While flying, I missed the challenge of engineering so I started to code in my spare time, beginning with simple websites and server-side code. I then found .NET and moved over to ASP.NET. Today I mostly work in C#/C++/Arduino C inside Visual Studio as a freelance developer on client projects including Xamarin Mobile, embedded systems, and IoT, as well as how they connect to and use the cloud.

How long have you been active in the open source community?

I have been active for few years starting with the OpenBionics repo and more recently PRs into Xamarin.Forms and my own open source projects, including Handy.

What first attracted you to using open source?

It’s a great place to see how others do things and learn best practices. By making the .NET stack open source, Microsoft has made it easier to fix bugs and test it locally in your project before pushing code changes as a PR to help others. It means bugs get found and fixed much quicker than if it was left to just the core team.

What are your favourite ever open source projects?

I really like the Xamarin.Forms project, and I've done some work with allReady from Humanitarian Tool Box. My favourite has to be Handy, as it mixes my love of engineering, electronics and software, including mobile, all into one project. Best of all, it’s literally giving someone a hand.

What was the inspiration behind Handy?

Kayden is a local 15 year old and the son of close friends. He was born without a left forearm and hand, as well as the middle fingers on his right hand, so life is a challenge at times. From a very young age Kayden and his parents have been visiting hospital to be measured and fitted with a prosthetic left arm. Great, you might think!

Sadly, these arms are exceedingly basic and consist of some heavy plastic with a heavy metal hook on the end, which attaches to Kayden with Velcro and is actuated with a wire going up his sleeve to his other shoulder. Now, this is better than nothing at all, and is far more than what's available in many parts of the world, but we should be able to do better. We can do better.

Kayden's mum asked if I can help with my 3D printer after seeing a story on the news in late 2016. I have taken the project, adapted it and changed it using my background skills in robotics and the years of tinkering with mobile apps. Being able Kayden and the family is special; seeing the smile on his face when he plays with the latest changes and tries new things that previously he couldn’t do. Best of all, my own children have taken a keen interest and have helped along the way.

Where did you start and how did the project go?

Where all projects begin - hours of searching! I then 3D printed prototypes to see what worked and what didn’t. Kayden, being a teenager, can be brutal in the feedback, but that's exactly what the project needs to drag it forward.

I wrote about Handy and the big picture on my blog. I also talk about some of the challenges I faced in another post.

Did you collaborate or use other OS code?

I got lots of help from my eldest son, who did all the 3D design and modifications for the printed parts. Many friends also contributed ideas on the code and Xamarin App. A lot of the recent ideas for the project have come from the many meet-up and conference talks I have given.

Other OS projects I have used include OpenBionics, Userdialogs, Xamarin.Forms, Xamarin.Essentials, Adafruit drivers for their controllers and sensor boards, and Sharpnado.

How successful has it been so far?

Kayden loves the hand and arm but we are still working to improve the fit of the socket and the way it works to suit him. His NHS prosthetic specialist has taken a very keen interest in the project and we are now working together to improve parts of the socket and fit, not just for Kayden but for future users too. With the team's specialist knowledge and help, we hope to make the design simple and easy to replicate.

What’s next for the project? What are your ambitions for it going forwards?

We want to get to the point where Kayden can reliably use the hand on a daily basis rather than the current ad-hoc use. I also want to build a kit to send anywhere in the world to help them learn how to build these arms for their local community.

We're also moving onto legs - my uncle had his amputated last year and hates the NHS prosthetic, so I agreed to take a look. At the moment Leggy is still in mechanical design; we have tried a lot of different designs and are hopefully settling on one of the current two designs soon.

I plan to blog about the journey but it's still very much a work in progress. Once we have a design, we'll open source the STL files that can be printed from.

-=-

If you’d like to know more about Microsoft and open source, you can find more stories and info here.