PowerShell OneGet: Gist-As-A-Package

This article will cover a new powerful feature delivered in the PowerShell 5.0 November Preview. This feature is OneGet. OneGet is a unified package manager for package management systems. A package manager or package management system is a collection of software tools that automates the process of installing, upgrading, configuring, and removing software packages for a computer’s operating system in a consistent manner.

What is OneGet?

OneGet is a unified package manager for package management systems. Environments like Perl, Python, Ruby, Node.js, and JavaScript have them. For the Windows world there is the NuGet and Chocolatey package management systems. PowerShell OneGet delivers a common set of cmdlets to install/uninstall packages, add/remove/query package repositories, and query a system for the software installed, regardless of the installation technology underneath.

Plus, OneGet is open-sourced. This means you can jump on GitHub, see the code used to implement OneGet, participate in discussions about features, and priorities. But wait, there’s more! You can log issues you hit, and you can even create a copy of the source code, make changes and (if you want) request them to be incorporated into the official release.

OneGet also has an SDK that lets others create providers to interop with other technologies. It seamlessly integrates this layer so you, the PowerShell user, don’t even know you’re looking at different repositories containing any array of source code.

I used the OneGet SDK to create my OneGet Gist package provider.

Gists

Using Gist is a great way to share code. Whether it’s a simple snippet or a full app, Gist is a great way to get your point across. And the fact that every Gist can be copied and modified makes it even better.

You can discover gists others have created by going to the gist home page and clicking All Gists. This will take you to a page of all gists sorted and displayed by time of creation or update. You can also search gists by language with Gist Search. Gist search uses the same search syntax as code search.

When you register (for free) on GitHub, you can create gists under your name. Registering lets others discover and install your scripts using the new PowerShell cmdlets found in the OneGet module.

Let’s Get Started

Let’s say you’re searching the Gist repository for some scripts (or a colleague sent you a link to his scripts). Using your browser to navigate to the gist and you have a couple of options to get that code to your machine. You can copy and paste it to a file, to an editor, or you can download it as a zip file (then unzip and edit the unzipped content).

Using the Gist Package Provider plugin for OneGet, all you need to do is use Install-Package.

2.5 steps to getting it working

I outline the steps and then walk through them.

1 – Install PowerShell 5.0 November Preview.

2 – Get the Gist package I wrote, using Install-Module (another new feature, that is part of the PowerShellGet Package Management Module).

2.5 – Restart the PowerShell console (this is a one-time requirement).

You’re ready to go.

PowerShellGet

PowerShellGet is a package manager for Windows PowerShell.  More specifically, it is a wrapper around a new Windows component called OneGet, and it enables simplified package management of PowerShell modules.

Check out Kirk Munro’s write-up for a deep dive.

PowerShellGet is written by Microsoft and leverages the same OneGet SDK I did to get the job done.

PowerShellGet has a repository, the PowerShell Gallery. The PowerShell Gallery is the central repository for Windows PowerShell content. You can find new Windows PowerShell commands or Desired State Configuration (DSC) resources in the Gallery.

On it you’ll find the Gist OneGet provider and you can also check out another module I publish, PowerShellHumanizer, it is used for manipulating and displaying strings, enums, dates, times, timespans, numbers, and quantities.

Sanity Check

After you install the November Preview, make sure you have the correct version running, 5.0.9883.0 (or greater if you’re running the latest Windows 10).

Now you’re ready to install the OneGet Gist Provider, Install-Module GistProvider. You need to run as administrator. If this is your first time running a cmdlet from PowerShellGet, you’ll be prompted to install NuGet, go ahead and say yes. The PowerShell Gallery is set as an untrusted repository out of the box because the repository is not curated. So, you’ll be prompted asking your permission to install it, type y, and press enter.

Now, restart the PowerShell console. This is a one-time operation because of how OneGet initializes providers and is required only after you install an OneGet package provider.

Is the Package Provider Ready?

After restarting the PowerShell console, make sure the Gist Provider was installed. Use the Get-PackageProvider to list all of the OneGet package providers available.

Let’s see the provider in action:

This sends the list of all my, dfinke, public gists to Out-GridView.

Typing in Find-Package with no parameters, will not return any Gist package info. Why? Because querying the entire Gist repo of authors and their gists would be in the thousands of thousands, so you need to narrow down to the authors you want to query.

You can search for gists using the GitHub webpage. Here is the URL to query all gists with PowerShell, https://gist.github.com/search?q=powershell.

You can specify an array of authors for the –Source parameter, for example:

Using the filtering capability of Out-GridView, you can see a list of gists by author (Source).

How to Install a Gist

I have a gist called CFSBuddy.ps1. While OneGet does not support wildcards (yet) you can pass a string to the -Name parameter for matching. Here I’m searching across multiple authors:

When you find the package you want, pipe the results to Install-Package. Again, the Gist Provider is marked as untrusted, prompting you for approval to continue.

Where’s the Gist?

The gist are installed in $env:LOCALAPPDATA\OneGet\Gist. It saves the downloaded file based on the name the author of the gist saved it as. After installing the CFSBuddy.ps1 script, I can run it like this.

. $env:LOCALAPPDATA\OneGet\Gist\CFSBuddy.ps1

You should see this.

I built this GUI to make it easier to work with the new ConvertFrom-String cmdlet. ConvertFrom-String lets you parse a file by providing a template that contains examples of the desired output data rather than by writing a (potentially complex) script.

This PowerShell based GUI lets you easily try out how ConvertFrom-String acts on your data. As you type in either the Data textbox or the Template textbox, two things happen. The PowerShell that does the work is automatically generated and put in the Code textbox at the bottom, and the PowerShell is executed putting the output in the Results textbox. This GUI really speeds up how you interact with ConvertFrom-String.

Check out this great write-up on ConvertFrom-String.

Multiple Gists Using a One-Liner

This example searches all gists in the repo for author dfinke that contains the string ‘get’. It returns 9 matching gists.

Piping that to Install-Package will install all the gists (NOTE: I’m using the –Force switch, now OneGet will not to prompt me about the Gist Provider being an untrusted source).

Another Great Way to Share Your Solutions

Now that you’ve seen how easy it is to discover and install gists. You can register as a user on GitHub, paste and save your scripts, then email, tweet, blog, post to the Facebook PowerShell page for colleagues and the community to try it out, like this:

1

Install-Package –Source dfinke –Name CFSBuddy.ps1 –Force 

They paste this into a PowerShell console, press enter and the script is located, downloaded and ready to run. Gists are SRR, scripts ready to run.

Rate Limits

GitHub has rate limits. If you do not pass in credentials, you can make 60 requests in an hour. After 60 requests in the hour, the mechanism the Gist Provider uses will no longer return packages. If you use credentials, you can make up to 5,000 requests per hour. The OneGet *Package cmdlets support credentials and this will work if you have registered on GitHub.

Gist Provider on GitHub

I wrote this provider after attending the Microsoft MVP Summit and I’ve put the code up on my GitHub Repo. I encourage you to check out how it was done (and my other PowerShell repos).

If you’re up for it, make a copy and your own changes. Please open issues, ask questions or submit suggestion changes/improvements.

As a side note, GitHub is a social network for building software better, together.

So, if you like the provider, visit GitHub and click the star button (and do it for other projects you like). It’s a great way to collaborate, learn, improve your skills and engage with many different communities.

Summary

We’ve covered a lot of features and concepts, including OneGet, PowerShellGet, OneGet Providers (e.g. Gist), GitHub Gist, and only mentioned ConvertFrom-String.

OneGet and its providers are the easiest way to get PowerShell modules installed (as well as DSC Resources) and it is not just for PowerShell. Check out the list of desired plugins here https://github.com/OneGet/oneget/issues/77. Some are already in development.

As a bonus, OneGet has a DSC Resource too. This means more flexibility for your automated DevOps scenarios.

Happy scripting!

Thank you to June Blender for reviewing the article and the great suggestions.