Publishing Scripts to the PowerShell Gallery
Learning the process of publishing a standalone script was like assembling new IKEA furniture: A wave of motivation and confidence, some tentative assembly, frustration because it’s not fitting correctly, a rip-and-replace on one side, and some lasting anger at lacking documentation/components.
Gratuitous simile aside, the PS Gallery is really handy, and I’d love to encourage uploading more cool stuff. To that end, I’ve documented the entire process as of January 2017 here, and I hope it helps you feel confident in publishing your own scripts!
Full disclosure: I’d love for you to publish a module, too. Modules are the preferred delivery method if you know what you’re doing, but there are still use cases for standalone scripts. And, you know, this article isn’t about
Publish-Module. Moving on!
Start to Finish:
- Create a PowerShell Gallery Account
- Create Your Sweet Script
- Publish-Script: Take One
- Update-ScriptFileInfo, the Right Way
- Publish-Script: Take Two
- Using Scripts From the Gallery
Create a PowerShell Gallery Account
- Register (probably with an existing personal account?)
- Allow access to the PS Gallery app
- Select a username
- You’re registered!
- All signed in? Now view your profile (by clicking your username in the top right)
- You’ll need your API key!
Your profile–where you copy your API key–should look like this:
Important: Guard your API key like a password! With obnoxious green boxes!
Create Your Sweet Script
My example for today is Measure-LastCommand.
Measure-LastCommand is a simple script that calculates the total runtime of any command you previously executed. Here’s the important stuff:
The red arrows aren’t important right now; I’m just calling out that I have collapsed both the function’s comment-based help and its parameter block. And please forgive the line break…tried to keep things readable in image format.
Finally made your
Get-SimpsonsQuote script pretty enough that you don’t feel self-conscious sharing it? Awesome. Now let’s start screwing with it.
Publish-Script: Take One
Oh, ok. It needs
Update-ScriptFileInfo -Force first.
Again, I’m assuming you already finished tidying up your masterpiece.
New-ScriptFileInfoalso exists, and assumes you’ll start your new script by defining the PS Gallery info first. Which seems unlikely. And it runs into the same problems I complain about below, so I’m ignoring it.
Update-ScriptFileInfo -Path $MLC -Force -Description 'testing' works with no complaints, so let’s open things up and…whaaat the hell just happened. Quarantining that to its own Gist:
Ugh. Unnecessary white space, nonsense trailing spaces, and to really zoom in on this:
- So many blank lines
- Why did Description need its own comment block?
- And now there are duplicate Description fields? How’s that work?
- Is that…is that a redundant, empty
Param ()block? WHY?!?
brb, going for a long walk.
Update-ScriptFileInfo, the Right Way
Ok, doing this in three steps. First, to answer the above:
- I kill those blank lines. I mean, wth man
- It doesn’t need its own block
- Yes to redundant
.DESCRIPTION, I’ll come back to that
- Gretchen, stop trying to make double
Param ()block happen. It’s not going to happen.
Second, here’s a template for using
Update-ScriptFileInfo as of January 2017. Hopefully it provides an idea both of what options there are to define, as well as how to format most parameters.
As the template alludes, “Description” in PS Gallery land is similar to “Synopsis” in your comment-based help. Basically, your PSScriptInfo Description is a synopsis for the general public. Synopsis/Description in your help continue to function as expected, and can be more targeted to your niche audience.
HINT: Need examples of how others did it? Here’s a list of PS Gallery items; filter to just the Script item type on that page. That shows how Name/Description/etc. are displayed. You can also
Find-Script Measure-LastCommand | Format-List *, or
Save-Script -Name Measure-LastCommand -Path "$env:USERPROFILE\Desktop"to
stealrepurpose anyone’s finished product!
Note that Name is determined by the filename (without file extension) of your script, NOT the function name(s) within.
Third, this is how I published my finished script with reformatted PSScriptInfo:
As you tweak the formatting to your preference, use the
Test-ScriptFileInfo command to ensure everything is still working as expected.
Publish-Script: Take Two
With PSScriptInfo populated, and with Test-ScriptFileInfo returning no errors, you’re ready to go.
$MLC = "$env:USERPROFILE\Desktop\Measure-LastCommand.ps1" $Key = 'asdf-jkl-12345' Publish-Script -Path $MLC -NuGetApiKey $Key -Verbose
No username/password necessary, just done! You’ll want to search the PowerShell Gallery for your new pride and joy, and you can always
Install-Script with it too, just to make sure it works as expected.
Using Scripts From the Gallery
You have the option to either:
- Specify your own directory to store the file
- Dot-source the file whenever you’d like to call the function
- Adds ‘C:\Program Files\WindowsPowerShell\Scripts’ to your PATH environment variable
- Which tries to load the script every time you launch PowerShell, automagically
I’ve had mixed results with
Install-Script working in subsequent sessions. For now, I’m sticking with
Save-Script, but I hope to find more reliable results when installing in the future, because it’s really easy.
- The PS Gallery is an easy way to get and share both modules and scripts with the world
Publish-Scriptwith your API key
- And, when publishing updates, ensure your script retains the same GUID as before
- Seriously though, make
For both of us?:
- The PowerShellGet module was open-sourced in Sept 2016
- Hopefully most of this article becomes obsolete with some pull requests!
Measure-LastCommand can be found wherever fine scripts are available. (He means it’s on the Internet.)