In PowerShell 5.0, Microsoft introduced the PowerShellGet module. This module contains cmdlets for different tasks. E.g. it lets you easily install / upload PowerShell modules / scripts from and to an online gallery such as PowerShellGallery.com. It even lets you find scripts, modules and DSC resources in such repositories. This is a fantastic way to share your script goodies and make it available to others, who can use them on-premise or even in Azure Automation for their runbooks or DSC projects.
In every collaboration scenario, there must be some rules. Publishing scripts has also some rules to follow, otherwise all scripts will end in a chaos and no one will ever find an appropriate script with the latest version etc. Therefore we need to provide structured data for version control, prerequisites and author information. This can be done using the PowerShellGet module.
Here just an overview of the cmdlets provided by this module…
Here comes the first pain point, if you try to run a cmdlet e.g. from your Windows 10 client, check the version of the module. In the screenshot above I ran it on an Azure VM with Windows Server 2016 TP4 installed. On my actual Windows 10 client I see this…
As you can see, there is a difference in version and cmdlet count. If you think now, that you could just upgrade the PowerShell version to the latest release on your Windows 10 box, well you need to wait until end of February 2016. Microsoft has pulled the latest RTM release back, because of some major issues. Find the post and details of the status on the PowerShell blog . If you managed to get to the latest release of the PowerShellGet module and you have the full set of cmdlets available, you are ready to start.
So how does that work?
Let’s assume we want to publish a PowerShell script to http://PowerShellGallery.com . Before you can start, you need to register with your Microsoft or Organizational account and then you will be ask to give PowerShell Gallery access to your account.
After registration you will get a key which will be needed later for uploading your files.
The least information needed to publish a script or a module is the following metadata provided in the header part of the script:
- Version number
- A URI to the license terms of the script
In order to get a template structure for the metadata just run…
New-ScriptFileInfo -Path C:\Temp\myscript.ps1 -Version 1.0 -Description “My description”
This will create a new script file with a bunch of header data. As I have mentioned before, a must requirement are only VERSION, DESCRIPTION, AUTHOR and LICENSEURI, if you want to publish your script. If you don’t add this data, the Publish-Script or Publish-Module cmdlet will complain and you won’t be able to upload the files to the PowerShellGallery.com . After you finished editing the data and you feel like having everything the way you want it, then you are ready to publish your script. As an example I have just played with it and this is, how it could look like….
If you already have a file written and you just need to update the metadata you could use Update-ScriptFileInfo -Path “C:\Temp\Script.ps1” -Version 2.0 –PassThru. I was not able to do so, the cmdlet always failed requesting to provide all parameters (null value was not allowed).
If you are in doubt about your metadata, you simply can test it by using the cmdlet Test-ScriptFileInfo -Path C:\temp\Get-ExpiredWebhook.ps1 this will read the information and display it accordingly…
…and all properties shown here…
But there is another problem, which I initially wanted to blog about and took me few minutes to figure out. If you have a line break within your description, it look like this…
Trying to upload to PowerShellGallery using the Publish-Script -Path C:\Users\returnone\Desktop\Get-ExpiredWebhook.ps1 -NuGetApiKey 12345678-1234-1234-1234-123456789123 fails with the following error which is in my opinion not very clear…
<br>Publish-PSArtifactUtility : Cannot process argument transformation on parameter 'ElementValue'. Cannot convert value<br>to type System.String.<br>At C:\Program Files\WindowsPowerShell\Modules\Powershellget\22.214.171.124\PSModule.psm1:2154 char:17<br>+ ... Publish-PSArtifactUtility -PSScriptInfo $PSScriptInfo `<br>+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br>+ CategoryInfo : InvalidData: (:) [Publish-PSArtifactUtility], ParameterBindingArgumentTransformationExce<br>ption<br>+ FullyQualifiedErrorId : ParameterArgumentTransformationError,Publish-PSArtifactUtility</p> <p>
After removing the line break, the Publish-Script cmdlet worked perfectly. I could reproduce the error and each time I saw this problem. The encoding was UTF-8 and just a plain text file / script.
If you want to know more about publishing scripts to PowerShellGallery.com go to that site and explore it. If you want to know more about the PowerShellGet module in general, which is available in PowerShell 5.0 go to TechNet here .
The idea behind these cmdlet is very cool and also easy to use, but there is still some work to do fixing some of these bugs.