powershellget
Documentation
Table of Contents
Description
This is an auto-generated module, using the Puppet DSC Builder to vendor and expose the PowerShell module's DSC resources as Puppet resources. The functionality of this module comes entirely from the vendored PowerShell resources, which are pinned at v2.2.5. The PowerShell module describes itself like this:
PowerShell module with commands for discovering, installing, updating and publishing the PowerShell artifacts like Modules, DSC Resources, Role Capabilities and Scripts.
For information on troubleshooting to determine whether any encountered problems are with the Puppet wrapper or the DSC resource, see the troubleshooting section below.
Requirements
This module, like all auto-generated Puppetized DSC modules, relies on two important technologies in the Puppet stack: the Puppet Resource API and the puppetlabs/pwshlib Puppet module.
The Resource API provides a simplified option for writing types and providers and is responsible for how this module is structured. The Resource API ships inside of Puppet starting with version 6. While it is technically possible to add the Resource API functionality to Puppet 5.5.x, the DSC functionality has not been tested in this setup. For more information on the Resource API, review the documentation.
The module also depends on the pwshlib module. This Puppet module includes two important things: the ruby-pwsh library for running PowerShell code from ruby and the base provider for DSC resources, which this module leverages.
All of the actual work being done to call the DSC resources vendored with this module is in this file from the pwshlib module. This is important for troubleshooting and bug reporting, but doesn't impact your use of the module except that the end result will be that nothing works, as the dependency is not installed alongside this module!
Usage
You can specify any of the DSC resources from this module like a normal Puppet resource in your manifests. The examples below use DSC resources from from the PowerShellGet repository, regardless of what module you're looking at here; the syntax, not the specifics, is what's important.
For reference documentation about the DSC resources exposed in this module, see the Reference Forge tab, or the REFERENCE.md file.
# Include a meaningful title for your resource declaration
dsc_psrepository { 'Add team module repo':
dsc_name => 'foo',
dsc_ensure => present,
# This location is nonsense, can be any valid folder on your
# machine or in a share, any location the SourceLocation param
# for the DSC resource will accept.
dsc_sourcelocation => 'C:\Program Files',
# You must always pass an enum fully lower-cased;
# Puppet is case sensitive even when PowerShell isn't
dsc_installationpolicy => untrusted,
}
dsc_psrepository { 'Trust public gallery':
dsc_name => 'PSGallery',
dsc_ensure => present,
dsc_installationpolicy => trusted,
}
dsc_psmodule { 'Make Ruby manageable via uru':
dsc_name => 'RubyInstaller',
dsc_ensure => present,
}
For more information about using a built module, check out our narrative documentation.
Properties
Note that the only properties specified in a resource declaration which are passed to Invoke-Dsc are all prepended with dsc.
If a property does _not start with dsc_ it is used to control how Puppet interacts with DSC/other Puppet resources - for example,
specifying a unique name for the resource for Puppet to distinguish between declarations or Puppet metaparameters (notifies,
before, etc).
Troubleshooting
In general, there are three broad categories of problems:
- Problems with the way the underlying DSC resource works.
- Problems with the type definition, where you can't specify a valid set of properties for the DSC resource
- Problems with calling the underlying DSC resource - the parameters aren't being passed correctly or the resource can't be found
Unfortunately, problems with the way the underlying DSC resource works are something we can't help directly with. You'll need to file an issue with the upstream maintainers for the PowerShell module.
Problems with the type definition are when a value that should be valid according to the DSC resource's documentation and code is not accepted by the Puppet wrapper. If and when you run across one of these, please file an issue with the Puppet DSC Builder; this is where the conversion happens and once we know of a problem we can fix it and regenerate the Puppet modules. To help us identify the issue, please specify the DSC module, version, resource, property and values that are giving you issues. Once a fix is available we will regenerate and release updated versions of this Puppet wrapper.
Problems with calling the underlying DSC resource become apparent by comparing <value passed in in puppet>
with <value received by DSC>
.
In this case, please file an issue with the puppetlabs/pwshlib module, which is where the DSC base provider actually lives.
We'll investigate and prioritize a fix and update the puppetlabs/pwshlib module.
Updating to the pwshlib version with the fix will immediately take advantage of the improved functionality without waiting for this module to be reconverted and published.
For specific information on troubleshooting a generated module, check the troubleshooting guide for the puppet.dsc module.
Known Limitations
Currently, because of the way Puppet caches files on agents, use of the legacy puppetlabs-dsc
module is not compatible with this or any auto-generated DSC module.
Inclusion of both will lead to pluginsync conflicts.
Reference
Table of Contents
Resource types
dsc_psmodule
: The DSC PSModule resource type. Automatically generated from version 2.2.5dsc_psrepository
: The DSC PSRepository resource type. Automatically generated from version 2.2.5
Resource types
dsc_psmodule
The DSC PSModule resource type. Automatically generated from version 2.2.5
Properties
The following properties are available in the dsc_psmodule
type.
dsc_allowclobber
Data type: Optional[Boolean]
dsc_author
Data type: Optional[String]
dsc_description
Data type: Optional[String]
dsc_ensure
Data type: Optional[Enum['Present', 'Absent']]
dsc_guid
Data type: Optional[String]
dsc_installationpolicy
Data type: Optional[Enum['Trusted', 'Untrusted']]
dsc_installedversion
Data type: Optional[String]
dsc_maximumversion
Data type: Optional[String]
dsc_minimumversion
Data type: Optional[String]
dsc_modulebase
Data type: Optional[String]
dsc_moduletype
Data type: Optional[String]
dsc_repository
Data type: Optional[String]
dsc_requiredversion
Data type: Optional[String]
dsc_skippublishercheck
Data type: Optional[Boolean]
Parameters
The following parameters are available in the dsc_psmodule
type.
dsc_force
Data type: Optional[Boolean]
dsc_name
namevar
Data type: String
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
name
namevar
Data type: String
Description of the purpose for this resource declaration.
dsc_psrepository
The DSC PSRepository resource type. Automatically generated from version 2.2.5
Properties
The following properties are available in the dsc_psrepository
type.
dsc_ensure
Data type: Optional[Enum['Present', 'Absent']]
dsc_installationpolicy
Data type: Optional[Enum['Trusted', 'Untrusted']]
dsc_packagemanagementprovider
Data type: Optional[String]
dsc_publishlocation
Data type: Optional[String]
dsc_registered
Data type: Optional[Boolean]
dsc_scriptpublishlocation
Data type: Optional[String]
dsc_scriptsourcelocation
Data type: Optional[String]
dsc_sourcelocation
Data type: Optional[String]
dsc_trusted
Data type: Optional[Boolean]
Parameters
The following parameters are available in the dsc_psrepository
type.
dsc_name
namevar
Data type: String
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
name
namevar
Data type: String
Description of the purpose for this resource declaration.
2.2.5
- Security patch for code injection bug
2.2.4.1
- Remove catalog file
2.2.3
- Update
HelpInfoUri
to point to the latest content (#560) - Improve discovery of usable nuget.exe binary (Thanks bwright86!) (#558)
2.2.2
Bug Fix
- Update casing of DscResources output
2.2.1
Bug Fix
- Allow DscResources to work on case sensitive platforms (#521)
- Fix for failure to return credential provider when using private feeds (#521)
2.2
Bug Fix
- Fix for prompting for credentials when passing in -Credential parameter when using Register-PSRepository
2.1.5
New Features
- Add and remove nuget based repositories as a nuget source when nuget client tool is installed (#498)
Bug Fix
- Fix for 'Failed to publish module' error thrown when publishing modules (#497)
2.1.4
- Fixed hang while publishing some packages (#478)
2.1.3
New Features
- Added -Scope parameter to Update-Module (Thanks @lwajswaj!) (#471)
- Added -Exclude parameter to Publish-Module (Thanks @Benny1007!) (#191)
- Added -SkipAutomaticTags parameter to Publish-Module (Thanks @awickham10!) (#452)
Bug Fix
- Fixed issue with finding modules using macOS and .NET Core 3.0
2.1.2
New Feature
- Added support for registering repositories with special characters
2.1.1
- Fix DSC resource folder structure
2.1.0
Breaking Change
- Default installation scope for Update-Module and Update-Script has changed to match Install-Module and Install-Script. For Windows PowerShell (version 5.1 or below), the default scope is AllUsers when running in an elevated session, and CurrentUser at all other times. For PowerShell version 6.0.0 and above, the default installation scope is always CurrentUser. (#421)
Bug Fixes
- Update-ModuleManifest no longer clears FunctionsToExport, AliasesToExport, nor NestModules (#415 & #425) (Thanks @pougetat and @tnieto88!)
- Update-Module no longer changes repository URL (#407)
- Update-ModuleManifest no longer preprends 'PSGet_' to module name (#403) (Thanks @ThePoShWolf)
- Update-ModuleManifest now throws error and fails to update when provided invalid entries (#398) (Thanks @pougetat!)
- Ignore files no longer being included when uploading modules (#396)
New Features
- New DSC resource, PSRepository (#426) (Thanks @johlju!)
- Piping of PS respositories (#420)
- utf8 support for .nuspec (#419)
2.0.4
Bug Fix
- Remove PSGallery availability checks (#374)
2.0.3
Bug fixes and Improvements
- Fix CommandAlreadyAvailable error for PackageManagement module (#333)
- Remove trailing whitespace when value is not provided for Get-PSScriptInfoString (#337) (Thanks @thomasrayner)
- Expanded aliases for improved readability (#338) (Thanks @lazywinadmin)
- Improvements for Catalog tests (#343)
- Fix Update-ScriptInfoFile to preserve PrivateData (#346) (Thanks @tnieto88)
- Import modules with many commands faster (#351)
New Features
- Tab completion for -Repository parameter (#339) and for Publish-Module -Name (#359) (Thanks @matt9ucci)
2.0.1
Bug fixes
- Resolved Publish-Module doesn't report error but fails to publish module (#316)
- Resolved CommandAlreadyAvailable error while installing the latest version of PackageManagement module (#333)
2.0.0
Breaking Change
- Default installation scope for Install-Module, Install-Script, and Install-Package has changed. For Windows PowerShell (version 5.1 or below), the default scope is AllUsers when running in an elevated session, and CurrentUser at all other times. For PowerShell version 6.0.0 and above, the default installation scope is always CurrentUser.
1.6.7
Bug fixes
- Resolved Install/Save-Module error in PSCore 6.1.0-preview.4 on Ubuntu 18.04 OS (WSL/Azure) (#313)
- Updated error message in Save-Module cmdlet when the specified path is not accessible (#313)
- Added few additional verbose messages (#313)
1.6.6
Dependency Updates
- Add dependency on version 4.1.0 or newer of NuGet.exe
- Update NuGet.exe bootstrap URL to https://aka.ms/psget-nugetexe
Build and Code Cleanup Improvements
- Improved error handling in network connectivity tests.
Bug fixes
- Change Update-ModuleManifest so that prefix is not added to CmdletsToExport.
- Change Update-ModuleManifest so that parameters will not reset to default values.
- Specify AllowPrereleseVersions provider option only when AllowPrerelease is specified on the PowerShellGet cmdlets.
1.6.5
New features
- Allow Pester/PSReadline installation when signed by non-Microsoft certificate (#258)
- Whitelist installation of non-Microsoft signed Pester and PSReadline over Microsoft signed Pester and PSReadline.
Build and Code Cleanup Improvements
-
Splitting of functions (#229) (Thanks @Benny1007)
- Moves private functions into respective private folder.
- Moves public functions as defined in PSModule.psd1 into respective public folder.
- Removes all functions from PSModule.psm1 file.
- Dot sources the functions from PSModule.psm1 file.
- Uses Export-ModuleMember to export the public functions from PSModule.psm1 file.
-
Add build step to construct a single .psm1 file (#242) (Thanks @Benny1007)
- Merged public and private functions into one .psm1 file to increase load time performance.
Bug fixes
- Fix null parameter error caused by MinimumVersion in Publish-PackageUtility (#201)
- Change .ExternalHelp link from PSGet.psm1-help.xml to PSModule-help.xml in PSModule.psm1 file (#215)
- Change Publish-* to allow version comparison instead of string comparison (#219)
- Ensure Get-InstalledScript -RequiredVersion works when versions have a leading 0 (#260)
- Add positional path to Save-Module and Save-Script (#264, #266)
- Ensure that Get-AuthenticodePublisher verifies publisher and that installing or updating a module checks for approprite catalog signature (#272)
- Update HelpInfoURI to 'http://go.microsoft.com/fwlink/?linkid=855963' (#274)
1.6.0
New features
-
Prerelease Version Support (#185)
- Implemented prerelease versions functionality in PowerShellGet cmdlets.
- Enables publishing, discovering, and installing the prerelease versions of modules and scripts from the PowerShell Gallery.
- Documentation
-
Enabled publish cmdlets on PWSH and Nano Server (#196)
- Dotnet command version 2.0.0 or newer should be installed by the user prior to using the publish cmdlets on PWSH and Windows Nano Server.
- Users can install the dotnet command by following the instructions specified at https://aka.ms/dotnet-install-script.
- On Windows, users can install the dotnet command by running Invoke-WebRequest -Uri 'https://dot.net/v1/dotnet-install.ps1' -OutFile '.\dotnet-install.ps1'; & '.\dotnet-install.ps1' -Channel Current -Version '2.0.0'
- Publish cmdlets on Windows PowerShell supports using the dotnet command for publishing operations.
Breaking Change
- PWSH: Changed the installation location of AllUsers scope to the parent of $PSHOME instead of $PSHOME. It is the SHARED_MODULES folder on PWSH.
Bug fixes
- Update HelpInfoURI to 'https://go.microsoft.com/fwlink/?linkid=855963' (#195)
- Ensure MyDocumentsPSPath path is correct (#179) (Thanks @lwsrbrts)
1.5.0.0
New features
-
Added support for modules requiring license acceptance (#150)
-
Added version for REQUIREDSCRIPTS (#162)
- Enabled following scenarios for REQUIREDSCRIPTS
- [1.0] - RequiredVersion
- [1.0,2.0] - Min and Max Version
- (,1.0] - Max Version
- 1.0 - Min Version
- Enabled following scenarios for REQUIREDSCRIPTS
Bug fixes
- Fixed empty version value in nuspec (#157)
1.1.3.2
- Disabled PowerShellGet Telemetry on PS Core as PowerShell Telemetry APIs got removed in PowerShell Core beta builds. (#153)
- Fixed for DateTime format serialization issue. (#141)
- Update-ModuleManifest should add ExternalModuleDependencies value as a collection. (#129)
1.1.3.1
New features
- Added
PrivateData
field to ScriptFileInfo. (#119)
Bug fixes
1.1.2.0
Bug fixes
1.1.1.0
Bug fixes
1.1.0.0
- Initial release from GitHub.
- PowerShellCore support.
For full history of release notes see changelog:
https://github.com/PowerShell/PowerShellGet/blob/master/CHANGELOG.md
Dependencies
- puppetlabs/pwshlib (>= 0.7.0 < 2.0.0)