What is the PowerShell Gallery?

Microsoft states:

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

Wait a second, doesn’t that sound a lot like the Microsoft Script Center?  Yes, it does.  The two both serve as a searchable repository for scripts and modules around the PowerShell scripting language.  The PowerShell Gallery offers up some distinctly different capabilities however.  For one, all scripts and modules are interacted with through, you guessed it, the PowerShell console.  While you can search the web-based gallery all other actions: downloading, installing, and publishing of PowerShell scripts and modules are handled from within PowerShell.  The Microsoft Script Center’s web-centric platform remains an excellent resource for System Administrator Scripters and other IT professionals.  The PowerShell gallery just has a much more devops(y) feel and, to date, has a repository base that more reflects that line of work.

There’s likely to be some cross-over between the two as the PowerShell Gallery matures and the Script Center will likely be with us for some time.  The PowerShell Gallery’s ability to rapidly search for, install, and easily update (something Script Center wasn’t great at) scripts and modules will likely make it the repository of choice moving forward though.

PowerShell Gallery Setup 101

All that’s required is the PowerShellGet module and NuGet provider (package manger)

Essentially, if you have Windows 10, you’re likely good to go. You can confirm you’re running the latest Windows Management Framework by running the following command:

PS C:\> $PSVersionTable.PSVersion 
Major Minor Build Revision
----- ----- ----- --------
5     0     10586 117 

If not you’ll require: Windows Management Framework 5.0

Or for those of you still running PowerShell 3 or 4 you’ll require the MSI Installer: MSI – PackageManagement PowerShell Modules Preview

Once your appropriate install is in place you’ll need a quick reboot and then you’ll have access to the PowerShellGet module:

PS C:\> Get-Module | select Name,Version | ft -AutoSize
Name Version
---- -------
ISE 1.0.0.0
Microsoft.PowerShell.Management 3.1.0.0
Microsoft.PowerShell.Utility 3.1.0.0
PackageManagement 1.0.0.1
PowerShellGet 1.0.0.1

Next, you’ll need the NuGet provider. The following code will check your system for it, and if not found, will install it for you:

#install NuGet if not already installed
$testNuGet = $null
$nuGet = Get-PackageProvider | Select-Object -ExpandProperty Name
foreach($result in $nuGet){
 if($result -eq "NuGet"){
 $testNuGet = $true
 }
}
if($testNuGet -eq $true){
 Write-Host "NuGet is already installed" -ForegroundColor Magenta
}
else{
 Install-PackageProvider -Name NuGet -Force
}

Using PowerShell Gallery

Updating PowerShellGet help

As a first step I recommend getting the updated help information for your new module.  It contains a lot of cmdlets you’re likely unfamiliar with you’ll want access to this information!

#get the updated help
Update-Help -Module PowerShellGet

Finding your first PowerShell Gallery Script

Find-Script and Find-Module

Lets say for example, you wanted to find scripts related to Hyper-V:

Find-Module -Repository PSGallery -Tag Hyper-V | fl
Find-Module -Repository PSGallery -Filter Hyper-V | fl

Script authors can provide descriptions and tags about their script.  I’m not 100% certain but I believe the filter parameter deals more with the description of a script/module while the tag focuses on just the tags.

This example returned one result:

Name : Diag-V
Version : 2.0
Type : Module
Description : Diag-V is a PowerShell Module collection of primarily Hyper-V diagnostic functions, as well as 
 several windows diagnostic functions useful when interacting with Hyper-V servers.
 
 With the module imported diagnostics can be run via the desired function name, alternatively, 
 Diag-V can also present a simple choice menu that enables you to browse via console all 
 diagnostics and execute the desired choice.
Author : Jake Morrison
CompanyName : jakewmorrison
Copyright : (c) 2017-2018 Jacob Morrison. All rights reserved.
PublishedDate : 12/11/17 03:38:31
InstalledDate : 
UpdatedDate : 
LicenseUri : 
ProjectUri : https://github.com/techthoughts2/Diag-V
IconUri : 
Tags : {Hyper-V, Diag-V, Diagnostic, Tests...}
Includes : {Function, RoleCapability, Command, DscResource...}
PowerShellGetFormatVersion : 
ReleaseNotes : Complete re-write from original script version. Converted Diag-V from a ps1 PowerShell script 
 to a fully supported PowerShell module. Redesigned all diagnostic functions: Improved error 
 control, General bug fixes, Better readability, Added new Hyper-V log parser function
Dependencies : {}
RepositorySourceLocation : https://www.powershellgallery.com/api/v2/
Repository : PSGallery
PackageManagementProvider : NuGet

Testing and Inspecting a script or module

As with all repositories it isn’t time to just start running your newly found Hyper-V script.  If the author has any website info, you might want to check it our first to ensure that script does what you are expecting.  You should also save the script and inspect the code to ensure it aligns with your objectives.  The following two cmdlets allow you to save (not install) the script for further review.

Save-Script and Save-Module

Save-Module -Name Diag-V -Repository PSGallery -Path "C:\TestScripts"

Downloading and installing a script or module from PowerShell Gallery

Once satisfied with the contents of the script/module it’s time to download and install it.

Install-Script and Install-Module

Install-Module-Name "Diag-V" -Repository PSGallery

This script/module will now be available to you on the device you have installed it on.

Verifying which scripts and modules you have installed from PowerShell Gallery

Get-InstalledScript and Get-InstalledModule

Keeping your scripts and modules current from PowerShell Gallery

This is something that’s really nice to have, the ability to easily update the script to take advantage of the latest improvements!

Update-Script and Update-Module

Update-Module -Name "Diag-V"

Publishing to PowerShell Gallery

As a first step, you’ll have to register as a user on the PowerShell Gallery website – this is a quick and easy process – especially if you already have a Microsoft account.

Armed with a login, you’ll be able to click on your username which will take you the page that contains your API key.  This API key is required to Publish scripts or modules to the PowerShell Gallery.

Once you have your API key you’re ready to get your script or module published.

Don’t forget to also check out the PowerShellGallery Publishing Guidelines and Best Practices

Publishing modules to PS Gallery

Publishing modules is relatively straightforward.  The module simply has to be installed on the current machine you wish to publish from.

With the module installed you simply use:

Publish-Module

Publish-Module -Name "Diag-V" `
 -NuGetApiKey "your-api-key-goes-here" `
 -Repository PSGallery

You can then visit your PowerShell Gallery page and fine tune any synopsis and description information.

Publishing scripts to PS Gallery

Publishing scripts to the PowerShell Gallery is a little more tricky.

New-ScriptFileInfo and Test-ScriptFileInfo and Publish-Script

In order to Publish your script/module you’ll need to generate some very specific PowerShell Gallery help syntax.  I found this to be the most challenging part of the process as the placement and spacing of this code block seemed to be very touchy and it took a bit of fiddling with Test-ScriptFileInfo before I got it right.

<#PSScriptInfo
.VERSION 1.0
.GUID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
.AUTHOR 
 Jake Morrison - TechThoughts - https://techthoughts.info
.COMPANYNAME 
 TechThoughts
.COPYRIGHT 
 Jake Morrison - please credit TechThoughts - https://techthoughts.info if used
.TAGS 
 Hyper-V,Diag-V,Diagnostic,Hyper-V Diagnostic,Tests,VM,VMs,VHD,VHDs,VHDXs,VHDX,CSV
.LICENSEURI 
.PROJECTURI 
.ICONURI 
.RELEASENOTES
 Initial Release - More info on this script and video demo at: https://techthoughts.info/diag-v/
#>

I suggest starting with New-ScriptFileInfo which will just generate the PowerShell Gallery help block to a temporary file.  From there you can edit it and then place it into your script.

New-ScriptFileInfo -Path "C:\PSFiles\PSGalleryHelpCode.ps1" -Verbose

Once you have your new file, you can edit it and copy it into your script that you wish to publish (see example above).

You’ll definitely want to utilize the Test-ScriptFileInfo cmdlet to ensure that everything is working as expected, otherwise you won’t be able to upload.

Take some time to really flesh out your description and tags as these are the only things that others have to locate your script.

Test-ScriptFileInfo -Path "C:\PSFiles\Diag-V.ps1"

Once Test-ScriptFileInfo is happy you’re ready to publish your script!

Publish-Script -Path "C:\PSFiles\Diag-V.ps1" -NuGetApiKey <your_apiKey>

Congratulations, you’re now a PowerShell Gallery user!