PowerShell Gallery 101
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
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-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 -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!
Testing for nuget is a lot easier than the sample shown here!
Just do this
If (Get-PackageProvider Nuget) {
‘nuget installed’
}
else {
Install-PackageProvider -Name NuGet -ForceBootstrap
}