How YOU can create a script package for the PowerShell gallery
Tags: powershell, devops, tutorial
Published: 2021-10-21 17:22:38

---
title: How YOU can create a script package for the PowerShell gallery
published: true
description: this article describes how to create and publish a package for the PowerShell gallery
tags: powershell, devops, tutorial
series: powershell-tutorials
cover_image: https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xi2rpr76xbh586szpc23.png
---

> 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:

```powershell
<#
.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:

   ```powershell
   $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:

   ```powershell
   <#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

   ```powershell
   Test-ScriptFileInfo -Path ./swapi.ps1
   ```

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

   ```output
   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.
1. Select API keys menu option in top-right part of the page.
1. Select "Create" and expand that section. Here you are faced with following fields:

   ![PowerShell gallery](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ohy73771pe16nrnydi5t.png)

1. Fill in the following values:
   
   ![API key values](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3bhewxudd3vhpi5niiwg.png)

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

1. Publish your script using `Publish-Script`:

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

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

1. 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:

    ```powershell
    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.

1. Verify install with `Get-InstallledScript`

   ```powershell
   Get-InstalledScript
   ```

   ![Installed package info](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/uii0hfmazj7y83je7kx3.png) 
   

   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`:

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

   it says something like so:

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

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

   ```powershell
   . /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.

   ```powershell
   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.

   ```powershell
   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:

   ```output
   /package-swapi
     swapi.ps1 
   ```

1. dot source with:

   ```powershell
   cd package-swapi
   . swapi.ps1
   ```

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

   ```powershell
   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 :)