PowerShellGet 3.0 Preview 11 Release

Amber Erickson

We are excited to announce that an important update to our preview of PowerShellGet 3.0 is now available on the PowerShell Gallery!

This preview release marks the completion of a complete refactor of this module and is a major step towards being feature complete for PowerShellGet 3.0.

PowerShellGet 3.0 is a complete re-write of PowerShellGet with the following goals:

• Create a more intuitive package manager: Make PowerShellGet more intuitive and easier to use by removing unnecessary prompts when possible.
• Address top customer issues: Many of the top customer issues in previous versions of the module have been challenging to resolve because of architecture decisions made early on in the development of PowerShellGet. Below we enumerate many of these issues we hope to resolve. To view a full enumeration of these issues see this GitHub milestone.
• Allow for a smooth transition to v3: Transitioning from lower versions of PowerShellGet to 3.0 and above should be as painless as possible. With the help of our compatibility module, CompatPowerShellGet, explained in more detail below, our goal is to enable users and scripts built on PowerShellGet 2.0 to move seamlessly to 3.0.
• Improve maintainability of the codebase: This goal is addressed by removing the provider model that PowerShellGet was originally built on.

This means that PowerShellGet 3.0 does not take a dependency on PackageManagement, NuGet or any other package provider, simplifying the codebase.

Using the lessons learned from previous versions of the module, along with a cleaner implementation and interface, we have improved efficiency and quality, allowing us to more quickly address bugs as they arise and iterate on our vNext issues.

The purpose of this release to get critical user feedback to improve the module through subsequent preview releases before we finalize the design for a Release Candidate expected later this year.

It’s been many months since our last release, but we believe that this preview is well worth the wait. We’ve spent the last 6+ months working on bringing PowerShellGet 3.0 from a prototype stage to something efficient, maintainable, fully tested, and backwards compatible.

How to Install PowerShellGet 3.0 Preview 11

Prerequisites

Please ensure that you have the latest (non-prerelease) version of PowerShellGet and PackageManagement installed. To check the version you currently have installed run the command:

Get-InstalledModule PowerShellGet, PackageManagement

The latest version of PowerShellGet is 2.2.5, and the latest version of PackageManagement is 1.4.7. To install the latest versions of these modules run the following:

Install-Module PowerShellGet -Force -AllowClobber

Installing the Preview

To install this preview release side-by-side with your existing PowerShellGet version, open any PowerShell console and run:

Install-Module PowerShellGet -Force -AllowPrerelease

If you run the command Get-Command -ModuleName PowerShellGet you will get a good picture of the side-by-side cmdlet interfaces.

CommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
Cmdlet          Find-PSResource                                    3.0.0      PowerShellGet
Cmdlet          Get-PSResource                                     3.0.0      PowerShellGet
Cmdlet          Get-PSResourceRepository                           3.0.0      PowerShellGet
Cmdlet          Install-PSResource                                 3.0.0      PowerShellGet
Cmdlet          Publish-PSResource                                 3.0.0      PowerShellGet
Cmdlet          Register-PSResourceRepository                      3.0.0      PowerShellGet
Cmdlet          Save-PSResource                                    3.0.0      PowerShellGet
Cmdlet          Set-PSResourceRepository                           3.0.0      PowerShellGet
Cmdlet          Uninstall-PSResource                               3.0.0      PowerShellGet
Cmdlet          Unregister-PSResourceRepository                    3.0.0      PowerShellGet
Cmdlet          Update-PSResource                                  3.0.0      PowerShellGet

Features

• A complete refactor of cmdlets which abstract all PSResource types (Module, Script, DSCResource, RoleCapability, Command) to a single set of cmdlets which use the noun “PSResource”. Many of these cmdlets use a -Type parameter for the user to specify the PSResource type if they would like. For example:Find-PSResource -Name PowerShellGet -Type Module -Prerelease

• For the cmdlets Register-PSRepository and Set-PSRepository a -Priority parameter allows setting the search order of repositories with a lower value indicating a higher priority. This addresses a common complaint with lower versions of PowerShellGet, which is that a resource found in multiple repositories would trigger a prompt that would require the user to specify which repository specifically the resource should come from. With this new feature, if -Priority is not specified, the default value is 50. The PSGallery, which is registered by default, has an editable value of 50. If two PSRepositories have the same priority the “Trusted” one will be chosen, if they also have the same level of trust the first one alphabetically will be selected. Of course, a specific repository can always be specified.

• • For Find-PSResource the -Repository parameter supports wildcard search. If no repository is specified, the cmdlet will return the latest version found from the repository with the highest priority.

    Find-PSResource Az.Sql -Repository *
    
    Name   Version Repository      Description
    ----   ------- ----------      -----------
    Az.Sql 2.5.0   PSGallery       Microsoft Azure PowerShell - SQL service cmdlets for Azure Resource...
    Az.Sql 2.5.0   PoshTestGallery Microsoft Azure PowerShell - SQL service cmdlets for Azure Resource...

    Find-PSResource Az.Sql
    
    Name   Version Repository      Description
    ----   ------- ----------      -----------
    Az.Sql 2.5.0   PSGallery       Microsoft Azure PowerShell - SQL service cmdlets for Azure Resource...

• For Find-PSResource and Install-PSResource the -Version parameter will accept strings (with wildcard support) based on the Nuget version range syntax:

  Find-PSResource Microsoft.PowerShell.GraphicalTools -Version *
  Name                                Version Repository Description
  ----                                ------- ---------- -----------
  Microsoft.PowerShell.GraphicalTools 0.2.0   PSGallery  Cross-platform GUI Tools for Pow…
  Microsoft.PowerShell.GraphicalTools 0.1.1   PSGallery  Cross-platform GUI Tools for Pow…

  Find-PSResource Microsoft.PowerShell.GraphicalTools -Version "(0.0,1.0)"
  
  Name                                Version Repository Description
  ----                                ------- ---------- -----------
  Microsoft.PowerShell.GraphicalTools 0.2.0   PSGallery  Cross-platform GUI Tools for Pow…

  Find-PSResource Microsoft.PowerShell.GraphicalTools -Version "0.1.1"
  
  Name                                Version Repository Description
  ----                                ------- ---------- -----------
  Microsoft.PowerShell.GraphicalTools 0.1.1   PSGallery  Cross-platform GUI Tools for Pow…

• Install-PSResource has a -DestinationPath parameter which allows the user to specify the target directory instead of one based on the -Scope parameter (default Scope is CurrentUser). Note that in this release “x86” paths, and Linux paths are not yet supported. Expect to see this support in future releases.
• Update-PSResource has an -UpdateTo parameter with values MinorVersion (the default), MajorVersion, and PatchVersion MinorVersion allows updating to the latest minor version (e.g. 6.2.1 to 6.3.0). MajorVersion allows updating to the latest major version (e.g. 6.2.1 to 7.0.0). PatchVersion allows updating to the latest patch version (e.g. 6.2.1 to 6.2.4).
• Publish-PSResource functionality
• There is support for NuGet v2 and v3 endpoints for PSRepositories.
• Error handling, warnings, -Verbose, and -Debug parameters

For the full list of issues expected to be resolved in this release refer to this GitHub project. If any of the features on this list are not behaving how you would expect them to, or would prefer them to be sure to open an issue in our GitHub repository.

Features to Expect in Coming Preview Releases

This module is not yet feature complete. Below is a list of features that we are still in the process of implementing which you can expect to see in future preview releases.

• We will introduce a New-RequiredResourceFile cmdlet which will create a template file. If the switch -AsPSD1 is used it will create a psd1 file, otherwise it will default to JSON.
• New-ScriptFileInfo cmdlet
• Test-ScriptFileInfo cmdlet
• Update-ScriptFileInfo cmdlet
• Update-ModuleManifest cmdlet
• Dependency management. In future releases, Install-PSResource will accept a path to a psd1 or JSON file (using -RequiredResourceFile), or a hash table or JSON (using -RequiredResource) where the key is the module name and the value is either the required version specified using Nuget version range syntax or a hash table where repository is set to the URL of the repository and version contains the Nuget version range syntax.

Install-PSResource -RequiredResource @{
  Configuration = "[1.3.1,2.0)"
  Pester        = @{
    version = "[4.4.2,4.7.0]"
    repository = "https://www.powershellgallery.com"
    credential = $cred
    allowPrerelease = $true
  }
}

In this case the modules named “Configuration”, and “Pester” will be installed. The JSON format will be the same as if this hashtable is passed to ConvertTo-Json:

{
  "Configuration": "[1.3.1,2.0)",
  "Pester": {
    "version": "[4.4.2,4.7.0]",
    "credential": null,
    "repository": "https://www.powershellgallery.com",
    "allowPrerelease": true
  }
}

• Save-PSResource -Type Library will download nupkgs that have a lib folder in order to make it easier to use arbitrary libraries with PowerShell scripts. The dependent native library in runtimes matching the current system runtime will be copied to the root of the destination specified. An -IncludeAllRuntimes can be used to explicitly retain the runtimes directory hierarchy within the nupkg to the root of the destination.
• Native credential management/credential persistence for registered PSRepositories
• Publish-PSResource will include a -DestinationPath parameter to publish a resource to a particular file path

Using the CompatPowerShellGet module

CompatPowerShellGet is a compatibility module that allows use of PowerShellGet 2.x (and below) cmdlet syntax with PowerShellGet 3.0 (and above) functionality by making a best effort mapping between the cmdlet interfaces of both versions of the module. New PowerShell scripts that only leverage PowerShellGet v3 cmdlets do not need to use this compatibility module. For example, if a user has the CompatPowerShellGet module installed and runs the command:

Install-Module PowerShellGet -MinimumVersion 1 -MaximumVersion 2 -AllowPrerelease 

the CompatPowerShellGet module will get autoloaded into the PowerShell Session and will map the command to PowerShellGet 3.0 syntax:

Install-PSResource PowerShellGet -Version "[1,2]" -Prerelease" 

The command will then be executed by the PowerShellGet 3.0 implementation. The user will also get a warning to update their script to the new cmdlet interface:

WARNING: The cmdlet 'Install-Module' is deprecated, please use 'Install-PSResource’.

This module is designed so that users will not need to immediately update their scripts in order to update to the latest version of PowerShell or to begin taking advantage of the performance improvements already available in PowerShellGet 3.0. We still do recommend that authors begin making the minimal changes required to update their scripts to the new cmdlet interface.

This compatibility module is designed so that it takes precedence over legacy versions of PowerShellGet. If you have this compatibility module installed and would not like it to be used, you can remove it from the PowerShell session using the Remove-Module command.

Please note that this flow is only possible if the user has both the CompatPowerShellGet module installed and the PowerShellGet 3.0 preview module installed. Once PowerShellGet 3.0 is generally available it will be a dependency of CompatPowerShellGet.

Please also note that this compatibility module will not be called if you use fully qualified cmdlets. For example, if you use PowerShellGet\Install-Module this will call a legacy version of PowerShellGet. If this is a common scenario for you, and will be a barrier to migrating to PowerShellGet 3.0 we would appreciate that feedback in our GitHub repository.

Improvements we are Considering post-GA

One important goal of PowerShellGet 3.0 is to improve the supportability of the module. As a result, once this work is complete we will iterate more quickly, and tackle other top customer issues. This list represents issues we are considering tackling, but have not committed to yet.

To track the full list of issues we are considering we are using the vNext milestone in our GitHub Repository.

How to Track the Development of this Module

GitHub is the best place to track the bugs/feature requests related to this module. We have used a combination of projects and labels on our GitHub repo to track issues for this upcoming release. We are using the label Resolved-3.0 to label issues that we plan to release at some point in before we release the module as GA (generally available). To track issues/features to particular preview and GA releases we are using GitHub projects which are titled to reflect the release.

Timeline/Roadmap

Expect to see preview releases more frequently as new functionality is added and bug fixes are made. Our goal is to keep a release cadence of roughly every 2 weeks. User feedback will help us determine when we can have a Release Candidate version of the module which will be supported to be used in production. Based on user feedback, if we believe the 3.0 release is complete, then we will publish a 3.0 version of the module as Generally Available. Since these milestones are quality, rather than date, driven we can not offer an exact timeline at this point, but hope to release the module later this year.

How to Give feedback and Get Support

We cannot overstate how critical user feedback is at this stage in the development of the module. Feedback from preview releases help inform design decisions without incurring a breaking change once generally available and used in production.

In order to help us to make key decisions around the behavior of the module please give us feedback by opening issues in our GitHub repository.

Sydney Smith, Amber Erickson, Anam Navied, Paul Higinbotham PowerShell Team

Amber Erickson Software Engineer, PowerShell

Follow