Forge Home

pwshlib

pdk
supported
Provide library code for interoperating with PowerShell.

535,648 downloads

47,581 latest version

5.0 quality score

Version information

  • 0.10.1 (latest)
  • 0.10.0
  • 0.9.0
  • 0.8.0
  • 0.7.4
  • 0.7.3
  • 0.7.2
  • 0.7.1
  • 0.7.0
  • 0.6.3
  • 0.6.2
  • 0.6.1
  • 0.6.0
  • 0.5.1
  • 0.5.0
  • 0.4.1
  • 0.4.0
  • 0.3.0
  • 0.2.0
  • 0.1.0
released Aug 23rd 2021
This version is compatible with:
  • Puppet Enterprise 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x
  • Puppet >= 6.0.0 < 8.0.0
  • Windows
    ,
    CentOS
    ,
    Debian
    ,
    Fedora
    ,
    OSX
    ,
    RedHat
    ,
    Ubuntu

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'puppetlabs-pwshlib', '0.10.1'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add puppetlabs-pwshlib
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install puppetlabs-pwshlib --version 0.10.1

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

puppetlabs/pwshlib — version 0.10.1 Aug 23rd 2021

pwshlib

This module enables you to leverage the ruby-pwsh gem to execute PowerShell from within your Puppet providers without having to instantiate and tear down a PowerShell process for each command called. It supports Windows PowerShell as well as PowerShell Core - if you're running PowerShell v3+, this gem supports you.

The Manager class enables you to execute and interoperate with PowerShell from within ruby, leveraging the strengths of both languages as needed.

Prerequisites

Include puppetlabs-pwshlib as a dependency in your module and you can leverage it in your providers by using a requires statement, such as in this example:

require 'puppet/resource_api/simple_provider'
begin
  require 'ruby-pwsh'
rescue LoadError
  raise 'Could not load the "ruby-pwsh" library; is the dependency module puppetlabs-pwshlib installed in this environment?'
end

# Implementation for the foo type using the Resource API.
class Puppet::Provider::Foo::Foo < Puppet::ResourceApi::SimpleProvider
  def get(context)
    context.debug("PowerShell Path: #{Pwsh::Manager.powershell_path}")
    context.debug('Returning pre-canned example data')
    [
      {
        name: 'foo',
        ensure: 'present',
      },
      {
        name: 'bar',
        ensure: 'present',
      },
    ]
  end

  def create(context, name, should)
    context.notice("Creating '#{name}' with #{should.inspect}")
  end

  def update(context, name, should)
    context.notice("Updating '#{name}' with #{should.inspect}")
  end

  def delete(context, name)
    context.notice("Deleting '#{name}'")
  end
end

Aside from adding it as a dependency to your module metadata, you will probably also want to include it in your .fixtures.yml file:

fixtures:
  forge_modules:
    pwshlib: "puppetlabs/pwshlib"

Using the Library

Instantiating the manager can be done using some defaults:

# Instantiate the manager for Windows PowerShell, using the default path and arguments
# Note that this takes a few seconds to instantiate.
posh = Pwsh::Manager.instance(Pwsh::Manager.powershell_path, Pwsh::Manager.powershell_args)
# If you try to create another manager with the same arguments it will reuse the existing one.
ps = Pwsh::Manager.instance(Pwsh::Manager.powershell_path, Pwsh::Manager.powershell_args)
# Note that this time the return is very fast.
# We can also use the defaults for PowerShell Core, though these only work if PowerShell is
# installed to the default paths - if it is installed anywhere else, you'll need to specify
# the full path to the pwsh executable.
pwsh = Pwsh::Manager.instance(Pwsh::Manager.pwsh_path, Pwsh::Manager.pwsh_args)

Execution can be done with relatively little additional work - pass the command string you want executed:

# Instantiate the Manager:
posh = Pwsh::Manager.instance(Pwsh::Manager.powershell_path, Pwsh::Manager.powershell_args)
# Pretty print the output of `$PSVersionTable` to validate the version of PowerShell running
# Note that the output is a hash with a few different keys, including stdout.
Puppet.debug(posh.execute('$PSVersionTable'))
# Lets reduce the noise a little and retrieve just the version number:
# Note: We cast to a string because PSVersion is actually a Version object.
Puppet.debug(posh.execute('[String]$PSVersionTable.PSVersion'))
# We could store this output to a ruby variable if we wanted, for further use:
ps_version = posh.execute('[String]$PSVersionTable.PSVersion')[:stdout].strip
Puppet.debug("The PowerShell version of the currently running Manager is #{ps_version}")

For more information, please review the online reference documentation for the gem.