PowerShellGet 3.0 Preview 1

[Server Man]

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

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

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 -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).
• 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 = "PowerShell Gallery | Home" 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": "PowerShell Gallery | Home", "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.


Please note that PowerShell/PowerShellGet now represents the codebase for PowerShellGet 3.0. If you are looking for the source code, or issues related to previous versions of PowerShellGet, use PowerShell/PowerShellGetV2.

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


The post PowerShellGet 3.0 Preview 1 appeared first on PowerShell.

Continue reading...