PowerShellGet 3.0 Preview 1

We are excited to announce that our first preview release of PowerShellGet 3.0 is now available on the PowerShell Gallery. This is a major update to PowerShell’s experience for discovering, installing, updating and publishing PowerShell resources like modules, DSC resources, role capabilities and scripts. This was first proposed in RFC PR #185 and superseded by RFC PR #237. Thanks for all the community feedback! For a detailed view of the update to PowerShellGet please refer to the RFC.

This early preview release of the module is not feature complete and has breaking changes intended to improve the user experience. For this reason, the preview release will work side-by-side with your existing PowerShellGet v2 module.

The purpose of this release to begin gathering the critical user feedback to improve the module through subsequent preview releases before we finalize the design for General Availability later this year.

How to Install PowerShellGet 3.0 Preview 1

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.3, and the latest version of PackageManagement is 1.4.6.

To install the latest versions of these modules run the following at the start of a fresh PowerShell session:

Install-Module PowerShellGet -Force -AllowClobber

Installing the Preview side by side

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

Install-Module PowerShellGet -Force -AllowPrerelease

To register the PSGallery run the command:

Register-PSResourceRepository -PSGallery

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

CommandType     Name                                               Version    Source
-----------   ----                                              -------     ------
Function        Find-Command                                       2.2.3      PowerShel.
Function        Find-DscResource                                   2.2.3      PowerShel.
Function        Find-Module                                        2.2.3      PowerShel.
Function        Find-RoleCapability                                2.2.3      PowerShel.
Function        Find-Script                                        2.2.3      PowerShel.
Function        Get-InstalledModule                                2.2.3      PowerShel.
Function        Get-InstalledScript                                2.2.3      PowerShel.
Function        Get-PSRepository                                   2.2.3      PowerShel.
Function        Install-Module                                     2.2.3      PowerShel.
Function        Install-Script                                     2.2.3      PowerShel.
Function        New-ScriptFileInfo                                 2.2.3      PowerShel.
Function        Publish-Module                                     2.2.3      PowerShel.
Function        Publish-Script                                     2.2.3      PowerShel.
Function        Register-PSRepository                              2.2.3      PowerShel.
Function        Save-Module                                        2.2.3      PowerShel.
Function        Save-Script                                        2.2.3      PowerShel.
Function        Set-PSRepository                                   2.2.3      PowerShel.
Function        Test-ScriptFileInfo                                2.2.3      PowerShel.
Function        Uninstall-Module                                   2.2.3      PowerShel.
Function        Uninstall-Script                                   2.2.3      PowerShel.
Function        Unregister-PSRepository                            2.2.3      PowerShel.
Function        Update-Module                                      2.2.3      PowerShel.
Function        Update-ModuleManifest                              2.2.3      PowerShel.
Function        Update-Script                                      2.2.3      PowerShel.
Function        Update-ScriptFileInfo                              2.2.3      PowerShel.
Cmdlet          Find-PSResource                                    3.0.0      PowerShel.
Cmdlet          Get-PSResource                                     3.0.0      PowerShel.
Cmdlet          Get-PSResourceRepository                           3.0.0      PowerShel.
Cmdlet          Install-PSResource                                 3.0.0      PowerShel.
Cmdlet          Register-PSResourceRepository                      3.0.0      PowerShel.
Cmdlet          Set-PSResourceRepository                           3.0.0      PowerShel.
Cmdlet          Uninstall-PSResource                               3.0.0      PowerShel.
Cmdlet          Unregister-PSResourceRepository                    3.0.0      PowerShel.

High-Level Goals of PowerShellGet 3.0

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

• 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 OneGet, NuGet or any other package provider. Further, this version is written in C# instead of PowerShell script which has allowed us to simplify the code base. By using the lessons learned from previous versions of the module we hope that a cleaner implementation and interface will allow us to more quickly address bugs as they arise and iterate on our vNext issues more efficiently.
• 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 view this GitHub query.

Features of this Release

• A new set 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.

Find-PSResource
Get-PSResource 
Get-PSResourceRepository 
Install-PSResource 
Register-PSResourceRepository 
Set-PSResourceRepository 
Uninstall-PSResource 
Unregister-PSResourceRepository 
Update-PSResource 
SYNTAX 
Find-PSResource [[-Name] <string[]>] [-Type {Module | Script | DscResource | RoleCapability | Command}] [-Version <string>] [-Prerelease] [-ModuleName <string>] [-Tags <string[]>] [-Repository <string[]>] [-Credential <pscredential>] [-IncludeDependencies] [-WhatIf] [-Confirm] [<CommonParameters>] 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. If 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.

• 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.

• 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.0   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.0   PSGallery  Cross-platform GUI Tools for Pow.

• Install-PSResource has a-DestinationPath parameter which allows the user to specify the target directory instead of the default one. 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.

• There is support for NuGet v2 and v3 endpoints for PSRepositories.

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.

Table of Implemented Parameters in this Release

What’s Coming Next

Features to Expect in Coming Preview Releases

This module is not feature complete, meaning many issues/bugs in this release may just be features we have not finished implementing. 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.

• Publish functionality (in the meantime the publish functionality of PowerShellGet2.x works nicely side-by-side)
• Error handling, warnings, -Verbose, and -Debug parameters (for the full list of missing parameter see the table above).
• Local cache–this important feature significantly improves the performance of Find/Install operations. Look forward to it in future releases.
• 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 andversion 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 } }

• 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.
• Save-PSResource -Type Library will download nupkgs that have a lib folder. The dependent native library in runtimes matching the current system runtime will be copied to the root of the destination specified. A -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

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 hope to iterate more quickly, and tackle other top customer issues. This list represents issues we are considering tackling but have not committed to yet.

• We will explore automatic updating of the cache in which on any operation that reaches out to a repository, a REST API will be called to see if the hash of the cache matches the current cache and if not, a new one is downloaded. This system may also take into consideration how recently the cache has been updated to avoid constant updates.
• We will explore an Enable-PowerShellGetAlias cmdlet that will allow users to use known cmdlets like Install-Module from the PowerShellGet 3.0 implementation.
• We will explore uninstalling orphaned dependencies automatically.

To track the full list of issues we are considering we are using the label vNext 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 as new functionality is added/changes are made at approximately a monthly cadence until the module is feature-complete. Through this process we will also be adapting the module based on user feedback. Once we feel we have reached a sufficient quality and completeness, we will release a “Release Candidate” version of the module. Assuming this release does not require any high impact changes, we will then release that 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 PowerShell Team