ruby-pwsh 0.4.1 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fcc279675091bc4fcf7b31a7f309561c49b14352895424f72ca9170ffd51de3
-  data.tar.gz: 2c1160616d59bc30f1a641469617e0b941e610bf48e8c640a1de2a95df66778c
+  metadata.gz: bde547f250bf8294f79418a4f2bdb085745ca28ccf9063ad5e8f9ebd64d65e06
+  data.tar.gz: 5b8a638232f9b385dec03c585dbd499b91c04df1d3a3e08fbab895668fea4760
 SHA512:
-  metadata.gz: f957369ca4ed3b5932c843195bd9ec20614dd7211b8f0fd1e1ed76833aa8912d897a5341d605c89b95e7b76a9ba623c3064709e2ed1182415dbb907285d61dbd
-  data.tar.gz: 7508304850d8663c31f8ce420accf3a3007e594176365199ddb910e50a383ab7dc2b7e17911213c3fc5cea66eafcfb4ae89b7554f03b47df94fcd81483cad056
+  metadata.gz: 245d16db7ea15ff1d7fab3b23ddfb6eb13934062126043c0ec1cc9d3b824e2fe1635ec39b89f352925d8022fdc1ab0b140d085ba60631959302c5960bdd68080
+  data.tar.gz: 7e2f20f08be81c6b72bcd8bd96736ab99cf4b8ebc4d7c0e1eaca5ce6906356be2c9fd6c459cc2ebdb2c704c024996f4214312b148191ce7959fa0318e7282a00

data/.rubocop.yml

@@ -1,3 +1,5 @@
+Gemspec/RequiredRubyVersion:
+  Enabled: false
 Layout/EndOfLine:
   Description: Don't enforce CRLF on Windows.
   Enabled: false
@@ -28,4 +30,12 @@ Naming/FileName:
 Style/RescueStandardError:
   Enabled: false
 Style/ExpandPathArguments:
-  Enabled: false
+  Enabled: false
+Style/Documentation:
+  Enabled: false
+Style/ClassAndModuleChildren:
+  Exclude:
+    - lib/puppet/provider/dsc_base_provider/dsc_base_provider.rb
+Style/ClassVars:
+  Exclude:
+    - lib/puppet/provider/dsc_base_provider/dsc_base_provider.rb

data/.travis.yml

@@ -19,6 +19,7 @@ script:
   - 'bundle exec rake $CHECK'
 rvm:
   - 2.5.1
+  - 2.7
 matrix:
   include:
   - env: CHECK="rubocop"

data/CHANGELOG.md

@@ -2,7 +2,55 @@
 
 All notable changes to this project will be documented in this file.The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org).
 
-## [0.4.1](https://github.com/puppetlabs/ruby-pwsh/tree/0.4.1) (2020-02-12)
+## [0.6.2](https://github.com/puppetlabs/ruby-pwsh/tree/0.6.2) (2020-12-09)
+
+[Full Changelog](https://github.com/puppetlabs/ruby-pwsh/compare/0.6.1...0.6.2)
+
+### Fixed
+
+- \(MAINT\) Ensure parameters are canonicalized [\#75](https://github.com/puppetlabs/ruby-pwsh/pull/75) ([michaeltlombardi](https://github.com/michaeltlombardi))
+
+## [0.6.1](https://github.com/puppetlabs/ruby-pwsh/tree/0.6.1) (2020-11-25)
+
+[Full Changelog](https://github.com/puppetlabs/ruby-pwsh/compare/0.6.0...0.6.1)
+
+### Fixed
+
+- \(maint\) - Removal of inappropriate terminology [\#70](https://github.com/puppetlabs/ruby-pwsh/pull/70) ([pmcmaw](https://github.com/pmcmaw))
+- \(Maint\) Fix ensurability in the dsc base provider [\#69](https://github.com/puppetlabs/ruby-pwsh/pull/69) ([michaeltlombardi](https://github.com/michaeltlombardi))
+
+## [0.6.0](https://github.com/puppetlabs/ruby-pwsh/tree/0.6.0) (2020-11-24)
+
+[Full Changelog](https://github.com/puppetlabs/ruby-pwsh/compare/0.5.1...0.6.0)
+
+### Added
+
+- \(GH-81\) Handle parameters in the dsc base provider [\#62](https://github.com/puppetlabs/ruby-pwsh/pull/62) ([michaeltlombardi](https://github.com/michaeltlombardi))
+- \(GH-74\) Remove special handling for ensure in the dsc base provider [\#61](https://github.com/puppetlabs/ruby-pwsh/pull/61) ([michaeltlombardi](https://github.com/michaeltlombardi))
+- \(GH-59\) Refactor away from Simple Provider [\#60](https://github.com/puppetlabs/ruby-pwsh/pull/60) ([michaeltlombardi](https://github.com/michaeltlombardi))
+
+### Fixed
+
+- \(GH-57\) Handle datetimes in dsc [\#58](https://github.com/puppetlabs/ruby-pwsh/pull/58) ([michaeltlombardi](https://github.com/michaeltlombardi))
+- \(GH-55\) Handle intentionally empty arrays [\#56](https://github.com/puppetlabs/ruby-pwsh/pull/56) ([michaeltlombardi](https://github.com/michaeltlombardi))
+
+## [0.5.1](https://github.com/puppetlabs/ruby-pwsh/tree/0.5.1) (2020-09-25)
+
+[Full Changelog](https://github.com/puppetlabs/ruby-pwsh/compare/0.5.0...0.5.1)
+
+### Fixed
+
+- \(MAINT\) Ensure dsc provider finds dsc resources during agent run [\#45](https://github.com/puppetlabs/ruby-pwsh/pull/45) ([michaeltlombardi](https://github.com/michaeltlombardi))
+
+## [0.5.0](https://github.com/puppetlabs/ruby-pwsh/tree/0.5.0) (2020-08-20)
+
+[Full Changelog](https://github.com/puppetlabs/ruby-pwsh/compare/0.4.1...0.5.0)
+
+### Added
+
+- \(IAC-1045\) Add the DSC base Puppet provider to pwshlib [\#39](https://github.com/puppetlabs/ruby-pwsh/pull/39) ([michaeltlombardi](https://github.com/michaeltlombardi))
+
+## [0.4.1](https://github.com/puppetlabs/ruby-pwsh/tree/0.4.1) (2020-02-13)
 
 [Full Changelog](https://github.com/puppetlabs/ruby-pwsh/compare/0.4.0...0.4.1)
 
@@ -16,7 +64,7 @@ All notable changes to this project will be documented in this file.The format i
 
 ### Added
 
-- \(MODULES-10389\) Add puppet feature for dependent modules to leverage [\#20](https://github.com/puppetlabs/ruby-pwsh/pull/20) ([cmccrisken-puppet](https://github.com/cmccrisken-puppet))
+- \(MODULES-10389\) Add puppet feature for dependent modules to leverage [\#20](https://github.com/puppetlabs/ruby-pwsh/pull/20) ([sanfrancrisko](https://github.com/sanfrancrisko))
 
 ## [0.3.0](https://github.com/puppetlabs/ruby-pwsh/tree/0.3.0) (2019-12-04)
 
@@ -41,4 +89,4 @@ All notable changes to this project will be documented in this file.The format i
 
 
 
-\* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/skywinder/Github-Changelog-Generator)*
+\* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/github-changelog-generator/github-changelog-generator)*

data/CONTRIBUTING.md

@@ -79,7 +79,7 @@ process as easy as possible.
 
 2.  Sending your patches
 
-    To submit your changes via a GitHub pull request, we _highly_ recommend that you have them on a topic branch, instead of directly on "master".
+    To submit your changes via a GitHub pull request, we _highly_ recommend that you have them on a topic branch, instead of directly on "main".
     It makes things much easier to keep track of, especially if you decide to work on another thing before your first change is merged in.
 
     GitHub has some pretty good [general documentation](http://help.github.com/) on using their site.

data/Gemfile

@@ -17,25 +17,20 @@ group :test do
 end
 
 group :development do
-  # TODO: Use gem instead of git. Section mapping is merged into master, but not yet released
-  gem 'github_changelog_generator', git: 'https://github.com/skywinder/github-changelog-generator.git', ref: '20ee04ba1234e9e83eb2ffb5056e23d641c7a018'
+  gem 'github_changelog_generator', '~> 1.15' if Gem::Version.new(RUBY_VERSION.dup) >= Gem::Version.new('2.3.0')
   gem 'yard'
 end
 
 group :puppet do
   gem 'pdk', '~> 1.0'
+  gem 'puppet'
 end
 
 group :pry do
   gem 'fuubar'
 
-  if RUBY_VERSION == '1.8.7'
-    gem 'debugger'
-  elsif RUBY_VERSION =~ /^2\.[01]/
-    gem 'byebug', '~> 9.0.0'
+  if Gem::Version.new(RUBY_VERSION.dup) >= Gem::Version.new('2.4.0')
     gem 'pry-byebug'
-  elsif RUBY_VERSION =~ /^2\.[23456789]/
-    gem 'pry-byebug' # rubocop:disable Bundler/DuplicatedGem
   else
     gem 'pry-debugger'
   end

data/README.md

@@ -70,4 +70,50 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org). -->
 
+## Releasing the Gem and Puppet Module
+
+Steps to release an update to the gem and module include:
+
+1. Ensure that the release branch is up to date with the main:
+   ```bash
+   git push upstream upstream/main:release --force
+   ```
+1. Checkout a new working branch for the release prep (where xyz is the appropriate version, sans periods):
+   ```bash
+   git checkout -b maint/release/prep-xyz upstream/release
+   ```
+1. Update the version in `lib/pwsh/version.rb` and `metadata.json` to the appropriate version for the new release.
+1. Run the changelog update task (make sure to verify the changelog, correctly tagging PRs as needed):
+   ```bash
+   bundle exec rake changelog
+   ```
+1. Commit your changes with a short, sensible commit message, like:
+   ```text
+   git add lib/pwsh/version.rb
+   git add metadata.json
+   git add CHANGELOG.md
+   git commit -m '(MAINT) Prep for x.y.z release'
+   ```
+1. Push your changes and submit a pull request for review _against the **release** branch_:
+   ```bash
+   git push -u origin maint/release/prep-xyz
+   ```
+1. Ensure tests pass and the code is merged to `release`.
+1. Grab the commit hash from the merge commit on release, use that as the tag for the version (replacing `x.y.z` with the appropriate version and  `commithash` with the relevant one), then push the tags to upstream:
+   ```bash
+   bundle exec rake tag['x.y.z', 'commithash']
+   ```
+1. Build the Ruby gem and publish:
+   ```bash
+   bundle exec rake build
+   bundle exec rake push['ruby-pwsh-x.y.z.gem']
+   ```
+1. Verify that the correct version now exists on [RubyGems](https://rubygems.org/search?query=ruby-pwsh)
+1. Build the Puppet module:
+   ```bash
+   bundle exec rake build_module
+   ```
+1. Publish the updated module version (found in the `pkg` folder) to [the Forge](https://forge.puppet.com/puppetlabs/pwshlib).
+1. Submit the [mergeback PR from the release branch to main](https://github.com/puppetlabs/ruby-pwsh/compare/main...release).
+
 ## Known Issues

data/appveyor.yml

@@ -0,0 +1,38 @@
+---
+version: 1.1.x.{build}
+branches:
+  only:
+    - main
+    - release
+clone_depth: 10
+environment:
+  matrix:
+    -
+      RUBY_VERSION: 25-x64
+      CHECK: rubocop
+    -
+      RUBY_VERSION: 25
+      CHECK: spec
+      COVERAGE: yes
+matrix:
+  fast_finish: true
+install:
+  - set PATH=C:\Ruby%RUBY_VERSION%\bin;%PATH%
+  - bundle install --jobs 4 --retry 2
+  - type Gemfile.lock
+build: off
+build_script:
+  - dir .
+test_script:
+  - ruby -v
+  - gem -v
+  - bundle -v
+  - pwsh -v
+  - bundle exec rake %CHECK%
+notifications:
+  - provider: Email
+    to:
+      - nobody@nowhere.com
+    on_build_success: false
+    on_build_failure: false
+    on_build_status_changed: false

data/lib/puppet/provider/dsc_base_provider/dsc_base_provider.rb

@@ -0,0 +1,758 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'ruby-pwsh'
+require 'pathname'
+require 'json'
+
+class Puppet::Provider::DscBaseProvider
+  # Initializes the provider, preparing the class variables which cache:
+  # - the canonicalized resources across calls
+  # - query results
+  # - logon failures
+  def initialize
+    @@cached_canonicalized_resource = []
+    @@cached_query_results = []
+    @@logon_failures = []
+    super
+  end
+
+  # Look through a cache to retrieve the hashes specified, if they have been cached.
+  # Does so by seeing if each of the specified hashes is a subset of any of the hashes
+  # in the cache, so {foo: 1, bar: 2} would return if {foo: 1} was the search hash.
+  #
+  # @param cache [Array] the class variable containing cached hashes to search through
+  # @param hashes [Array] the list of hashes to search the cache for
+  # @return [Array] an array containing the matching hashes for the search condition, if any
+  def fetch_cached_hashes(cache, hashes)
+    cache.reject do |item|
+      matching_hash = hashes.select { |hash| (item.to_a - hash.to_a).empty? || (hash.to_a - item.to_a).empty? }
+      matching_hash.empty?
+    end.flatten
+  end
+
+  # Implements the canonicalize feature of the Resource API; this method is called first against any resources
+  # defined in the manifest, then again to conform the results from a get call. The method attempts to retrieve
+  # the DSC resource from the machine; if the resource is found, this method then compares the downcased values
+  # of the two hashes, overwriting the manifest value with the discovered one if they are case insensitively
+  # equivalent; this enables case insensitive but preserving behavior where a manifest declaration of a path as
+  # "c:/foo/bar" if discovered on disk as "C:\Foo\Bar" will canonicalize to the latter and prevent any flapping.
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param resources [Hash] the hash of the resource to canonicalize from either manifest or invocation
+  # @return [Hash] returns a hash representing the current state of the object, if it exists
+  def canonicalize(context, resources)
+    canonicalized_resources = []
+    resources.collect do |r|
+      if fetch_cached_hashes(@@cached_canonicalized_resource, [r]).empty?
+        canonicalized = invoke_get_method(context, r)
+        if canonicalized.nil?
+          canonicalized = r.dup
+          @@cached_canonicalized_resource << r.dup
+        else
+          parameters = r.select { |name, _properties| parameter_attributes(context).include?(name) }
+          canonicalized.merge!(parameters)
+          canonicalized[:name] = r[:name]
+          if r[:dsc_psdscrunascredential].nil?
+            canonicalized.delete(:dsc_psdscrunascredential)
+          else
+            canonicalized[:dsc_psdscrunascredential] = r[:dsc_psdscrunascredential]
+          end
+          downcased_result = recursively_downcase(canonicalized)
+          downcased_resource = recursively_downcase(r)
+          downcased_result.each do |key, value|
+            canonicalized[key] = r[key] unless downcased_resource[key] == value
+            canonicalized.delete(key) unless downcased_resource.keys.include?(key)
+          end
+          # Cache the actually canonicalized resource separately
+          @@cached_canonicalized_resource << canonicalized.dup
+        end
+      else
+        canonicalized = r
+      end
+      canonicalized_resources << canonicalized
+    end
+    context.debug("Canonicalized Resources: #{canonicalized_resources}")
+    canonicalized_resources
+  end
+
+  # Attempts to retrieve an instance of the DSC resource, invoking the `Get` method and passing any
+  # namevars as the Properties to Invoke-DscResource. The result object, if any, is compared to the
+  # specified properties in the Puppet Resource to decide whether it needs to be created, updated,
+  # deleted, or whether it is in the desired state.
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param names [Hash] the hash of namevar properties and their values to use to get the resource
+  # @return [Hash] returns a hash representing the current state of the object, if it exists
+  def get(context, names = nil)
+    # Relies on the get_simple_filter feature to pass the namevars
+    # as an array containing the namevar parameters as a hash.
+    # This hash is functionally the same as a should hash as
+    # passed to the should_to_resource method.
+    context.debug('Collecting data from the DSC Resource')
+
+    # If the resource has already been queried, do not bother querying for it again
+    cached_results = fetch_cached_hashes(@@cached_query_results, names)
+    return cached_results unless cached_results.empty?
+
+    if @@cached_canonicalized_resource.empty?
+      mandatory_properties = {}
+    else
+      canonicalized_resource = @@cached_canonicalized_resource[0].dup
+      mandatory_properties = canonicalized_resource.select do |attribute, _value|
+        (mandatory_get_attributes(context) - namevar_attributes(context)).include?(attribute)
+      end
+      # If dsc_psdscrunascredential was specified, re-add it here.
+      mandatory_properties[:dsc_psdscrunascredential] = canonicalized_resource[:dsc_psdscrunascredential] if canonicalized_resource.keys.include?(:dsc_psdscrunascredential)
+    end
+    names.collect do |name|
+      name = { name: name } if name.is_a? String
+      invoke_get_method(context, name.merge(mandatory_properties))
+    end
+  end
+
+  # Determines whether a resource is ensurable and which message to write (create, update, or delete),
+  # then passes the appropriate values along to the various sub-methods which themselves call the Set
+  # method of Invoke-DscResource. Implementation borrowed directly from the Resource API Simple Provider
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param changes [Hash] the hash of whose key is the name_hash and value is the is and should hashes
+  def set(context, changes)
+    changes.each do |name, change|
+      is = change.key?(:is) ? change[:is] : (get(context, [name]) || []).find { |r| r[:name] == name }
+      context.type.check_schema(is) unless change.key?(:is)
+
+      should = change[:should]
+
+      name_hash = if context.type.namevars.length > 1
+                    # pass a name_hash containing the values of all namevars
+                    name_hash = {}
+                    context.type.namevars.each do |namevar|
+                      name_hash[namevar] = change[:should][namevar]
+                    end
+                    name_hash
+                  else
+                    name
+                  end
+
+      # for compatibility sake, we use dsc_ensure instead of ensure, so context.type.ensurable? does not work
+      if context.type.attributes.key?(:dsc_ensure)
+        is = create_absent(:name, name) if is.nil?
+        should = create_absent(:name, name) if should.nil?
+
+        # HACK: If the DSC Resource is ensurable but doesn't report a default value
+        # for ensure, we assume it to be `Present` - this is the most common pattern.
+        should_ensure = should[:dsc_ensure].nil? ? 'Present' : should[:dsc_ensure].to_s
+        is_ensure = is[:dsc_ensure].to_s
+
+        if is_ensure == 'Absent' && should_ensure == 'Present'
+          context.creating(name) do
+            create(context, name_hash, should)
+          end
+        elsif is_ensure == 'Present' && should_ensure == 'Present'
+          context.updating(name) do
+            update(context, name_hash, should)
+          end
+        elsif is_ensure == 'Present' && should_ensure == 'Absent'
+          context.deleting(name) do
+            delete(context, name_hash)
+          end
+        end
+      else
+        context.updating(name) do
+          update(context, name_hash, should)
+        end
+      end
+    end
+  end
+
+  # Creates a hash with the name / name_hash and sets dsc_ensure to absent for comparison
+  # purposes; this handles cases where the resource isn't found on the node.
+  #
+  # @param namevar [Object] the name of the variable being used for the resource name
+  # @param title [Hash] the hash of namevar properties and their values
+  # @return [Hash] returns a hash representing the absent state of the resource
+  def create_absent(namevar, title)
+    result = if title.is_a? Hash
+               title.dup
+             else
+               { namevar => title }
+             end
+    result[:dsc_ensure] = 'Absent'
+    result
+  end
+
+  # Attempts to set an instance of the DSC resource, invoking the `Set` method and thinly wrapping
+  # the `invoke_set_method` method; whether this method, `update`, or `delete` is called is entirely
+  # up to the Resource API based on the results
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param name [String] the name of the resource being created
+  # @return [Hash] returns a hash indicating whether or not the resource is in the desired state, whether or not it requires a reboot, and any error messages captured.
+  def create(context, name, should)
+    context.debug("Creating '#{name}' with #{should.inspect}")
+    invoke_set_method(context, name, should)
+  end
+
+  # Attempts to set an instance of the DSC resource, invoking the `Set` method and thinly wrapping
+  # the `invoke_set_method` method; whether this method, `create`, or `delete` is called is entirely
+  # up to the Resource API based on the results
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param name [String] the name of the resource being created
+  # @return [Hash] returns a hash indicating whether or not the resource is in the desired state, whether or not it requires a reboot, and any error messages captured.
+  def update(context, name, should)
+    context.debug("Updating '#{name}' with #{should.inspect}")
+    invoke_set_method(context, name, should)
+  end
+
+  # Attempts to set an instance of the DSC resource, invoking the `Set` method and thinly wrapping
+  # the `invoke_set_method` method; whether this method, `create`, or `update` is called is entirely
+  # up to the Resource API based on the results
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param name [String] the name of the resource being created
+  # @return [Hash] returns a hash indicating whether or not the resource is in the desired state, whether or not it requires a reboot, and any error messages captured.
+  def delete(context, name)
+    context.debug("Deleting '#{name}'")
+    invoke_set_method(context, name, name.merge({ dsc_ensure: 'Absent' }))
+  end
+
+  # Invokes the `Get` method, passing the name_hash as the properties to use with `Invoke-DscResource`
+  # The PowerShell script returns a JSON representation of the DSC Resource's CIM Instance munged as
+  # best it can be for Ruby. Once that JSON is parsed into a hash this method further munges it to
+  # fit the expected property definitions. Finally, it returns the object for the Resource API to
+  # compare against and determine what future actions, if any, are needed.
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param name_hash [Hash] the hash of namevars to be passed as properties to `Invoke-DscResource`
+  # @return [Hash] returns a hash representing the DSC resource munged to the representation the Puppet Type expects
+  def invoke_get_method(context, name_hash)
+    context.debug("retrieving #{name_hash.inspect}")
+
+    # Do not bother running if the logon credentials won't work
+    return name_hash if !name_hash[:dsc_psdscrunascredential].nil? && logon_failed_already?(name_hash[:dsc_psdscrunascredential])
+
+    query_props = name_hash.select { |k, v| mandatory_get_attributes(context).include?(k) || (k == :dsc_psdscrunascredential && !v.nil?) }
+    resource = should_to_resource(query_props, context, 'get')
+    script_content = ps_script_content(resource)
+    context.debug("Script:\n #{redact_secrets(script_content)}")
+    output = ps_manager.execute(script_content)[:stdout]
+    context.err('Nothing returned') if output.nil?
+
+    data = JSON.parse(output)
+    context.debug("raw data received: #{data.inspect}")
+    error = data['errormessage']
+    unless error.nil?
+      # NB: We should have a way to stop processing this resource *now* without blowing up the whole Puppet run
+      # Raising an error stops processing but blows things up while context.err alerts but continues to process
+      if error =~ /Logon failure: the user has not been granted the requested logon type at this computer/
+        logon_error = "PSDscRunAsCredential account specified (#{name_hash[:dsc_psdscrunascredential]['user']}) does not have appropriate logon rights; are they an administrator?"
+        name_hash[:name].nil? ? context.err(logon_error) : context.err(name_hash[:name], logon_error)
+        @@logon_failures << name_hash[:dsc_psdscrunascredential].dup
+        # This is a hack to handle the query cache to prevent a second lookup
+        @@cached_query_results << name_hash # if fetch_cached_hashes(@@cached_query_results, [data]).empty?
+      else
+        context.err(error)
+      end
+      # Either way, something went wrong and we didn't get back a good result, so return nil
+      return nil
+    end
+    # DSC gives back information we don't care about; filter down to only
+    # those properties exposed in the type definition.
+    valid_attributes = context.type.attributes.keys.collect(&:to_s)
+    parameters = context.type.attributes.select { |_name, properties| [properties[:behaviour]].collect.include?(:parameter) }.keys.collect(&:to_s)
+    data.select! { |key, _value| valid_attributes.include?("dsc_#{key.downcase}") }
+    data.reject! { |key, _value| parameters.include?("dsc_#{key.downcase}") }
+    # Canonicalize the results to match the type definition representation;
+    # failure to do so will prevent the resource_api from comparing the result
+    # to the should hash retrieved from the resource definition in the manifest.
+    data.keys.each do |key| # rubocop:disable Style/HashEachMethods
+      type_key = "dsc_#{key.downcase}".to_sym
+      data[type_key] = data.delete(key)
+      camelcase_hash_keys!(data[type_key]) if data[type_key].is_a?(Enumerable)
+      # Convert DateTime back to appropriate type
+      data[type_key] = Puppet::Pops::Time::Timestamp.parse(data[type_key]) if context.type.attributes[type_key][:mof_type] =~ /DateTime/i
+      # PowerShell does not distinguish between a return of empty array/string
+      #  and null but Puppet does; revert to those values if specified.
+      if data[type_key].nil? && query_props.keys.include?(type_key) && query_props[type_key].is_a?(Array)
+        data[type_key] = query_props[type_key].empty? ? query_props[type_key] : []
+      end
+    end
+    # If a resource is found, it's present, so refill this Puppet-only key
+    data.merge!({ name: name_hash[:name] })
+
+    # Have to check for this to avoid a weird canonicalization warning
+    # The Resource API calls canonicalize against the current state which
+    # will lead to dsc_ensure being set to absent in the name_hash even if
+    # it was set to present in the manifest
+    name_hash_has_nil_keys = name_hash.select { |_k, v| v.nil? }.count.positive?
+    # We want to throw away all of the empty keys if and only if the manifest
+    # declaration is for an absent resource and the resource is actually absent
+    data.reject! { |_k, v| v.nil? } if data[:dsc_ensure] == 'Absent' && name_hash[:dsc_ensure] == 'Absent' && !name_hash_has_nil_keys
+
+    # Cache the query to prevent a second lookup
+    @@cached_query_results << data.dup if fetch_cached_hashes(@@cached_query_results, [data]).empty?
+    context.debug("Returned to Puppet as #{data}")
+    data
+  end
+
+  # Invokes the `Set` method, passing the should hash as the properties to use with `Invoke-DscResource`
+  # The PowerShell script returns a JSON hash with key-value pairs indicating whether or not the resource
+  # is in the desired state, whether or not it requires a reboot, and any error messages captured.
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param should [Hash] the desired state represented definition to pass as properties to Invoke-DscResource
+  # @return [Hash] returns a hash indicating whether or not the resource is in the desired state, whether or not it requires a reboot, and any error messages captured.
+  def invoke_set_method(context, name, should)
+    context.debug("Invoking Set Method for '#{name}' with #{should.inspect}")
+
+    # Do not bother running if the logon credentials won't work
+    return nil if !should[:dsc_psdscrunascredential].nil? && logon_failed_already?(should[:dsc_psdscrunascredential])
+
+    apply_props = should.select { |k, _v| k.to_s =~ /^dsc_/ }
+    resource = should_to_resource(apply_props, context, 'set')
+    script_content = ps_script_content(resource)
+    context.debug("Script:\n #{redact_secrets(script_content)}")
+
+    output = ps_manager.execute(script_content)[:stdout]
+    context.err('Nothing returned') if output.nil?
+
+    data = JSON.parse(output)
+    context.debug(data)
+
+    context.err(data['errormessage']) unless data['errormessage'].empty?
+    # TODO: Implement this functionality for notifying a DSC reboot?
+    # notify_reboot_pending if data['rebootrequired'] == true
+    data
+  end
+
+  # Converts a Puppet resource hash into a hash with the information needed to call Invoke-DscResource,
+  # including the desired state, the path to the PowerShell module containing the resources, the invoke
+  # method, and metadata about the DSC Resource and Puppet Type.
+  #
+  # @param should [Hash] A hash representing the desired state of the DSC resource as defined in Puppet
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param dsc_invoke_method [String] the method to pass to Invoke-DscResource: get, set, or test
+  # @return [Hash] a hash with the information needed to run `Invoke-DscResource`
+  def should_to_resource(should, context, dsc_invoke_method)
+    resource = {}
+    resource[:parameters] = {}
+    %i[name dscmeta_resource_friendly_name dscmeta_resource_name dscmeta_module_name dscmeta_module_version].each do |k|
+      resource[k] = context.type.definition[k]
+    end
+    should.each do |k, v|
+      # PSDscRunAsCredential is considered a namevar and will always be passed, even if nil
+      # To prevent flapping during runs, remove it from the resource definition unless specified
+      next if k == :dsc_psdscrunascredential && v.nil?
+
+      resource[:parameters][k] = {}
+      resource[:parameters][k][:value] = v
+      %i[mof_type mof_is_embedded].each do |ky|
+        resource[:parameters][k][ky] = context.type.definition[:attributes][k][ky]
+      end
+    end
+    resource[:dsc_invoke_method] = dsc_invoke_method
+
+    # Because Puppet adds all of the modules to the LOAD_PATH we can be sure that the appropriate module lives here during an apply;
+    # PROBLEM: This currently uses the downcased name, we need to capture the module name in the metadata I think.
+    # During a Puppet agent run, the code lives in the cache so we can use the file expansion to discover the correct folder.
+    root_module_path = $LOAD_PATH.select { |path| path.match?(%r{#{resource[:dscmeta_module_name].downcase}/lib}) }.first
+    resource[:vendored_modules_path] = if root_module_path.nil?
+                                         File.expand_path(Pathname.new(__FILE__).dirname + '../../../' + 'puppet_x/dsc_resources') # rubocop:disable Style/StringConcatenation
+                                       else
+                                         File.expand_path("#{root_module_path}/puppet_x/dsc_resources")
+                                       end
+    resource[:attributes] = nil
+    context.debug("should_to_resource: #{resource.inspect}")
+    resource
+  end
+
+  # Return a UUID with the dashes turned into underscores to enable the specifying of guaranteed-unique
+  # variables in the PowerShell script.
+  #
+  # @return [String] a uuid with underscores instead of dashes.
+  def random_variable_name
+    # PowerShell variables can't include dashes
+    SecureRandom.uuid.gsub('-', '_')
+  end
+
+  # Return a Hash containing all of the variables defined for instantiation as well as the Ruby hash for their
+  # properties so they can be matched and replaced as needed.
+  #
+  # @return [Hash] containing all instantiated variables and the properties that they define
+  def instantiated_variables
+    @@instantiated_variables ||= {}
+  end
+
+  # Clear the instantiated variables hash to be ready for the next run
+  def clear_instantiated_variables!
+    @@instantiated_variables = {}
+  end
+
+  # Return true if the specified credential hash has already failed to execute a DSC resource due to
+  # a logon error, as when the account is not an administrator on the machine; otherwise returns false.
+  #
+  # @param [Hash] a credential hash with a user and password keys where the password is a sensitive string
+  # @return [Bool] true if the credential_hash has already failed logon, false otherwise
+  def logon_failed_already?(credential_hash)
+    @@logon_failures.any? do  |failure_hash|
+      failure_hash['user'] == credential_hash['user'] && failure_hash['password'].unwrap == credential_hash['password'].unwrap
+    end
+  end
+
+  # Recursively transforms any enumerable, camelCasing any hash keys it finds
+  #
+  # @param enumerable [Enumerable] a string, array, hash, or other object to attempt to recursively downcase
+  # @return [Enumerable] returns the input object with hash keys recursively camelCased
+  def camelcase_hash_keys!(enumerable)
+    if enumerable.is_a?(Hash)
+      enumerable.keys.each do |key| # rubocop:disable Style/HashEachMethods
+        name = key.dup
+        name[0] = name[0].downcase
+        enumerable[name] = enumerable.delete(key)
+        camelcase_hash_keys!(enumerable[name]) if enumerable[name].is_a?(Enumerable)
+      end
+    else
+      enumerable.each { |item| camelcase_hash_keys!(item) if item.is_a?(Enumerable) }
+    end
+  end
+
+  # Recursively transforms any object, downcasing it to enable case insensitive comparisons
+  #
+  # @param object [Object] a string, array, hash, or other object to attempt to recursively downcase
+  # @return [Object] returns the input object recursively downcased
+  def recursively_downcase(object)
+    case object
+    when String
+      object.downcase
+    when Array
+      object.map { |item| recursively_downcase(item) }
+    when Hash
+      transformed = {}
+      object.transform_keys(&:downcase).each do |key, value|
+        transformed[key] = recursively_downcase(value)
+      end
+      transformed
+    else
+      object
+    end
+  end
+
+  # Parses the DSC resource type definition to retrieve the names of any attributes which are specified as mandatory for get operations
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @return [Array] returns an array of attribute names as symbols which are mandatory for get operations
+  def mandatory_get_attributes(context)
+    context.type.attributes.select { |_attribute, properties| properties[:mandatory_for_get] }.keys
+  end
+
+  # Parses the DSC resource type definition to retrieve the names of any attributes which are specified as mandatory for set operations
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @return [Array] returns an array of attribute names as symbols which are mandatory for set operations
+  def mandatory_set_attributes(context)
+    context.type.attributes.select { |_attribute, properties| properties[:mandatory_for_set] }.keys
+  end
+
+  # Parses the DSC resource type definition to retrieve the names of any attributes which are specified as namevars
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @return [Array] returns an array of attribute names as symbols which are namevars
+  def namevar_attributes(context)
+    context.type.attributes.select { |_attribute, properties| properties[:behaviour] == :namevar }.keys
+  end
+
+  # Parses the DSC resource type definition to retrieve the names of any attributes which are specified as parameters
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @return [Array] returns an array of attribute names as symbols which are parameters
+  def parameter_attributes(context)
+    context.type.attributes.select { |_name, properties| properties[:behaviour] == :parameter }.keys
+  end
+
+  # Look through a fully formatted string, replacing all instances where a value matches the formatted properties
+  # of an instantiated variable with references to the variable instead. This allows us to pass complex and nested
+  # CIM instances to the Invoke-DscResource parameter hash without constructing them *in* the hash.
+  #
+  # @param string [String] the string of text to search through for places an instantiated variable can be referenced
+  # @return [String] the string with references to instantiated variables instead of their properties
+  def interpolate_variables(string)
+    modified_string = string
+    # Always replace later-created variables first as they sometimes were built from earlier ones
+    instantiated_variables.reverse_each do |variable_name, ruby_definition|
+      modified_string = modified_string.gsub(format(ruby_definition), "$#{variable_name}")
+    end
+    modified_string
+  end
+
+  # Parses a resource definition (as from `should_to_resource`) for any properties which are PowerShell
+  # Credentials. As these values need to be serialized into PSCredential objects, return an array of
+  # PowerShell lines, each of which instantiates a variable which holds the value as a PSCredential.
+  # These credential variables can then be simply assigned in the parameter hash where needed.
+  #
+  # @param resource [Hash] a hash with the information needed to run `Invoke-DscResource`
+  # @return [String] An array of lines of PowerShell to instantiate PSCredentialObjects and store them in variables
+  def prepare_credentials(resource)
+    credentials_block = []
+    resource[:parameters].each do |_property_name, property_hash|
+      next unless property_hash[:mof_type] == 'PSCredential'
+      next if property_hash[:value].nil?
+
+      variable_name = random_variable_name
+      credential_hash = {
+        'user' => property_hash[:value]['user'],
+        'password' => escape_quotes(property_hash[:value]['password'].unwrap)
+      }
+      instantiated_variables.merge!(variable_name => credential_hash)
+      credentials_block << format_pscredential(variable_name, credential_hash)
+    end
+    credentials_block.join("\n")
+    credentials_block == [] ? '' : credentials_block
+  end
+
+  # Write a line of PowerShell which creates a PSCredential object and assigns it to a variable
+  #
+  # @param variable_name [String] the name of the Variable to assign the PSCredential object to
+  # @param credential_hash [Hash] the Properties which define the PSCredential Object
+  # @return [String] A line of PowerShell which defines the PSCredential object and stores it to a variable
+  def format_pscredential(variable_name, credential_hash)
+    "$#{variable_name} = New-PSCredential -User #{credential_hash['user']} -Password '#{credential_hash['password']}' # PuppetSensitive"
+  end
+
+  # Parses a resource definition (as from `should_to_resource`) for any properties which are CIM instances
+  # whether at the top level or nested inside of other CIM instances, and, where they are discovered, adds
+  # those objects to the instantiated_variables hash as well as returning a line of PowerShell code which
+  # will create the CIM object and store it in a variable. This then allows the CIM instances to be assigned
+  # by variable reference.
+  #
+  # @param resource [Hash] a hash with the information needed to run `Invoke-DscResource`
+  # @return [String] An array of lines of PowerShell to instantiate CIM Instances and store them in variables
+  def prepare_cim_instances(resource)
+    cim_instances_block = []
+    resource[:parameters].each do |_property_name, property_hash|
+      next unless property_hash[:mof_is_embedded]
+
+      # strip dsc_ from the beginning of the property name declaration
+      # name = property_name.to_s.gsub(/^dsc_/, '').to_sym
+      # Process nested CIM instances first as those neeed to be passed to higher-order
+      # instances and must therefore be declared before they must be referenced
+      cim_instance_hashes = nested_cim_instances(property_hash[:value]).flatten.reject(&:nil?)
+      # Sometimes the instances are an empty array
+      unless cim_instance_hashes.count.zero?
+        cim_instance_hashes.each do |instance|
+          variable_name = random_variable_name
+          instantiated_variables.merge!(variable_name => instance)
+          class_name = instance['cim_instance_type']
+          properties = instance.reject { |k, _v| k == 'cim_instance_type' }
+          cim_instances_block << format_ciminstance(variable_name, class_name, properties)
+        end
+      end
+      # We have to handle arrays of CIM instances slightly differently
+      if property_hash[:mof_type] =~ /\[\]$/
+        class_name = property_hash[:mof_type].gsub('[]', '')
+        property_hash[:value].each do |hash|
+          variable_name = random_variable_name
+          instantiated_variables.merge!(variable_name => hash)
+          cim_instances_block << format_ciminstance(variable_name, class_name, hash)
+        end
+      else
+        variable_name = random_variable_name
+        instantiated_variables.merge!(variable_name => property_hash[:value])
+        class_name = property_hash[:mof_type]
+        cim_instances_block << format_ciminstance(variable_name, class_name, property_hash[:value])
+      end
+    end
+    cim_instances_block == [] ? '' : cim_instances_block.join("\n")
+  end
+
+  # Recursively search for and return CIM instances nested in an enumerable
+  #
+  # @param enumerable [Enumerable] a hash or array which may contain CIM Instances
+  # @return [Hash] every discovered hash which does define a CIM Instance
+  def nested_cim_instances(enumerable)
+    enumerable.collect do |key, value|
+      if key.is_a?(Hash) && key.key?('cim_instance_type')
+        key
+        # TODO: Are there any cim instancees 3 levels deep, or only 2?
+        # if so, we should *also* keep searching and processing...
+      elsif key.is_a?(Enumerable)
+        nested_cim_instances(key)
+      elsif value.is_a?(Enumerable)
+        nested_cim_instances(value)
+      end
+    end
+  end
+
+  # Write a line of PowerShell which creates a CIM Instance and assigns it to a variable
+  #
+  # @param variable_name [String] the name of the Variable to assign the CIM Instance to
+  # @param class_name [String] the CIM Class to instantiate
+  # @param property_hash [Hash] the Properties which define the CIM Instance
+  # @return [String] A line of PowerShell which defines the CIM Instance and stores it to a variable
+  def format_ciminstance(variable_name, class_name, property_hash)
+    definition = "$#{variable_name} = New-CimInstance -ClientOnly -ClassName '#{class_name}' -Property #{format(property_hash)}"
+    # AWFUL HACK to make New-CimInstance happy ; it can't parse an array unless it's an array of Cim Instances
+    # definition = definition.gsub("@(@{'cim_instance_type'","[CimInstance[]]@(@{'cim_instance_type'")
+    # EVEN WORSE HACK - this one we can't even be sure it's a cim instance...
+    # but I don't _think_ anything but nested cim instances show up as hashes inside an array
+    definition = definition.gsub('@(@{', '[CimInstance[]]@(@{')
+    interpolate_variables(definition)
+  end
+
+  # Munge a resource definition (as from `should_to_resource`) into valid PowerShell which represents
+  # the `InvokeParams` hash which will be splatted to `Invoke-DscResource`, interpolating all previously
+  # defined variables into the hash.
+  #
+  # @param resource [Hash] a hash with the information needed to run `Invoke-DscResource`
+  # @return [String] A string representing the PowerShell definition of the InvokeParams hash
+  def invoke_params(resource)
+    params = {
+      Name: resource[:dscmeta_resource_friendly_name],
+      Method: resource[:dsc_invoke_method],
+      Property: {}
+    }
+    if resource.key?(:dscmeta_module_version)
+      params[:ModuleName] = {}
+      params[:ModuleName][:ModuleName] = "#{resource[:vendored_modules_path]}/#{resource[:dscmeta_module_name]}/#{resource[:dscmeta_module_name]}.psd1"
+      params[:ModuleName][:RequiredVersion] = resource[:dscmeta_module_version]
+    else
+      params[:ModuleName] = resource[:dscmeta_module_name]
+    end
+    resource[:parameters].each do |property_name, property_hash|
+      # strip dsc_ from the beginning of the property name declaration
+      name = property_name.to_s.gsub(/^dsc_/, '').to_sym
+      params[:Property][name] = case property_hash[:mof_type]
+                                when 'PSCredential'
+                                  # format can't unwrap Sensitive strings nested in arbitrary hashes/etc, so make
+                                  # the Credential hash interpolable as it will be replaced by a variable reference.
+                                  {
+                                    'user' => property_hash[:value]['user'],
+                                    'password' => escape_quotes(property_hash[:value]['password'].unwrap)
+                                  }
+                                when 'DateTime'
+                                  # These have to be handled specifically because they rely on the *Puppet* DateTime,
+                                  # not a generic ruby data type (and so can't go in the shared util in ruby-pwsh)
+                                  "[DateTime]#{property_hash[:value].format('%FT%T%z')}"
+                                else
+                                  property_hash[:value]
+                                end
+    end
+    params_block = interpolate_variables("$InvokeParams = #{format(params)}")
+    # Move the Apostrophe for DateTime declarations
+    params_block = params_block.gsub("'[DateTime]", "[DateTime]'")
+    # HACK: Handle intentionally empty arrays - need to strongly type them because
+    # CIM instances do not do a consistent job of casting an empty array properly.
+    empty_array_parameters = resource[:parameters].select { |_k, v| v[:value].empty? }
+    empty_array_parameters.each do |name, properties|
+      param_block_name = name.to_s.gsub(/^dsc_/, '')
+      params_block = params_block.gsub("#{param_block_name} = @()", "#{param_block_name} = [#{properties[:mof_type]}]@()")
+    end
+    # HACK: make CIM instances work:
+    resource[:parameters].select { |_key, hash| hash[:mof_is_embedded] && hash[:mof_type] =~ /\[\]/ }.each do |_property_name, property_hash|
+      formatted_property_hash = interpolate_variables(format(property_hash[:value]))
+      params_block = params_block.gsub(formatted_property_hash, "[CimInstance[]]#{formatted_property_hash}")
+    end
+    params_block
+  end
+
+  # Given a resource definition (as from `should_to_resource`), return a PowerShell script which has
+  # all of the appropriate function and variable definitions, which will call Invoke-DscResource, and
+  # will correct munge the results for returning to Puppet as a JSON object.
+  #
+  # @param resource [Hash] a hash with the information needed to run `Invoke-DscResource`
+  # @return [String] A string representing the PowerShell script which will invoke the DSC Resource.
+  def ps_script_content(resource)
+    template_path = File.expand_path('../', __FILE__)
+    # Defines the helper functions
+    functions     = File.new("#{template_path}/invoke_dsc_resource_functions.ps1").read
+    # Defines the response hash and the runtime settings
+    preamble      = File.new("#{template_path}/invoke_dsc_resource_preamble.ps1").read
+    # The postscript defines the invocation error and result handling; expects `$InvokeParams` to be defined
+    postscript    = File.new("#{template_path}/invoke_dsc_resource_postscript.ps1").read
+    # The blocks define the variables to define for the postscript.
+    credential_block = prepare_credentials(resource)
+    cim_instances_block = prepare_cim_instances(resource)
+    parameters_block = invoke_params(resource)
+    # clean them out of the temporary cache now that they're not needed; failure to do so can goof up future executions in this run
+    clear_instantiated_variables!
+
+    [functions, preamble, credential_block, cim_instances_block, parameters_block, postscript].join("\n")
+  end
+
+  # Convert a Puppet/Ruby value into a PowerShell representation. Requires some slight additional
+  # munging over what is provided in the ruby-pwsh library, as it does not handle unwrapping Sensitive
+  # data types or interpolating Credentials.
+  #
+  # @param value [Object] The object to format into valid PowerShell
+  # @return [String] A string representation of the input value as valid PowerShell
+  def format(value)
+    Pwsh::Util.format_powershell_value(value)
+  rescue RuntimeError => e
+    raise unless e.message =~ /Sensitive \[value redacted\]/
+
+    string = Pwsh::Util.format_powershell_value(unwrap(value))
+    string.gsub(/#PuppetSensitive'}/, "'} # PuppetSensitive")
+  end
+
+  # Unwrap sensitive strings for formatting, even inside an enumerable, appending '#PuppetSensitive'
+  # to the end of the string in preparation for gsub cleanup.
+  #
+  # @param value [Object] The object to unwrap sensitive data inside of
+  # @return [Object] The object with any sensitive strings unwrapped and annotated
+  def unwrap(value)
+    case value
+    when Puppet::Pops::Types::PSensitiveType::Sensitive
+      "#{value.unwrap}#PuppetSensitive"
+    when Hash
+      unwrapped = {}
+      value.each do |k, v|
+        unwrapped[k] = unwrap(v)
+      end
+      unwrapped
+    when Array
+      unwrapped = []
+      value.each do |v|
+        unwrapped << unwrap(v)
+      end
+      unwrapped
+    else
+      value
+    end
+  end
+
+  # Escape any nested single quotes in a Sensitive string
+  #
+  # @param text [String] the text to escape
+  # @return [String] the escaped text
+  def escape_quotes(text)
+    text.gsub("'", "''")
+  end
+
+  # While Puppet is aware of Sensitive data types, the PowerShell script is not
+  # and so for debugging purposes must be redacted before being sent to debug
+  # output but must *not* be redacted when sent to the PowerShell code manager.
+  #
+  # @param text [String] the text to redact
+  # @return [String] the redacted text
+  def redact_secrets(text)
+    # Every secret unwrapped in this module will unwrap as "'secret' # PuppetSensitive" and, currently,
+    # no known resources specify a SecureString instead of a PSCredential object. We therefore only
+    # need to redact strings which look like password declarations.
+    modified_text = text.gsub(/(?<=-Password )'.+' # PuppetSensitive/, "'#<Sensitive [value redacted]>'")
+    if modified_text =~ /'.+' # PuppetSensitive/
+      # Something has gone wrong, error loudly?
+    else
+      modified_text
+    end
+  end
+
+  # Instantiate a PowerShell manager via the ruby-pwsh library and use it to invoke PowerShell.
+  # Definiing it here allows re-use of a single instance instead of continually instantiating and
+  # tearing a new instance down for every call.
+  def ps_manager
+    debug_output = Puppet::Util::Log.level == :debug
+    # TODO: Allow you to specify an alternate path, either to pwsh generally or a specific pwsh path.
+    Pwsh::Manager.instance(Pwsh::Manager.powershell_path, Pwsh::Manager.powershell_args, debug: debug_output)
+  end
+end

data/lib/puppet/provider/dsc_base_provider/invoke_dsc_resource_functions.ps1

@@ -0,0 +1,124 @@
+function new-pscredential {
+    [CmdletBinding()]
+    param (
+        [parameter(Mandatory = $true,
+            ValueFromPipelineByPropertyName = $true)]
+        [string]
+        $user,
+
+        [parameter(Mandatory = $true,
+            ValueFromPipelineByPropertyName = $true)]
+        [string]
+        $password
+    )
+
+    $secpasswd = ConvertTo-SecureString $password -AsPlainText -Force
+    $credentials = New-Object System.Management.Automation.PSCredential ($user, $secpasswd)
+    return $credentials
+}
+
+Function ConvertTo-CanonicalResult {
+  [CmdletBinding()]
+  param(
+      [Parameter(Mandatory, Position = 1)]
+      [psobject]
+      $Result,
+
+      [Parameter(DontShow)]
+      [string]
+      $PropertyPath,
+
+      [Parameter(DontShow)]
+      [int]
+      $RecursionLevel = 0
+  )
+
+  $MaxDepth = 5
+  $CimInstancePropertyFilter = { $_.Definition -match 'CimInstance' -and $_.Name -ne 'PSDscRunAsCredential' }
+
+  # Get the properties which are/aren't Cim instances
+  $ResultObject = @{ }
+  $ResultPropertyList = $Result | Get-Member -MemberType Property | Where-Object { $_.Name -ne 'PSComputerName' }
+  $CimInstanceProperties = $ResultPropertyList | Where-Object -FilterScript $CimInstancePropertyFilter
+
+  foreach ($Property in $ResultPropertyList) {
+      $PropertyName = $Property.Name
+      if ($Property -notin $CimInstanceProperties) {
+          $Value = $Result.$PropertyName
+          if ($PropertyName -eq 'Ensure' -and [string]::IsNullOrEmpty($Result.$PropertyName)) {
+              # Just set 'Present' since it was found /shrug
+              # If the value IS listed as absent, don't update it unless you want flapping
+              $Value = 'Present'
+          }
+          else {
+              if ($Value -is [string] -or $value -is [string[]]) {
+                  $Value = $Value
+              }
+
+              if ($Value.Count -eq 1 -and $Property.Definition -match '\\[\\]') {
+                  $Value = @($Value)
+              }
+          }
+      }
+      elseif ($null -eq $Result.$PropertyName) {
+          if ($Property -match 'InstanceArray') {
+              $Value = @()
+          }
+          else {
+              $Value = $null
+          }
+      }
+      elseif ($Result.$PropertyName.GetType().Name -match 'DateTime') {
+          # Handle DateTimes especially since they're an edge case
+          $Value = Get-Date $Result.$PropertyName -UFormat "%Y-%m-%dT%H:%M:%S%Z"
+      }
+      else {
+          # Looks like a nested CIM instance, recurse if we're not too deep in already.
+          $RecursionLevel++
+
+          if ($PropertyPath -eq [string]::Empty) {
+              $PropertyPath = $PropertyName
+          }
+          else {
+              $PropertyPath = "$PropertyPath.$PropertyName"
+          }
+
+          if ($RecursionLevel -gt $MaxDepth) {
+              # Give up recursing more than this
+              return $Result.ToString()
+          }
+
+          $Value = foreach ($item in $Result.$PropertyName) {
+              ConvertTo-CanonicalResult -Result $item -PropertyPath $PropertyPath -RecursionLevel ($RecursionLevel + 1) -WarningAction Continue
+          }
+
+          # The cim instance type is the last component of the type Name
+          # We need to return this for ruby to compare the result hashes
+          # We do NOT need it for the top-level properties as those are defined in the type
+          If ($RecursionLevel -gt 1 -and ![string]::IsNullOrEmpty($Value) ) {
+              # If there's multiple instances, you need to add the type to each one, but you
+              # need to specify only *one* name, otherwise things end up *very* broken.
+              if ($Value.GetType().Name -match '\[\]') {
+                  $Value | ForEach-Object -Process {
+                      $_.cim_instance_type = $Result.$PropertyName.CimClass.CimClassName[0]
+                  }
+              } else {
+                  $Value.cim_instance_type = $Result.$PropertyName.CimClass.CimClassName
+                  # Ensure that, if it should be an array, it is
+                  if ($Result.$PropertyName.GetType().Name -match '\[\]') {
+                      $Value = @($Value)
+                  }
+              }
+          }
+      }
+
+      if ($Property.Definition -match 'InstanceArray') {
+          if ($Value.Count -lt 2) { $Value = @($Value) }
+      }
+
+      $ResultObject.$PropertyName = $Value
+  }
+
+  # Output the final result
+  $ResultObject
+}

data/lib/puppet/provider/dsc_base_provider/invoke_dsc_resource_postscript.ps1

@@ -0,0 +1,23 @@
+Try {
+  $Result = Invoke-DscResource @InvokeParams
+} catch {
+  $Response.errormessage   = $_.Exception.Message
+  return ($Response | ConvertTo-Json -Compress)
+}
+
+# keep the switch for when Test passes back changed properties
+Switch ($invokeParams.Method) {
+  'Test' {
+    $Response.indesiredstate = $Result.InDesiredState
+    return ($Response | ConvertTo-Json -Compress)
+  }
+  'Set' {
+    $Response.indesiredstate = $true
+    $Response.rebootrequired = $Result.RebootRequired
+    return ($Response | ConvertTo-Json -Compress)
+  }
+  'Get' {
+    $CanonicalizedResult = ConvertTo-CanonicalResult -Result $Result
+    return ($CanonicalizedResult | ConvertTo-Json -Compress -Depth 10)
+  }
+}

data/lib/puppet/provider/dsc_base_provider/invoke_dsc_resource_preamble.ps1

@@ -0,0 +1,8 @@
+$script:ErrorActionPreference = 'Stop'
+$script:WarningPreference = 'SilentlyContinue'
+
+$response = @{
+    indesiredstate = $false
+    rebootrequired = $false
+    errormessage   = ''
+}

data/lib/pwsh.rb

@@ -14,10 +14,10 @@ require 'logger'
 module Pwsh
   # Standard errors
   class Error < StandardError; end
+
   # Create an instance of a PowerShell host and manage execution of PowerShell code inside that host.
   class Manager
-    attr_reader :powershell_command
-    attr_reader :powershell_arguments
+    attr_reader :powershell_command, :powershell_arguments
 
     # We actually want this to be a class variable.
     @@instances = {} # rubocop:disable Style/ClassVars
@@ -70,7 +70,7 @@ module Pwsh
     def self.win32console_enabled?
       @win32console_enabled ||= defined?(Win32) &&
                                 defined?(Win32::Console) &&
-                                Win32::Console.class == Class
+                                Win32::Console.instance_of?(Class)
     end
 
     # TODO: This thing isn't called anywhere and the variable it sets is never referenced...
@@ -471,7 +471,7 @@ Invoke-PowerShellUserCode @params
     # @return [String] The UTF-8 encoded string containing the payload
     def self.read_length_prefixed_string!(bytes)
       # 32 bit integer in Little Endian format
-      length = bytes.slice!(0, 4).unpack('V').first
+      length = bytes.slice!(0, 4).unpack1('V')
       return nil if length.zero?
 
       bytes.slice!(0, length).force_encoding(Encoding::UTF_8)
@@ -586,7 +586,7 @@ Invoke-PowerShellUserCode @params
 
       pipe_reader = Thread.new(@pipe) do |pipe|
         # Read a Little Endian 32-bit integer for length of response
-        expected_response_length = pipe.sysread(4).unpack('V').first
+        expected_response_length = pipe.sysread(4).unpack1('V')
 
         next nil if expected_response_length.zero?
 

data/lib/pwsh/util.rb

@@ -12,7 +12,7 @@ module Pwsh
     def on_windows?
       # Ruby only sets File::ALT_SEPARATOR on Windows and the Ruby standard
       # library uses that to test what platform it's on.
-      !!File::ALT_SEPARATOR # rubocop:disable Style/DoubleNegation
+      !!File::ALT_SEPARATOR
     end
 
     # Verify paths specified are valid directories which exist.
@@ -117,16 +117,16 @@ module Pwsh
     #
     # @return [String] representation of the value for interpolation
     def format_powershell_value(object)
-      if %i[true false].include?(object) || %w[trueclass falseclass].include?(object.class.name.downcase) # rubocop:disable Lint/BooleanSymbol
+      if %i[true false].include?(object) || %w[trueclass falseclass].include?(object.class.name.downcase)
         "$#{object}"
-      elsif object.class.name == 'Symbol' || object.class.ancestors.include?(Numeric)
+      elsif object.instance_of?(Symbol) || object.class.ancestors.include?(Numeric)
         object.to_s
-      elsif object.class.name == 'String'
+      elsif object.instance_of?(String)
         "'#{escape_quotes(object)}'"
-      elsif object.class.name == 'Array'
-        '@(' + object.collect { |item| format_powershell_value(item) }.join(', ') + ')'
-      elsif object.class.name == 'Hash'
-        '@{' + object.collect { |k, v| format_powershell_value(k) + ' = ' + format_powershell_value(v) }.join('; ') + '}'
+      elsif object.instance_of?(Array)
+        "@(#{object.collect { |item| format_powershell_value(item) }.join(', ')})"
+      elsif object.instance_of?(Hash)
+        "@{#{object.collect { |k, v| "#{format_powershell_value(k)} = #{format_powershell_value(v)}" }.join('; ')}}"
       else
         raise "unsupported type #{object.class} of value '#{object}'"
       end

data/lib/pwsh/version.rb

@@ -2,5 +2,5 @@
 
 module Pwsh
   # The version of the ruby-pwsh gem
-  VERSION = '0.4.1'
+  VERSION = '0.6.2'
 end

data/metadata.json

@@ -1,11 +1,11 @@
 {
   "name": "puppetlabs-pwshlib",
-  "version": "0.4.1",
+  "version": "0.6.2",
   "author": "puppetlabs",
   "summary": "Provide library code for interoperating with PowerShell.",
   "license": "MIT",
   "source": "https://github.com/puppetlabs/ruby-pwsh",
-  "project_page": "https://github.com/puppetlabs/ruby-pwsh/blob/master/pwshlib.md",
+  "project_page": "https://github.com/puppetlabs/ruby-pwsh/blob/main/pwshlib.md",
   "issues_url": "https://github.com/puppetlabs/ruby-pwsh/issues",
   "dependencies": [
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-pwsh
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.6.2
 platform: ruby
 authors:
 - Puppet, Inc.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-02-13 00:00:00.000000000 Z
+date: 2020-12-10 00:00:00.000000000 Z
 dependencies: []
 description: PowerShell code manager for ruby.
 email:
@@ -31,8 +31,13 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- appveyor.yml
 - design-comms.png
 - lib/puppet/feature/pwshlib.rb
+- lib/puppet/provider/dsc_base_provider/dsc_base_provider.rb
+- lib/puppet/provider/dsc_base_provider/invoke_dsc_resource_functions.ps1
+- lib/puppet/provider/dsc_base_provider/invoke_dsc_resource_postscript.ps1
+- lib/puppet/provider/dsc_base_provider/invoke_dsc_resource_preamble.ps1
 - lib/pwsh.rb
 - lib/pwsh/util.rb
 - lib/pwsh/version.rb