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.

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

has a 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

Cmdlet Implemented parameters Not implemented Install-PSResource -Name -Version -Prerelease -Repository -Credential -Scope -Reinstall -InputObject -DestinationPath [partially implemented] -NoClobber -IgnoreDifferentPublisher -TrustRepository -Force [there hasn’t been a need for force yet since the things you would force aren’t implemented] -Quiet -AcceptLicense -PassThru Update-PSResource -Name -Version -Prerelease -Credential -Repository [Update should be discovering the repository from the xml metadata instead of from user input, this will be fixed in future releases] -InputObject -UpdateTo -Force -Quiet -AcceptLicense -PassThru Find-PSResource -Name -Type -Version – Prerelease -ModuleName -Tags -Repository -Credential -IncludeDependencies [Nothing] Uninstall-PSResource -Name -Version -PrereleaseOnly [Nothing] Save-PSResource -Name -Version -Prerelease -Repository -Credential -AsNupkg -Path -AcceptLicense Get-PSResource -Name -Version -Prerelease Register-PSResourceRepository -Name -URL -PSGallery -Credential [credential persistence has not been implemented yet so this parameter is not currently being passed to anything] -Trusted -Priority -Repositories -Proxy[for any proxies other than the default proxy] -ProxyCredential[see above regarding -Proxy] Unregister-PSResourceRepository -Name [Nothing] Get-PSResourceRepository -Name -URL -Credential -Trusted -Priority -Repositories -Proxy [for any proxies other than the default proxy] -ProxyCredential [see above regarding -Proxy]

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

, and 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 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 } }

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.

cmdlet which will create a template file. If the switch 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.

will download nupkgs that have a folder. The dependent native library in matching the current system runtime will be copied to the root of the destination specified. A can be used to explicitly retain the 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.

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