How YOU can create a script package for the PowerShell gallery

TLDR; this article covers how to build a package for the PowerShell gallery. This is a great way to share your scripts and modules with others. You want to help the community, right? Of course, you do :)

Here's the steps we are about to take:

• Author script. First you need to create a script. In this case we are creating a script, but you can also create and upload a module to PowerShell gallery.
• Document it. When you document your script, you do so, so Get-Help will work with it, this is highly recommended to do.
• Prepare the package. To be able to upload your script, it needs a specific set of metadata, there are commands that will help you do that.
• Sign up for PowerShell gallery. It's free to sign up for the gallery, but what you do need from it is an API key that will help you publish your package.
• Publish. Using a command, you can push your package to the gallery. At this point you have bragging rights, and can show your friends :)
• Save or install package. There are two different approaches you can use to consume a package, pick one.
• that's it :)

Author script

To author a script, you need a file ending in .ps1. Then you can use the PowerShell scripting language to add your commands and/or parameters.

Support Get-Help

To support the Get-Help command, you want to add some documentation that supports. Add for example the above meta information right on top of a function:

<#
.SYNOPSIS

Retrieves a planet

.DESCRIPTION

A command that retrieves a planet by id

.PARAMETER Id
Specifies the record you want back

.INPUTS

Id

.OUTPUTS

Object. 

.EXAMPLE

PS> Get-Planet 1

#>
Function Get-Planet {
  implementation...
}

Document it

Before you can upload your package, it needs some metadata. Without this metadata, your package will be rejected if you try to upload it. The metadata you need are information on things like version, author, company and a description. What you do is to feed that information into a command and out comes metadata + a unique GUID. At this point you need to add this metadata to the top of your script file.

First, let's generate the metadata, or script info, as it's also referred to:

1. Generate script file info:

   $Parms = @{
       Path = "./new.ps1"
       Version = "1.0"
       Author = "<email>"
       CompanyName = "<company>"
       Description = "Description"
   }
   New-ScriptFileInfo @Parms -PassThru

this creates a file _new.ps1_.

You will also get meta information within the above file that looks something like so:

   <#PSScriptInfo

    .VERSION 1.0

    .GUID <a unique GUID>

    .AUTHOR <email>

    .COMPANYNAME <company>

    .COPYRIGHT

    .TAGS the tags you want, comma separated

    .LICENSEURI https://mit-license.org

    .PROJECTURI link to for example github, if that's where you store the code

    .ICONURI

    .EXTERNALMODULEDEPENDENCIES 

    .REQUIREDSCRIPTS

    .EXTERNALSCRIPTDEPENDENCIES

    .RELEASENOTES


    .PRIVATEDATA

    #>

    <# 

    .DESCRIPTION 
     Description 

    #> 

Next, you want to perhaps fill in more info in the above meta information. You want to make sure you have a nice project description and tags for better visibility in the gallery. Next, you can verify that the script file and its script info validates.

1. Ensure all is good with script file info

   Test-ScriptFileInfo -Path ./swapi.ps1

If everything is good, you will get a response similar to:

   Version              Name                      Author               Description
   -------              ----                      ------               -----------
   1.1                  swapi                     author               Description

Great, you are ready for the next step, which is to publish your script to the gallery.

Sign up for the PowerShell Gallery

1. Navigate to https://www.powershellgallery.com/ and create a user.
2. Select API keys menu option in top-right part of the page.
3. Select "Create" and expand that section. Here you are faced with following fields:

1. Fill in the following values:

and select "Create". Now copy this API key, you will use it next.

1. Publish your script using Publish-Script:
   

   Publish-Script -Path ./swapi.ps1 -NuGetApiKey <api key>
   

   That should take a few seconds, once done, you will be able to find your script.

2. In PowerShell gallery, select "Manage Packages", expand "Published Packages", there's your package, give yourself a high-five, well done!! :)

Consume your package

To ensure everything work as intended, we will try to consume our package by downloading it from the PowerShell gallery and use it on our machine. We have two options on how to do that:

• Install the script. This will place the script in a specific downloads folder. We will still need to dot source it to use it.
• Save the script. This will allow is to save the script to a destination on our machine that we decide, we still need to dot source to use it.

a) Install script

1. Install from the PowerShell gallery:
   

   Install-Script -Name swapi -Force
   

   At this point, your script was installed on your machine, in a specific script folder. Next, you need to find that script folder, so you can dot source and use the content of the script.

2. Verify install with Get-InstallledScript
   

   Get-InstalledScript

Great, you were able to get some information back on that the package (your script), was downloaded from PowerShell Gallery. Next, you need to find the install path of the script, to be able to use it.

1. To use the script, we first need to localize it with Get-InstalledScript:

   (Get-InstalledScript -Name "swapi").InstalledLocation

it says something like so:

   /Users/<user>/.local/share/powershell/Scripts

1. dot source from there, use the response in the last step and dot source it like so:

   . /Users/<user./.local/share/powershell/Scripts/swapi.ps1

Note the usage of "." and then the path as the second argument, that's what's meant by dot sourcing.

At this point, your script is on your machine, the content of it is available to use.

1. To test it out, try running Get-Planet, you elected to download the swapi.

   Get-Planet 2

This should give a JSON response.

b) Save script and then dot source

In this second approach, instead of installing the script, you would save it to disk at a location you specify. The big difference is that it doesn't end up in pre-determined install location, but rather in a place you choose.

   Save-Script -Name swapi -Repository PSGallery –Path ./package-swapi -Force

creates a package-swapi subdirectory and places the script in there. So your file system looks like so:

   /package-swapi
     swapi.ps1 

1. dot source with:

   cd package-swapi
   . swapi.ps1

1. To test it out, try running Get-Planet, you elected to download the swapi package.

   Get-Planet 2

This should give a JSON response.

Summary

Congratulations, you've managed to create a package for PowerShell gallery, upload it to the gallery and managed to download and use said package.

You've come a long way, now build your own packages, share them with the community and let me know.

Thanks for reading :)